11 · 怎样把 Hermes 接入飞书，并完成第一个移动端任务

不再守在电脑前：从飞书发出一个边界清楚的任务，并收到可核对的回复。

这是第一篇场景课程。你会以飞书为完整主案例，创建或配置机器人、启动 Gateway，再从飞书私聊发送一个只需文字回答的小任务。钉钉、企业微信和微信只作为后续选型参考，本篇不展开它们的配置步骤。

看完会得到什么

• 一个已经连接 Hermes 的飞书机器人
• 一次从飞书发出、由 Hermes 完成的移动端任务
• 一套“Gateway 在线、消息能进、回复能回”的三段式验收方法
• 一个可以立即停用机器人、停止 Gateway 和撤销应用凭据的恢复入口

开始前

• 预计时间：25—45 分钟；企业管理员审批时间不计入
• 前置课程：建议先完成 01—10，至少已完成安装、模型配置、权限与排错课程
• 已验证日期：2026-07-18
• 已实测环境：Hermes Agent 0.18.2，Linux x86_64；本地核对了 hermes gateway、setup、install、start、stop 和 status 帮助
• 平台事实：已对照当日 Hermes 官方飞书文档与飞书开放平台；应用发布和企业审批以你所在租户的实际界面为准
• 输入位置：系统终端、飞书开放平台、飞书私聊
• 本篇会修改：Hermes 的飞书连接配置；飞书开放平台中的一个应用；选择后台服务时还会安装 Gateway 用户服务
• 本篇不会修改：正式项目文件、群聊历史、其他消息平台配置，也不会要求公开任何 App Secret

先认识本篇术语

术语	中文直觉	本篇用途
Gateway	消息入口与 Hermes 之间的“接线员”	接收飞书事件，把任务交给 Agent，再把回复送回飞书
飞书应用	机器人在飞书中的身份与权限容器	提供机器人能力、事件订阅和凭据
App ID / App Secret	应用身份与秘密凭据	让 Hermes 以该应用身份连接飞书；Secret 不能进入普通聊天
WebSocket 长连接	Hermes 主动向飞书建立并维持连接	推荐模式，不要求你准备公网回调地址
事件订阅	飞书允许应用接收的事件清单	至少需要消息接收事件，机器人才能看见新消息
Allowlist	允许使用机器人的用户清单	防止任何能找到机器人的人都能调用 Agent

先看流程

先让应用具备最小消息能力，再建立连接。完成标准不是“配置页面没有报错”，而是飞书消息能进入 Hermes、Hermes 的真实回复也能回到同一私聊。

动手前先决定：前台运行还是后台服务

使用场景	建议方式	停止方式
第一次练习、正在排错	前台运行 hermes gateway run	回到该终端按 Ctrl+C
日常在个人电脑使用	安装用户服务后启动	hermes gateway stop
常驻服务器	先阅读官方生产与安全说明，再选择服务方式	按部署方式停止服务

第一次练习优先使用前台运行。你能直接看见连接错误，也能用 Ctrl+C 明确停止，不必先处理开机启动问题。

第一步：运行飞书配置向导

在系统终端中输入：

hermes gateway setup

• 输入位置：运行 Hermes 的电脑或服务器终端
• 读取或修改：读取现有 Gateway 配置；选择飞书后保存该平台所需的连接信息
• 成功判断：向导完成飞书配置，不显示缺少必需凭据的错误
• 失败先查：运行 hermes --version，确认命令来自当前 Hermes 安装；再对照官方飞书页面检查向导要求

在向导中选择飞书。官方文档当前把扫码创建列为推荐路径：使用飞书移动端扫描向导显示的二维码，由向导创建带正确权限的应用并保存连接信息。只在 Hermes 官方向导与飞书正式授权页面中操作，不把二维码、App Secret 或授权结果截图发给他人。

如果你的企业策略不允许扫码创建，向导会进入手动配置路径。此时到飞书开放平台创建应用，启用机器人能力，再把 App ID 和 App Secret 输入向导的安全提示位置。不要把 Secret 写进命令参数或普通对话。

第二步：只授予这次练习需要的能力

如果扫码路径已经自动配置，仍应在飞书开放平台核对权限。手动路径至少需要以下消息能力；权限名称以飞书控制台当日显示为准：

Hermes 官方文档列出的权限	用途
im:message	接收和读取消息
im:message:send_as_bot	以机器人身份回复
im:resource	读取用户发送的图片、文件和音频；第 13 篇会用到
im:chat	获取会话或群聊元数据
im:chat:readonly	读取会话列表与成员信息

