> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.alephant.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.alephant.io/_mcp/server.

# 钉钉机器人

> 使用钉钉 Stream 模式配置机器人，并控制应用凭证、机器人能力、事件订阅、版本发布和测试边界。

钉钉机器人用于在钉钉会话中调用艾维斯能力。建议优先使用 `Stream` 接入方式：机器人配置页面保存 `Client ID` 和 `Client Secret`，钉钉侧添加机器人能力和事件订阅后，通过长连接接收消息。

上线前应把它当作受控入口来配置：只响应已批准来源的消息，只使用当前用户、群或绑定 Agent 可访问的知识与工具，并让每次回复都能被追踪和审计。

## 适用场景

| 场景     | 建议                                           |
| ------ | -------------------------------------------- |
| 团队知识问答 | 将机器人发布到已批准的钉钉组织或成员范围，并绑定对应团队可访问的 Agent 或文档集。 |
| 内部支持   | 使用独立的钉钉企业内部应用，便于凭证轮换、日志筛选和权限复核。              |
| 项目群助手  | 为项目群限定知识范围和工具范围，项目结束后下线或移除可用范围。              |
| 敏感知识问答 | 先验证用户、群和文档集权限，不把机器人配置成绕过权限的共享代理。             |

## 管理边界

| 项目 | 建议                                      |
| -- | --------------------------------------- |
| 入口 | 使用已批准的钉钉企业内部应用、机器人能力和事件订阅。              |
| 身份 | 将机器人绑定到明确的艾维斯工作区和 owner，不把机器人当作管理员代理。   |
| 响应 | 仅返回当前用户、群或绑定 Agent 可访问的知识和工具结果。         |
| 权限 | 只开通机器人消息接收所需权限；需要更多会话能力时再单独申请。          |
| 运维 | 记录 Client ID、版本发布时间、接入方式、可用范围、密钥轮换和负责人。 |

## 配置前检查

开始配置前，请确认：

