hermes教程-飞书 / Lark 设置

飞书 / Lark 设置

Hermes Agent 与飞书和 Lark 集成，作为一个功能完整的机器人。连接后，您可以在私聊或群聊中与代理对话，在家庭聊天中接收定时任务结果，并通过标准网关流程发送文本、图片、音频和文件附件。

该集成支持两种连接模式：

• websocket — 推荐；Hermes 发起出站连接，您无需公共 webhook 端点
• webhook — 当您希望飞书/Lark 通过 HTTP 将事件推送到您的网关时使用

Hermes 的行为

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

group_sessions_per_user: true

仅当您明确希望每个聊天共享一个会话时，才将其设置为 false。

步骤 1：创建飞书 / Lark 应用

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

hermes gateway setup

选择 飞书 / Lark，然后使用飞书或 Lark 移动应用扫描二维码。Hermes 将自动创建一个具有正确权限的机器人应用并保存凭据。

备选：手动设置

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

1. 打开飞书或 Lark 开发者控制台：
   • 飞书：https://open.feishu.cn/
   • Lark：https://open.larksuite.com/
2. 创建一个新应用。
3. 在 凭据与基本信息 中，复制 App ID 和 App Secret。
4. 为应用启用 机器人 能力。
5. 运行 hermes gateway setup，选择 飞书 / Lark，并在提示时输入凭据。

警告

请保密 App Secret。任何拥有它的人都可以冒充您的应用。

配置权限

在飞书开发者控制台中，转到 权限管理 并添加以下范围。您可以在权限页面批量导入它们。

必需权限：

推荐权限（用于完整功能）：

配置事件

在 事件与回调 中：

1. 将连接模式设置为 长连接（WebSocket）（推荐）或配置 webhook URL
2. 在 事件配置 部分，订阅：
   • im.message.receive_v1 — 接收消息必需

发布应用

配置权限和事件后，转到 版本管理 并发布应用的新版本。权限在版本发布并批准后才会生效（对于企业应用，可能需要管理员批准）。

步骤 2：选择连接模式

推荐：WebSocket 模式

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

FEISHU_CONNECTION_MODE=websocket

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

工作原理： 适配器在后台执行线程中运行 Lark SDK 的 WebSocket 客户端。入站事件（消息、反应、卡片操作）被分发到主 asyncio 循环。断开连接时，SDK 将自动尝试重连。

可选：Webhook 模式

仅当您已经在可访问的 HTTP 端点后运行 Hermes 时，才使用 webhook 模式。

FEISHU_CONNECTION_MODE=webhook

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

要求： 必须安装 aiohttp Python 包。

您可以自定义 webhook 服务器的绑定地址和路径：

FEISHU_WEBHOOK_HOST=127.0.0.1   # 默认：127.0.0.1
FEISHU_WEBHOOK_PORT=8765         # 默认：8765
FEISHU_WEBHOOK_PATH=/feishu/webhook  # 默认：/feishu/webhook

当飞书发送 URL 验证挑战（type: url_verification）时，webhook 会自动响应，以便您在飞书开发者控制台中完成订阅设置。当设置了 FEISHU_VERIFICATION_TOKEN 时，挑战响应会受其门控——缺少或令牌不匹配的挑战请求将被拒绝，以防止未经身份验证的远程通过回显攻击者控制的挑战数据来证明端点控制。

步骤 3：配置 Hermes

选项 A：交互式设置

hermes gateway setup

选择 飞书 / 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

然后从飞书/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 请求：

计算出的哈希值使用时间安全比较与 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   # 默认

在所有模式下，机器人必须被显式 @提及（或 @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

也可在 config.yaml 中配置为 feishu.allow_bots（两者都设置时环境变量优先）。

对等机器人不需要添加到 FEISHU_ALLOWED_USERS——该白名单仅适用于人类发送者。

授予 application:bot.basic_info:read 范围以显示对等机器人名称；没有它，对等机器人仍能正确路由，但会显示为它们的 open_id。

交互式卡片操作

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

• 按钮点击变为：/card button {"key": "value", ...}
• 卡片定义中的 value 负载作为 JSON 包含在内。
• 卡片操作在 15 分钟窗口内去重，以防止重复处理。

网关驱动的更新提示使用原生的飞书 是 / 否 卡片，而不是回退到纯文本回复。当 hermes update --gateway 需要确认时，适配器将选定的答案记录在 Hermes 的 .update_response 文件中，并内联替换卡片为已解决状态。

卡片操作事件以 MessageType.COMMAND 分发，因此它们通过正常的命令处理管道流动。

这也是 命令批准 的工作方式——当代理需要运行危险命令时，它会发送一个带有“允许一次”/“会话”/“始终”/“拒绝”按钮的交互式卡片。用户点击一个按钮，卡片操作回调将批准决定返回给代理。

必需的飞书应用配置

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

1. 订阅卡片操作事件： 在 事件订阅 中，将 card.action.trigger 添加到您订阅的事件中。

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

