钉钉配置

Hermes Agent 可作为聊天机器人与钉钉（DingTalk）集成，让您通过私信或群聊与 AI 助手交流。机器人通过钉钉的 Stream 模式连接 —— 这是一种长连接 WebSocket，无需公网 URL 或 Webhook 服务器 —— 并通过钉钉的 session webhook API 以 Markdown 格式回复消息。

在配置之前，先了解大多数人最想知道的内容：Hermes 在您的钉钉工作区中的行为方式。

Hermes 行为说明

场景	行为
私信（1:1 聊天）	Hermes 响应所有消息，无需 `@提及`，每个私信拥有独立会话。
群聊	Hermes 仅在被 `@提及` 时响应，未提及时忽略消息。
多人共享群聊	默认情况下，Hermes 在同一群组内为每位用户隔离会话历史。除非您明确禁用此功能，否则两个人在同一群里交谈不会共享聊天记录。

钉钉的会话模型

默认情况下：

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

通过 config.yaml 控制：

group_sessions_per_user: true

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

group_sessions_per_user: false

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

前置条件

安装所需的 Python 包：

pip install "hermes-agent[dingtalk]"

或单独安装：

pip install dingtalk-stream httpx alibabacloud-dingtalk

dingtalk-stream — 钉钉 Stream 模式的官方 SDK（基于 WebSocket 的实时消息）
httpx — 通过 session webhook 发送回复的异步 HTTP 客户端
alibabacloud-dingtalk — 钉钉 OpenAPI SDK，用于 AI 卡片、表情反应和媒体下载

第一步：创建钉钉应用

前往钉钉开发者控制台。
使用钉钉管理员账号登录。
点击应用开发 → 企业内部应用 → 创建应用（H5 微应用或机器人，具体选项因控制台版本而异）。
填写：
- 应用名称：例如 Hermes Agent
- 描述：可选
创建后，进入凭据与基础信息，找到 Client ID（AppKey）和 Client Secret（AppSecret），分别复制。

凭据仅显示一次

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

第二步：启用机器人能力

在应用设置页面，转到添加应用能力 → 机器人。
启用机器人能力。
在消息接收模式下，选择 Stream 模式（推荐 —— 无需公网 URL）。

提示

Stream 模式是推荐的配置方式。它使用从您的机器主动发起的长连接 WebSocket，无需公网 IP、域名或 Webhook 端点，即可在 NAT、防火墙和本地机器上正常工作。

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

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

查找方法：

询问您的钉钉组织管理员 —— 用户 ID 在钉钉管理控制台的通讯录 → 成员中配置。
或者，机器人会在日志中记录每条传入消息的 sender_id。启动网关，向机器人发送消息，然后在日志中查看您的 ID。

第四步：配置 Hermes Agent

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

运行引导式配置命令：

hermes gateway setup

出现提示时选择 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 文件中添加以下内容：

# 必填
DINGTALK_CLIENT_ID=your-app-key
DINGTALK_CLIENT_SECRET=your-app-secret

# 安全：限制可与机器人交互的用户
DINGTALK_ALLOWED_USERS=user-id-1

# 多个允许的用户（逗号分隔）
# DINGTALK_ALLOWED_USERS=user-id-1,user-id-2

# 可选：群聊访问控制（与 Slack/Telegram/Discord/WhatsApp 一致）
# DINGTALK_REQUIRE_MENTION=true
# DINGTALK_FREE_RESPONSE_CHATS=cidABC==,cidDEF==
# DINGTALK_MENTION_PATTERNS=^小马
# DINGTALK_HOME_CHANNEL=cidXXXX==
# DINGTALK_ALLOW_ALL_USERS=true

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

group_sessions_per_user: true

gateway:
  platforms:
    dingtalk:
      extra:
        # 在群组中需要 @提及 后机器人才回复（与 Slack/Telegram/Discord 保持一致）。
        # 私信忽略此设置 —— 机器人在 1:1 聊天中始终回复。
        require_mention: true

        # 平台级别允许列表。设置后，只有这些钉钉用户 ID 才能与机器人交互
        # （与 DINGTALK_ALLOWED_USERS 语义相同，但在此处配置而非 .env 中）。
        allowed_users:
          - user-id-1
          - user-id-2

group_sessions_per_user: true 在共享群聊中保持每个参与者的上下文隔离
require_mention: true 防止机器人响应每条群消息 —— 仅在被 @提及时才回答
dingtalk.extra 下的 allowed_users 是 DINGTALK_ALLOWED_USERS 的替代方式；若两者同时设置，则取并集

启动网关

配置完成后，启动钉钉网关：

hermes gateway

机器人应在几秒钟内连接到钉钉 Stream 模式。向它发送一条消息（私信或在已添加机器人的群组中）进行测试。

提示

您可以在后台运行 hermes gateway 或作为 systemd 服务持续运行。详情请参阅部署文档。

功能特性

AI 卡片

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

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

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

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

表情反应

Hermes 会自动为您的消息添加表情反应以显示处理状态：

🤔Thinking —— 机器人开始处理您的消息时添加
🥳Done —— 响应完成时添加（替换 Thinking 反应）

这些反应在私信和群聊中均可使用。

显示设置

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

display:
  platforms:
    dingtalk:
      show_reasoning: false   # 在回复中显示模型推理/思考过程
      streaming: true         # 启用流式响应（配合 AI 卡片使用）
      tool_progress: all      # 显示工具执行进度（all/new/off）
      interim_assistant_messages: true  # 显示中间注释消息

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

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

故障排查

机器人不响应消息

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

解决方案：验证应用设置中已启用机器人能力并选择了 Stream 模式，确认您的用户 ID 在 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 设置是否正确。Client ID 是您的 AppKey，Client Secret 是钉钉开发者控制台中的 AppSecret。

Stream 断连 / 重连循环

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

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

机器人离线

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

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

"No session_webhook available"

原因：机器人尝试回复但没有 session webhook URL。通常发生在 Webhook 已过期或机器人在接收消息后重启的情况下。

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

安全性

注意

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

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

说明

Stream 模式：无需公网 URL、域名或 Webhook 服务器。连接通过 WebSocket 从您的机器主动发起，可在 NAT 和防火墙后面正常工作。
AI 卡片：可选择使用富 AI 卡片而非纯 Markdown 进行回复，通过 card_template_id 配置。
表情反应：自动的 🤔Thinking/🥳Done 反应显示处理状态。
Markdown 响应：回复以钉钉的 Markdown 格式呈现，支持富文本显示。
媒体支持：传入消息中的图片和文件会被自动解析，可由视觉工具处理。
消息去重：适配器在 5 分钟窗口内对消息进行去重，防止重复处理同一消息。
自动重连：Stream 连接断开时，适配器会以指数退避自动重连。
消息长度限制：每条消息的响应上限为 20,000 个字符，超出部分将被截断。

Hermes 行为说明​

钉钉的会话模型​

前置条件​

第一步：创建钉钉应用​

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

第三步：找到您的钉钉用户 ID​

第四步：配置 Hermes Agent​

方式 A：交互式配置（推荐）​

方式 B：手动配置​

启动网关​

功能特性​

AI 卡片​

表情反应​

显示设置​

故障排查​

机器人不响应消息​

"dingtalk-stream not installed" 错误​

"DINGTALK_CLIENT_ID and DINGTALK_CLIENT_SECRET required"​

Stream 断连 / 重连循环​

机器人离线​

"No session_webhook available"​

安全性​

说明​