钉钉接入——国内办公必备 | Easy Understand Hermes Agent

这篇教程带你一步步把 Hermes Agent 接入钉钉，让 AI 助手在你的企业聊天窗口里随叫随到。

先搞懂：机器人进群后怎么表现？

场景	行为
私聊（1对1）	每条消息都回复，不用 @ 它
群聊	只有 @ 它才回复，否则装哑巴
多人共用的群	默认每个人有独立对话记忆，互不干扰

这个“每人独立记忆”的开关在 config.yaml 里控制：

group_sessions_per_user: true   # true=各聊各的，false=全群共享一份聊天记录

准备工作：装依赖

打开终端，执行：

cd ~/.hermes/hermes-agent && uv pip install -e ".[dingtalk]"

装不上的话，手动装这三个包也行：dingtalk-stream（钉钉官方流模式 SDK）、httpx（发消息用的 HTTP 客户端）、alibabacloud-dingtalk（钉钉开放平台 SDK，用于 AI 卡片、表情回应等）。

第1步：创建钉钉应用

打开钉钉开发者后台，用管理员账号登录。
点击 应用开发 → 企业内部应用 → 创建应用（选 H5 微应用或机器人）。
填个名字，比如 Hermes Agent，描述随意。
创建成功后，进入 凭证与基础信息，找到 Client ID（AppKey） 和 Client Secret（AppSecret），立刻复制保存——密钥只显示一次，丢了只能重新生成。

第2步：启用机器人能力

在应用设置页找到 添加能力 → 机器人，启用它。然后在 消息接收模式 里选 Stream Mode（流模式）。

为什么推荐流模式？ 它就像你家水管直接接自来水公司，不需要自己挖井（不用公网 IP、不用域名、不用配 webhook 服务器）。机器人从你电脑主动拨号连上钉钉服务器，在公司防火墙后面、家里 NAT 网络下都能跑。

第3步：找到你的钉钉 User ID

钉钉 User ID 是一串字母数字混合的字符串，由企业管理员分配。找法有两种：

问管理员：在钉钉管理后台的 通讯录 → 成员 里能看到。
自己查：启动网关后给机器人发条消息，终端日志里会打印 sender_id，那就是你的 ID。

第4步：配置 Hermes Agent

推荐用交互式配置，一条命令搞定：

hermes gateway setup

选择 DingTalk，然后二选一：

扫码授权（推荐）：终端会打印一个二维码，用钉钉手机版扫一下，Client ID 和 Secret 自动写入 ~/.hermes/.env，不用去开发者后台翻。
手动粘贴：把刚才复制的 Client ID、Client Secret 和允许使用的 User ID 粘进去。

小提示：扫码时钉钉授权页可能显示 openClaw 字样，这是钉钉官方模板还没适配 Hermes 导致的，不影响使用，机器人完全属于你自己的企业。

不想用向导？手动改配置文件也行。 在 ~/.hermes/.env 里加：

DINGTALK_CLIENT_ID=你的AppKey
DINGTALK_CLIENT_SECRET=你的AppSecret
DINGTALK_ALLOWED_USERS=你的UserID   # 多个用逗号分隔

可选配置（~/.hermes/config.yaml）：

gateway:
  platforms:
    dingtalk:
      extra:
        require_mention: true   # 群里必须 @ 才回复
        allowed_users:          # 白名单，只让这些人用
          - user-id-1

启动网关

hermes gateway

几秒钟内机器人就连上钉钉了。私聊或群里 @ 它试试。

加分项：AI 卡片与表情回应

AI 卡片：在 config.yaml 里配 card_template_id，回复会变成结构化卡片，支持流式刷新内容。
表情回应：机器人思考时自动加 🤔，回复完变成 🥳，处理状态一目了然。

常见问题

机器人不回复：检查机器人能力是否启用、Stream Mode 是否选中、你的 User ID 是否在白名单里。
报错 dingtalk-stream not installed：pip install dingtalk-stream httpx 补装。
报错缺少 Client ID/Secret：确认 .env 文件里两个变量都填了，然后重启网关。

总结一下：创建应用 → 启用机器人 → 拿到 User ID → 配置凭证 → 启动网关，五步搞定。流模式免公网、免域名，对国内用户特别友好。

下篇预告：消息平台接入系列还没完——下一期我们聊聊 飞书接入，同样是国内办公刚需，看看 Hermes 在飞书里又有什么新玩法。