跳到主要内容

飞书 / 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 会自动创建一个具有正确权限的机器人应用并保存凭据。

备选方式:手动设置

如果无法使用扫码创建,向导会回退到手动输入:

  1. 打开飞书或 Lark 开发者控制台:
  2. 创建一个新应用。
  3. 凭据与基本信息 中,复制 App IDApp Secret
  4. 为应用启用 机器人 能力。
  5. 运行 hermes gateway setup,选择 飞书 / Lark,然后根据提示输入凭据。
注意

请妥善保管 App Secret。任何拥有它的人都可以冒充你的应用。

第二步:选择连接模式

当 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_KEYFEISHU_VERIFICATION_TOKEN 可以同时使用,实现纵深防御。

群聊消息策略

环境变量 FEISHU_GROUP_POLICY 控制 Hermes 在群聊中是否以及如何响应:

FEISHU_GROUP_POLICY=allowlist   # 默认值
行为
openHermes 会响应任何群组中任何用户的 @提及。
allowlistHermes 仅响应 FEISHU_ALLOWED_USERS 中列出的用户的 @提及。
disabledHermes 完全忽略所有群组消息。

在所有模式下,机器人必须被明确 @提及(或 @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

  1. 订阅卡片动作事件:
    事件订阅 中,将 card.action.trigger 添加到已订阅事件中。

  2. 启用交互式卡片能力:
    应用功能 > 机器人 中,确保 交互式卡片 开关已开启。这告诉飞书你的应用可以接收卡片动作回调。

  3. 配置卡片请求 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 条消息,因此同一文档上的后续评论可以保持上下文。

三级访问控制

文档评论回复是 仅显式授予 模式——没有隐式的全部允许模式。权限按以下顺序解析(按字段,先匹配者生效):

  1. 精确文档 —— 规则限定于特定文档 token。
  2. 通配符 —— 匹配文档模式的规则。
  3. 顶层 —— 工作区的默认规则。

每条规则支持两种策略:

  • 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:readonlydrive: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_animationGIF 降级为文件附件(飞书没有原生 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_SECONDS0.6秒
每批最大消息数HERMES_FEISHU_TEXT_BATCH_MAX_MESSAGES8
每批最大字符数HERMES_FEISHU_TEXT_BATCH_MAX_CHARS4000

媒体批处理

短时间内连续发送的多个媒体附件(例如拖拽多张图片)会被合并为单个事件:

设置项环境变量默认值
静默期HERMES_FEISHU_MEDIA_BATCH_DELAY_SECONDS0.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_interval120秒两次重连尝试之间的等待时间
心跳间隔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_SIZE2048 条

所有环境变量

变量是否必需默认值描述
FEISHU_APP_ID飞书/Lark App ID
FEISHU_APP_SECRET飞书/Lark App Secret
FEISHU_DOMAINfeishufeishu(中国)或 lark(国际)
FEISHU_CONNECTION_MODEwebsocketwebsocketwebhook
FEISHU_ALLOWED_USERS(空)用户白名单的 open_id 列表,逗号分隔
FEISHU_ALLOW_BOTSnone接受来自其他机器人的消息:nonementionsall
FEISHU_REQUIRE_MENTIONtrue群组消息是否需要 @提及机器人
FEISHU_HOME_CHANNEL用于定时任务/通知输出的聊天 ID
FEISHU_ENCRYPT_KEY(空)Webhook 签名验证的加密密钥
FEISHU_VERIFICATION_TOKEN(空)Webhook 负载认证的验证令牌
FEISHU_GROUP_POLICYallowlist群组消息策略:openallowlistdisabled
FEISHU_BOT_OPEN_ID(空)机器人的 open_id(用于 @提及检测)
FEISHU_BOT_USER_ID(空)机器人的 user_id(用于 @提及检测)
FEISHU_BOT_NAME(空)机器人的显示名称(用于 @提及检测)
FEISHU_WEBHOOK_HOST127.0.0.1Webhook 服务器绑定地址
FEISHU_WEBHOOK_PORT8765Webhook 服务器端口
FEISHU_WEBHOOK_PATH/feishu/webhookWebhook 端点路径
HERMES_FEISHU_DEDUP_CACHE_SIZE2048最大跟踪的去重消息 ID 数量
HERMES_FEISHU_TEXT_BATCH_DELAY_SECONDS0.6文本突发去抖静默期
HERMES_FEISHU_TEXT_BATCH_MAX_MESSAGES8每个文本批次合并的最大消息数
HERMES_FEISHU_TEXT_BATCH_MAX_CHARS4000每个文本批次合并的最大字符数
HERMES_FEISHU_MEDIA_BATCH_DELAY_SECONDS0.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:messageim:resource 权限范围
机器人身份未自动检测通常是访问飞书机器人信息接口时的临时网络问题。可手动设置 FEISHU_BOT_OPEN_IDFEISHU_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 及其他基于网关的消息平台相同的核心工具。