飛書 / Lark 集成設置

Hermes Agent 與飛書和 Lark 集成，作為功能完整的機器人使用。連接成功後，您可以在私聊或群聊中與該 Agent 交流，通過主聊天接收定時任務結果，並通過常規網關流程發送文本、圖片、音頻和文件附件。

該集成支持兩種連接模式：

websocket — 推薦使用；Hermes 主動發起出站連接，無需公開的 Webhook 端點
webhook — 當您希望飛書/Lark 通過 HTTP 向您的網關推送事件時非常有用

Hermes 的行為表現

上下文	行為
私聊	Hermes 對每條消息都作出響應。
群聊	Hermes 僅在被 @ 提及的情況下才響應。
共享群聊	默認情況下，共享群聊中的會話歷史按用戶隔離。

此共享群聊行為由 config.yaml 控制：

group_sessions_per_user: true

僅當您明確希望每個群聊共享一個統一對話時，才將其設置為 false。

第一步：創建飛書 / Lark 應用

打開飛書或 Lark 開發者控制檯：
- 飛書：https://open.feishu.cn/
- Lark：https://open.larksuite.com/
創建一個新應用。
在 憑證與基本信息 中，複製 App ID 和 App Secret。
為應用啟用 機器人 功能。

注意

請妥善保管 App Secret。任何持有該密鑰的人都可以冒充您的應用。

第二步：選擇連接模式

推薦：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），並在以下地址提供飛書端點：

/feishu/webhook

要求： 必須安裝 aiohttp Python 包。

您可以自定義 Webhook 服務器的綁定地址和路徑：

FEISHU_WEBHOOK_HOST=127.0.0.1   # 默認：127.0.0.1
FEISHU_WEBHOOK_PORT=8765         # 默認值：8765
FEISHU_WEBHOOK_PATH=/feishu/webhook  # 默認值：“0”

當飛書發送 URL 驗證挑戰（type: url_verification）時，Webhook 會自動響應，以便您在飛書開發者控制檯中完成訂閱設置。

第三步：配置 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 國際版

第四步：啟動網關

hermes gateway

然後從飛書/Lark 向機器人發送消息，以確認連接已激活。

主聊天（Home Chat）

在飛書/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 完全忽略所有群組消息。

在所有模式下，機器人必須在群組中被顯式 @提及（或 @所有人）後，消息才會被處理。私信消息則繞過此限制。

@提及門控的機器人身份

為了在群組中精確檢測 @提及，適配器需要知道機器人的身份。該身份可以顯式提供：

FEISHU_BOT_OPEN_ID=ou_xxx
FEISHU_BOT_USER_ID=xxx
FEISHU_BOT_NAME=MyBot

如果以上均未設置，適配器將在啟動時通過 Application Info API 嘗試自動發現機器人名稱。為此，需授予 admin:app.info:readonly 或 application:application:self_manage 權限範圍。

交互式卡片操作

當用戶點擊由機器人發送的交互式卡片上的按鈕或進行其他交互時，適配器會將這些操作作為合成的 /card 命令事件進行路由：

按鈕點擊變為：/card button {"key": "value", ...}
卡片定義中的操作 value 負載會以 JSON 格式包含在內。
卡片操作在 15 分鐘窗口內去重，以防止重複處理。

卡片操作事件以 MessageType.COMMAND 類型分發，因此會通過正常的命令處理流程。

要使用此功能，請在飛書應用的事件訂閱中啟用 交互式卡片 事件（card.action.trigger）。

媒體支持

入站（接收）

適配器會接收並緩存來自用戶的以下媒體類型：

類型	擴展名	處理方式
圖片	.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 等	下載並緩存為文檔

來自富文本（帖子）消息的媒體內容，包括內聯圖片和文件附件，也會被提取並緩存。

對於小尺寸的文本類文檔（.txt, .md），文件內容會自動注入到消息文本中，使 Agent 可以直接讀取，無需調用工具。

出站（發送）

方法	發送內容
`send`	文本或富文本帖子消息（根據 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 渲染與帖子回退

當出站文本包含 Markdown 格式（標題、粗體、列表、代碼塊、鏈接等）時，適配器會自動將其作為飛書帖子消息發送，並嵌入 md 標籤，而非純文本。這可在飛書客戶端中實現富文本渲染。

如果飛書 API 拒絕帖子負載（例如因不支持某些 Markdown 構造），適配器會自動回退為發送純文本並移除 Markdown 格式。這種兩階段回退機制確保消息始終能送達。

未檢測到 Markdown 的純文本消息將以簡單的 text 消息類型發送。

ACK Emoji 反饋

當適配器接收到入站消息時，會立即添加 ✅（OK）emoji 反饋，以表明消息已被接收並正在處理。這為 Agent 完成響應前提供了視覺反饋。

該反饋是持久的——在響應發送後，該 emoji 仍保留在消息上，作為接收憑證。

用戶對機器人消息的 emoji 反饋也會被追蹤。如果用戶在機器人發送的消息上添加或移除 emoji 反饋，該操作會被路由為合成文本事件（reaction:added:EMOJI_TYPE 或 reaction:removed:EMOJI_TYPE），以便 Agent 能夠響應用戶反饋。