只做本篇文字私聊时，核心是消息接收与机器人发送。不要为了“以后也许会用”顺手授予通讯录写入、文档写入或其他管理权限。第 13 篇需要多媒体时，再确认 im:resource 是否已经具备。

在“事件与回调”中选择长连接模式，并订阅：

im.message.receive_v1

这是接收消息所需的事件。完成权限与事件设置后，到版本管理发布应用版本。企业自建应用可能需要管理员审批；权限未随版本发布并获批时，页面配置完成也不会生效。

第三步：为访问范围加一道门

生产或团队使用时，应设置允许使用机器人的飞书用户 Open ID。推荐通过 hermes gateway setup 的对应提示完成，不要在教程、截图或公开 Issue 中展示真实 ID。

官方文档说明：如果用户 allowlist 留空，任何能够接触机器人的人都可能调用它。群聊还受群策略和 @ 提及规则影响，但本篇只在私聊验证，避免把第一次测试扩散到群内。

本篇的最小原则是：

• 先只允许自己的测试账号；
• 先用私聊，不把机器人加入正式群；
• 不关闭群聊的 @ 提及要求；
• 不开启机器人之间自动互发消息；
• 扩大范围前，先确认工具、数据和费用边界。

第四步：启动 Gateway

第一次练习，在终端运行：

hermes gateway run

• 输入位置：运行 Hermes 的系统终端
• 读取或修改：读取已保存的平台和模型配置；进程保持运行，不安装后台服务
• 成功判断：进程持续运行，没有立即退出；日志显示飞书适配器已启动或连接已建立
• 失败先查：先看当前终端错误，再运行后面的深度状态检查；常见原因是凭据缺失、应用未发布、SDK 依赖缺失或同一 App ID 已被另一实例占用

保持这个终端窗口打开。另开一个终端检查：

hermes gateway status --deep

• 输入位置：同一台机器的另一个终端
• 读取或修改：只读取 Gateway 服务与平台状态
• 成功判断：状态结果能识别 Gateway；如果使用前台模式，服务管理器状态与前台进程状态可能不同，应结合前台日志判断
• 失败先查：确认第一个终端中的 hermes gateway run 仍在运行，并检查它的最新错误

如果你已经完成一次前台验证，再考虑后台服务：

hermes gateway install
hermes gateway start
hermes gateway status --deep

这三条命令分别安装当前用户的 Gateway 服务、启动服务并检查状态。它们会改变用户服务配置；第一次排错不必执行。需要撤销时运行 hermes gateway stop，并按官方 CLI 文档决定是否卸载服务。

第五步：从飞书完成第一个移动端任务

打开与机器人的飞书私聊，发送：

请只根据这条消息回答，不调用网页、文件或终端工具。
把下面三项整理成“目标 / 截止时间 / 验收标准”三行：
目标：准备一次 30 分钟的新手分享
截止时间：本周五 18:00
验收标准：有标题、三段提纲和一份会后检查表
如果信息不足，只指出缺口，不要自行补充。

这个练习故意只使用当前消息：

• 不需要读取你的电脑文件；
• 不需要联网；
• 不需要向第三方发送消息；
• 输出只有三行，容易核对；
• 原文中的时间和标准都能逐项追溯。

成功标准不是固定措辞，而是飞书中收到一条真实回复，且三项信息没有被改写成别的日期、时长或交付物。

第六步：停止一次，再恢复一次

完成回复后，回到前台 Gateway 终端按：

Ctrl+C

然后再次从飞书发送一条测试消息。此时不应期待 Hermes 正常回复；这一步证明你知道怎样切断消息入口。随后重新运行：

hermes gateway run

再发送：

只回复：Gateway 已恢复。

收到回复后，本篇的“连接—停止—恢复”闭环才完成。不要伪造或预设机器人必须返回某个系统日志；只核对你真实收到的消息。

权限检查

本篇会访问：

• 飞书应用的消息事件、会话信息和机器人发送能力；
• Hermes 本地保存的平台配置；
• 你主动发送给机器人的测试消息；
• 所选模型服务，用于生成回复。

可以批准：

• 为测试应用授予完成收发消息所需的最小权限；
• 让 Gateway 建立向外的长连接；
• 让机器人回复你自己的测试私聊。

需要停下来确认：

