ByteNoteByteNote
字

字节笔记本

2026年6月21日

hermes教程-DingTalk

#AI 前沿
API中转
¥120
每日科技简报 · 每天一篇,快速了解科技圈大事

DingTalk 设置

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

在开始设置之前，以下是大多数人最想了解的部分：Hermes 进入您的钉钉工作空间后的行为方式。

Hermes 的行为方式

上下文行为
私聊（1对1聊天）Hermes 回复每一条消息。无需 @提及。每个私聊拥有独立的会话。
群聊当您 @提及 Hermes 时，它会回复。如果没有提及，Hermes 会忽略该消息。
多用户共享群组默认情况下，Hermes 在群组内按用户隔离会话历史。同一群组中两人对话不会共享同一份记录，除非您显式禁用此功能。

钉钉中的会话模型

默认情况下：

  • 每个私聊拥有自己的会话
  • 共享群聊中的每个用户在该群组内拥有自己的会话

这由 config.yaml 控制：

yaml
group_sessions_per_user: true

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

yaml
group_sessions_per_user: false

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

前提条件

安装所需的 Python 包：

bash
pip install "hermes-agent[dingtalk]"

或单独安装：

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

步骤 1：创建钉钉应用

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

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

步骤 2：启用机器人能力

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

提示

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

步骤 3：找到您的钉钉用户 ID

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

要找到您的 ID：

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

步骤 4：配置 Hermes Agent

选项 A：交互式设置（推荐）

运行引导式设置命令：

bash
hermes gateway setup

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

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

注意——openClaw 品牌披露

由于钉钉的 verification_uri_complete 在 API 层硬编码为 openClaw 身份，因此二维码当前在 openClaw 源字符串下授权，直到阿里巴巴/钉钉-Real-AI 在服务端注册一个 Hermes 特定的模板。这纯粹是钉钉展示同意屏幕的方式——您创建的机器人完全属于您，并且对您的租户私有。

选项 B：手动配置

将以下内容添加到您的 ~/.hermes/.env 文件中：

bash
## 必需
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 中的可选行为设置：

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 的替代方案；如果两者都设置，则合并

启动网关

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

bash
hermes gateway

机器人应在几秒钟内连接到钉钉的 Stream 模式。发送一条消息——无论是私聊还是已添加机器人的群组——进行测试。

提示

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

功能

AI 卡片

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

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

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

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

表情反应

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

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

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

显示设置

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

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

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

yaml
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 包。

修复：安装它：

bash
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。

流断开 / 重连循环

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

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

机器人离线

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

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

"No session_webhook available" 错误

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

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

安全

警告

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

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

备注

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

hermes教程-通过SSH/远程主机进行OAuth

下一篇

hermes教程-DingTalk

分享: