OpenClaw 飛書整合全流程：從建立應用到訊息收發的完整指南

兩種整合方式，先幫你挑

OpenClaw 整合飛書有兩條路線：內建外掛和官方飛書外掛。功能取向不同，先看比較再動手：

這篇教學主要講內建外掛的完整設定流程，涵蓋 90% 以上的使用情境。官方外掛在後面單獨一節介紹。

整合飛書前的準備工作

開始之前，先確認以下幾點：

• OpenClaw 已安裝並執行中（版本 ≥ 2026.2）。還沒裝的先去看 安裝教學
• 飛書開放平台帳號：前往 open.feishu.cn（Lark 國際版用 open.larksuite.com）
• 確認 Gateway 正常運作：

openclaw gateway status

好消息：不需要公用 IP 或網域。內建外掛預設走 WebSocket 長連線，是 OpenClaw 主動連到飛書伺服器，在 NAT 後面也能用。

第一步：建立飛書機器人應用

1. 登入 open.feishu.cn → 進入開發者後台
2. 點選建立企業自建應用
3. 填寫應用名稱（例如「AI 助手」）和說明，簡單寫就好
4. 進入應用詳情 → 憑證與基本資訊 → 複製 App ID（格式 cli_xxx）和 App Secret

⚠️ App Secret 等同密碼，不要提交到 Git，不要貼到群組裡。

Lark 國際版使用者：操作步驟完全一樣，只是網域換成 open.larksuite.com，後續設定中 domain 設為 "lark"。

第二步：設定飛書機器人權限

飛書權限設定有兩種做法：

做法 A：批次匯入（推薦，省事）

進入應用 → 開發設定 → 權限管理 → 點選批次開通 → 貼上以下 JSON：

{
  "scopes": {
    "tenant": [
      "im:chat", "im:message", "im:message:send_as_bot",
      "im:message.p2p_msg:readonly", "im:message.group_at_msg:readonly",
      "im:message.group_msg", "im:message:readonly", "im:resource",
      "im:chat.members:bot_access",
      "im:chat.access_event.bot_p2p_chat:read",
      "contact:user.employee_id:readonly",
      "application:application:self_manage", "application:bot.menu:write",
      "cardkit:card:write",
      "docs:document.content:read", "sheets:spreadsheet",
      "wiki:wiki:readonly", "event:ip_list"
    ],
    "user": [
      "im:chat.access_event.bot_p2p_chat:read"
    ]
  }
}

做法 B：手動勾選

在權限管理頁面逐一搜尋上面的權限名稱並開通。權限蠻多的，建議還是用做法 A。

第三步：啟用飛書機器人 & 事件訂閱

這一步很關鍵，少設一項都可能導致機器人沒反應。

啟用機器人

進入應用 → 應用能力 → 機器人 → 點選啟用。

設定事件訂閱

進入 事件與回呼 → 事件訂閱 → 選擇 「使用長連線接收事件」。

接著新增以下事件：

⚠️ 如果沒設定事件訂閱，飛書聊天介面不會出現訊息輸入框，看起來就像機器人不存在一樣。

⚠️ 這也是「飛書應用未建立長連線」最常見的原因——事件訂閱沒選長連線模式，或者根本沒新增任何事件。

第四步：發布飛書應用

設定好權限和事件後，還需要發布應用才會生效：

1. 進入 版本管理與發布 → 建立版本
2. 填寫版本號和更新說明 → 送出審核
3. 如果你是租戶管理員，一般秒過；普通開發者可能需要管理員審批，視組織審核規則而定

發布成功後，在飛書裡搜尋你的應用名稱（例如「AI 助手」）就能找到機器人了。

第五步：OpenClaw 飛書頻道設定

CLI 快速設定

最簡單的方式，互動式引導：

openclaw channels add    # 選擇 Feishu，貼上 App ID 和 Secret
openclaw gateway restart

手動設定

編輯 ~/.openclaw/openclaw.json：

{
  channels: {
    feishu: {
      enabled: true,
      domain: "feishu",            // Lark 國際版用 "lark"
      connectionMode: "websocket",
      dmPolicy: "pairing",
      groupPolicy: "open",
      requireMention: true,
      streaming: true,
      typingIndicator: true,
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "你的 App Secret",
          botName: "AI 助手"
        }
      }
    }
  }
}

