钉钉设置

Hermes Agent 可作为聊天机器人集成到钉钉（DingTalk），让你通过单聊或群聊与 AI 助手对话。机器人通过钉钉的 Stream Mode（流模式）连接——一种长连接 WebSocket，无需公网 URL 或 webhook 服务器——并通过钉钉的 session webhook API 以 markdown 格式回复消息。

在开始设置之前，先了解大多数人最关心的内容：Hermes 进入你的钉钉工作空间后的行为方式。

Hermes 的行为方式

场景	行为
单聊（1:1 对话）	Hermes 响应每条消息，无需 `@提及`，每个单聊有独立会话。
群聊	Hermes 仅在被 `@提及` 时响应，未被提及则忽略消息。
多用户共享群聊	默认情况下，Hermes 在群内按用户隔离会话历史。同一群中的两个用户不共享同一对话记录，除非你明确禁用该功能。

钉钉中的会话模型

默认情况下：

每个单聊有独立会话

共享群聊中的每个用户在该群内有独立会话

通过 config.yaml 控制：

仅当你明确希望整个群共享一个对话时，才将其设为 false：

本指南将带你完成完整的设置流程——从创建钉钉机器人到发送第一条消息。

前置条件

安装所需的 Python 包：

或单独安装：

dingtalk-stream — 钉钉官方 Stream Mode SDK（基于 WebSocket 的实时消息）

httpx — 异步 HTTP 客户端，用于通过 session webhook 发送回复

alibabacloud-dingtalk — 钉钉 OpenAPI SDK，用于 AI 卡片、emoji 反应和媒体下载

第一步：创建钉钉应用

前往钉钉开发者控制台。

使用钉钉管理员账号登录。

点击应用开发 → 自建应用 → 创建 H5 微应用（或根据控制台版本选择机器人）。

填写：

应用名称：例如 Hermes Agent

描述：可选

创建完成后，进入凭证与基础信息，找到你的 Client ID（AppKey）和 Client Secret（AppSecret），复制两者。

凭证仅显示一次

Client Secret 仅在创建应用时显示一次。如果丢失，需要重新生成。切勿公开分享这些凭证或将其提交到 Git。

第二步：启用机器人能力

在应用设置页面，进入添加能力 → 机器人。

启用机器人能力。

在消息接收模式下，选择 Stream Mode（推荐——无需公网 URL）。

提示

Stream Mode 是推荐的设置方式。它使用从你的机器发起的长连接 WebSocket，无需公网 IP、域名或 webhook 端点，可在 NAT、防火墙及本地机器后正常工作。

第三步：找到你的钉钉用户 ID

Hermes Agent 使用你的钉钉用户 ID 来控制谁可以与机器人交互。钉钉用户 ID 是由组织管理员设置的字母数字字符串。

查找方式：

询问你的钉钉组织管理员——用户 ID 在钉钉管理后台的通讯录 → 成员中配置。

或者，机器人会在日志中记录每条传入消息的 sender_id。启动 gateway，向机器人发送一条消息，然后在日志中查找你的 ID。

第四步：配置 Hermes Agent

方式 A：交互式设置（推荐）

运行引导式设置命令：

在提示时选择 DingTalk。设置向导支持两种授权路径：

二维码设备流（推荐）。 用钉钉手机 App 扫描终端中打印的二维码——Client ID 和 Client Secret 将自动返回并写入 ~/.hermes/.env，无需前往开发者控制台。

手动粘贴。 如果你已有凭证（或扫码不方便），在提示时粘贴你的 Client ID、Client Secret 和允许的用户 ID。

openClaw 品牌披露

由于钉钉的 verification_uri_complete 在 API 层硬编码为 openClaw 身份，在 Alibaba / DingTalk-Real-AI 在服务端注册 Hermes 专属模板之前，二维码目前以 openClaw 来源字符串进行授权。这仅是钉钉呈现授权界面的方式——你创建的机器人完全属于你，且对你的租户私有。

方式 B：手动配置

在 ~/.hermes/.env 文件中添加以下内容：

~/.hermes/config.yaml 中的可选行为设置：

group_sessions_per_user: true 在共享群聊中保持每个参与者的上下文隔离

require_mention: true 防止机器人响应每条群消息——仅在有人 @提及时才回答

dingtalk.extra 下的 allowed_users 是 DINGTALK_ALLOWED_USERS 的替代方式；若两者同时设置，则合并生效

启动 Gateway

配置完成后，启动钉钉 gateway：

机器人应在几秒内连接到钉钉的 Stream Mode。发送一条消息——单聊或已添加机器人的群聊均可——进行测试。

提示

你可以在后台运行 hermes gateway，或将其配置为 systemd 服务以持续运行。详见部署文档。

功能特性

AI 卡片

Hermes 可以使用钉钉 AI 卡片代替纯 markdown 消息进行回复。卡片提供更丰富、更结构化的展示，并支持在 agent 生成响应时进行流式更新。

要启用 AI 卡片，在 config.yaml 中配置卡片模板 ID：

