DingTalk

Hermes Agent 可作为聊天机器人接入 DingTalk（钉钉），让你通过私聊或群聊与 AI 助手对话。它通过 DingTalk 的 Stream Mode 建立长连接 WebSocket，无需公网 URL 或 webhook 服务，并通过 DingTalk 的 session webhook API 以 Markdown 格式回复消息。

Hermes 的行为方式

Context	Behavior
DMs (1:1 chat)	Hermes 会回复每一条消息，无需 `@mention`。每个私聊都有独立会话。
Group chats	只有当你 `@mention` Hermes 时它才会回复；未提及时会忽略该消息。
Shared groups with multiple users	默认按用户隔离同一群里的会话历史。

DingTalk 中的会话模型

默认情况下：

每个私聊拥有自己的独立会话
共享群聊中，每个用户在群内也拥有自己的独立会话

这一行为由 config.yaml 控制：

group_sessions_per_user: true

如果你明确希望整个群共用同一段对话，可设为：

group_sessions_per_user: false

前提条件

安装所需 Python 包：

pip install "hermes-agent[dingtalk]"

或者单独安装：

pip install dingtalk-stream httpx alibabacloud-dingtalk

dingtalk-stream：DingTalk 官方 Stream Mode SDK
httpx：通过 session webhook 发送回复时使用的异步 HTTP 客户端
alibabacloud-dingtalk：用于 AI Cards、emoji reactions 和媒体下载的 DingTalk OpenAPI SDK

第 1 步：创建 DingTalk App

打开 DingTalk Developer Console
使用 DingTalk 管理员账号登录
点击 Application Development → Custom Apps → Create App via H5 Micro-App（或某些版本控制台中的 Robot）
填写应用名称与描述
创建后进入 Credentials & Basic Info，记录 Client ID（AppKey）与 Client Secret（AppSecret）

凭据只展示一次

Client Secret 通常只会在创建时展示一次。若遗失，需要重新生成。不要公开分享这些凭据，也不要提交到 Git。

第 2 步：启用 Robot 能力

在应用设置页进入 Add Capability → Robot
启用机器人能力
在 Message Reception Mode 中选择 Stream Mode（推荐，无需公网 URL）

提示

Stream Mode 是推荐方式。它由你的机器主动发起 WebSocket 长连接，因此无需公网 IP、域名或 webhook，适合 NAT、防火墙之后或本地开发环境。

第 3 步：找到你的 DingTalk User ID

Hermes Agent 使用 DingTalk User ID 控制谁可以与 bot 交互。这个 ID 通常是由组织管理员设置的字母数字字符串。

获取方式：

直接询问你们组织的 DingTalk 管理员。管理员可在 Contacts → Members 中查看
也可以先启动网关，给 bot 发一条消息，然后从日志中查看记录下来的 sender_id

第 4 步：配置 Hermes Agent

Option A: Interactive Setup (Recommended)

hermes gateway setup

选择 DingTalk 后，向导支持两种授权路径：

二维码设备流（推荐）：使用 DingTalk 手机端扫描终端中的二维码，Client ID 与 Client Secret 会自动回填并写入 ~/.hermes/.env
手动粘贴：如果你已准备好凭据，也可以直接手动输入 Client ID、Client Secret 和允许的用户 ID

openClaw branding disclosure

由于 DingTalk 的 verification_uri_complete 目前仍在 API 层硬编码为 openClaw 身份，因此二维码授权界面可能显示为 openClaw 来源，直到 Alibaba / DingTalk-Real-AI 在服务端注册 Hermes 专属模板。这只影响授权页展示，不影响你创建的 bot 归属和私有性。

Option B: Manual Configuration

把以下内容加入 ~/.hermes/.env：

# Required
DINGTALK_CLIENT_ID=your-app-key
DINGTALK_CLIENT_SECRET=your-app-secret

# Security: restrict who can interact with the bot
DINGTALK_ALLOWED_USERS=user-id-1

# Multiple allowed users (comma-separated)
# DINGTALK_ALLOWED_USERS=user-id-1,user-id-2

可选行为配置写到 ~/.hermes/config.yaml：

group_sessions_per_user: true

Start the Gateway

