<!-- Source: https://hermesbible.com/docs/user-guide/messaging/feishu -->

Section: Messaging Platforms · URL: https://hermesbible.com/docs/user-guide/messaging/feishu

Feishu / Lark 設定指南

Hermes Agent 與 Feishu 和 Lark 整合為功能完整的機器人。連線後，你可以在私訊或群組聊天中與 Agent 對話、在主聊天室接收定時任務的執行結果，並透過一般的閘道流程傳送文字、圖片、音訊和檔案附件。

此整合支援兩種連線模式：

• websocket — 建議使用；Hermes 主動開啟外連連線，不需要公開的 webhook 端點
• webhook — 當你希望 Feishu/Lark 透過 HTTP 將事件推送到閘道時使用

Hermes 的行為模式

共用聊天的行為由 config.yaml 控制：

group_sessions_per_user: true

只有在你明確希望每個聊天共用一個對話時，才設為 false。

步驟 1：建立 Feishu / Lark 應用程式

建議方式：掃碼建立（單一指令）

hermes gateway setup

選擇 Feishu / Lark，然後用 Feishu 或 Lark 行動應用程式掃描 QR code。Hermes 會自動建立具有正確權限的機器人應用程式並儲存憑證。

替代方式：手動設定

如果掃碼建立不可用，設定精靈會退回手動輸入：

1. 開啟 Feishu 或 Lark 開發者主控台：
   • Feishu：https://open.feishu.cn/
   • Lark：https://open.larksuite.com/
2. 建立新應用程式。
3. 在 憑證與基本資訊 中，複製 App ID 和 App Secret。
4. 為應用程式啟用 機器人 功能。
5. 執行 hermes gateway setup，選擇 Feishu / Lark，並在提示時輸入憑證。

WARNING

請妥善保管 App Secret。任何取得此密鑰的人都可以冒充你的應用程式。

設定權限

在 Feishu 開發者主控台中，前往 權限管理 並新增以下範圍。你可以在權限頁面中大量匯入。

必要權限：

建議權限（以獲得完整功能）：

設定事件

在 事件與回呼 中：

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 模式

只有在你已將 Hermes 運行在可存取的 HTTP 端點後方時，才使用 webhook 模式。

FEISHU_CONNECTION_MODE=webhook

在 webhook 模式下，Hermes 會啟動一個 HTTP 伺服器（透過 aiohttp）並在以下路徑提供 Feishu 端點：

/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  # 預設值：/feishu/webhook

當 Feishu 傳送 URL 驗證挑戰（type: url_verification）時，webhook 會自動回應，讓你可以在 Feishu 開發者主控台中完成訂閱設定。當設定了 FEISHU_VERIFICATION_TOKEN 時，挑戰回應會受到驗證——缺少或不匹配 token 的挑戰請求會被拒絕，以防止未經驗證的遠端透過回送攻擊者控制的挑戰資料來證明端點控制權。

步驟 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 用於中國版 Feishu
• lark 用於國際版 Lark

步驟 4：啟動閘道

hermes gateway

然後從 Feishu/Lark 訊息機器人以確認連線已建立。

主聊天室

在 Feishu/Lark 聊天中使用 /set-home 將該聊天標記為定時任務結果和跨平台通知的主頻道。

你也可以預先設定：

FEISHU_HOME_CHANNEL=oc_xxx

安全性

使用者允許名單

在正式環境中，設定 Feishu Open ID 的允許名單：

FEISHU_ALLOWED_USERS=ou_xxx,ou_yyy

如果你將允許名單留空，任何能存取機器人的人都可能使用它。在群組聊天中，訊息處理前會先檢查寄件者的 open_id 是否在允許名單中。

Webhook 加密金鑰

在 webhook 模式下運行時，設定加密金鑰以啟用傳入 webhook 負載的簽章驗證：

FEISHU_ENCRYPT_KEY=your-encrypt-key

此金鑰可在 Feishu 應用程式設定的 事件訂閱 區段中找到。設定後，適配器會使用以下簽章演算法驗證每個 webhook 請求：

SHA256(timestamp + nonce + encrypt_key + body)

計算出的雜湊值會透過時間安全比較與 x-lark-signature 標頭進行比對。簽章無效或缺少簽章的請求會被回傳 HTTP 401。

TIP

在 WebSocket 模式下，簽章驗證由 SDK 自行處理，因此 FEISHU_ENCRYPT_KEY 是選用的。在 webhook 模式下，強烈建議在正式環境中設定。

驗證 Token

