钉钉通道配置

钉钉推荐使用 Stream 长连接模式，无需公网 IP，支持 AI Card 流式输出。

模式	说明	公网 IP	推荐
Stream 长连接	注册网关后 WebSocket 通信	不需要	推荐
Webhook 回调	标准 HTTP 回调	需要	预留

配置步骤

1. 创建企业内部应用

1. 登录 钉钉开放平台
2. 进入「应用开发」->「企业内部应用」
3. 点击「创建应用」，选择「H5 微应用」或「机器人」
4. 填写应用名称和描述

2. 获取应用凭证

在应用详情页 ->「凭证与基础信息」中获取：

• AppKey — 应用唯一标识
• AppSecret — 应用密钥

3. 开启机器人能力

1. 在应用详情页 ->「机器人与消息推送」
2. 开启「机器人配置」开关
3. 记录 robotCode（机器人编码）
4. 消息接收模式选择 Stream 模式

4. 在 OpenVort 中配置

登录 OpenVort Web 后台，进入「通道管理」，点击钉钉的「配置」按钮：

字段	值	必填
App Key	凭证与基础信息中获取	是
App Secret	凭证与基础信息中获取	是
机器人编码	机器人配置中的 robotCode	是
回复模式	card（流式）或 markdown（普通）	否
Card Template ID	钉钉卡片模板 ID	流式模式必填
Card Content Key	卡片正文变量名，通常为 content	否

环境变量方式：

OPENVORT_DINGTALK_APP_KEY=dingxxxxxxxx
OPENVORT_DINGTALK_APP_SECRET=your_app_secret
OPENVORT_DINGTALK_ROBOT_CODE=dingxxxxxxxx

保存后点击「测试连接」验证。

---

AI Card 流式输出（推荐）

钉钉支持通过 AI Card 模板实现流式输出，AI 回复时用户可以实时看到内容逐字输出。

创建 AI Card 模板

1. 登录 钉钉开放平台
2. 进入「卡片平台」->「卡片模板」
3. 创建新模板，类型选择「AI 卡片」
4. 在模板中添加一个 Markdown 组件
5. 绑定变量名（默认使用 content）
6. 发布模板，记录模板 ID

配置 OpenVort

在钉钉通道配置中补充填写：

字段	值
回复模式	card
Card Template ID	卡片模板 ID
Card Content Key	模板中的变量名（默认 content）

环境变量方式：

OPENVORT_DINGTALK_MESSAGE_TYPE=card
OPENVORT_DINGTALK_CARD_TEMPLATE_ID=your_template_id
OPENVORT_DINGTALK_CARD_TEMPLATE_KEY=content

如果不配置 AI Card，回复模式将使用普通 Markdown，用户需等待 AI 完整回复后才能看到内容。

---

使用说明

单聊

直接给机器人发送消息即可。打开钉钉，搜索应用名称，发送消息。

群聊

在群聊中需要 @ 机器人才能触发回复：

1. 将机器人添加到群聊中
2. 发送消息时 @ 机器人名称
3. 未 @ 的消息会被忽略

语音消息

支持接收用户发送的语音消息，通过 ASR 自动转写为文字。需在 OpenVort 中配置语音识别服务。

---

常见问题

Q: Stream 模式连接不上？

1. 确认 AppKey、AppSecret 填写正确
2. 检查网络连通性（需能访问 api.dingtalk.com）
3. 确认应用已发布上线
4. 在开放平台「机器人与消息推送」中确认消息接收模式为 Stream

Q: AI Card 不显示流式效果？

1. 确认卡片模板已发布
2. 检查 Card Template ID 和 Card Content Key 是否正确
3. 确认「回复模式」设置为 card
4. 检查钉钉客户端版本是否支持 AI 卡片

Q: 群聊中机器人不回复？

确认发送消息时已 @ 机器人。钉钉群聊中，未 @ 机器人的消息不会被转发到应用。