钉钉设置
Hermes Agent 与钉钉（DingTalk）集成作为聊天机器人，让您可以通过私聊或群聊与您的 AI 助手进行对话。该机器人通过钉钉的流模式（Stream Mode）连接——一种长期保持的 WebSocket 连接，无需公网 URL 或 Webhook 服务器——并通过钉钉的会话 Webhook API 以 Markdown 格式发送回复。
在设置之前，这里是最让人关心的部分：Hermes 在您的钉钉工作区中将如何表现。
Hermes 的行为表现
| 上下文 | 行为 |
|---|---|
| 私聊（1:1 聊天） | Hermes 对每条消息都作出响应。无需 @提及。每个私聊都有独立的会话。 |
| 群聊 | 当您 @提及 它时，Hermes 才会响应。未被提及的消息，Hermes 会忽略。 |
| 多人共享的群组 | 默认情况下，Hermes 在群组内为每个用户隔离会话历史。两个人在同一个群组中聊天时，不会共享同一份对话记录，除非您显式禁用此功能。 |
钉钉中的会话模型
默认情况下：
- 每个私聊拥有独立的会话
- 在共享群聊中，每个用户拥有独立的会话
这由 config.yaml 控制：
group_sessions_per_user: true
仅当您明确希望整个群组共享一个对话时，才将其设置为 false：
group_sessions_per_user: false
本指南将引导您完成完整的设置流程——从创建钉钉机器人到发送第一条消息。
先决条件
安装所需的 Python 包：
pip install dingtalk-stream httpx
dingtalk-stream—— 钉钉官方提供的流模式 SDK（基于 WebSocket 的实时消息）httpx—— 用于通过会话 Webhook 发送回复的异步 HTTP 客户端
第一步：创建钉钉应用
- 访问 钉钉开发者控制台。
- 使用您的钉钉管理员账号登录。
- 点击 应用开发 → 自建应用 → 通过 H5 小程序创建应用（或根据控制台版本选择 机器人）。
- 填写以下信息：
- 应用名称：例如
Hermes Agent - 描述：可选
- 应用名称：例如
- 创建完成后，进入 凭证与基本信息 页面，找到您的 Client ID（AppKey）和 Client Secret（AppSecret）。请复制这两项。
Client Secret 仅在创建应用时显示一次。如果丢失，您需要重新生成。请勿将这些凭证公开分享，也请勿提交到 Git。
第二步：启用机器人功能
- 在应用设置页面，点击 添加能力 → 机器人。
- 启用机器人功能。
- 在 消息接收模式 中，选择 流模式（推荐——无需公网 URL）。
流模式是推荐的配置。它使用从您的机器发起的长期 WebSocket 连接，因此无需公网 IP、域名或 Webhook 端点。该模式可在 NAT、防火墙后以及本地机器上正常工作。
第三步：查找您的钉钉用户 ID
Hermes Agent 使用您的钉钉用户 ID 来控制谁可以与机器人互动。钉钉用户 ID 是由组织管理员设置的字母数字字符串。
要查找您的用户 ID：
- 请向您的钉钉组织管理员咨询——用户 ID 在钉钉管理员控制台的 通讯录 → 成员 中配置。
- 或者，机器人会记录每条消息的
sender_id。启动网关后，向机器人发送一条消息，然后检查日志以获取您的 ID。
第四步：配置 Hermes Agent
选项 A：交互式设置（推荐）
运行引导式设置命令：
hermes gateway setup
提示时选择 DingTalk，然后粘贴您的 Client ID、Client Secret 和允许的用户 ID。
选项 B：手动配置
将以下内容添加到您的 ~/.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
group_sessions_per_user: true在共享群聊中为每位参与者保持上下文隔离
启动网关
配置完成后，启动钉钉网关：
hermes gateway
机器人应在几秒内连接到钉钉的流模式。向它发送一条消息——无论是私聊还是已添加的群聊——以进行测试。
您可以将 hermes gateway 在后台运行，或作为 systemd 服务运行以实现持久化操作。详情请参阅部署文档。
故障排除
机器人不响应消息
原因：机器人功能未启用，或 DINGTALK_ALLOWED_USERS 中未包含您的用户 ID。
解决方法：确认您的应用设置中已启用机器人功能，并选择了流模式。检查您的用户 ID 是否在 DINGTALK_ALLOWED_USERS 中。重启网关。
“dingtalk-stream 未安装” 错误
原因：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。
流连接中断 / 重连循环
原因：网络不稳定、钉钉平台维护或凭证问题。
修复方法：适配器会自动使用指数退避机制重连（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 代理部署的更多信息，请参阅 安全指南。
注意事项
- 流模式：无需公网 URL、域名或 webhook 服务器。连接由您的机器通过 WebSocket 主动发起，因此可在 NAT 和防火墙后正常工作。
- Markdown 格式回复：回复内容以钉钉的 Markdown 格式进行渲染，支持富文本显示。
- 消息去重：适配器在 5 分钟窗口内对消息进行去重，防止重复处理同一消息。
- 自动重连：若流连接中断，适配器将自动使用指数退避机制重新连接。
- 消息长度限制：每条回复最多限制为 20,000 个字符，超出部分将被截断。