Hermes agent怎么接入钉钉？完整搭建指南

Hermes Agent 是由 Nous Research 开发的“自进化”AI 智能体框架，能从任务中自动提炼技能并越用越强。接入钉钉的核心价值在于：将 AI 智能体无缝融入国内最主流的企业办公场景，让它成为团队群里 7×24 小时在线的专属 AI 员工，辅助协作、解答问题、处理任务。

本文大纲

👉 一、核心结论：官方已支持，但需手动配置

👉 二、准备工作：检查环境与安装依赖

👉 三、第一步：在钉钉开放平台创建机器人

👉 四、第二步：在 Hermes Agent 中配置钉钉渠道

👉 五、第三步：启动服务并测试连接

👉 六、常见问题与排障指南

👉 七、进阶玩法与安全建议

👉 总结

一、核心结论：官方已支持，但需手动配置

关于 Hermes Agent 能否接入钉钉，当前状态如下：

维度	状态
官方支持	✅ 已原生支持，Gateway 内置钉钉适配器
配置方式	需手动运行 hermes gateway setup 选择 DingTalk
实现难度	⭐⭐（中等，需在钉钉开放平台完成应用创建）
稳定性	⭐⭐⭐⭐（官方适配器，较稳定）

需要注意的是，钉钉渠道在一键安装脚本中并不会默认出现，只有通过 hermes gateway setup 命令手动配置才会显示。

二、准备工作：检查环境与安装依赖

在正式配置之前，建议先完成以下检查和准备。

1. 更新 Hermes Agent 至最新版本

确保你使用的是最新版本的 Hermes Agent，以获得最完整的钉钉适配支持：

hermes update

2. 检查基础环境

运行 hermes doctor 检查依赖和配置状态：

hermes doctor

确认输出中 Python、Node.js、ripgrep、ffmpeg 等核心依赖均显示 ✓。

3. 配置好大语言模型

如果尚未配置模型，请先运行：

hermes setup

按交互向导选择模型供应商（如 OpenRouter、Anthropic、OpenAI 或本地 Ollama）并完成 API Key 配置。

三、第一步：在钉钉开放平台创建机器人

这是整个流程的前半段——让钉钉知道“有这么一个机器人存在”。

1. 登录钉钉开放平台

访问钉钉开放平台：https://open.dingtalk.com/，使用你的钉钉账号登录，进入“开发者后台”。

2. 创建企业自建应用

在“应用开发”页面，选择“企业内部开发”，点击“创建应用”。填写应用名称（如“Hermes智能助手”）、应用描述和应用图标。

⚠️ 重要：创建应用时务必选择“开发模式”为“开发应用”，不要选择“快捷链接”，否则后续鉴权会失败，报“无效的agentid”错误。

3. 添加机器人能力

在应用详情页，点击“应用能力” → “机器人”，开启机器人配置。设置机器人名称和头像，点击“发布”保存。

4. 获取关键凭证

在应用详情页的“凭证与基础信息”中，记录以下信息（后续配置需要）：

• AppKey：应用的唯一标识
• AppSecret：应用的密钥，用于接口调用鉴权
• RobotCode：机器人编码（部分场景需要）

5. 配置权限

在左侧导航栏进入“权限管理”，至少添加以下权限：

• qyapi_get_member_list — 获取成员信息
• qyapi_manage_agent — 管理应用

如果希望机器人能够在群聊中接收消息，还需要在“事件与回调”中配置接收消息的回调地址（详见进阶玩法部分）。

6. 发布应用

完成配置后，在“版本管理与发布”中创建版本并提交发布。发布后，钉钉内的成员才能搜索到该机器人。

四、第二步：在 Hermes Agent 中配置钉钉渠道

钉钉侧准备就绪后，回到 Hermes Agent 完成对接。

1. 启动 Gateway 配置向导

在终端中运行以下命令，进入交互式配置流程：

hermes gateway setup

在渠道列表中使用方向键选择 DingTalk（钉钉）。

2. 填写钉钉应用凭证

按提示依次输入在钉钉开放平台获取的凭证信息：

配置项	填写说明
AppKey	填入钉钉开放平台获取的 AppKey
AppSecret	填入钉钉开放平台获取的 AppSecret
RobotCode	填入钉钉机器人的 RobotCode（如有）
CorpId	填入企业 ID（可在钉钉开放平台“首页”查看）

💡 提示：输入 AppSecret 时屏幕不会显示任何字符，直接粘贴后按回车即可。

3. 配置访问控制

在“Allowed user IDs”步骤直接按回车（留空，不限制）；在“Enable open access”选项上按回车确认，允许群内所有成员与机器人对话。

4. 保存配置