OpenClaw 飛書設定項目說明

第六步：啟動 OpenClaw Gateway 並配對飛書

啟動 Gateway

openclaw gateway           # 啟動
openclaw logs --follow     # 即時查看日誌

配對流程

1. 在飛書裡找到你的機器人，發一則訊息（隨便說句話就行）
2. 終端機日誌會出現一組配對碼
3. 在終端機裡核准配對：

openclaw pairing approve feishu <配對碼>

4. 再給機器人發一則訊息，確認 AI 正常回覆

驗證連線狀態：

openclaw gateway status
# 應該看到 Feishu: connected

到這一步，基本的訊息收發就跑通了。

飛書群組聊天機器人設定

預設情況下群組已經可用（groupPolicy: "open"），但你可能想做更細緻的控制。

群組白名單

只允許特定群組使用機器人：

{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      groups: {
        "oc_xxx": {},                    // 群組 ID
        "oc_yyy": {
          requireMention: false          // 這個群不用 @，直接回覆所有訊息
        }
      }
    }
  }
}

群組 ID 可以在飛書群組設定中查看，格式是 oc_ 開頭的一串字元。

按群組設定是否需要 @

全域的 requireMention 可以在單個群組裡覆寫，適合不同群組有不同用法的情境。

飛書 Webhook 模式設定

如果你的網路環境限制了 WebSocket 外連（例如某些企業防火牆），可以改用 Webhook 模式：

{
  channels: {
    feishu: {
      connectionMode: "webhook",
      verificationToken: "來自飛書後台",
      encryptKey: "來自飛書後台",
      webhookPath: "/feishu/events",
      webhookPort: 3000
    }
  }
}

Webhook 模式需要你的伺服器有公開可存取的網址，飛書會主動推送事件到你的伺服器。在飛書後台的事件訂閱中填寫你的回呼網址即可。

絕大多數情況下 WebSocket 就夠了，Webhook 模式僅在網路受限時考慮。

飛書多 Agent 路由設定

如果你有多個 AI Agent，可以按頻道和對話類型分配：

{
  bindings: [
    { agentId: "main", match: { channel: "feishu", peer: { kind: "direct" } } },
    { agentId: "support", match: { channel: "feishu", peer: { kind: "direct", id: "ou_xxxxx" } } },
    { agentId: "team-helper", match: { channel: "feishu", peer: { kind: "group", id: "oc_xxxxxxxxx" } } }
  ]
}

這在組織裡很實用——你可以同時跑一個通用助手、一個客服 agent、一個開發工具 agent，全部透過同一個飛書機器人運作，但背後對接不同的模型和提示詞。私訊預設走 main agent，特定使用者或群組可以路由到不同的 agent。

OpenClaw 官方飛書外掛

官方飛書外掛由字節跳動飛書團隊維護，功能比內建外掛強很多，能操作文件、行事曆、任務、多維表格、知識庫等飛書工作區的幾乎所有功能。

版本需求：Linux/macOS ≥ 2026.2.26，Windows ≥ 2026.3.2，Node.js ≥ 22

安裝官方飛書外掛

npm config set registry https://registry.npmjs.org
curl -o /tmp/feishu-plugin.tgz https://sf3-cn.feishucdn.com/obj/open-platform-opendoc/4d184b1ba733bae2423a89e196a2ef8f_QATOjKH1WN.tgz
npm install /tmp/feishu-plugin.tgz -g
rm /tmp/feishu-plugin.tgz
feishu-plugin-onboard install

配對與授權

1. 在飛書裡對機器人發訊息，取得配對碼
2. 核准配對並發送授權通知：

openclaw pairing approve feishu <code> --notify

3. 機器人會回覆一則授權連結，點選完成 OAuth 授權
4. 發送 /feishu start 驗證外掛是否正常運作

診斷指令

遇到問題時用這幾個指令排查：

