Hermes Agent 接入钉钉：Stream Mode 机器人完整指南

接入后的会话行为

单聊中机器人回复每条消息；群聊默认仅在被 @ 时回复。共享群默认按发送者隔离会话，避免不同成员互相看到上下文。

# ~/.hermes/config.yaml
group_sessions_per_user: true

只有明确需要全群共享一段上下文时才设为 false；企业群中建议保持按用户隔离。

创建应用并启用机器人

在钉钉开发者后台创建企业内部应用，保存 Client ID（AppKey）和 Client Secret（AppSecret），然后添加机器人能力并选择 Stream Mode。

1. 1. 打开 https://open-dev.dingtalk.com/ 并创建应用。
2. 2. 在“凭证与基础信息”保存 Client ID 与 Client Secret。
3. 3. 添加机器人能力，将消息接收模式设为 Stream Mode。
4. 4. 从管理员后台或 Gateway 日志获取允许使用者的 DingTalk User ID。

Client Secret 不应提交到 Git、截图或聊天记录；泄露后立即在后台重新生成。

运行 Hermes 配置向导

推荐使用向导。钉钉支持二维码设备授权，也支持手工粘贴凭据。二维码流程会自动将凭据写入 `~/.hermes/.env`。

hermes gateway setup
# 手工配置时写入 ~/.hermes/.env
DINGTALK_CLIENT_ID=your-app-key
DINGTALK_CLIENT_SECRET=your-app-secret
DINGTALK_ALLOWED_USERS=user-id-1,user-id-2

启动并验证

Stream Mode 是由 Hermes 主动建立的长连接，适合本地电脑、内网服务器与 NAT 环境。

1. 1. 先给机器人发送一条单聊消息。
2. 2. 把机器人加入测试群并 @机器人。
3. 3. 确认未在 allowlist 的账号无法触发 Agent。

hermes gateway start
hermes gateway status
# WSL/systemd 不稳定时
hermes gateway run

生产配置建议

可按平台设置 require_mention、允许用户、Home Channel、AI Card 和展示策略。AI Card 支持更丰富的结构与流式更新。

DINGTALK_REQUIRE_MENTION=true
DINGTALK_HOME_CHANNEL=cidXXXX==

• 群聊保持 require_mention=true。
• 使用明确的用户 allowlist。
• Gateway 交给 systemd、launchd 或进程管理器守护。
• 先用 Markdown 回复跑通，再启用 AI Card 模板。

常见问题

提示缺少凭据时核对 AppKey/AppSecret；连接反复断开时检查网络和凭据；session webhook 过期属于钉钉限制，发送一条新消息即可获得新的回复通道。

hermes gateway status
hermes doctor