你可以在钉钉开发者控制台的应用 AI 卡片设置中找到卡片模板 ID。启用 AI 卡片后，所有回复均以带流式文本更新的卡片形式发送。

Emoji 反应

Hermes 会自动在你的消息上添加 emoji 反应以显示处理状态：

🤔Thinking — 机器人开始处理你的消息时添加

🥳Done — 响应完成时添加（替换 Thinking 反应）

这些反应在单聊和群聊中均有效。

显示设置

你可以独立于其他平台自定义钉钉的显示行为：

若要禁用工具进度和中间消息以获得更简洁的体验：

故障排查

机器人不响应消息

原因：机器人能力未启用，或 DINGTALK_ALLOWED_USERS 中不包含你的用户 ID。

解决方法：确认应用设置中已启用机器人能力且已选择 Stream Mode。检查你的用户 ID 是否在 DINGTALK_ALLOWED_USERS 中。重启 gateway。

"dingtalk-stream not installed" 错误

原因：Python 包 dingtalk-stream 未安装。

解决方法：安装它：

"DINGTALK_CLIENT_ID and DINGTALK_CLIENT_SECRET required"

原因：凭证未在环境变量或 .env 文件中设置。

解决方法：确认 DINGTALK_CLIENT_ID 和 DINGTALK_CLIENT_SECRET 已在 ~/.hermes/.env 中正确设置。Client ID 是你的 AppKey，Client Secret 是钉钉开发者控制台中的 AppSecret。

Stream 断开 / 重连循环

原因：网络不稳定、钉钉平台维护或凭证问题。

解决方法：适配器会以指数退避（2s → 5s → 10s → 30s → 60s）自动重连。检查凭证是否有效，以及应用是否未被停用。确认你的网络允许出站 WebSocket 连接。

机器人离线

原因：Hermes gateway 未运行，或连接失败。

解决方法：检查 hermes gateway 是否正在运行。查看终端输出中的错误信息。常见问题：凭证错误、应用被停用、dingtalk-stream 或 httpx 未安装。

"No session_webhook available"

原因：机器人尝试回复但没有 session webhook URL。通常发生在 webhook 过期或机器人在收到消息和发送回复之间重启的情况下。

解决方法：向机器人发送一条新消息——每条传入消息都会提供一个新的 session webhook 用于回复。这是钉钉的正常限制；机器人只能回复最近收到的消息。

安全

警告

务必设置 DINGTALK_ALLOWED_USERS 以限制可与机器人交互的用户。若未设置，gateway 默认拒绝所有用户作为安全措施。只添加你信任的人的用户 ID——已授权用户对 agent 的全部能力拥有完整访问权限，包括工具使用和系统访问。

有关保护 Hermes Agent 部署的更多信息，请参阅安全指南。

注意事项

Stream Mode：无需公网 URL、域名或 webhook 服务器。连接由你的机器通过 WebSocket 发起，可在 NAT 和防火墙后正常工作。

AI 卡片：可选择使用富文本 AI 卡片代替纯 markdown 回复。通过 card_template_id 配置。

Emoji 反应：自动添加 🤔Thinking/🥳Done 反应以显示处理状态。

Markdown 响应：回复以钉钉 markdown 格式呈现，支持富文本展示。

媒体支持：传入消息中的图片和文件会自动解析，可由视觉工具处理。

消息去重：适配器在 5 分钟窗口内对消息进行去重，防止同一消息被处理两次。

自动重连：若 stream 连接断开，适配器会以指数退避自动重连。

消息长度限制：每条消息的响应上限为 20,000 个字符，超出部分将被截断。

"DingTalk"

钉钉设置#

Hermes 的行为方式#

钉钉中的会话模型#

前置条件#

第一步：创建钉钉应用#

第二步：启用机器人能力#

第三步：找到你的钉钉用户 ID#

第四步：配置 Hermes Agent#

方式 A：交互式设置（推荐）#

方式 B：手动配置#

启动 Gateway#

功能特性#

AI 卡片#

Emoji 反应#

显示设置#

故障排查#

机器人不响应消息#

"dingtalk-stream not installed" 错误#

"DINGTALK_CLIENT_ID and DINGTALK_CLIENT_SECRET required"#

Stream 断开 / 重连循环#

机器人离线#

"No session_webhook available"#

安全#

注意事项#

钉钉设置

Hermes 的行为方式

钉钉中的会话模型

前置条件

第一步：创建钉钉应用

第二步：启用机器人能力

第三步：找到你的钉钉用户 ID

第四步：配置 Hermes Agent

方式 A：交互式设置（推荐）

方式 B：手动配置

启动 Gateway

功能特性

AI 卡片

Emoji 反应

显示设置

故障排查

机器人不响应消息

"dingtalk-stream not installed" 错误

"DINGTALK_CLIENT_ID and DINGTALK_CLIENT_SECRET required"

Stream 断开 / 重连循环

机器人离线

"No session_webhook available"

安全

注意事项