額外的驗證層，用於檢查 webhook 負載中的 token 欄位：

FEISHU_VERIFICATION_TOKEN=your-verification-token

此 token 也可在 Feishu 應用程式設定的 事件訂閱 區段中找到。設定後，每個傳入的 webhook 負載必須在其 header 物件中包含匹配的 token。不匹配的 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 和顯示名稱。只有在自動偵測無法存取 Feishu 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 分鐘的時間窗口進行去重，以防止重複處理。

閘道驅動的更新提示會使用原生的 Feishu 是 / 否 卡片，而非退回純文字回覆。當 hermes update --gateway 需要確認時，適配器會將選擇的答案記錄在 Hermes 的 .update_response 檔案中，並以已解決狀態原地替換卡片。

卡片互動事件以 MessageType.COMMAND 分派，因此會經過一般的指令處理管線。

這也是指令審核的運作方式 — 當 Agent 需要執行危險指令時，它會傳送一個帶有「允許一次」/「本次會話」/「總是允許」/「拒絕」按鈕的互動式卡片。使用者點擊按鈕後，卡片互動回呼會將審核決定傳回給 Agent。

必要的 Feishu 應用程式設定

互動式卡片需要在 Feishu 開發者主控台中完成三個設定步驟。缺少任何一個都會在使用者點擊卡片按鈕時產生錯誤 200340。

1. 訂閱卡片互動事件： 在 事件訂閱 中，將 card.action.trigger 加入已訂閱的事件。

2. 啟用互動式卡片功能： 在 應用功能 > 機器人 中，確認 互動式卡片 開關已啟用。這會告訴 Feishu 你的應用程式可以接收卡片互動回呼。

3. 設定卡片請求 URL（僅限 webhook 模式）： 在 應用功能 > 機器人 > 訊息卡片請求 URL 中，將 URL 設為與你的事件 webhook 相同的端點（例如 https://your-server:8765/feishu/webhook）。在 WebSocket 模式下，這由 SDK 自動處理。

WARNING

若未完成全部三個步驟，Feishu 會成功傳送互動式卡片（傳送只需 im:message:send 權限），但點擊任何按鈕都會回傳錯誤 200340。卡片看起來正常運作 — 錯誤只會在使用者互動時才出現。

文件留言智慧回覆

除了聊天之外，適配器也能回應在 Feishu/Lark 文件 上留下的 @ 提及。當使用者在文件上留言（區域文字選取或整份文件的留言）並 @提及機器人時，Hermes 會讀取文件內容及周邊的留言串，並在留言串中直接張貼 LLM 回覆。

由 drive.notice.comment_add_v1 事件驅動，處理器：

• 並行擷取文件內容和留言時間軸（整份文件留言串 20 則訊息，區域選取留言串 12 則）。
• 使用 feishu_doc + feishu_drive 工具集，限定在該留言串的範圍內執行 Agent。
• 以 4000 字元為單位切割回覆，並以串接回覆方式發回。
• 為每個文件快取 session 1 小時（上限 50 則訊息），使同一文件的後續留言能保留上下文。

三層存取控制

文件留言回覆採用明確授權模式 — 沒有隱含的全允許模式。權限按以下順序解析（每個欄位的第一個匹配結果生效）：

1. 精確文件 — 針對特定文件 token 的規則。
2. 萬用字元 — 匹配文件模式的規則。
3. 頂層 — 工作區的預設規則。

每個規則可使用兩種策略：

• allowlist — 靜態的使用者/租戶名單。
• pairing — 靜態名單 ∪ 運行時核准的儲存庫。適用於審核者可即時授權的部署場景。

規則儲存在 ~/.hermes/feishu_comment_rules.json（pairing 授權儲存在 ~/.hermes/feishu_comment_pairing.json），支援修改時間快取的熱重載 — 編輯會在下一個留言事件時生效，無需重啟閘道。

CLI 指令：

# 檢視目前的規則和 pairing 狀態
python -m gateway.platforms.feishu_comment_rules status

# 模擬特定文件 + 使用者的存取檢查
python -m gateway.platforms.feishu_comment_rules check <fileType:fileToken> <user_open_id>

# 在運行時管理 pairing 授權
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>

必要的 Feishu 應用程式設定

在已授予的聊天/卡片權限之外，還需新增文件留言事件：

• 在 事件訂閱 中訂閱 drive.notice.comment_add_v1。
• 授予 docs:doc:readonly 和 drive:drive:readonly 範圍，使處理器能夠讀取文件內容。

