DingTalk 设置

Hermes Agent 以聊天机器人形式集成 DingTalk（钉钉），让您通过私聊或群聊与 AI 助手交流。机器人通过钉钉的 Stream 模式连接——这是一种长连接 WebSocket，无需公共 URL 或 webhook 服务器——并通过钉钉的会话 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 Mode SDK（基于 WebSocket 的实时消息通信）
httpx — 用于通过会话 webhook 发送回复的异步 HTTP 客户端
alibabacloud-dingtalk — 钉钉 OpenAPI SDK，用于 AI 卡片、表情反应和媒体下载

第一步：创建钉钉应用

前往钉钉开发者后台。
使用钉钉管理员账号登录。
点击 应用开发 → 自定义应用 → 创建应用（根据控制台版本选择 H5 微应用或机器人）。
填写：
- 应用名称：例如 Hermes Agent
- 描述：可选
创建完成后，进入 凭证与基础信息 查找您的 Client ID（AppKey）和 Client Secret（AppSecret）。复制两者。

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

第二步：开启机器人能力

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

:::tip Stream 模式是推荐的设置方式。它使用从您的机器发起的长连接 WebSocket，因此您不需要公共 IP、域名或 webhook 端点。这可以在 NAT、防火墙后面以及本地机器上工作。 :::

第三步：查找钉钉用户 ID

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

查找方式：

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

第四步：配置 Hermes Agent

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

运行引导式设置命令：

hermes gateway setup

按提示选择 DingTalk。设置向导可以通过以下两种方式之一授权：

二维码设备流程（推荐）。 使用钉钉手机应用扫描终端中打印的二维码——您的 Client ID 和 Client Secret 会自动返回并写入 ~/.hermes/.env。无需进入开发者后台。
手动粘贴。 如果您已有凭证（或二维码扫描不方便），按提示粘贴您的 Client ID、Client Secret 和允许的用户 ID。

:::note openClaw 品牌披露由于钉钉的 verification_uri_complete 在 API 层硬编码为 openClaw 身份，二维码目前以 openClaw 源字符串授权，直到阿里巴巴/钉钉-Real-AI 在服务端注册 Hermes 专用模板。这只是钉钉展示同意屏幕的方式——您创建的机器人完全属于您，且对您的租户私有。 :::

方式 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 模式。发送一条消息测试——可以是私聊，也可以是已添加机器人的群聊。

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

功能

AI 卡片

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

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

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

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

表情反应

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

🤔思考中——机器人在开始处理您的消息时添加
🥳完成——回复完成时添加（替换思考反应）

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

显示设置

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

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 和 DINGTALK_CLIENT_SECRET”

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

解决方法： 确认 ~/.hermes/.env 中正确设置了 DINGTALK_CLIENT_ID 和 DINGTALK_CLIENT_SECRET。Client ID 是您的 AppKey，Client Secret 是来自钉钉开发者后台的 AppSecret。

Stream 断开/重连循环

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

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

机器人离线

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

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

“无 session_webhook 可用”

原因： 机器人尝试回复但没有会话 webhook URL。这通常发生在接收到消息和发送回复之间 webhook 过期或机器人重启时。

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

安全

:::warning 始终设置 DINGTALK_ALLOWED_USERS 来限制谁可以与机器人交互。没有它，网关默认拒绝所有用户作为安全措施。只添加您信任的用户 ID——授权用户可以完全访问代理的能力，包括工具使用和系统访问。 :::

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

说明

Stream 模式： 无需公共 URL、域名或 webhook 服务器。连接通过 WebSocket 从您的机器发起，因此可以在 NAT 和防火墙后面工作。
AI 卡片： 可选择使用丰富的 AI 卡片代替纯 markdown 进行回复。通过 card_template_id 配置。
表情反应： 自动添加 🤔思考中/🥳完成反应显示处理状态。
Markdown 回复： 回复以钉钉的 markdown 格式发送，实现富文本显示。
媒体支持： 入站消息中的图片和文件会自动解析，可由视觉工具处理。
消息去重： 适配器在 5 分钟窗口内对消息去重，防止重复处理同一消息。
自动重连： 如果流连接断开，适配器使用指数退避自动重连。
消息长度限制： 每条消息的回复限制为 20,000 字符。超长回复会被截断。

好奇心花园🪴

探索

最近的笔记

note-template

getMoon.js

getWeather.js

DingTalk