钉钉机器人
钉钉机器人
钉钉机器人用于在钉钉会话中调用艾维斯能力。建议优先使用 Stream 接入方式：机器人配置页面保存 Client ID 和 Client Secret，钉钉侧添加机器人能力和事件订阅后，通过长连接接收消息。
上线前应把它当作受控入口来配置：只响应已批准来源的消息，只使用当前用户、群或绑定 Agent 可访问的知识与工具，并让每次回复都能被追踪和审计。
适用场景
管理边界
配置前检查
开始配置前，请确认：
- 已登录钉钉开发者平台，且当前账号可以创建企业内部应用和发布应用版本。
- 已打开艾维斯中的钉钉机器人配置页面，准备填写
Client ID、Client Secret和接入方式。 - 已明确机器人允许服务的群、部门、成员、工作区和默认 Agent 或知识范围。
- 计划使用
Stream接入方式。钉钉 HTTP 回调对接口响应延迟要求较高，通常需要在约 1.5 秒内完成响应；为降低接入失败概率，建议优先使用Stream。
Client Secret是敏感信息。只应保存到受保护配置中，不要写入公开文档、Agent 指令、截图、工单或聊天记录。
创建钉钉应用
打开钉钉开发者平台，进入企业内部应用列表，点击“创建应用”，按页面提示填写应用名称、描述、图标等基础信息并完成创建。建议应用名称与艾维斯中的机器人显示名称保持一致，便于管理员和成员识别。
创建后进入应用详情页，确认当前应用属于预期企业或组织，并继续配置凭证、机器人能力和版本发布。
配置应用凭证
在钉钉应用详情页复制 Client ID 和 Client Secret。返回艾维斯机器人配置页面，将它们分别填入“客户端 ID”和“客户端密钥”，并确认接入方式选择 Stream。
配置时请注意：
Client ID与Client Secret必须来自同一个钉钉应用。- 不要把企业 ID、机器人名称、用户 ID 或手机号填入“客户端 ID”。
- 如果重新生成了
Client Secret，需要同步更新艾维斯配置；否则机器人可能无法建立连接。 - 如果页面提示已保存且没有更换密钥，可以保持密钥字段为空。
添加机器人能力
在钉钉开发者平台中点击“添加应用能力”，选择并添加“机器人”能力。
进入机器人配置页，将消息接收模式设置为 Stream，然后保存并发布机器人配置。
如果钉钉页面提示机器人配置尚未发布，后续即使艾维斯侧凭证已保存，钉钉侧也可能不会推送消息。
配置事件订阅
添加事件订阅时，推荐选择 Stream 模式，并保持与艾维斯机器人配置页面中的接入方式一致。完成配置后，点击“已完成接入”，验证连接通道；验证通过后点击“保存”。
事件订阅和应用版本发布是两项独立检查。事件订阅已保存但版本未发布，或版本已发布但 Stream 连接验证失败，都可能导致机器人无法收到消息。
创建版本并发布
打开“版本管理”，提交并发布最新版本。发布完成后检查：
- 版本状态正常或已发布。
- 当前机器人能力已包含在版本中。
- 可用范围符合预期，例如仅部分成员、指定部门或指定企业范围可用。
- 最近修改已经发布，不存在待发布配置。
测试钉钉机器人
测试前，请先在艾维斯机器人配置页确认：
- 机器人开关为已启用。
- 接入方式为
Stream。 Client ID和Client Secret已保存。- 绑定的 Agent、知识范围和工具范围符合当前测试场景。
- 钉钉侧机器人能力、事件订阅和应用版本均已保存并发布。
然后在钉钉中搜索刚创建的机器人，打开会话后发送测试消息。配置正确时，机器人应能收到消息并返回回复；实际响应时间取决于网络、模型调用和后端处理耗时。
验证访问边界
完成基础回复测试后，再验证治理边界：
- 使用授权成员发送一个应当能回答的问题，确认机器人返回正确内容。
- 使用未授权成员、未授权群或无权访问文档集的问题进行测试，确认机器人不会返回敏感数据。
- 在追踪或请求日志中确认来源平台、用户上下文、绑定 Agent、响应结果和错误信息可审计。
- 更换
Client Secret、接入方式、事件订阅、机器人能力或可用范围后，重新发布钉钉版本并重复测试。
常见问题排查
安全与维护建议
- 仅在艾维斯配置页保存真实密钥，不把密钥写入文档、截图、工单、聊天记录或代码仓库。
- 密钥疑似泄露时，应在钉钉开发者平台重新生成，并立即同步更新艾维斯配置。
- 权限按最小可用范围申请。只需要消息自动回复时，不要额外开通通讯录、审批或管理类权限。
- 机器人长期不用时，先在艾维斯侧关闭机器人，再在钉钉开发者平台收回权限或下线应用版本。
- 生产环境建议记录每次钉钉应用版本发布的时间、发布人、变更内容和验证结果。