确认配置内容无误后，选择 Done 保存。配置会被写入 ~/.hermes/config.yaml 中。

五、第三步：启动服务并测试连接

1. 启动 Gateway

配置完成后，启动 Gateway 服务：

hermes gateway start

如果希望在前台运行以便观察日志，可以使用：

hermes gateway run

2. 设置为后台常驻服务（推荐）

为了让 Agent 在服务器重启后也能自动运行，建议将其注册为系统服务。在 Gateway 配置向导的最后一步，会询问 Install as a systemd service?，输入 Y 并按提示完成配置即可。

3. 在钉钉中找到机器人

打开钉钉 App，在搜索框中输入你创建的应用名称，找到机器人并进入对话。

4. 发送测试消息

向机器人发送一条消息，例如“你好，请介绍一下你自己”。如果一切正常，机器人应该能够流式回复。

📌 小提示：首次对话可能需要完成配对授权，按照 Hermes Agent 的提示操作即可。

六、常见问题与排障指南

在配置过程中可能会遇到以下问题，这里提供快速解决方案：

🔧 问题一：配置后机器人无响应，日志显示“未启用任何消息平台”

这是社区反馈的常见问题。按以下步骤排查：

1. 检查 ~/.hermes/config.yaml 中是否已包含 DingTalk 配置段。
2. 确认钉钉应用的“开发模式”为“开发应用”而非“快捷链接”。
3. 检查钉钉应用是否已完成发布。
4. 运行 hermes gateway status 查看 Gateway 运行状态。

🔧 问题二：群聊里 @ 机器人没有反应，但私聊正常

可能原因是缺少群聊相关权限。到钉钉开放平台的“权限管理”中补充 qyapi_manage_agent 和 qyapi_get_member_list 权限。

🔧 问题三：切换模型供应商后 API Key 不跟随切换

这是 Hermes Agent 当前版本的已知行为。解决方法：手动编辑 ~/.hermes/config.yaml 文件，在对应 provider 下配置正确的 api_key。

🔧 问题四：模型名称显示为空

在钉钉聊天窗口中向机器人发送 /model 命令，手动指定模型名称，看到正确显示即代表设置成功。

🔧 问题五：Gateway 启动后频繁断连

检查服务器网络是否稳定。如果部署在 VPS 上，建议使用 systemd 服务模式运行，自动实现断线重连。

七、进阶玩法与安全建议

接入钉钉只是第一步，以下进阶玩法可以让你充分发挥 Hermes Agent 的潜力。

🛡️ 安全建议

• 权限最小化：在钉钉开放平台中，只授予机器人必需的权限，避免过度授权。
• 访问控制：在 hermes gateway setup 的“Allowed user IDs”步骤中，可以填入指定的用户 ID 白名单，限制只有特定成员可以与机器人对话。
• 密钥管理：AppSecret 等敏感信息存放在 ~/.hermes/.env 中，权限自动设为 0600，请勿将该文件上传到公开仓库。

🚀 进阶配置

• 多实例配置：通过 Hermes Agent 的 Multi-profile 功能，可以启动多个完全隔离的 Agent 实例，每个实例使用不同的钉钉应用，分配给不同团队使用。
• 技能固化：随着在钉钉中的使用，Hermes Agent 会自动将成功的任务流程固化为 Skill 文件（存放在 ~/.hermes/skills/ 目录）。你可以将这些 Skill 分享给团队其他成员，实现能力的快速复制。
• 定时任务推送：利用 Hermes Agent 内置的 Cron 调度器，可以设定定时任务，每天固定时间向钉钉群推送工作简报、数据日报等。
• 接入多个消息平台：同一个 Hermes Agent 核心可以同时接入钉钉、飞书、微信、Telegram 等多个平台，共享同一套记忆和技能。无论你在哪个平台发送消息，Agent 都能记住你之前的对话。

总结

Hermes Agent 接入钉钉的核心步骤可归纳为“三步走”：钉钉开放平台创建应用并获取凭证 → 运行 hermes gateway setup 选择 DingTalk 并填写凭证 → 启动 Gateway 并在钉钉中测试。整个过程不涉及复杂的代码开发，通过交互式命令行即可完成配置。接入后，你就拥有了一个 7×24 小时在线的团队 AI 助手，它能记住对话历史、自动沉淀技能，并随着使用越用越懂你和你的团队。

如果你想把 Hermes Agent 这类 AI 智能体的能力扩展到更复杂的企业级自动化场景——比如跨系统数据同步、智能审批、多 Agent 协同编排——可以了解一下「实在Agent」。它能把大模型调用、RPA 流程编排和数据流转串成一条线，让你的 AI 助手从“会聊天”升级为“能干活”的生产力中枢。