Feishu / Lark 设置

Hermes Agent 与 Feishu 和 Lark 作为全功能机器人集成。连接后，你可以在直接消息或群聊中与 agent 聊天，在主聊天中接收 cron 作业结果，并通过正常网关流程发送文本、图片、音频和文件附件。

集成支持两种连接模式：

• websocket — 推荐；Hermes 打开出站连接，无需公共 webhook 端点
• webhook — 当你希望通过 HTTP 将 Feishu/Lark 事件推送到网关时有用

Hermes 的行为

上下文	行为
直接消息	Hermes 响应每条消息
群聊	只有在聊天中被 @mention 时 Hermes 才响应
共享群聊	默认情况下，会话历史在共享聊天中按用户隔离

此共享聊天行为由 config.yaml 控制：

group_sessions_per_user: true

仅在你明确希望每个聊天一个共享对话时才将其设置为 false。

步骤 1：创建 Feishu / Lark 应用

推荐：扫码创建（一命令）

hermes gateway setup

选择 Feishu / Lark 并用 Feishu 或 Lark 手机应用扫描二维码。Hermes 将自动创建具有正确权限的机器人应用并保存凭证。

备选：手动设置

如果扫码创建不可用，向导会回退到手动输入：

1. 打开 Feishu 或 Lark 开发者控制台：
   • Feishu：https://open.feishu.cn/
   • Lark：https://open.larksuite.com/
2. 创建新应用
3. 在 Credentials & Basic Info 中，复制 App ID 和 App Secret
4. 为应用启用 Bot 能力
5. 运行 hermes gateway setup，选择 Feishu / Lark 并在提示时输入凭证

注意

保持 App Secret 私密。拥有它的人可以冒充你的应用。

步骤 2：选择连接模式

推荐：WebSocket 模式

当 Hermes 运行在笔记本、工作站或私人服务器上时使用 WebSocket 模式。无需公共 URL。官方 Lark SDK 打开并维护与自动重连的持久出站 WebSocket 连接。

FEISHU_CONNECTION_MODE=websocket

要求： 必须安装 websockets Python 包。SDK 内部处理连接生命周期、心跳和自动重连。

可选：Webhook 模式

仅当你已通过可访问的 HTTP 端点运行 Hermes 时才使用 webhook 模式。

FEISHU_CONNECTION_MODE=webhook

在 webhook 模式下，Hermes 启动 HTTP 服务器（通过 aiohttp）并在以下地址提供 Feishu 端点：

/feishu/webhook

要求： 必须安装 aiohttp Python 包。

步骤 3：配置 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 国际版

步骤 4：启动网关

hermes gateway

然后从 Feishu/Lark 向机器人发送消息以确认连接正常。

主聊天

在 Feishu/Lark 聊天中使用 /set-home 将其标记为 cron 作业结果和跨平台通知的主频道。

安全

用户白名单

对于生产环境，设置 Feishu Open ID 白名单：

FEISHU_ALLOWED_USERS=ou_xxx,ou_yyy

如果将白名单留空，任何能联系到机器人的人都可能使用它。在群聊中，在处理消息之前会检查发送者的 open_id。

Webhook 加密密钥

在 webhook 模式下运行时，设置加密密钥以启用入站 webhook 负载的签名验证：

FEISHU_ENCRYPT_KEY=your-encrypt-key

此密钥可在 Feishu 应用的 Event Subscriptions 部分找到。设置后，适配器使用以下签名算法验证每个 webhook 请求：

SHA256(timestamp + nonce + encrypt_key + body)

提示

在 WebSocket 模式下，签名验证由 SDK 本身处理，因此 FEISHU_ENCRYPT_KEY 是可选的。在 webhook 模式下，强烈建议生产环境使用。

群组消息策略

FEISHU_GROUP_POLICY 环境变量控制 Hermes 在群聊中的响应方式：

FEISHU_GROUP_POLICY=allowlist   # 默认

值	行为
open	Hermes 响应任何群中任何用户的 @mention
allowlist	Hermes 仅响应 FEISHU_ALLOWED_USERS 中用户的 @mention
disabled	Hermes 完全忽略所有群组消息

交互式卡片操作

当用户点击按钮或与机器人发送的交互式卡片交互时，适配器将这些作为合成 /card 命令事件路由：

• 按钮点击变为：/card button {"key": "value", ...}
• 卡定义中的 value 负载作为 JSON 包含在内

注意

交互式卡片需要 Feishu 开发者控制台中的三步配置。缺少任何一步都会导致用户点击卡片按钮时返回错误 200340。

媒体支持

入站（接收）

适配器接收并缓存以下媒体类型：

类型	扩展名	处理方式
图片	.jpg, .png, .gif, .webp, .bmp	通过 Feishu API 下载并本地缓存
音频	.ogg, .mp3, .wav, .m4a, .aac, .flac, .opus, .webm	下载并缓存；小型文本文件自动提取
视频	.mp4, .mov, .avi, .mkv, .webm, .m4v, .3gp	下载并缓存为文档
文件	.pdf, .doc, .docx, .xls, .xlsx, .ppt, .pptx 等	下载并缓存为文档

出站（发送）

方法	发送内容
send	文本或富文本消息（基于 markdown 内容自动检测）
send_image / send_image_file	上传图片到 Feishu，作为原生图片气泡发送
send_document	上传文件到 Feishu API，作为文件附件发送
send_voice	上传音频文件作为 Feishu 文件附件
send_video	上传视频并作为原生媒体消息发送

突发保护与批处理

适配器包含对快速消息突发的去抖处理：

文本批处理

当用户快速发送多条文本消息时，它们会被合并成单个事件再分派：

| 设置 | 环境变量 | 默认值 | |---------|---------|---------|---------| | 安静期 | 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秒 |

所有环境变量

| 变量 | 必填 | 默认值 | 描述 | |----------|----------|---------|-------------|-------------| | FEISHU_APP_ID | ✅ | — | Feishu/Lark App ID | | FEISHU_APP_SECRET | ✅ | — | Feishu/Lark App Secret | | FEISHU_DOMAIN | — | feishu | feishu（中国）或 lark（国际） | | FEISHU_CONNECTION_MODE | — | websocket | websocket 或 webhook | | FEISHU_ALLOWED_USERS | — | (空) | 逗号分隔的 open_id 列表用于用户白名单 | | FEISHU_HOME_CHANNEL | — | — | 用于 cron/通知输出的聊天 ID | | FEISHU_ENCRYPT_KEY | — | (空) | Webhook 签名验证的加密密钥 | | FEISHU_VERIFICATION_TOKEN | — | (空) | Webhook 负载认证的验证令牌 | | FEISHU_GROUP_POLICY | — | allowlist | 群组消息策略：open、allowlist、disabled | | FEISHU_WEBHOOK_HOST | — | 127.0.0.1 | Webhook 服务器绑定地址 | | FEISHU_WEBHOOK_PORT | — | 8765 | Webhook 服务器端口 | | FEISHU_WEBHOOK_PATH | — | /feishu/webhook | Webhook 端点路径 |

故障排除

问题	修复
lark-oapi 未安装	安装 SDK：pip install lark-oapi
websockets 未安装；websocket 模式不可用	安装 websockets：pip install websockets
aiohttp 未安装；webhook 模式不可用	安装 aiohttp：pip install aiohttp
FEISHU_APP_ID 或 FEISHU_APP_SECRET 未设置	设置两个环境变量或通过 hermes gateway setup 配置
点击审批按钮时错误 200340	在 Feishu 开发者控制台中启用 Interactive Card 能力并配置 Card Request URL