• 要求关闭企业安全设置或授予管理员级权限；
• 要求把 App Secret、用户 Open ID 或聊天 ID 发进普通对话；
• 要求关闭 allowlist，或让机器人无需 @ 提及就读取所有群消息；
• 要求把测试机器人直接加入正式业务群；
• 要求把 Gateway 暴露到公网，但没有域名、TLS、签名验证和访问控制方案。

不应输入的信息：真实客户资料、未脱敏内部文件、API key、App Secret、密码、私钥和助记词。

为什么主案例使用长连接与私聊

长连接由 Hermes 主动建立，不要求新手先拥有公网回调地址，也减少了端口、反向代理和签名校验变量。私聊则把事件来源、回复目标和会话范围压缩到一个人，便于验证访问控制。

这不表示长连接天然免除所有安全工作。应用仍有凭据、权限、allowlist 和模型费用；运行 Gateway 的系统账户仍决定本地工具能接触什么。消息平台只是入口，不是新的安全沙箱。

出错时按这个顺序查

机器人完全不回复

1. 确认 hermes gateway run 进程仍在运行；
2. 运行 hermes gateway status --deep；
3. 检查 App ID / App Secret 是否已经由向导保存，不要打印 Secret；
4. 在飞书开放平台确认机器人能力、im.message.receive_v1 事件和应用版本已经发布；
5. 检查企业管理员是否仍未批准权限；
6. 对照 Hermes 官方飞书排错表。

私聊可用，群聊不回复

本篇不要求群聊通过。需要继续排查时，依次确认：机器人是否被明确 @ 提及、群策略是否为 allowlist、发送者是否在允许清单。不要把“关闭提及要求”当作第一修复方案。

图片或文件收不到

留到第 13 篇完整验证。先检查飞书应用是否有 im:resource，再确认 Gateway 日志是否显示资源下载失败。

同一个应用只有一台机器能连接

官方排错说明指出，同一 App ID 被另一个本地 Hermes Gateway 使用时会冲突。停止旧实例，再启动当前实例；不要同时让多个测试环境争用同一应用身份。

怀疑凭据泄露

1. 立即停止 Gateway；
2. 在飞书开放平台轮换或重置 App Secret；
3. 从 Hermes 本地配置中移除旧值，再通过向导重新配置；
4. 检查应用日志和异常调用；
5. 缩小权限与 allowlist 后重新验证。

删除聊天中的 Secret 不等于完成撤销。

钉钉、企业微信和微信怎样参考

这三个平台的接入方式、事件模型和部署前提不同，不应把飞书步骤原样照搬。选型时只做三件事：

1. 打开 Hermes 官方对应平台页面，确认当前是否支持你的账号与接入模式；
2. 运行 hermes gateway setup，只使用向导当日提供的入口；
3. 分别核对凭据、回调或长连接要求、允许用户范围和停止方式。

本篇不展开它们的按钮和字段，避免把不同平台误写成同一套配置。

本篇作品

保存一份不含敏感信息的验收记录：

平台：飞书
验证日期：2026-07-18
Gateway 运行方式：前台 / 用户服务（二选一）
私聊任务：已收到 / 未收到真实回复
停止测试：停止后不再回复
恢复测试：重新启动后恢复回复
凭据：未写入聊天、截图或仓库

可以保存飞书回复截图，但必须裁掉 App Secret、真实用户 ID、内部群名和其他无关消息。

本篇验收

• [ ] hermes gateway setup 已完成飞书配置
• [ ] 飞书应用已启用机器人能力、消息事件和最小权限，并完成必要发布或审批
• [ ] Gateway 能以前台进程或用户服务方式保持运行
• [ ] 从飞书私聊发出的三行整理任务收到了真实回复
• [ ] 回复中的目标、时间和验收标准可追溯到输入，没有自行补充
• [ ] allowlist 至少限制到测试用户，或能说明尚未上线前为什么必须补上
• [ ] 能停止 Gateway，并在重新启动后恢复消息
• [ ] 没有在聊天、截图或仓库中暴露 App Secret、用户 ID 或聊天 ID

下一篇

下一篇会创建一个有真实输出的 Cron 计划任务，并完成查看、手动触发、暂停、恢复和删除。你还会明确每次运行可能产生的模型成本，以及输出究竟保存或发送到哪里。

官方来源

• Hermes：飞书接入
• Hermes：Messaging Gateway
• Hermes：CLI Commands
• Hermes：Security
• 飞书开放平台
• Hermes：钉钉接入
• Hermes：企业微信接入
• Hermes：微信接入