manuallatest产品手册 / 钉钉
在钉钉开发者平台首页右侧的企业信息卡片中复制 CorpId
钉钉
一、前置条件
- 拥有钉钉开放平台账号（企业内部应用或第三方应用均可）
- Agentic Engine 平台的管理员权限
二、创建钉钉应用并获取凭证
前往 钉钉开放平台，登录后按以下步骤操作：
- 进入「开发者后台」→「应用开发」→「企业内部应用」，点击「创建应用」
- 填写应用名称和描述
- 应用创建成功后，进入应用详情页 →「凭证与基础信息」，记录以下两个值：
| 字段名称 | 对应平台字段 | 说明 |
|---|---|---|
| AppKey | Client ID | 应用唯一标识，用于 OAuth 授权 |
| AppSecret | Client Secret | 应用密钥，请妥善保管，不要泄露 |
获取企业 CorpId
打开钉钉开发者平台并登录。在首页右侧的企业信息卡片中找到 CorpId，复制完整值。添加钉钉渠道时，必须将该 CorpId 与 Client ID、Client Secret 一起填写。
CorpId 是当前企业的唯一标识，每个企业的值不同；请使用自己企业页面中显示的完整值，不要照抄示例或截图中的值。
- 进入「添加应用能力」→「机器人」，机器人配置中消息接收模式选择「Stream模式」
- 在应用的「权限管理」中，开通以下权限：
通讯录个人信息读权限、企业员工手机号信息、钉钉群基础信息管理权限、成员信息读权限、企业内机器人发消息权限、互动卡片实例写权限、AI卡片流式更新权限、智能交互卡片写权限。无需开通「企业存储应用读权限」：该权限用于企业存储类接口，当前渠道实现不会调用这类接口。 - 在「安全设置」中，将 Agentic Engine 的服务器 IP 添加到出口 IP 白名单，并配置 OAuth 重定向URL（回调域名）为：
https://<your-domain>/api/dingtalk-oauth/callback - 每次修改配置之后在「版本管理与发布」部分点击「查看版本详情」编辑版本号和版本描述之后点击「发布」
三、在平台中添加钉钉渠道
管理员登录 Agentic Engine，进入「系统管理」→「Agent 管理」→「渠道管理」：
- 点击「新建渠道」，渠道类型选择 钉钉
- 填写以下配置项：
| 配置项 | 是否必填 | 说明 |
|---|---|---|
| 渠道名称 | 必填 | 显示名称，如「企业钉钉」。 |
| Corp ID | 必填 | 钉钉企业唯一标识，用于验证企业身份并建立群聊空间；可在钉钉管理后台的企业信息中复制。 |
| Client ID | 必填 | 填入钉钉应用的 AppKey。 |
| Client Secret | 必填 | 填入钉钉应用的 AppSecret。 |
| 交互提问卡片模板 ID | 可选 | 钉钉 AI Card 模板的 ID，形如「xxxxxxxx.schema」。需使用已发布且符合项目变量契约的钉钉 AI Card 模板；留空时，提问将自动使用文字回答。 |
| 默认模型 | 可选 | 单 Agent 渠道任务使用；不填则使用系统全局默认模型。Team 使用各成员自身配置的模型。 |
| 渠道输入附加说明 | 可选 | 作为每轮渠道输入的附加说明，不会替代 Agent 自身的系统提示词。 |
- 点击「保存」，渠道创建成功后状态显示为「运行中」
提示
同一企业可以创建多个钉钉渠道实例，但同一个钉钉机器人身份不能在同一环境中重复配置。修改 Client ID、Client Secret 或 Corp ID 后需要重新验证并重新启用对应群聊空间；仅修改名称、默认模型或渠道输入附加说明不会让已验证空间失效。
四、用户绑定钉钉账号
管理员完成渠道配置后，普通用户可在用户菜单的「渠道绑定」中绑定自己的钉钉账号：
OAuth 授权绑定
- 打开 AE 的用户菜单，进入「渠道绑定」，在「钉钉」下找到目标渠道实例，点击「绑定」
- 系统跳转至钉钉 OAuth 授权页面，扫码或登录钉钉账号完成授权
- 授权成功后自动回跳平台，绑定状态变为「已绑定」
如果点击「绑定」后弹出的是绑定码对话框，请在钉钉中向机器人私聊发送对话框里的完整绑定命令（绑定码有效期 10 分钟），详见渠道概览与绑定。
五、群聊消息分发
群聊消息分发可以让同一个钉钉机器人按规则把不同问题交给不同的 Agent 或 Team。一个「群聊空间」对应配置中的企业 CorpId，规则对该企业内使用此机器人的群聊生效。只有已绑定 Agentic Engine 账号、并在群里明确 @机器人的成员才能发起任务。
管理员配置
- 确认应用使用 Stream 模式，Client ID、Client Secret 和 CorpId 均已填写，并已开通群基础信息、机器人发消息、互动卡片和 AI 卡片流式更新等本文前述权限。
- 进入「系统管理 → Agent 管理 → 渠道管理」，在对应钉钉渠道上打开「消息分发」（弹窗标题为「群聊消息分发」）。验证成功后系统会按 CorpId 建立群聊空间。
- 选择默认使用的 Agent/Team。启用群聊分发前必须配置默认项。
- 按需添加最多 19 条规则。每条规则选择一个 Agent/Team，填写必填的「调用指令」，还可以填写最多 10 个关键词，然后打开启用开关并保存。
- 在群中发送
@机器人 /help做验收。
| 配置项 | 规则 |
|---|---|
| 默认 Agent/Team | 启用前必须配置；未指定调用指令、且未命中关键词时使用。 |
| 调用指令 | 必填，1～32 个字符；可使用字母、数字、- 和 _，不能使用系统保留命令。大小写以及全角、半角差异不视为不同指令。 |
| 关键词 | 可不填；每条规则最多 10 个，每个 2～32 个字符。多个关键词同时命中时优先更长的关键词；同长度无法唯一判断时回到默认 Agent/Team。 |
| 可选范围 | 可选择已启用且可运行的系统/企业 Agent，以及当前企业的 Team；个人 Agent 不会出现在候选中。 |
群聊中的使用方式
| 用途 | 示例 | 说明 |
|---|---|---|
| 查看可用能力 | @机器人 /help@机器人 能力清单 | 只展示当前用户可使用且当前可运行的能力。 |
| 指定 Agent/Team | @机器人 /analysis 分析本周数据 | 也可以发送 @机器人 @analysis 分析本周数据。 |
| 按关键词分发 | @机器人 帮我检查埋点方案 | 命中关键词时使用对应规则，未命中时使用默认项。 |
| 取消任务 | @机器人 /cancel | 必须整条消息精确发送。已输出正文保留，并另外发送一条取消确认。 |
| 兼容旧写法 | @机器人 /agent analysis 分析本周数据 | 仍可使用，但推荐直接使用 /analysis。 |
命令边界：群聊分发不支持 /new；私聊仍支持 /new、/agent 和 /cancel。普通新任务必须先 @机器人；等待用户回答时按机器人卡片或文字提示继续。
公开上下文与个人数据：系统只使用近期明确 @机器人并实际进入处理的公开群聊轮次作为参考；未 @机器人的普通群消息、其他群、私聊和个人记忆不会混入。
六、常见问题
渠道状态异常 / 无法连接
- 检查 Client ID 和 Client Secret 是否填写正确
- 确认应用在钉钉开放平台的状态为「已上线」或「开发中」
OAuth 回调失败
- 确认钉钉应用「安全设置」中已添加平台服务器 IP 白名单
- 确认回调地址已正确配置，且与平台实际部署域名完全一致（包括协议和路径）
用户无法绑定账号
- 确认钉钉应用已开通相关权限
- 确认应用回调地址配置正确
相关页面与下一步
这篇文档对你有帮助吗？