把 AI Agent 接上飛書/Lark:新手的第一個企業渠道

在微信、WhatsApp、Telegram、飛書這幾個常用渠道裡，飛書/Lark 是官方能力矩陣唯一每一格都勾的一行：語音、圖片、檔案、主題、表情回應、輸入中提示、串流輸出，全部支援(Hermes 支援的 Discord、Slack、Matrix 同樣全勾，但不在這系列的範圍裡)。它也是「企業場景裡最像 Telegram 的一條路」——有正規的開放平台與官方 Bot 機制，不用掃個人帳號的 QR、不碰灰色地帶。做完這篇文章你會得到：一個能在飛書私訊與群組裡對話的 agent,私訊有問必答，群組被 @ 才開口。全程約 20–30 分鐘。

這篇是新手路徑:走官方推薦的掃碼建應用 + WebSocket 長連線，不需要公網 IP、不需要配 webhook。Hermes 的安裝、初始化、手動建應用的完整細節，以及把 Hermes 當 OpenClaw 維運助手的進階用法，在 安裝 Hermes Agent 與 Hermes 飛書集成進階篇 那篇；這篇專注在「最短路徑收到第一則回覆」與「誰能跟你的 Bot 說話」。

這個渠道的能力邊界

先看官方能力矩陣，飛書這行沒有短板:

平台	語音	圖片	檔案	主題	表情回應	輸入中	串流
Telegram	✅	✅	✅	✅	—	✅	✅
WhatsApp(橋接)	—	✅	✅	—	—	✅	✅
WhatsApp Cloud API	✅	✅	✅	—	—	✅	—
Weixin(微信)	✅	✅	✅	—	—	✅	—
Feishu / Lark	✅	✅	✅	✅	✅	✅	✅

(取自官方 Messaging Gateway 文件的平台對比表。「語音」指 TTS 語音回覆與/或語音訊息轉錄。)

幾個飛書特有的行為，先知道就不會慌:

• 私訊必回，群組要 @:私訊裡 Hermes 回應每一則訊息；群組裡只有 Bot 被 @mention 才處理。共享群組中,session 歷史預設按使用者隔離(group_sessions_per_user: true)——同一個群裡，你和同事各自跟 Bot 對話，互不看到對方的上下文。
• 表情回應就是進度條:agent 處理你的訊息時,Bot 會在該訊息上掛一個「Typing」表情；回覆送達時清除，處理失敗則換成「CrossMark」。不想要這個行為設 FEISHU_REACTIONS=false。
• Markdown 走富文本:出站訊息含 Markdown 時,adapter 自動改用飛書的 post(富文本)訊息鑲嵌渲染；若飛書 API 拒收 post,自動降級為去格式的純文本——訊息不會丟，只是變醜。
• 核准是按鈕，不是打字:agent 要跑危險指令時，發的是一張互動卡片(Allow Once / Session / Always / Deny 按鈕),點按鈕即完成核准。這依賴應用側的回調配置，配錯會報 200340(見常見錯誤)。
• 進階能力:Bot 還能回應飛書文檔評論裡的 @mention(讀文檔與評論串、就地回覆),以及被邀請進視訊會議時自動嘗試入會。這兩項要額外的權限與事件訂閱，新手先跳過，官方文件有完整說明。

前置需求

• 一個飛書(中國版)或 Lark(國際版)帳號，手機上裝好對應 App——掃碼建應用要用。
• 你在所屬企業租戶裡有權建立應用;企業自建應用發布版本時可能需要管理員審批，先確認你能過這一關。
• Hermes Agent 已安裝、模型已配置（見 安裝 Hermes Agent）。
• WebSocket 模式需要 websockets Python 套件；缺了的話 hermes pm repair 能補。
• 觀念上認得 環境變數與 .env 與 API Key 級別的憑證:App Secret 屬於「拿到就能冒充你的應用」那一類，不進聊天視窗、不進版本庫。

步驟

1/6啟動設定精靈

第 1 步，共 6 步 啟動設定精靈

步驟一：啟動設定精靈

hermes gateway setup

預期輸出:方向鍵操作的互動清單，已配置的平台有標記。選擇 Feishu / Lark。

步驟二：掃碼讓 Hermes 自動建應用

精靈首選掃碼建應用:它顯示一個 QR code,用飛書或 Lark 手機 App 掃描並確認。Hermes 會自動建立一個權限正確的 Bot 應用，並把憑證存好——App ID、App Secret 都不用你手抄。

預期輸出:精靈顯示應用建立成功、憑證已寫入。若掃碼建應用在你的環境不可用(例如租戶政策限制),精靈會退回手動輸入模式：到 open.feishu.cn(飛書)或 open.larksuite.com(Lark)建應用，在「憑證與基礎資訊」複製 App ID 與 App Secret,啟用 Bot 能力，再回填給精靈。手動路徑的逐步細節看 進階篇。

步驟三：在開放平台核對三件事(權限、事件、發布)

掃碼建應用會把權限配好，但手動建應用或想驗證時,到開發者後台核對:

1. 權限管理:必要 scope 為 im:message(收發訊息)、im:message:send_as_bot(以 Bot 身分發送)、im:resource(讀取使用者傳的圖片/檔案/音訊)、im:chat 與 im:chat:readonly(群組中繼資料與成員)。權限頁支援批次匯入。
2. 事件與回調:連線模式選長連線(WebSocket)——這是指定的推薦模式,Hermes 主動出站連線，你不需要公網端點；在事件配置頁訂閱 im.message.receive_v1(收訊息的必要事件)。要讓核准按鈕能點，還要在回調配置頁(和事件配置是兩個分頁)加 card.action.trigger,並在應用功能裡開啟互動卡片能力。
3. 版本管理:建立並發布一個版本。權限與事件配置在版本發布(企業應用還需審批通過)之前不會生效——這是新手最常漏的一步。

預期輸出:後台顯示新版本已發布/已通過。

步驟四：設定環境變數

掃碼路徑的憑證已由精靈寫入；手動路徑在 ~/.hermes/.env 補齊:

FEISHU_APP_ID=cli_xxxxxxxxxxxxxxx        # 佔位範例,換成你的
FEISHU_APP_SECRET=your-app-secret        # 佔位範例,換成你的
FEISHU_DOMAIN=feishu                     # 飛書中國版;Lark 國際版填 lark
FEISHU_CONNECTION_MODE=websocket         # 推薦:免公網 IP
# 強烈建議:只放行這些 open_id
FEISHU_ALLOWED_USERS=ou_xxxxxxxx,ou_yyyyyyyy

預期輸出:無——存檔即可。FEISHU_ALLOWED_USERS 填的是飛書的 open_id(形如 ou_ 開頭);不知道自己的 open_id 時，先跳過這行，用步驟五的配對流程取得。

步驟五：啟動 gateway,發第一則訊息

hermes gateway

預期輸出:日誌顯示 feishu adapter 以 WebSocket 模式連線成功。在飛書裡找到這個 Bot 應用、打開私訊，發 /help,再發一句「你好」:

你:你好
(你的訊息上出現「Typing」表情回應)
Bot:(回覆,以富文本渲染)
(Typing 表情消失)

陌生人私訊 Bot 會收到一次性配對碼;你在機器上核准，對方就進入 allowlist:

hermes pairing approve feishu <CODE>
hermes pairing list

從 hermes pairing list 或 gateway 日誌就能拿到對方的 open_id,回填進 FEISHU_ALLOWED_USERS 讓名單固化下來。

步驟六：拉進群組、設 home channel

把 Bot 加入一個群組，@它發一句話——只有被 @ 才會回應，這是預設行為。私訊或群組裡發 /sethome,把該對話設為 home channel:排程任務結果、gateway 重啟通知、其他平台 adapter 熔斷時的告警都送到這裡(也可以直接用 FEISHU_HOME_CHANNEL=oc_xxx 預設，群組 chat ID 形如 oc_ 開頭)。

預期輸出:群組裡 @Bot 得到回覆，未被 @ 的訊息不觸發;/sethome 收到確認。gateway 是單一背景程序服務所有平台，之後再接 Telegram、WhatsApp 不必另開程序；執行中可用 /platform list 看各 adapter 狀態,/platform pause feishu、/platform resume feishu 單獨暫停與恢復。

誰可以跟你的 Bot 說話

Hermes 的安全預設：gateway 拒絕所有不在 allowlist、也沒有經 DM 配對的使用者——對一個有終端機權限的 Bot,這是刻意設計。飛書這條路的完整控制面:

allowlist:FEISHU_ALLOWED_USERS=ou_xxx,ou_yyy(逗號分隔 open_id),或全域 GATEWAY_ALLOWED_USERS。群組裡,allowlist 在訊息被處理前先檢查傳送者的 open_id。GATEWAY_ALLOW_ALL_USERS=true 能一次全開——官方標明不建議，對能執行終端機指令的 Bot 不要這樣做。

