跳到主要内容

钉钉对接指南

将 Sage AI 接入钉钉企业内部应用机器人后，员工可在钉钉单聊或群聊中与 AI 对话。钉钉支持两种消息接入方式：Stream 长连接 与 HTTP URL 回调，钉钉后台与 AI 工作台必须选择同一种。

配置 IM 渠道可将 Sage AI 对话接入团队 IM，实现即时问答与协作。机器人自动绑定当前资源域并遵循权限管控，如需访问全部权限数据，可前往「全部资源域」配置。请勿在不同账号、环境或资源域中重复绑定同一 IM 凭证，否则可能导致消息丢失或对话中断。

先决条件​

要求说明
功能菜单具备 AI 工作台 / 安全运营 / IM 渠道 菜单权限
操作权限配置、解绑需读写权限
钉钉账号建议具备企业内部应用创建与发布权限
网络Stream 长连接：平台可出站访问钉钉公网即可；HTTP URL 回调：平台需提供公网 HTTPS 消息接收地址
模型至少配置一个可用推理模型；IM 侧默认 Auto

两种接入方式（必读）​

对比项Stream 长连接（WebSocket）URL 回调（HTTP）
适用场景无私网暴露、私有化内网，配置更简单有公网 HTTPS，由钉钉主动推送消息
AI 工作台选择「WebSocket 长连接（Stream）」「使用 URL 回调（HTTP）」
钉钉侧消息模式Stream 模式HTTP 模式
需填写凭证Client ID、Client SecretClient ID、Client Secret；aes_key、token 选填
是否回填地址不需要回填消息接收地址保存后生成 Webhook，切换 HTTP 后必须粘贴并发布
保存时校验校验连通性，通过后「已连接」校验 Client ID / Secret，通过后「已连接」并生成 Webhook

两侧必须一致：工作台选长连接时，钉钉机器人保持 Stream；工作台选 URL 回调时，钉钉必须改为 HTTP 并填入 Webhook（且使用 https://）。

整体流程（一览）​

1. 钉钉开发者后台新建企业内部应用，启用机器人能力
        ↓
2. 开通消息 / 卡片相关权限，获取 Client ID、Client Secret
        ↓
3. 二选一连接方案（两侧必须一致）
   ┌────────────────────────────────┬────────────────────────────────────┐
   │ Stream 长连接                   │ HTTP URL 回调                      │
   │ ① 钉钉创建并保存/发布机器人      │ ①（可选）事件订阅生成 AES Key、Token │
   │ ② 消息模式保持 Stream 并保存     │ ② AI 工作台选 URL 回调并保存         │
   │ ③ AI 工作台选长连接并保存        │ ③ 钉钉切 HTTP，粘贴 HTTPS Webhook    │
   │ ④ 连通校验通过即可               │ ④ 钉钉侧保存并发布                   │
   └────────────────────────────────┴────────────────────────────────────┘
        ↓
4. 发布应用 → 单聊 / 群聊添加机器人测试

一、创建钉钉应用与机器人​

1. 登录开发者后台​

访问 钉钉开发者后台，使用管理员账号登录：

登录开发者后台

若提示未加入组织，可先创建个人企业：

创建个人组织

2. 创建应用​

  1. 进入 应用开发，点击 创建应用。
  2. 填写应用名称、描述等（后续可改），点击 保存。

创建应用

image-20260821180135111

3. 添加机器人能力​

  1. 在「添加应用能力」中找到 机器人，点击 添加机器人。
  2. 填写机器人名称、描述、预览图。
  3. 点击 确认发布。

image-20260821180158803

image-20260821180219926

确认发布机器人

二、配置权限​

在应用详情 权限管理 中搜索并开通以下权限（名称以钉钉当前控制台为准）：

  • Card.Streaming.Write
  • Card.Instance.Write
  • qyapi_robot_sendmsg

image-20260821180243153

三、获取应用凭证​

1. Client ID / Client Secret​

进入 凭证与基础信息：

  • Client ID（也叫 AppKey）
  • Client Secret（也叫 AppSecret）

image-20260821180300930

重要

请妥善保管 Client Secret，不要泄露。

2. AES Key / Token（仅 URL 回调时建议配置）​

若使用 HTTP URL 回调 且需要消息加密：

  1. 进入 开发配置 → 事件订阅。
  2. 推送方式选择 HTTP 推送。
  3. 生成并保存 AES Key、Token（对应 AI 工作台选填的 aes_key、token）。

