🤖HermesBlog
Hermes 消息平台接入 · 第17篇2026/8/9· Easy Understand Hermes Agent

飞书接入——一站式协作平台

Hermes 消息平台接入第17篇：飞书。文档、群聊、机器人全打通。

这篇教程将手把手教你如何把 Hermes Agent 接入飞书或 Lark，让你直接在聊天窗口里指挥 AI 助手。

飞书接入：给机器人配钥匙

准备工作：像“配钥匙”一样创建应用

要让 Hermes 在飞书里“安家”，首先得在飞书开放平台创建一个“应用”——你可以把它想象成给机器人配一把专属钥匙。

推荐方式（一条命令搞定）：

hermes gateway setup

选择 Feishu / Lark，然后用飞书手机App扫码，Hermes 会自动帮你创建好应用并配好权限，省心省力。

手动创建（备选方案）：

  1. 打开飞书开放平台（https://open.feishu.cn/）或 Lark 国际版控制台
  2. 创建一个新应用，在“凭证与基础信息”里找到 App ID 和 App Secret（相当于账号密码）
  3. 开启“机器人”能力
  4. 在“权限管理”里添加以下权限（可批量导入）：

必选权限：

权限 用途
im:message 接收和读取消息
im:message:send_as_bot 以机器人身份发消息
im:resource 访问用户发的图片、文件
im:chat 获取群聊信息
im:chat:readonly 读取群列表和成员信息

强烈建议加上： im:message.reactions:readonly（接收表情回应）、admin:app.info:readonly（自动识别机器人身份，用于 @ 判断）、contact:user.id:readonly（识别用户身份）

  1. 在“事件与回调”里订阅 im.message.receive_v1 事件（这是接收消息的“开关”）
  2. 发布应用版本——不发布的话权限不会生效哦！

选择连接方式：像选“电话线”还是“对讲机”

WebSocket 模式（推荐）：Hermes 主动连上飞书的服务器，不需要公网地址，适合个人电脑或内网服务器使用。

FEISHU_CONNECTION_MODE=websocket

底层用的是官方 Lark SDK，它会自己处理心跳和断线重连。万一连接彻底断了（SDK 重试放弃或线程退出），Hermes 的守护逻辑会用带上限的退避策略把客户端重建起来。断线期间，hermes gateway status 会把该平台显示为 retrying，直到重新连上。

Webhook 模式：适合已有公网服务器的用户，飞书会把消息“推”到你的服务器上。

FEISHU_CONNECTION_MODE=webhook

配置 Hermes：填写“通讯录”

把以下配置加到 ~/.hermes/.env 文件里：

FEISHU_APP_ID=cli_xxx
FEISHU_APP_SECRET=secret_xxx
FEISHU_DOMAIN=feishu        # 国内版用 feishu，国际版用 lark
FEISHU_CONNECTION_MODE=websocket

# 强烈建议设置以下两项：
FEISHU_ALLOWED_USERS=ou_xxx,ou_yyy   # 允许使用的用户ID白名单
FEISHU_HOME_CHANNEL=oc_xxx           # 接收定时任务结果的群聊ID

启动网关

hermes gateway

然后给机器人发条消息试试，通了就大功告成！

安全设置：给门上把锁

用户白名单：生产环境务必设置 FEISHU_ALLOWED_USERS，否则任何能接触到机器人的人都能使用它。

群聊策略：默认只在被 @ 时回复，可通过 FEISHU_GROUP_POLICY 调整：

  • allowlist（默认）：只回复白名单用户
  • open：任何人 @ 都回复
  • disabled：完全不理会群消息

注意默认的 allowlist 策略下，如果 FEISHU_ALLOWED_USERS 是空的，群里所有人的消息都会被拒掉（私聊不受影响）。第一次被拒时会打一条 WARNING 日志，告诉你该配哪些键，之后就降到 DEBUG 了。如果你用的是多 profile 网关，每个 profile 只读自己的 .env——默认 profile 里写的 FEISHU_GROUP_POLICY=open 不会作用到别的 profile 的机器人身上，得放到 profiles/<name>/.env 里，或者用那个 profile 的 config.yaml 里的 group_rules。

加密验证（Webhook 模式）：设置 FEISHU_ENCRYPT_KEY 和 FEISHU_VERIFICATION_TOKEN，防止别人伪造消息。

交互卡片：让按钮真正能用

Hermes 的命令审批、hermes update --gateway 的确认提示，都是通过飞书的交互卡片来完成的——卡片上会有“允许一次 / 本次会话 / 始终允许 / 拒绝”之类的按钮。如果你发现卡片能正常发出来，但一点按钮就报错 200340，那多半是卡片回调没配好。

需要在飞书开发者后台做这几件事：

  1. 订阅卡片回调（注意：不是“事件”）：进入 开发配置 > 事件与回调，打开 回调配置 标签页——它和放 im.message.receive_v1 的 事件配置 标签页是分开的——在“订阅的回调”里加上 card.action.trigger。把它当成事件来加是收不到按钮点击的。
  2. 设置回调的接收方式：在同一个标签页里，如果 Hermes 跑在 websocket 模式，就选 长连接（Lark SDK 会复用现有连接接收回调）；如果是 webhook 模式，就填请求地址（和事件 webhook 用同一个端点，例如 https://your-server:8765/feishu/webhook）。飞书必须能访问并解析这个地址，否则点击会以 200342/200343 失败。
  3. 开启交互卡片能力：在 应用功能 > 机器人 里，确保 交互卡片 开关是打开的。
  4. 发布新版本：回调相关的改动只有在 版本管理与发布 里创建并发布新版本之后才会生效（企业应用还需要管理员审批）。

:::warning 如果卡片回调没配好，飞书仍然能成功发送交互卡片（发送只需要 im:message:send 权限），但用户一点按钮就会返回错误 200340。卡片看起来是正常的——问题只在用户点击时才暴露，而且这次点击根本不会到达 Hermes（日志里什么都没有），因为飞书在投递回调之前就把它拒掉了。 :::

如果看到错误码 200672 / 200673，说明回调已经到达 Hermes，是飞书拒绝了响应；遇到这种情况，请带上对应的 gateway.log 日志提 issue。

小总结

接入飞书就像给 Hermes 装了个“中国本地电话”——扫码创建应用、配置权限、选择连接方式、设置安全策略，四步就搞定。现在你可以在飞书里直接和 AI 对话了！

下篇预告：我们将探索 Hermes 的“记忆宫殿”——如何配置长期记忆，让 AI 真正“记住”你的偏好和对话历史。

📖 官方文档

本文根据 Hermes Agent 官方文档编写，原文见：官方文档 › user-guide/messaging/feishu

← 返回全部文章