1. 已登录[钉钉开发者平台](https://open-dev.dingtalk.com/fe/app?hash=%23%2Fcorp%2Fapp#/corp/app)，且当前账号可以创建企业内部应用和发布应用版本。
2. 已打开艾维斯中的钉钉机器人配置页面，准备填写 `Client ID`、`Client Secret` 和接入方式。
3. 已明确机器人允许服务的群、部门、成员、工作区和默认 Agent 或知识范围。
4. 计划使用 `Stream` 接入方式。钉钉 HTTP 回调对接口响应延迟要求较高，通常需要在约 1.5 秒内完成响应；为降低接入失败概率，建议优先使用 `Stream`。

> `Client Secret` 是敏感信息。只应保存到受保护配置中，不要写入公开文档、Agent 指令、截图、工单或聊天记录。

## 创建钉钉应用

打开钉钉开发者平台，进入企业内部应用列表，点击“创建应用”，按页面提示填写应用名称、描述、图标等基础信息并完成创建。建议应用名称与艾维斯中的机器人显示名称保持一致，便于管理员和成员识别。

![钉钉开发者平台中创建企业内部应用](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/99ce2f16ae9d4fd41013ac64b20ff5be49cd95f2184356a5eb1aa2a3bc27264e/assets/aivis/dingtalk-bot/dingtalk-create-app.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260805%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260805T130311Z&X-Amz-Expires=604800&X-Amz-Signature=754a2c90362e2141e3a7ecfc82485c65c114905d6b4ebe044cf08dac117d9727&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

创建后进入应用详情页，确认当前应用属于预期企业或组织，并继续配置凭证、机器人能力和版本发布。

## 配置应用凭证

在钉钉应用详情页复制 `Client ID` 和 `Client Secret`。返回艾维斯机器人配置页面，将它们分别填入“客户端 ID”和“客户端密钥”，并确认接入方式选择 `Stream`。

![钉钉开发者平台应用详情页展示 Client ID 和 Client Secret](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/d3e62adf9ed0d5243f2ff7c1af4d3dd9205954241e4e6c11714ea3fd19369307/assets/aivis/dingtalk-bot/dingtalk-client-credentials.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260805%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260805T130311Z&X-Amz-Expires=604800&X-Amz-Signature=c3f9c805a490d91b39a889e35f1cd1027e7595dd5e65478eb475aa49a47e38b5&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

![艾维斯机器人配置页面选择 Stream 方式并填写钉钉凭证](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/2a7df6b77cfe05ed494bedcd1a3ab513d9b95dcc92862f652f6dcdbfc651d10a/assets/aivis/dingtalk-bot/aivis-dingtalk-stream-config.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260805%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260805T130311Z&X-Amz-Expires=604800&X-Amz-Signature=749c4f1db77f5bbfeb08210b5c8494f49a6cd86a0189a612e63016fa7f584404&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

| 钉钉开发者平台         | 艾维斯配置字段       | 说明                   |
| --------------- | ------------- | -------------------- |
| `Client ID`     | 客户端 ID        | 标识当前钉钉企业内部应用。        |
| `Client Secret` | 客户端密钥         | 用于应用鉴权和建立 Stream 连接。 |
| 消息接收模式 `Stream` | 接入方式 `Stream` | 两侧必须保持一致。            |

配置时请注意：

* `Client ID` 与 `Client Secret` 必须来自同一个钉钉应用。
* 不要把企业 ID、机器人名称、用户 ID 或手机号填入“客户端 ID”。
* 如果重新生成了 `Client Secret`，需要同步更新艾维斯配置；否则机器人可能无法建立连接。
* 如果页面提示已保存且没有更换密钥，可以保持密钥字段为空。

## 添加机器人能力

在钉钉开发者平台中点击“添加应用能力”，选择并添加“机器人”能力。

![钉钉开发者平台为应用添加机器人能力](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/064b9fb62fd56eb32ab12cbe4fd7d42a7f55ab588d402f32364759ba9ffaaf65/assets/aivis/dingtalk-bot/dingtalk-add-bot-capability.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260805%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260805T130311Z&X-Amz-Expires=604800&X-Amz-Signature=b855fcd6ff2fb35b3a9fcca889ef642ce8879ef04122e3e9a3dc4aaa78920d88&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

进入机器人配置页，将消息接收模式设置为 `Stream`，然后保存并发布机器人配置。

![钉钉机器人配置页将消息接收模式设置为 Stream](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/fc83725e6f2032606e540f8e723b15f333fa0573093f9a8065b734b51dc4136a/assets/aivis/dingtalk-bot/dingtalk-bot-stream-mode.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260805%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260805T130311Z&X-Amz-Expires=604800&X-Amz-Signature=595746d22d3d30b6a084e3ed734b6de38796be8d427804e2988fb6c93c76c744&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

如果钉钉页面提示机器人配置尚未发布，后续即使艾维斯侧凭证已保存，钉钉侧也可能不会推送消息。

## 配置事件订阅

添加事件订阅时，推荐选择 `Stream` 模式，并保持与艾维斯机器人配置页面中的接入方式一致。完成配置后，点击“已完成接入”，验证连接通道；验证通过后点击“保存”。

![钉钉开发者平台配置事件订阅并验证 Stream 连接通道](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/b9477407e6e5e8860420911bfa389807069f31e7d1b997d24c0ddd3e616cdd9e/assets/aivis/dingtalk-bot/dingtalk-event-subscription-stream.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260805%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260805T130311Z&X-Amz-Expires=604800&X-Amz-Signature=90cfb09a5f93ff3be74cfe4e5e27adc6e53db045f05b41fdc0400f8d18d33735&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

事件订阅和应用版本发布是两项独立检查。事件订阅已保存但版本未发布，或版本已发布但 Stream 连接验证失败，都可能导致机器人无法收到消息。

## 创建版本并发布

打开“版本管理”，提交并发布最新版本。发布完成后检查：

* 版本状态正常或已发布。
* 当前机器人能力已包含在版本中。
* 可用范围符合预期，例如仅部分成员、指定部门或指定企业范围可用。
* 最近修改已经发布，不存在待发布配置。

![钉钉开发者平台发布应用版本](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/cb62d15bde5f0ea715a6dd8abe7569a275347696eaea0eb0df46edd7ede4120e/assets/aivis/dingtalk-bot/dingtalk-release-version.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260805%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260805T130311Z&X-Amz-Expires=604800&X-Amz-Signature=790f817ce781d7064348731f8f54c66ab7392c54a56e39905ff52d8f1698f2cb&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

## 测试钉钉机器人

测试前，请先在艾维斯机器人配置页确认：

1. 机器人开关为已启用。
2. 接入方式为 `Stream`。
3. `Client ID` 和 `Client Secret` 已保存。
4. 绑定的 Agent、知识范围和工具范围符合当前测试场景。
5. 钉钉侧机器人能力、事件订阅和应用版本均已保存并发布。

然后在钉钉中搜索刚创建的机器人，打开会话后发送测试消息。配置正确时，机器人应能收到消息并返回回复；实际响应时间取决于网络、模型调用和后端处理耗时。

![钉钉客户端中搜索刚创建的机器人](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/2213516ba8ea0e74a820788a942c3d942863ee7d50a7309ed71baa808bb142eb/assets/aivis/dingtalk-bot/dingtalk-search-bot.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260805%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260805T130311Z&X-Amz-Expires=604800&X-Amz-Signature=20b37a6bd7e2e82fc6919fa0bbf1fd80f998d4d32a1f95f22075cedf6a20bcc2&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

![钉钉机器人消息收发测试成功](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/e3c36ce52722a32f77941de8f7d6f20fced9fa3550b5bc4eb704c6e90827c045/assets/aivis/dingtalk-bot/dingtalk-bot-test.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260805%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260805T130311Z&X-Amz-Expires=604800&X-Amz-Signature=2be16183a13a621d2a6575f0742979d546e072826e8a947f7a4d9e83839612f1&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

## 验证访问边界

完成基础回复测试后，再验证治理边界：

1. 使用授权成员发送一个应当能回答的问题，确认机器人返回正确内容。
2. 使用未授权成员、未授权群或无权访问文档集的问题进行测试，确认机器人不会返回敏感数据。
3. 在追踪或请求日志中确认来源平台、用户上下文、绑定 Agent、响应结果和错误信息可审计。
4. 更换 `Client Secret`、接入方式、事件订阅、机器人能力或可用范围后，重新发布钉钉版本并重复测试。

## 常见问题排查

| 现象                 | 优先检查项                                                                  |
| ------------------ | ---------------------------------------------------------------------- |
| 艾维斯无法建立钉钉连接        | `Client ID` 与 `Client Secret` 是否来自同一应用，接入方式是否为 `Stream`，密钥是否被重新生成后未同步。 |
| 钉钉能发送消息，但艾维斯没有收到日志 | 机器人能力是否已添加，事件订阅是否保存，Stream 通道是否验证通过，最新版本是否已发布。                         |
| 单聊或群聊无回复           | 机器人是否已发布到目标可用范围，当前触发方式是否与钉钉权限和机器人能力一致。                                 |
| 应用修改后仍不生效          | 是否已在版本管理中创建并发布新版本。                                                     |
| 返回无权限或资源为空         | 除 API 权限外，还需确认目标知识库、Agent、群聊或其他资源已向当前机器人授权。                            |
| HTTP 回调模式不稳定       | 钉钉 HTTP 回调对响应延迟敏感；如无特殊要求，优先切回 `Stream` 模式。                             |

## 安全与维护建议

* 仅在艾维斯配置页保存真实密钥，不把密钥写入文档、截图、工单、聊天记录或代码仓库。
* 密钥疑似泄露时，应在钉钉开发者平台重新生成，并立即同步更新艾维斯配置。
* 权限按最小可用范围申请。只需要消息自动回复时，不要额外开通通讯录、审批或管理类权限。
* 机器人长期不用时，先在艾维斯侧关闭机器人，再在钉钉开发者平台收回权限或下线应用版本。
* 生产环境建议记录每次钉钉应用版本发布的时间、发布人、变更内容和验证结果。

## 相关页面

* [智能体](/aivis/agents/agents) 介绍如何配置可被机器人调用的 Agent。
* [用户、群组与角色](/aivis/governance/users-and-groups) 介绍访问边界如何应用到成员和群组。
* [追踪](/aivis/governance/tracing) 介绍如何审计机器人请求。
* [钉钉知识连接器](/aivis/knowledge/connectors/dingtalk) 介绍如何索引钉钉知识。