Hermes Agent 接入钉钉

准备工作

• 一个能登录 钉钉开放平台 的账号（要绑定公司主体的钉钉）
• 已经在跑的 Hermes Agent（先看 安装指南）
• 选 Stream 模式：不需要公网；选 HTTP 模式：需要一个公网 HTTPS URL

第一步：在钉钉开放平台建企业内部应用

1. 访问 open-dev.dingtalk.com/fe/app → 创建 H5 微应用 → 填名字。
2. 进入应用详情页 → 凭证与基础信息：记下 AppKey 和 AppSecret。
3. 左侧“应用能力” → “机器人” → 启用机器人能力 → 填机器人名字、头像。

第二步：选 Stream 模式还是 HTTP 模式

钉钉机器人有两种消息接收方式：

• Stream 模式（推荐）：Hermes 主动连钉钉的长连接服务器，钉钉把消息推过来。不需要 Hermes 暴露公网地址，配置简单。
• HTTP 模式：钉钉把消息 POST 到你填的回调 URL。需要 Hermes 有公网 HTTPS 地址，但延迟稍低。

Stream 模式适合大多数场景。如果你的 Hermes 部署在内网或者不想配公网域名，必选 Stream。

第三步（Stream 模式）：hermes.json 配置

{
  "channels": {
    "dingtalk": {
      "enabled": true,
      "mode": "stream",
      "appKey": "dingxxxxxxxxxxx",
      "appSecret": "${DINGTALK_APP_SECRET}",
      "robotCode": "ding_robot_xxx",
      "dmPolicy": "pairing"
    }
  },
  "plugins": {
    "entries": {
      "dingtalk": { "enabled": true }
    }
  }
}

robotCode 在“机器人能力”页面能看到，类似 ding_xxx。Stream 模式不需要回调 URL。

第三步（HTTP 模式）：填回调地址

1. 钉钉开放平台 → 应用详情 → 事件订阅。
2. 消息接收模式选 HTTP，回调 URL 填 https://你的-hermes-域名/dingtalk/events。
3. 订阅事件勾“机器人接收消息”。
4. 钉钉会立刻发一个验证请求，Hermes 配好后会自动响应“已验证”。

hermes.json 里 mode 改成 "http"：

"channels": {
  "dingtalk": {
    "mode": "http",
    "callbackPath": "/dingtalk/events",
    ...
  }
}

第四步：发布应用 + 安装到企业

1. 应用详情顶部 → 版本管理 → 创建版本（1.0.0）→ 提交审核。
2. 企业内部应用一般由企业管理员审核，几分钟到一天。
3. 审核通过后，管理员在“管理后台”给指定部门或人员授权使用。
4. 授权完成后，同事可以把机器人拉进群（搜机器人名字）或者直接私聊。

测试

• 把机器人拉进测试群，群里 @ 它：@MyBot 你好
• 私聊机器人（dmPolicy: "pairing" 时需先配对）
• 看 docker logs hermes 2>&1 | grep -i dingtalk 确认消息进来

常见报错

Stream 模式连不上

• AppKey 或 AppSecret 错了 —— 钉钉开放平台“凭证与基础信息”复制时容易带空格
• 容器出口 IP 没加白名单 —— 钉钉对 Stream 长连接没要求，但 HTTP API 调用（比如发消息）需要在“开发管理”里加 IP 白名单
• 容器在 NAT 后面但出口 IP 频繁变化 —— 加白名单要写实际出口 IP

事件订阅一直“未验证”（HTTP 模式）

• Hermes 没在公网 —— 钉钉访问不到 /dingtalk/events
• 没配 HTTPS —— 钉钉只认 HTTPS 真实证书
• 路径写错了 —— Hermes 的钉钉回调路径是 /dingtalk/events，不是 /api/dingtalk

消息能收到但机器人不回

• plugins.entries.dingtalk.enabled 没设 true
• OPENROUTER_API_KEY 或者其他模型 provider 没配好
• robotCode 漏填或填错 —— Hermes 不知道用哪个机器人发消息

回复消息报 forbidden / robot not allowed

机器人没有发消息权限。“应用能力” → “机器人” → 检查“消息推送”有没有开。开了之后必须重新发布一个版本，旧版本不生效。

群机器人 vs 应用机器人

钉钉里“自定义机器人”（群机器人）和“企业内部应用机器人”是两种不同东西：

• 群机器人：每个群单独建，只能在那个群用，不需要审核。Hermes 不直接支持群机器人，因为它没有事件回调。
• 企业内部应用机器人：本文讲的。一次配好整个企业都能用，支持事件回调和私聊。

如果你只想在一个群里用、且只需要发主动通知（比如 cron 推送报警），可以用群机器人 + Hermes 的 webhook 触发器。如果要双向对话，必须走应用机器人。

托管版：OpenClaw Launch

钉钉开放平台审核流程、IP 白名单、Stream 模式连接维护、AppSecret 安全存储 —— 自己搭都得管。 OpenClaw Launch 托管版直接提供 Hermes 的钉钉渠道，在 Dashboard 填 AppKey / AppSecret / RobotCode 就跑。首月 $3，之后 $6/月。

下一步

• Hermes Agent 中文介绍
• 接入飞书
• 接入微信
• OpenClaw 接入钉钉