image-20260821180328582

使用 Stream 长连接时，一般不必在此配置 HTTP 推送地址。

四、方式一：Stream 长连接接入​

适合无公网入口、希望少配置的场景。

重要

使用 Stream 长连接 时，请先在钉钉侧完成应用 / 机器人创建，确认消息模式为 Stream，并 保存 / 发布 机器人后，再回到 AI 工作台填写 Client ID / Client Secret 并保存。若尚未在钉钉保存机器人就先在 AI 工作台保存，可能提示信息无效并导致保存失败。

1. 钉钉侧准备并保持 Stream​

  1. 按前文完成应用创建、机器人能力添加与权限开通，并获取 Client ID、Client Secret。
  2. 确认机器人消息接收配置为 Stream 模式（不要改成 HTTP）。若此前改过 HTTP，请改回 Stream 并 保存 / 发布。

2. 在 AI 工作台配置​

  1. 进入 AI 工作台 → 安全运营 → IM 渠道 → 钉钉 → 配置。
  2. 连接方式选择 「WebSocket 长连接（Stream）」。
  3. 填写 Client ID、Client Secret，点击 「保存」。
字段是否必填说明默认值校验规则
Client ID必填Client ID / AppKey无非空；≤1000；不脱敏
Client Secret必填Client Secret / AppSecret无非空；≤1000；脱敏

image-20260821180454216

保存时进行连通性校验，通过后为「已连接」。长连接模式不会要求回填消息接收地址。

五、方式二：HTTP URL 回调接入​

适合已有公网 HTTPS、需由钉钉主动推送的场景。

1. 在 AI 工作台生成 Webhook​

  1. 进入 AI 工作台 → 安全运营 → IM 渠道 → 钉钉 → 配置。
  2. 连接方式选择 「使用 URL 回调（HTTP）」。
  3. 填写 Client ID、Client Secret；按需填写 aes_key、token。
  4. 点击 「保存」，复制生成的 Webhook。
字段是否必填说明默认值校验规则
Client ID必填Client ID / AppKey无非空；≤1000；不脱敏
Client Secret必填Client Secret / AppSecret无非空；≤1000；脱敏
aes_key选填消息加密密钥；留空则不开启加密无≤1000；脱敏
token选填回调校验 Token；留空则不开启加密无≤1000；脱敏

image-20260821180432206

2. 回填消息接收地址​

  1. 打开钉钉应用 / 机器人的消息接收配置。
  2. 将 Stream 模式 切换为 HTTP 模式：

image-20260821180509374

  1. 在「消息接收地址」中粘贴 Webhook：

image-20260821180613019

  1. 点击 发布 / 保存配置。

六、会话管理与解绑​

字段是否必填说明默认值校验规则
自动开启新会话必填超时未对话则自动新会话24 小时下拉 1–24 小时；不可关闭

点击 「解绑」 并二次确认后解除绑定。

七、发布应用​

应用必须发布后才能在企业内使用：

image-20260821180640318

image-20260821180658156

image-20260821180716693

image-20260821180733364

八、开始使用​

群聊​

  1. 确保群「归属组织」与创建机器人时的组织相同。
  2. 群设置 → 机器人 → 添加机器人 → 搜索并添加。

image-20260821180805686

image-20260821180829214

image-20260821180856094

在群内 @机器人 发送需求即可。

单聊​

image-20260821181010569

在顶部搜索机器人名称，进入会话直接发送消息。

项说明
模型Auto 路由
限流同一机器人约 1 分钟 ≤ 20 次提问

九、常见问题​

机器人没有响应？​

  1. 核对接入方式：工作台与钉钉是否同为 Stream，或同为 HTTP + Webhook。
  2. HTTP 模式：确认地址为 https，且已发布。
  3. 核对 Client ID / Client Secret。
  4. 确认三个权限已开通，应用已发布通过。
  5. 确认未跨账号 / 环境 / 资源域重复绑定。

长连接保存失败？​

  1. 确认已先在钉钉侧 保存 / 发布 机器人，消息模式为 Stream，再在 AI 工作台保存配置。
  2. 重新复制 Client ID、Client Secret，避免多余空格。
  3. 确认平台可出站访问钉钉公网服务。

群里找不到机器人？​

  1. 确认应用已发布。
  2. 确认群归属组织与机器人所属组织一致。
  3. 尝试重启钉钉客户端。

相关文档​