hermes gateway

几秒内 bot 就会连上 DingTalk Stream Mode。你可以发一条私聊消息，或者把它加到群里后进行测试。

功能

AI Cards

Hermes 可以使用 DingTalk AI Cards，而不是普通 Markdown 消息回复。AI Cards 展示更丰富，也支持在生成过程中进行流式更新。

在 config.yaml 中配置 card template ID 即可启用：

platforms:
  dingtalk:
    enabled: true
    extra:
      card_template_id: "your-card-template-id"

Emoji Reactions

Hermes 会自动给你的消息添加表情反馈，以表示处理状态：

🤔Thinking：开始处理时添加
🥳Done：处理完成后替换 Thinking reaction

Display Settings

你可以为 DingTalk 单独配置显示行为：

display:
  platforms:
    dingtalk:
      show_reasoning: false
      streaming: true
      tool_progress: all
      interim_assistant_messages: true

如果你想获得更简洁的体验：

display:
  platforms:
    dingtalk:
      tool_progress: off
      interim_assistant_messages: false

Troubleshooting

Bot 不响应消息

原因：未启用 robot 能力，或 DINGTALK_ALLOWED_USERS 中没有你的 User ID。

修复：确认 app 已启用 robot，并且使用的是 Stream Mode；检查 DINGTALK_ALLOWED_USERS；然后重启网关。

出现 “dingtalk-stream not installed”

原因：缺少 dingtalk-stream Python 包。

修复：

pip install dingtalk-stream httpx

出现 “DINGTALK_CLIENT_ID and DINGTALK_CLIENT_SECRET required”

原因：环境变量或 .env 未正确设置。

修复：确认 ~/.hermes/.env 中的 DINGTALK_CLIENT_ID 与 DINGTALK_CLIENT_SECRET 正确无误。

Stream 反复断线 / 重连循环

原因：网络不稳定、DingTalk 平台维护，或凭据异常。

修复：适配器会自动按 2s → 5s → 10s → 30s → 60s 的节奏退避重连；同时检查凭据是否有效，以及网络是否允许出站 WebSocket。

Bot 显示离线

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

修复：检查 hermes gateway 是否在运行，并查看终端错误输出。常见问题包括凭据错误、应用被停用，或缺少 dingtalk-stream / httpx。

“No session_webhook available”

原因：bot 尝试回复时没有可用 session webhook URL。通常是 webhook 已过期，或在收到消息后、发送回复前 bot 被重启。

修复：重新给 bot 发一条消息。每条入站消息都会带来新的 session webhook，这属于 DingTalk 的平台限制。

Security

注意

务必设置 DINGTALK_ALLOWED_USERS 来限制谁可以与 bot 交互。否则，出于安全考虑，网关默认会拒绝所有用户。只应授权你信任的人，因为被授权用户拥有 agent 的全部能力，包括工具调用和系统访问。

更多部署安全信息，请参见 Security Guide。

Notes

Stream Mode：无需公网 URL、域名或 webhook 服务
AI Cards：可选的富文本卡片回复方式
Emoji Reactions：自动显示 🤔Thinking / 🥳Done
Markdown responses：回复使用 DingTalk 的 Markdown 格式
Media support：入站图片和文件会自动解析，可供视觉类工具处理
Message deduplication：5 分钟窗口内对消息去重
Auto-reconnection：流连接掉线后自动退避重连
Message length limit：单条消息最长 20,000 字符，超出会被截断

Hermes 的行为方式​

DingTalk 中的会话模型​

前提条件​

第 1 步：创建 DingTalk App​

第 2 步：启用 Robot 能力​

第 3 步：找到你的 DingTalk User ID​

第 4 步：配置 Hermes Agent​

Option A: Interactive Setup (Recommended)​

Option B: Manual Configuration​

Start the Gateway​

功能​

AI Cards​

Emoji Reactions​

Display Settings​

Troubleshooting​

Bot 不响应消息​

出现 “dingtalk-stream not installed”​

出现 “DINGTALK_CLIENT_ID and DINGTALK_CLIENT_SECRET required”​

Stream 反复断线 / 重连循环​

Bot 显示离线​

“No session_webhook available”​

Security​

Notes​