DM 配對:不在名單的人私訊 Bot 拿到一次性配對碼，你用 hermes pairing approve feishu <CODE> 核准;hermes pairing list 查看、hermes pairing revoke feishu <id> 撤銷。配對碼 1 小時過期、有速率限制、密碼學亂數產生。

群組政策:FEISHU_GROUP_POLICY 預設 allowlist(只回應名單內使用者的 @),可設 open(任何人的 @ 都回應)或 disabled(群組全關)。注意一個容易困惑的組合：預設 allowlist + 空的 FEISHU_ALLOWED_USERS = 所有人類群訊息都被拒,私訊不受影響；第一次拒收會在日誌記一條 WARNING 告訴你該設哪些鍵。FEISHU_REQUIRE_MENTION=false 可以讓 Bot 讀取群內全部訊息而不必被 @——除非你真的要這個行為，否則保持預設。另外 FEISHU_ALLOW_BOTS 預設 none:其他 Bot 的訊息一律忽略，這同時擋掉了一類 Bot 互相觸發的迴圈與注入面。

分級(admin / 一般使用者):~/.hermes/config.yaml 的 gateway.platforms.feishu.extra 下設 allow_from(能進門)、allow_admin_from(admin:全部斜槓指令)、user_allowed_commands(一般使用者能跑的指令),群組 scope 另有 group_allow_admin_from 與 group_user_allowed_commands。沒設 allow_admin_from 時該 scope 不啟用分級。保底永遠有 /help 與 /whoami,任何人發 /whoami 可查自己的層級。

webhook 模式加一層:如果你之後改用 webhook 模式(需要公網端點),務必設 FEISHU_ENCRYPT_KEY(入站請求簽章驗證，不符者回 401)與 FEISHU_VERIFICATION_TOKEN(payload 內 token 比對)。WebSocket 模式下簽章驗證由官方 SDK 處理，這兩項可略。

最後是老規矩：群組場景的 agent 會讀到大量不可信的第三方文字,Prompt Injection（提示詞注入） 是真實攻擊面。allowlist + @mention 門檻 + 危險指令的卡片核准按鈕，是三道基本防線；更深入的圍欄設計見 Sandbox（沙箱）。

常見錯誤與修法

症狀	原因	修法
啟動報 lark-oapi not installed	缺飛書 SDK	python -c "import pm; pm.sync_venv(['feishu'], explicit=True)"
報 websockets not installed; websocket mode unavailable	缺 WebSocket 套件	hermes pm repair
Bot 私訊、群組都無反應	應用版本沒發布，權限與事件未生效	到版本管理發布新版本；企業應用等管理員審批
群組裡 @了也不回	群政策 allowlist 但傳送者不在 FEISHU_ALLOWED_USERS;或事件沒訂閱 im.message.receive_v1	補名單或改政策；核對事件訂閱；日誌找第一條 WARNING
點核准按鈕報 200340	卡片回調沒配對：要在回調配置分頁(不是事件配置)加 card.action.trigger,開互動卡片能力，並重新發布版本	照步驟三第 2 點補齊；這個錯誤發生在飛書側,Hermes 日誌裡不會有痕跡
收不到使用者傳的圖片/檔案	缺 im:resource 權限	補 scope 並重新發布版本
回覆變成純文本、格式盡失	飛書 API 拒收 post 富文本,adapter 自動降級	正常的 fallback 行為；查日誌看拒收原因
Another local Hermes gateway is already using this Feishu app_id	同一 app_id 只允許一個 gateway 實例	先停掉另一個實例
憑證在 .env,adapter 卻沒啟動	platforms.feishu.enabled: false 明確停用，優先級高於環境憑證	移除該鍵或改 true;啟動日誌有 WARNING
hermes gateway status 顯示 retrying	WebSocket 斷線,SDK 與 Hermes 監督器正在按退避重連	短暫斷線會自愈；持續失敗觸發熔斷後 /platform resume feishu

日誌永遠是第一現場:~/.hermes/logs/gateway.log。

下一步

• 深入配置與實戰場景(安裝四方式、手動建應用、讓 Hermes 讀 OpenClaw 專案做維運):安裝 Hermes Agent 與 Hermes 飛書集成進階篇
• 想先在最簡單的平台證明概念:Telegram 教學
• 把其他渠道也接上:微信、WhatsApp
• 剛裝好任何 agent 工具都適用的驗證清單:頭十分鐘
• 聊天內指令的完整參考:斜槓指令系統指南