飞书配置

Hermes Agent 以全功能 Bot 的形式集成飞书和 Lark。连接后，你可以在私信或群聊中与 Agent 对话，在主聊天中接收定时任务结果，并通过标准网关流程发送文本、图片、音频和文件附件。

适配器支持两种连接模式：

websocket — 推荐；Hermes 发起出站连接，无需公网 Webhook 端点
webhook — 适用于希望飞书/Lark 通过 HTTP 推送事件到网关的场景

Hermes 在飞书中的行为

场景	行为
私信	Hermes 回复每条消息
群聊	仅在 Bot 被 @提及时回复
共享群聊	默认按用户隔离会话历史

group_sessions_per_user: true     # 默认 — 按用户隔离
# group_sessions_per_user: false  # 共享一个对话

第一步：创建飞书/Lark 应用

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

hermes gateway setup

选择 Feishu / Lark，用飞书或 Lark 手机 App 扫描 QR 码。Hermes 会自动创建具有正确权限的 Bot 应用并保存凭据。

替代方案：手动设置

打开飞书或 Lark 开发者控制台：
- 飞书：https://open.feishu.cn/
- Lark：https://open.larksuite.com/
创建新应用
在 凭据与基础信息 中，复制 App ID 和 App Secret
为应用启用 机器人 能力
运行 hermes gateway setup，选择 Feishu / Lark，输入凭据

第二步：选择连接模式

推荐：WebSocket 模式

当 Hermes 运行在笔记本电脑、工作站或私有服务器上时使用。无需公网 URL。官方 Lark SDK 开启并维护持久化出站 WebSocket 连接，自动重连。

FEISHU_CONNECTION_MODE=websocket

需要 websockets Python 包。SDK 内部处理连接生命周期、心跳和自动重连。

可选：Webhook 模式

仅在 Hermes 运行在可达的 HTTP 端点后面时使用。

FEISHU_CONNECTION_MODE=webhook

Webhook 模式下，Hermes 启动 HTTP 服务器（通过 aiohttp），在 /feishu/webhook 提供飞书端点。

可自定义绑定地址和路径：

FEISHU_WEBHOOK_HOST=127.0.0.1        # 默认: 127.0.0.1
FEISHU_WEBHOOK_PORT=8765              # 默认: 8765
FEISHU_WEBHOOK_PATH=/feishu/webhook   # 默认: /feishu/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 给 Bot 发消息确认连接正常。

主聊天

在任何飞书/Lark 聊天中使用 /set-home 将其标记为主频道，用于定时任务结果和跨平台通知。

也可以预配置：FEISHU_HOME_CHANNEL=oc_xxx

安全

用户白名单

生产环境请设置飞书 Open ID 白名单：

FEISHU_ALLOWED_USERS=ou_xxx,ou_yyy

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

Webhook 加密密钥

Webhook 模式下，设置加密密钥以启用入站 Webhook 载荷的签名验证：

FEISHU_ENCRYPT_KEY=your-encrypt-key

验证算法：SHA256(timestamp + nonce + encrypt_key + body)，计算哈希与 x-lark-signature 头比较，使用时间安全比较。无效或缺失签名的请求返回 HTTP 401。

验证 Token

额外的认证层，检查 Webhook 载荷内的 token 字段：

FEISHU_VERIFICATION_TOKEN=your-verification-token

FEISHU_ENCRYPT_KEY 和 FEISHU_VERIFICATION_TOKEN 可以同时使用以实现纵深防御。

群组消息策略

FEISHU_GROUP_POLICY 环境变量控制 Hermes 是否以及如何在群聊中回复：

值	行为
`open`	Hermes 回复任何用户在任何群组中的 @提及
`allowlist`	仅回复白名单用户的 @提及（默认）
`disabled`	完全忽略所有群组消息

在所有模式下，Bot 必须被显式 @提及（或 @all）才会处理消息。私信始终绕过此门控。

设置 FEISHU_REQUIRE_MENTION=false 可让 Hermes 读取所有群组消息而无需 @提及。

交互式卡片操作

当用户点击 Bot 发送的交互式卡片上的按钮时，适配器将其路由为合成的 /card 命令事件：

按钮点击变为：/card button {"key": "value", ...}
卡片操作在 15 分钟窗口内去重以防止重复处理

命令审批也通过交互式卡片实现 — Agent 需要运行危险命令时，发送包含”允许一次”/“本次会话”/“始终允许”/“拒绝”按钮的交互式卡片。

必需的飞书应用配置

交互式卡片需要在飞书开发者控制台完成三步配置。缺少任何一步会导致用户点击按钮时出现错误 200340：

订阅卡片操作事件：在事件订阅中添加 card.action.trigger
启用交互式卡片能力：在应用功能 > 机器人中，确保交互式卡片开关已启用
配置卡片请求 URL（仅 Webhook 模式）：在应用功能 > 机器人 > 消息卡片请求 URL 中设置与事件 Webhook 相同的端点

文档评论回复

除了聊天，适配器还可以回答在飞书/Lark 文档上 @提及 Bot 的评论。当用户在文档上评论（本地文本选择或全文评论）并 @提及 Bot 时，Hermes 读取文档及周围评论线程，在线程中内联发布 LLM 回复。

三层访问控制

文档评论回复是显式授权 — 没有隐式的允许全部模式。权限按以下顺序解析（首个匹配生效）：

精确文档 — 限定到特定文档 Token 的规则
通配符 — 匹配文档模式的规则
顶层 — 工作区默认规则

每种规则有两种策略：allowlist（静态用户列表）和 pairing（静态列表 ∪ 运行时批准存储）。

规则存储在 ~/.hermes/feishu_comment_rules.json，支持热重载 — 编辑后无需重启网关。

Markdown 渲染

出站文本包含 Markdown 格式时（标题、粗体、列表、代码块、链接等），适配器自动以飞书富文本消息（post）形式发送，内嵌 md 标签，在飞书客户端中实现富文本渲染。

如果飞书 API 拒绝 post 载荷（如不支持的 Markdown 构造），适配器自动回退为纯文本发送。两阶段回退确保消息始终送达。

处理状态表情

Agent 工作时，Bot 在你的消息上显示 Typing 表情。回复到达时清除，处理失败时替换为 CrossMark。

设置 FEISHU_REACTIONS=false 可关闭。

突发保护与批量处理

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

文本批量

用户快速连续发送多条文本消息时，合并为单个事件：

设置	环境变量	默认值
静默期	`HERMES_FEISHU_TEXT_BATCH_DELAY_SECONDS`	0.6s
每批最大消息数	`HERMES_FEISHU_TEXT_BATCH_MAX_MESSAGES`	8
每批最大字符数	`HERMES_FEISHU_TEXT_BATCH_MAX_CHARS`	4000

按聊天串行化

同一聊天中的消息串行处理（一次一条），以保持对话连贯性。每个聊天有自己的锁，不同聊天的消息并发处理。

常见问题排查

问题	解决方法
启动失败：需要 aiohttp	安装：`pip install aiohttp`
启动失败：需要 websockets	安装：`pip install websockets`（WebSocket 模式需要）
Bot 在线但不回复	检查 Bot 是否被 @提及，检查 `FEISHU_GROUP_POLICY`
卡片按钮返回错误 200340	确保完成上述三步飞书应用配置
Webhook 签名验证失败	检查 `FEISHU_ENCRYPT_KEY` 是否与飞书开发者控制台一致
连接断开	WebSocket 模式会自动重连；Webhook 模式检查端点可达性