feishu-plugin-onboard doctor           # 檢查常見問題
feishu-plugin-onboard doctor --fix     # 自動修復偵測到的問題
feishu-plugin-onboard info --all       # 查看完整外掛資訊

⚠️ 安全提醒：官方外掛以你的使用者身份存取飛書工作區，擁有你帳號的所有權限。不建議在共用的 Bot 上啟用，避免其他使用者透過 AI 間接存取你的飛書資料。

OpenClaw 飛書常用指令速查

常見問題

需要公用 IP 嗎？

不需要。內建外掛預設用 WebSocket 長連線，OpenClaw 主動連到飛書伺服器，家裡的電腦、公司內網都能用。只有 Webhook 模式才需要公開網址。

飛書和 Lark 有什麼差別？

功能完全一樣，Lark 是飛書的國際版。設定上只需要把 domain 改成 "lark"，開放平台網域用 open.larksuite.com。

內建外掛和官方外掛怎麼選？

只需要訊息收發的話，內建外掛就夠了，設定簡單。如果需要 AI 幫你操作飛書文件、行事曆、多維表格這些，就選官方外掛。

能同時整合其他頻道嗎？

可以。OpenClaw 支援多頻道同時運作，飛書、Telegram、Discord 可以共用同一個 AI Agent，各頻道獨立設定互不影響。去 頻道總覽 看看還有哪些選擇。

回覆很慢怎麼辦？

先開啟 streaming: true（串流輸出），體感會快很多。如果還是慢，考慮換一個回應更快的模型，或者檢查你的 AI 服務是否有延遲。

App Secret 不小心洩漏了怎麼辦？

立刻到飛書開放平台重設 Secret，接著更新 OpenClaw 設定檔並重新啟動 Gateway。舊的 Secret 會立即失效。

飛書聊天介面沒有訊息輸入框怎麼辦？

這幾乎 100% 是事件訂閱沒設定好。回到飛書開放平台，確認已新增 im.message.receive_v1 事件、事件接收方式選的是「長連線」、應用已發布最新版本。

飛書提示「應用未建立長連線」怎麼辦？

代表飛書伺服器沒收到 OpenClaw 的 WebSocket 連線。先用 openclaw gateway status 確認 Gateway 在執行，再用 openclaw logs --follow 看有沒有連線錯誤。常見原因：Gateway 沒啟動、App ID 或 App Secret 填錯了、網路不通。確認設定無誤後執行 openclaw gateway restart 重新啟動。

機器人完全不回覆怎麼辦？

一步步排查：應用是否已發布（草稿狀態不生效）、權限裡有沒有 im:message:send_as_bot、dmPolicy 是不是設成了 disabled、AI 模型的 API Key 有沒有設定好。可以用 openclaw doctor 綜合診斷。

群組中 @機器人沒反應怎麼辦？

確認機器人已加入群組（在群組設定中查看）、groupPolicy 不是 disabled。如果用了 allowlist，檢查群組 ID 是否在清單裡。

訊息發送失敗提示權限不足怎麼辦？

回飛書開放平台補齊權限，補完之後要重新發布一個版本才能生效。

內建外掛和官方外掛衝突了怎麼辦？

正常情況下兩個外掛可以共存——內建外掛負責訊息收發，官方外掛負責工作區操作（文件、行事曆、任務等），OpenClaw 會自動去重事件。如果確實出現重複回覆，可以暫時停用其中一個：feishu-plugin-onboard disable（停用官方外掛）或 openclaw channels disable feishu（停用內建外掛）。

Windows 報 "spawn npm ENOENT" 怎麼辦？

這是官方外掛在 Windows 上的已知問題。推薦用 WSL2 執行 OpenClaw；臨時修正方案是找到 exec.js 檔案，在 spawn 呼叫中加上 shell: true。

飛書整合完成，下一步做什麼

飛書搞定了，可以繼續探索：

• 查看所有支援的頻道 — 50+ 頻道整合
• Skills 技能目錄 — 幫 AI 裝上更多能力
• 問題排除指南 — 通用問題排除
• OpenClaw 完整入門指南 — 從零開始的完整教學
• Telegram 整合指南 — 另一個熱門頻道
• Discord 整合指南 — 社群情境首選