突發保護與批量處理

適配器包含對快速消息洪流的去抖處理，以避免過度壓垮 Agent：

文本批量處理

當用戶在短時間內連續發送多條文本消息時，這些消息將在分發前合併為單個事件：

設置	環境變量	默認值
靜默期	`HERMES_FEISHU_TEXT_BATCH_DELAY_SECONDS`	0.6s
每批最大消息數	`HERMES_FEISHU_TEXT_BATCH_MAX_MESSAGES`	8
每批最大字符數	`HERMES_FEISHU_TEXT_BATCH_MAX_CHARS`	4000

媒體批量處理

快速連續發送多個媒體附件（例如拖拽多個圖片）會被合併為單個事件：

設置	環境變量	默認值
靜默期	`HERMES_FEISHU_MEDIA_BATCH_DELAY_SECONDS`	0.8s

按聊天序列化

同一聊天內的消息按順序處理（一次一個），以保持對話連貫性。每個聊天擁有獨立的鎖，因此不同聊天的消息可併發處理。

速率限制（Webhook 模式）

在 webhook 模式下，適配器會針對每個 IP 地址實施速率限制，以防止濫用：

窗口：60 秒滑動窗口
限制：每個窗口內，針對 (app_id, path, 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 ping 之間的秒數（可選；如果未設置，則默認為 SDK）

設置	配置鍵	默認值	描述
重連間隔	`ws_reconnect_interval`	120s	重連嘗試之間的等待時間
心跳間隔	`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"          # 打開|允許名單|黑名單|僅限管理員|關閉
          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"

策略	描述
`open`	群組內任何人均可使用機器人
`allowlist`	僅群組 `allowlist` 中的用戶可使用機器人
`blacklist`	除群組 `blacklist` 中的用戶外，其他人均可使用機器人
`admin_only`	僅全局 `admins` 列表中的用戶可在該群組使用機器人
`disabled`	機器人忽略該群組的所有消息

未在 group_rules 中列出的群組將回退到 default_group_policy（默認值為 FEISHU_GROUP_POLICY 的值）。

去重機制

入站消息通過消息 ID 進行去重，TTL 為 24 小時。去重狀態在重啟之間持久化保存至 ~/.hermes/feishu_seen_message_ids.json。

設置	環境變量	默認值
緩存大小	`HERMES_FEISHU_DEDUP_CACHE_SIZE`	2048 條記錄

所有環境變量

變量	是否必需	默認值	描述
`FEISHU_APP_ID`	✅	—	飛書/飛書 Lark 應用 ID
`FEISHU_APP_SECRET`	✅	—	飛書/飛書 Lark 應用密鑰
`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_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 未安裝`	安裝 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` 進行配置
`另一個本地 Hermes 網關正在使用此 Feishu app_id`	同一 app_id 同一時間只能被一個 Hermes 實例使用。請先停止其他網關。
機器人在群組中無響應	確保機器人被 @ 提及，檢查 `FEISHU_GROUP_POLICY`，若策略為 `allowlist`，請確認發送者在 `FEISHU_ALLOWED_USERS` 列表中
`Webhook 被拒絕：無效的驗證令牌`	確保 `FEISHU_VERIFICATION_TOKEN` 與 Feishu 應用的事件訂閱配置中的令牌一致
`Webhook 被拒絕：無效的簽名`	確保 `FEISHU_ENCRYPT_KEY` 與 Feishu 應用配置中的加密密鑰一致
發送的消息顯示為純文本	Feishu API 拒絕了發送負載；這是正常的降級行為。請檢查日誌以獲取詳細信息。
機器人未收到圖片/文件	為您的 Feishu 應用授予 `im:message` 和 `im:resource` 權限範圍
機器人身份無法自動檢測	授予 `admin:app.info:readonly` 權限範圍，或手動設置 `FEISHU_BOT_OPEN_ID` / `FEISHU_BOT_NAME`
`Webhook 請求頻率超出限制`	同一 IP 地址每分鐘請求超過 120 次。這通常是配置錯誤或循環導致的。

工具集

飛書 / Lark 使用 hermes-feishu 平臺預設，包含與 Telegram 及其他基於網關的消息平臺相同的通用工具。

Hermes 的行為表現​

第一步：創建飛書 / Lark 應用​

第二步：選擇連接模式​

推薦：WebSocket 模式​

可選：Webhook 模式​

第三步：配置 Hermes​

選項 A：交互式設置​

選項 B：手動配置​

第四步：啟動網關​

主聊天（Home Chat）​

安全性​

用戶白名單​

Webhook 加密密鑰​

驗證令牌​

群聊消息策略​

@提及門控的機器人身份​

交互式卡片操作​

媒體支持​

入站（接收）​

出站（發送）​

Markdown 渲染與帖子回退​

ACK Emoji 反饋​

突發保護與批量處理​

文本批量處理​

媒體批量處理​

按聊天序列化​

速率限制（Webhook 模式）​

Webhook 異常追蹤​

WebSocket 調優​

按群組訪問控制​

去重機制​

所有環境變量​

故障排除​

工具集​