會議邀請事件

你可以像邀請真人參與者一樣，將 Hermes Feishu/Lark 機器人邀請到視訊會議中。當機器人收到會議邀請事件時，Hermes 會自動啟動一個 Agent 回合，嘗試加入會議。

由 vc.bot.meeting_invited_v1 事件驅動，流程如下：

• 使用者邀請機器人加入 Feishu/Lark 視訊會議。
• Feishu/Lark 將會議邀請事件傳送給 Hermes。
• Hermes 提取邀請者、會議主題和會議號碼。
• 如果邀請者已通過一般閘道允許名單或 pairing 策略的授權，Agent 會收到會議號碼並嘗試自動加入。
• 如果邀請格式不正確，或 Agent 無法加入，Hermes 會丟棄事件或以簡潔的說明回覆邀請者。

缺少邀請者或 meeting_no 的格式不正確邀請會被忽略。

必要的 Feishu 應用程式設定

在已授予的聊天/卡片權限之外，還需新增視訊會議邀請事件：

• 在 事件訂閱 中訂閱 vc.bot.meeting_invited_v1。
• 啟用 Feishu/Lark 開發者主控台為該事件提示的視訊會議權限範圍。
• 保持 im:message 和 im:message:send_as_bot 啟用，以便 Hermes 能回覆邀請者。
• 確認閘道使用者允許名單或 pairing 策略已授權邀請者。會議邀請不會繞過一般的閘道存取檢查。

媒體支援

接收端（收到）

適配器從使用者接收並快取以下媒體類型：

富文字（post）訊息中的媒體，包括內嵌圖片和檔案附件，也會被提取並快取。

對於小型文字文件（.txt, .md），檔案內容會自動注入訊息文字中，讓 Agent 無需使用工具即可直接讀取。

傳送端（發出）

檔案上傳路由會根據副檔名自動判斷：

• .ogg, .opus → 以 opus 音訊上傳
• .mp4, .mov, .avi, .m4v → 以 mp4 媒體上傳
• .pdf, .doc(x), .xls(x), .ppt(x) → 以其文件類型上傳
• 其他所有檔案 → 以通用串流檔案上傳

Markdown 渲染與 Post 退回

當傳出的文字包含 markdown 格式（標題、粗體、列表、程式碼區塊、連結等）時，適配器會自動將其作為帶有內嵌 md 標籤的 Feishu post 訊息傳送，而非純文字。這可在 Feishu 用戶端中實現富格式渲染。

如果 Feishu API 拒絕 post 負載（例如因為不支援的 markdown 結構），適配器會自動退回為傳送去除 markdown 的純文字。這兩階段退回機制確保訊息始終能被送達。

純文字訊息（未偵測到 markdown）會以簡單的 text 訊息類型傳送。

處理狀態回應

當 Agent 正在處理時，機器人會在你的訊息上顯示 Typing 回應。回覆到達時會清除，處理失敗則會替換為 CrossMark。

設定 FEISHU_REACTIONS=false 可關閉此功能。

突發保護與批次處理

適配器包含對快速訊息突發的防抖機制，以避免 Agent 過載：

文字批次處理

當使用者在短時間內連續發送多則文字訊息時，會在分派前合併為單一事件：

媒體批次處理

短時間內連續傳送的多個媒體附件（例如拖曳多張圖片）會合併為單一事件：

每聊天序列化

同一聊天中的訊息會以序列化方式（一次處理一則）處理，以維護對話連貫性。每個聊天都有自己的鎖，因此不同聊天中的訊息會並行處理。

速率限制（Webhook 模式）

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

• 時間窗口： 60 秒滑動窗口
• 限制： 每個 (app_id, path, IP) 三元組每個窗口 120 個請求
• 追蹤上限： 最多追蹤 4096 個唯一金鑰（防止無限記憶體成長）

超過限制的請求會收到 HTTP 429（Too Many Requests）。

Webhook 異常追蹤

適配器會追蹤每個 IP 位址的連續錯誤回應。在同一個 IP 於 6 小時窗口內連續產生 25 次錯誤後，會記錄一條警告。這有助於偵測設定錯誤的用戶端或掃描嘗試。

額外的 webhook 防護措施：

• Body 大小限制： 最大 1 MB
• Body 讀取逾時： 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 調校和群組存取控制）。

疑難排解

工具集

Feishu / Lark 使用 hermes-feishu 平台預設工具集，包含與 Telegram 和其他基於閘道的訊息平台相同的核心工具。

---

---

Google Chat