飞书 / Lark 配置
Hermes Agent 可作为功能完备的机器人集成到飞书和 Lark 中。连接后,你可以在私聊或群聊中与 Agent 对话,在家庭聊天中接收定时任务结果,并通过常规网关流程发送文本、图片、音频和文件附件。
该集成支持两种连接模式:
websocket— 推荐;Hermes 发起出站连接,你无需提供公共 webhook 端点webhook— 当你希望飞书/Lark 通过 HTTP 将事件推送到你的网关时使用
Hermes 的行为方式
| 场景 | 行为 |
|---|---|
| 私聊 | Hermes 会回复每一条消息。 |
| 群聊 | 只有当机器人在群聊中被 @提及 时,Hermes 才会回复。 |
| 共享群聊 | 默认情况下,在共享群聊中,每个用户的会话历史是隔离的。 |
这种共享群聊的行为由 config.yaml 控制:
group_sessions_per_user: true
仅当你明确希望每个群聊只有一个共享会话时,才将其设置为 false。
第一步:创建飞书 / Lark 应用
推荐方式:扫码创建(一条命令)
hermes gateway setup
选择 飞书 / Lark,然后用飞书或 Lark 手机应用扫描二维码。Hermes 会自动创建一个具有正确权限的机器人应用并保存凭据。
备选方式:手动设置
如果无法使用扫码创建,向导会回退到手动输入:
- 打开飞书或 Lark 开发者控制台:
- 创建一个新应用。
- 在 凭据与基本信息 中,复制 App ID 和 App Secret。
- 为应用启用 机器人 能力。
- 运行
hermes gateway setup,选择 飞书 / Lark,然后根据提示输入凭据。
请妥善保管 App Secret。任何拥有它的人都可以冒充你的应用。
第二步:选择连接模式
推荐方式:WebSocket 模式
当 Hermes 运行在你的笔记本电脑、工作站或私有服务器上时,请使用 WebSocket 模式。无需公共 URL。官方的 Lark SDK 会打开并维护一个持久的出站 WebSocket 连接,并支持自动重连。
FEISHU_CONNECTION_MODE=websocket
要求: 必须安装 websockets Python 包。SDK 会在内部处理连接生命周期、心跳和自动重连。
工作原理: 适配器在后台执行器线程中运行 Lark SDK 的 WebSocket 客户端。入站事件(消息、反应、卡片操作)会被分发到主 asyncio 事件循环。断开连接时,SDK 将自动尝试重新连接。
可选方式:Webhook 模式
仅当你已经将 Hermes 运行在一个可访问的 HTTP 端点后面时,才使用 webhook 模式。
FEISHU_CONNECTION_MODE=webhook
在 webhook 模式下,Hermes 会启动一个 HTTP 服务器(通过 aiohttp),并在以下地址提供飞书端点:
/feishu/webhook
要求: 必须安装 aiohttp Python 包。
你可以自定义 Webhook 服务器的绑定地址和路径:
FEISHU_WEBHOOK_HOST=127.0.0.1 # default: 127.0.0.1
FEISHU_WEBHOOK_PORT=8765 # default: 8765
FEISHU_WEBHOOK_PATH=/feishu/webhook # default: /feishu/webhook
当飞书发送 URL 验证挑战(type: url_verification)时,Webhook 会自动响应,以便你在飞书开发者后台完成订阅设置。
第三步:配置 Hermes
选项 A:交互式设置
hermes gateway setup
选择 Feishu / Lark 并根据提示填写。
选项 B:手动配置
将以下内容添加到 ~/.hermes/.env:
FEISHU_APP_ID=cli_xxx
FEISHU_APP_SECRET=secret_xxx
FEISHU_DOMAIN=feishu
FEISHU_CONNECTION_MODE=websocket
# 可选但强烈建议
FEISHU_ALLOWED_USERS=ou_xxx,ou_yyy
FEISHU_HOME_CHANNEL=oc_xxx
FEISHU_DOMAIN 接受以下值:
feishu用于飞书中国版lark用于 Lark 国际版
第四步:启动网关
hermes gateway
然后在飞书/Lark 中给机器人发消息,确认连接已生效。
家庭聊天
在飞书/Lark 聊天中使用 /set-home 将其标记为家庭频道,用于接收定时任务结果和跨平台通知。
你也可以预先配置:
FEISHU_HOME_CHANNEL=oc_xxx
安全
用户白名单
在生产环境中,设置飞书 Open ID 白名单:
FEISHU_ALLOWED_USERS=ou_xxx,ou_yyy
如果白名单为空,任何能接触到机器人的用户都可能使用它。在群聊中,消息处理前会根据发送者的 open_id 检查白名单。
Webhook 加密密钥
在 Webhook 模式下运行时,设置加密密钥以启用对入站 Webhook 负载的签名验证:
FEISHU_ENCRYPT_KEY=your-encrypt-key
该密钥可在飞书应用配置的事件订阅部分找到。设置后,适配器会使用以下签名算法验证每个 Webhook 请求:
SHA256(timestamp + nonce + encrypt_key + body)
计算出的哈希值会与 x-lark-signature 头部进行时序安全比较。签名无效或缺失的请求将被拒绝并返回 HTTP 401。
在 WebSocket 模式下,签名验证由 SDK 自身处理,因此 FEISHU_ENCRYPT_KEY 是可选的。在 Webhook 模式下,强烈建议在生产环境中使用。
验证令牌
额外的一层身份验证,用于检查 Webhook 负载中的 token 字段:
FEISHU_VERIFICATION_TOKEN=your-verification-token
该令牌同样可在飞书应用的事件订阅部分找到。设置后,每个入站 Webhook 负载的 header 对象中必须包含匹配的 token。令牌不匹配的请求将被拒绝并返回 HTTP 401。
FEISHU_ENCRYPT_KEY 和 FEISHU_VERIFICATION_TOKEN 可以同时使用,实现纵深防御。
群聊消息策略
环境变量 FEISHU_GROUP_POLICY 控制 Hermes 在群聊中是否以及如何响应:
FEISHU_GROUP_POLICY=allowlist # 默认值
| 值 | 行为 |
|---|---|
open | Hermes 会响应任何群组中任何用户的 @提及。 |
allowlist | Hermes 仅响应 FEISHU_ALLOWED_USERS 中列出的用户的 @提及。 |
disabled | Hermes 完全忽略所有群组消息。 |
在所有模式下,机器人必须被明确 @提及(或 @all)后,消息才会被处理。私聊消息始终绕过此限制。
设置 FEISHU_REQUIRE_MENTION=false 可让 Hermes 读取所有群组消息而无需 @提及:
FEISHU_REQUIRE_MENTION=false
如需按聊天进行控制,可在 group_rules 条目中设置 require_mention — 请参阅下面的按群组访问控制。
机器人身份
Hermes 会在启动时自动检测机器人的 open_id 和显示名称。仅当自动检测无法访问飞书 API,或者你的应用使用租户级用户 ID 时,才需要手动设置这些值:
FEISHU_BOT_OPEN_ID=ou_xxx # 仅在自动检测失败时设置
FEISHU_BOT_USER_ID=xxx # 如果你的应用使用 sender_id_type=user_id,则必须设置
FEISHU_BOT_NAME=MyBot # 仅在自动检测失败时设置
机器人间消息传递
默认情况下,Hermes 会忽略其他机器人发送的消息。当你希望 Hermes 参与 A2A 编排或接收同一群组中其他机器人的通知时,可以启用机器人间消息传递。
FEISHU_ALLOW_BOTS=mentions # 默认值:none
| 值 | 行为 |
|---|---|
none | 忽略所有来自其他机器人的消息(默认)。 |
mentions | 仅当对方机器人 @提及 Hermes 时接受。 |
all | 接受所有对方机器人的消息。 |
也可以在 config.yaml 中配置为 feishu.allow_bots(两者都设置时,环境变量优先)。
对方机器人无需添加到 FEISHU_ALLOWED_USERS 中 — 该白名单仅适用于人类发送者。
授予 application:bot.basic_info:read 权限范围以显示对方机器人的名称;没有该权限时,对方机器人仍能正常路由,但会显示为它们的 open_id。
交互式卡片操作
当用户点击机器人发送的交互式卡片上的按钮或与之交互时,适配器会将这些操作路由为合成的 /card 命令事件:
- 按钮点击变为:
/card button {"key": "value", ...} - 卡片定义中的操作
value负载会以 JSON 形式包含在内。 - 卡片操作会在 15 分钟内去重,以防止重复处理。
卡片操作事件以 MessageType.COMMAND 类型分发,因此它们会流经正常的命令处理管道。
这也是命令审批的工作方式 — 当 Agent 需要执行危险命令时,它会发送一个带有“允许一次”/“会话”/“始终”/“拒绝”按钮的交互式卡片。用户点击按钮后,卡片操作回调会将审批决定传回给 Agent。
必需的飞书应用配置
交互式卡片需要在飞书开发者控制台中进行三个配置步骤。缺少任何一个都会导致用户在点击卡片按钮时出现错误 200340。
-
订阅卡片动作事件:
在 事件订阅 中,将card.action.trigger添加到已订阅事件中。 -
启用交互式卡片能力:
在 应用功能 > 机器人 中,确保 交互式卡片 开关已开启。这告诉飞书你的应用可以接收卡片动作回调。 -
配置卡片请求 URL(仅限 webhook 模式):
在 应用功能 > 机器人 > 消息卡片请求地址 中,将 URL 设置为你事件 webhook 的同一端点(例如https://your-server:8765/feishu/webhook)。在 WebSocket 模式下,SDK 会自动处理此配置。
如果没有完成以上三个步骤,飞书可以成功发送交互式卡片(发送只需 im:message:send 权限),但点击任何按钮都会返回错误 200340。卡片看似正常——只有用户与它交互时才会暴露错误。
文档评论智能回复
除聊天外,适配器还可以回复 飞书/ Lark 文档 中的 @ 提及。当用户在文档上评论(选择本地文本或整篇文档评论)并 @ 提及机器人时,Hermes 会读取文档内容及周围评论线程,并在该线程中内联发布 LLM 回复。
由 drive.notice.comment_add_v1 事件驱动,处理器会:
- 并行获取文档内容和评论时间线(整篇文档线程 20 条消息,本地选择线程 12 条消息)。
- 使用限定于该单一评论会话的
feishu_doc+feishu_drive工具集运行 Agent。 - 将回复按 4000 字符拆分,并以线程回复形式发布。
- 每个文档的会话缓存 1 小时,最多 50 条消息,因此同一文档上的后续评论可以保持上下文。
三级访问控制
文档评论回复是 仅显式授予 模式——没有隐式的全部允许模式。权限按以下顺序解析(按字段,先匹配者生效):
- 精确文档 —— 规则限定于特定文档 token。
- 通配符 —— 匹配文档模式的规则。
- 顶层 —— 工作区的默认规则。
每条规则支持两种策略:
allowlist—— 用户/租户的静态列表。pairing—— 静态列表 ∪ 运行时可批准的存储。适用于版主可以实时授予权限的发布场景。
规则存放在 ~/.hermes/feishu_comment_rules.json(配对授权存放在 ~/.hermes/feishu_comment_pairing.json)中,支持 mtime 缓存的 hot-reload——无需重启网关,编辑内容将在下一个评论事件时生效。
CLI:
# 查看当前规则和配对状态
python -m gateway.platforms.feishu_comment_rules status
# 模拟检查特定文档 + 用户的访问权限
python -m gateway.platforms.feishu_comment_rules check <fileType:fileToken> <user_open_id>
# 运行时管理配对授权
python -m gateway.platforms.feishu_comment_rules pairing list
python -m gateway.platforms.feishu_comment_rules pairing add <user_open_id>
python -m gateway.platforms.feishu_comment_rules pairing remove <user_open_id>
必需的飞书应用配置
在已授予的聊天/卡片权限基础上,添加文档评论事件:
- 在事件订阅中订阅
drive.notice.comment_add_v1。 - 授予
docs:doc:readonly和drive:drive:readonly作用域,以便处理器能够读取文档内容。
媒体支持
入站(接收)
适配器从用户处接收并缓存以下媒体类型:
| 类型 | 扩展名 | 处理方式 |
|---|---|---|
| 图片 | .jpg, .jpeg, .png, .gif, .webp, .bmp | 通过飞书 API 下载并本地缓存 |
| 音频 | .ogg, .mp3, .wav, .m4a, .aac, .flac, .opus, .webm | 下载并缓存;小型文本文件自动提取内容 |
| 视频 | .mp4, .mov, .avi, .mkv, .webm, .m4v, .3gp | 下载并作为文档缓存 |
| 文件 | .pdf, .doc, .docx, .xls, .xlsx, .ppt, .pptx 等 | 下载并作为文档缓存 |
富文本(post)消息中的媒体(包括内联图片和文件附件)也会被提取并缓存。
对于基于文本的小型文档(.txt, .md),文件内容会自动注入到消息文本中,以便 Agent 无需工具即可直接读取。
出站(发送)
| 方法 | 发送内容 |
|---|---|
send | 文本或富文本 post 消息(根据 markdown 内容自动检测) |
send_image / send_image_file | 将图片上传到飞书,然后以原生图片气泡形式发送(可附带标题) |
send_document | 将文件上传到飞书 API,然后以文件附件形式发送 |
send_voice | 将音频文件作为飞书文件附件上传 |
send_video | 上传视频并以原生媒体消息发送 |
send_animation | GIF 降级为文件附件(飞书没有原生 GIF 气泡) |
文件上传路由根据扩展名自动处理:
.ogg,.opus→ 作为opus音频上传.mp4,.mov,.avi,.m4v→ 作为mp4媒体上传.pdf,.doc(x),.xls(x),.ppt(x)→ 按其文档类型上传- 其他所有文件 → 作为通用流文件上传
Markdown 渲染与 Post 回退
当出站文本包含 markdown 格式(标题、加粗、列表、代码块、链接等)时,适配器会自动将其作为飞书 post 消息发送(内嵌 md 标签),而非纯文本。这样可以在飞书客户端中实现富文本渲染。
如果飞书 API 拒绝 post 载荷(例如由于不支持的 markdown 结构),适配器会自动回退为纯文本发送(去除 markdown)。这种两阶段回退机制确保消息始终能够送达。
纯文本消息(未检测到 markdown)会以简单的 text 消息类型发送。
处理状态反应
当 Agent 正在工作时,机器人会在你的消息上显示 Typing 反应。回复到达时该反应会消失,如果处理失败则替换为 CrossMark。
设置 FEISHU_REACTIONS=false 可关闭此功能。
突发保护与批处理
适配器包含对快速消息突发的防抖处理,以避免压垮 Agent:
文本批处理
当用户短时间内连续发送多条文本消息时,这些消息会被合并为单个事件再分发:
| 设置项 | 环境变量 | 默认值 |
|---|---|---|
| 静默期 | HERMES_FEISHU_TEXT_BATCH_DELAY_SECONDS | 0.6秒 |
| 每批最大消息数 | HERMES_FEISHU_TEXT_BATCH_MAX_MESSAGES | 8 |
| 每批最大字符数 | HERMES_FEISHU_TEXT_BATCH_MAX_CHARS | 4000 |
媒体批处理
短时间内连续发送的多个媒体附件(例如拖拽多张图片)会被合并为单个事件:
| 设置项 | 环境变量 | 默认值 |
|---|---|---|
| 静默期 | HERMES_FEISHU_MEDIA_BATCH_DELAY_SECONDS | 0.8秒 |
按会话串行化
同一会话内的消息会串行处理(一次一条),以保持对话连贯性。每个会话拥有独立的锁,因此不同会话的消息可以并发处理。
速率限制(Webhook 模式)
在 Webhook 模式下,适配器会按 IP 实施速率限制以防止滥用:
- 窗口: 60秒滑动窗口
- 限制: 每 (app_id, 路径, IP) 三元组每窗口 120 次请求
- 追踪上限: 最多追踪 4096 个唯一键(防止内存无限增长)
超出限制的请求会收到 HTTP 429(请求过多)响应。
Webhook 异常追踪
适配器会按 IP 地址追踪连续错误响应。当同一 IP 在 6 小时窗口内连续出现 25 次错误时,会记录一条警告日志。这有助于发现配置错误的客户端或探测行为。
其他 Webhook 保护措施:
- 请求体大小限制: 最大 1 MB
- 请求体读取超时: 30 秒
- Content-Type 强制要求: 仅接受
application/json
WebSocket 调优
使用 websocket 模式时,可以自定义重连和心跳行为:
platforms:
feishu:
extra:
ws_reconnect_interval: 120 # 重连尝试间隔(秒,默认值:120)
ws_ping_interval: 30 # WebSocket 心跳间隔(秒,可选;未设置时使用 SDK 默认值)
| 设置项 | 配置键 | 默认值 | 说明 |
|---|---|---|---|
| 重连间隔 | ws_reconnect_interval | 120秒 | 两次重连尝试之间的等待时间 |
| 心跳间隔 | ws_ping_interval | (SDK 默认值) | WebSocket 保活心跳的频率 |
按群组访问控制
除了全局的 FEISHU_GROUP_POLICY,你还可以通过 config.yaml 中的 group_rules 为每个群聊设置细粒度规则:
platforms:
feishu:
extra:
default_group_policy: "open" # 未在 group_rules 中配置的群组默认策略
admins: # 可管理机器人设置的用户
- "ou_admin_open_id"
group_rules:
"oc_group_chat_id_1":
policy: "allowlist" # open | allowlist | blacklist | admin_only | disabled
allowlist:
- "ou_user_open_id_1"
- "ou_user_open_id_2"
"oc_group_chat_id_2":
policy: "admin_only"
"oc_group_chat_id_3":
policy: "blacklist"
blacklist:
- "ou_blocked_user"
"oc_free_chat":
policy: "open"
require_mention: false # 针对该群聊覆盖 FEISHU_REQUIRE_MENTION 设置
| 策略 | 描述 |
|---|---|
open | 群组内任何人都可以使用机器人 |
allowlist | 只有群组 allowlist 中的用户可以使用机器人 |
blacklist | 除群组 blacklist 中的用户外,其他人都可以使用机器人 |
admin_only | 只有全局 admins 列表中的用户才能在该群组中使用机器人 |
disabled | 机器人忽略该群组中的所有消息 |
在 group_rules 条目中设置 require_mention: false 可以跳过该特定聊天的 @提及要求。如果省略,该聊天将继承全局的 FEISHU_REQUIRE_MENTION 值。
未在 group_rules 中列出的群组将回退到 default_group_policy(默认为 FEISHU_GROUP_POLICY 的值)。
去重
入站消息使用消息 ID 进行去重,生存时间为 24 小时。去重状态会在重启后持久化到 ~/.hermes/feishu_seen_message_ids.json。
| 设置项 | 环境变量 | 默认值 |
|---|---|---|
| 缓存大小 | HERMES_FEISHU_DEDUP_CACHE_SIZE | 2048 条 |
所有环境变量
| 变量 | 是否必需 | 默认值 | 描述 |
|---|---|---|---|
FEISHU_APP_ID | ✅ | — | 飞书/Lark App ID |
FEISHU_APP_SECRET | ✅ | — | 飞书/Lark App Secret |
FEISHU_DOMAIN | — | feishu | feishu(中国)或 lark(国际) |
FEISHU_CONNECTION_MODE | — | websocket | websocket 或 webhook |
FEISHU_ALLOWED_USERS | — | (空) | 用户白名单的 open_id 列表,逗号分隔 |
FEISHU_ALLOW_BOTS | — | none | 接受来自其他机器人的消息:none、mentions 或 all |
FEISHU_REQUIRE_MENTION | — | true | 群组消息是否需要 @提及机器人 |
FEISHU_HOME_CHANNEL | — | — | 用于定时任务/通知输出的聊天 ID |
FEISHU_ENCRYPT_KEY | — | (空) | Webhook 签名验证的加密密钥 |
FEISHU_VERIFICATION_TOKEN | — | (空) | Webhook 负载认证的验证令牌 |
FEISHU_GROUP_POLICY | — | allowlist | 群组消息策略:open、allowlist、disabled |
FEISHU_BOT_OPEN_ID | — | (空) | 机器人的 open_id(用于 @提及检测) |
FEISHU_BOT_USER_ID | — | (空) | 机器人的 user_id(用于 @提及检测) |
FEISHU_BOT_NAME | — | (空) | 机器人的显示名称(用于 @提及检测) |
FEISHU_WEBHOOK_HOST | — | 127.0.0.1 | Webhook 服务器绑定地址 |
FEISHU_WEBHOOK_PORT | — | 8765 | Webhook 服务器端口 |
FEISHU_WEBHOOK_PATH | — | /feishu/webhook | Webhook 端点路径 |
HERMES_FEISHU_DEDUP_CACHE_SIZE | — | 2048 | 最大跟踪的去重消息 ID 数量 |
HERMES_FEISHU_TEXT_BATCH_DELAY_SECONDS | — | 0.6 | 文本突发去抖静默期 |
HERMES_FEISHU_TEXT_BATCH_MAX_MESSAGES | — | 8 | 每个文本批次合并的最大消息数 |
HERMES_FEISHU_TEXT_BATCH_MAX_CHARS | — | 4000 | 每个文本批次合并的最大字符数 |
HERMES_FEISHU_MEDIA_BATCH_DELAY_SECONDS | — | 0.8 | 媒体突发去抖静默期 |
WebSocket 和每个群组的 ACL 设置通过 config.yaml 中的 platforms.feishu.extra 配置(参见上面的 WebSocket 调优 和 每个群组的访问控制)。
故障排除
| 问题 | 修复 |
|---|---|
lark-oapi not installed | 安装 SDK:pip install lark-oapi |
websockets not installed; websocket mode unavailable | 安装 websockets:pip install websockets |
aiohttp not installed; webhook mode unavailable | 安装 aiohttp:pip install aiohttp |
FEISHU_APP_ID or FEISHU_APP_SECRET not set | 设置这两个环境变量,或通过 hermes gateway setup 进行配置 |
Another local Hermes gateway is already using this Feishu app_id | 同一时间只能有一个 Hermes 实例使用同一个 app_id。请先停止另一个网关。 |
| 机器人在群聊中不响应 | 确保机器人被 @ 提及,检查 FEISHU_GROUP_POLICY,如果策略为 allowlist,请验证发送者是否在 FEISHU_ALLOWED_USERS 中 |
Webhook rejected: invalid verification token | 确保 FEISHU_VERIFICATION_TOKEN 与飞书应用事件订阅配置中的令牌一致 |
Webhook rejected: invalid signature | 确保 FEISHU_ENCRYPT_KEY 与飞书应用配置中的加密密钥一致 |
| 发送的消息显示为纯文本 | 飞书 API 拒绝了消息内容,这是正常的降级行为。查看日志了解详情。 |
| 机器人未收到图片/文件 | 为飞书应用授予 im:message 和 im:resource 权限范围 |
| 机器人身份未自动检测 | 通常是访问飞书机器人信息接口时的临时网络问题。可手动设置 FEISHU_BOT_OPEN_ID 和 FEISHU_BOT_NAME 作为临时方案。 |
启用 FEISHU_ALLOW_BOTS 后,其他机器人的消息仍被忽略 | Hermes 尚无法识别自身身份——请设置 FEISHU_BOT_OPEN_ID(如果应用使用 sender_id_type=user_id,还需设置 FEISHU_BOT_USER_ID)。 |
其他机器人显示为 ou_xxxxxx 而非名称 | 授予 application:bot.basic_info:read 权限范围。 |
| 点击审批按钮时出现错误 200340 | 在飞书开发者控制台中启用交互卡片能力并配置卡片请求地址。请参见上方的飞书应用必需配置。 |
Webhook rate limit exceeded | 同一 IP 每分钟超过 120 次请求。这通常是配置错误或循环导致的。 |
工具集
飞书 / Lark 使用 hermes-feishu 平台预设,包含与 Telegram 及其他基于网关的消息平台相同的核心工具。