3. 配置卡片请求 URL（仅 webhook 模式）： 在 应用功能 > 机器人 > 消息卡片请求 URL 中，将 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 工具集运行代理。
• 将回复分块为 4000 字符，并作为线程回复发布。
• 缓存每个文档的会话 1 小时，最多 50 条消息，以便对同一文档的后续评论保持上下文。

3 层访问控制

文档评论回复是 显式授权 的——没有隐式的全部允许模式。权限按以下顺序解析（每个字段第一个匹配获胜）：

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

每个规则有两种策略可用：

• allowlist — 用户/租户的静态列表。
• pairing — 静态列表 ∪ 运行时批准的存储。适用于版主可以实时授予访问权限的推广。

规则位于 ~/.hermes/feishu_comment_rules.json（配对授权位于 ~/.hermes/feishu_comment_pairing.json），具有 mtime 缓存的自动重载——编辑后无需重启网关即可在下一个评论事件生效。

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 范围，以便处理程序可以读取文档内容。

会议邀请事件

您可以像邀请人类参与者一样，将 Hermes 飞书/Lark 机器人邀请到视频会议中。当机器人收到会议邀请事件时，Hermes 可以自动启动一个代理轮次，尝试加入会议。

由 vc.bot.meeting_invited_v1 事件驱动，流程如下：

• 用户邀请机器人参加飞书/Lark 视频会议。
• 飞书/Lark 向 Hermes 发送会议邀请事件。
• Hermes 提取邀请者、会议主题和会议号码。
• 如果邀请者已通过标准网关白名单或配对策略授权，代理将收到会议号码并尝试自动加入。
• 如果邀请格式错误，或代理无法加入，Hermes 将丢弃该事件或向邀请者回复简洁的解释。

格式错误的邀请（不包含邀请者和 meeting_no）将被忽略。

必需的飞书应用配置

在已授予的聊天/卡片权限基础上，添加视频会议邀请事件：

• 在 事件订阅 中订阅 vc.bot.meeting_invited_v1。
• 启用飞书/Lark 开发者控制台为该事件提示的视频会议权限范围。
• 保持 im:message 和 im:message:send_as_bot 启用，以便 Hermes 可以回复邀请者。
• 确保网关用户白名单或配对策略授权了邀请者。会议邀请不会绕过正常的网关访问检查。

媒体支持

入站（接收）

适配器接收并缓存来自用户的以下媒体类型：

来自富文本（post）消息的媒体，包括内联图片和文件附件，也会被提取并缓存。

对于基于文本的小型文档（.txt, .md），文件内容会自动注入到消息文本中，以便代理无需工具即可直接读取。

出站（发送）

文件上传路由根据扩展名自动进行：

• .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 消息类型发送。

处理状态反应

当代理正在工作时，机器人会在您的消息上显示一个 Typing 反应。当回复到达时，它会被清除，如果处理失败则替换为 CrossMark。

设置 FEISHU_REACTIONS=false 以关闭它。

突发保护与批处理

适配器包含对快速消息突发的去抖处理，以避免压垮代理：

文本批处理

当用户快速连续发送多条文本消息时，它们会在分发前合并为单个事件：

媒体批处理

快速连续发送的多个媒体附件（例如，拖拽多张图片）会合并为单个事件：

每聊天串行化

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

速率限制（Webhook 模式）

在 webhook 模式下，适配器强制执行每 IP 速率限制以防止滥用：

• 窗口： 60 秒滑动窗口
• 限制： 每个窗口每个 (app_id, path, IP) 三元组 120 个请求
• 跟踪上限： 最多跟踪 4096 个唯一键（防止无界内存增长）

超过限制的请求会收到 HTTP 429（请求过多）。

Webhook 异常跟踪

适配器跟踪每个 IP 地址的连续错误响应。如果在 6 小时窗口内同一 IP 出现 25 次连续错误，则会记录警告。这有助于检测配置错误的客户端或探测尝试。

其他 webhook 保护措施：

• 正文大小限制： 最大 1 MB
• 正文读取超时： 30 秒
• Content-Type 强制： 仅接受 application/json

WebSocket 调优

使用 websocket 模式时，您可以自定义重连和 ping 行为：

platforms:
  feishu:
    extra:
      ws_reconnect_interval: 120   # 重连尝试之间的秒数（默认：120）
      ws_ping_interval: 30         # WebSocket ping 之间的秒数（可选；未设置时使用 SDK 默认值）

按群组访问控制

除了全局的 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

在 group_rules 条目上设置 require_mention: false 以跳过该特定聊天的 @提及 要求。省略时，聊天继承全局的 FEISHU_REQUIRE_MENTION 值。

未在 group_rules 中列出的群组回退到 default_group_policy（默认为 FEISHU_GROUP_POLICY 的值）。

去重

入站消息使用消息 ID 进行去重，TTL 为 24 小时。去重状态在重启后持久化到 ~/.hermes/feishu_seen_message_ids.json。

所有环境变量

WebSocket 和按群组 ACL 设置通过 config.yaml 在 platforms.feishu.extra 下配置（请参阅上面的 WebSocket 调优 和 按群组访问控制）。

故障排除

工具集

飞书 / Lark 使用 hermes-feishu 平台预设，其中包括与 Telegram 和其他基于网关的消息平台相同的核心工具。