OpenClaw Feishu / Lark 頻道
企業
中等
透過基於 WebSocket 的事件訂閱將 OpenClaw 連接到飛書（Feishu）或 Lark。此企業整合讓您的 AI 助手能夠在飛書/Lark（字節跳動旗下領先的企業協作平台）上處理私訊和群組訊息。OpenClaw 透過飛書開放平台的長連線（WebSocket）模式連接，因此無需公開 URL 或 Webhook 端點。只需建立飛書應用程式，輸入 App ID 和 App Secret，即可啟動助手。
快速資訊
難度中等
分類企業
支援功能數3 / 6
Feishu / Lark 支援功能
文字訊息
支援
媒體與檔案
支援
表情回應
不支援
討論串
不支援
語音訊息
不支援
群組聊天
支援
Feishu / Lark 前置條件
- 擁有飛書（feishu.cn）或 Lark（larksuite.com）租戶帳號且具有應用程式建立權限
- 已安裝飛書外掛：openclaw plugins install @openclaw/feishu
- OpenClaw Gateway 已執行並設定
- 伺服器已安裝 Node.js 18+
Feishu / Lark 快速設定
1
建立飛書/Lark 應用程式
前往飛書開放平台（open.feishu.cn/app）或 Lark 開發者主控台（open.larksuite.com/app）。建立新的企業應用程式，設定名稱、描述和圖示。在憑證頁面複製 App ID（格式：cli_xxx）和 App Secret。
2
設定權限和機器人功能
在應用程式的權限管理中批次匯入所需權限。在應用程式功能 > 機器人中啟用機器人功能。在事件訂閱中選擇「使用長連線」（WebSocket 模式）並新增 im.message.receive_v1 事件。透過版本管理與發布提交應用程式。
3
將飛書頻道設定新增至 OpenClaw
執行 'openclaw channels add' 並選擇 Feishu，或手動在 ~/.openclaw/openclaw.json 中新增頻道設定，填入 appId 和 appSecret。也可使用環境變數 FEISHU_APP_ID 和 FEISHU_APP_SECRET。
4
啟動 Gateway 並測試
執行 'openclaw gateway' 啟動服務。在飛書中向機器人發送私訊。如果使用預設的配對策略，透過 'openclaw pairing approve feishu <code>' 在終端中核准傳送者。
Feishu / Lark 設定範例
config.json
{
"channels": {
"feishu": {
"enabled": true,
"dmPolicy": "pairing",
"accounts": {
"main": {
"appId": "cli_xxx",
"appSecret": "YOUR_APP_SECRET",
"botName": "My AI Assistant"
}
}
}
}
}Feishu / Lark 深入了解
架構概述
OpenClaw 透過飛書開放平台的 WebSocket 長連線模式連接飛書。與傳統 Webhook 不同，此方式無需公開 URL 或防火牆設定 — Gateway 主動向飛書伺服器發起 WebSocket 連線，即時接收事件推送。
訊息流程：使用者在飛書中傳送訊息 → 飛書開放平台 → WebSocket 推送至 Gateway → OpenClaw 使用 AI 處理 → 透過飛書 Bot API 回覆 → 訊息在飛書中送達。
此架構非常適合在 NAT 或企業防火牆後的自託管部署，因為不需要任何入站連線。Gateway 自動維護 WebSocket 連線並處理重連。
建議使用 WebSocket 模式（長連線）— 無需公開 URL、無需 SSL 憑證，可在防火牆後正常運作。
飛書外掛透過 'openclaw plugins install @openclaw/feishu' 單獨安裝，保持核心 Gateway 輕量。
飛書應用程式建立與憑證取得
設定飛書整合需要在飛書開放平台建立應用程式：
1. 前往 open.feishu.cn/app（或 Lark 使用者前往 open.larksuite.com/app），建立新的企業應用程式。
2. 在憑證與基本資訊頁面，複製 App ID（格式：cli_xxx）和 App Secret — 這是您的驗證憑證。
3. 在權限管理中批次匯入所需的訊息權限。關鍵權限包括 im:message、im:message:send_as_bot 和 im:chat。
4. 在應用程式功能 > 機器人中啟用機器人功能，設定機器人名稱和描述。
5. 在事件訂閱中選擇「使用長連線」（WebSocket 模式），新增 im.message.receive_v1 事件以接收訊息。
6. 透過版本管理與發布提交應用程式。應用程式必須發布並審批通過才能接收訊息。
terminal
# 透過環境變數
export FEISHU_APP_ID="cli_xxx"
export FEISHU_APP_SECRET="your_app_secret"
# 或透過 CLI 精靈
openclaw channels add請妥善保管 App Secret。切勿將其提交至版本控制系統。正式環境請使用環境變數（FEISHU_APP_SECRET）。如果洩露，請立即在飛書開放平台主控台重設。
飛書與 Lark 設定差異
飛書（feishu.cn）是國內版本，Lark（larksuite.com）是國際版本。兩者使用相同的協定但連接不同的 API 端點。
預設情況下，OpenClaw 連接飛書（國內）API。如果您使用 Lark 國際版，請在設定中將 domain 設為 'lark'，這會自動將所有 API 呼叫切換到 Lark 端點。
openclaw.json
{
"channels": {
"feishu": {
"domain": "lark",
"accounts": {
"main": {
"appId": "cli_xxx",
"appSecret": "YOUR_APP_SECRET"
}
}
}
}
}國內使用者使用 'feishu'（預設），國際使用者使用 'lark'。domain 設定影響 API 端點，不影響應用程式建立平台。
私訊策略
私訊策略控制誰可以與您的 AI 助手進行私訊。OpenClaw 支援四種策略：
• pairing（預設）— 新使用者需要經過配對流程。他們傳送訊息後會收到配對碼，您透過 CLI 核准或拒絕。核准後即可自由聊天。
• allowlist — 僅允許在 allowFrom 中明確列出的飛書 Open ID 與機器人通訊，其他人將被靜默忽略。
• open — 任何人都可以獲得回覆，請謹慎使用。
• disabled — 私訊功能完全關閉。
openclaw.json
{
"channels": {
"feishu": {
"dmPolicy": "allowlist",
"allowFrom": ["ou_xxx", "ou_yyy"]
}
}
}要查找使用者的 Open ID（格式：ou_xxx），讓使用者私訊機器人後查看 Gateway 日誌，或使用 'openclaw pairing list feishu'。
群組聊天管理
OpenClaw 支援飛書群組聊天，提供靈活的存取控制：
• open（預設）— 群組內任何成員 @機器人即可觸發回覆。
• allowlist — 僅群組內已核准的使用者可以與機器人互動。
• disabled — 完全忽略群組訊息。
預設情況下，機器人在群組中需要 @提及（requireMention: true），避免在活躍群組中回覆每則訊息。
群組 ID（格式：oc_xxx）可在 Gateway 日誌中找到。將機器人加入群組，@提及它，然後查看 'openclaw logs --follow'。
openclaw.json
{
"channels": {
"feishu": {
"groupPolicy": "open",
"requireMention": true
}
}
}要查找群組 ID（oc_xxx），啟動 Gateway，在群組中 @機器人，然後查看日誌：openclaw logs --follow
串流回覆（互動卡片）
OpenClaw 支援透過飛書互動卡片進行串流 AI 回覆。啟用後，機器人會傳送一個初始卡片，隨著 AI 產生回覆逐步更新 — 類似 ChatGPT 即時輸出文字的效果。
相比等待完整回覆再傳送，這提供了更好的使用者體驗。串流卡片原地更新，不會在聊天中產生多則訊息。
openclaw.json
{
"channels": {
"feishu": {
"streaming": true
}
}
}串流回覆預設啟用。設定 streaming: false 可停用，改為傳送完整的純文字訊息。
訊息類型與媒體支援
OpenClaw 處理多種飛書訊息類型：
接收：文字訊息、富文本（貼文）、圖片、檔案、音訊、影片和貼圖。
傳送：文字訊息、圖片、檔案和音訊。富文本支援有限 — 機器人主要以純文字或串流卡片回覆。
媒體檔案受大小限制，預設最大下載大小為 30 MB（mediaMaxMb）。超過此限制的大型檔案將被略過並記錄警告。
openclaw.json
{
"channels": {
"feishu": {
"mediaMaxMb": 30,
"textChunkLimit": 2000
}
}
}多帳號與多代理路由
OpenClaw 支援同時執行多個飛書機器人帳號。每個帳號有獨立的 App ID、App Secret 和機器人名稱。這對需要為不同團隊或用途設定獨立機器人的組織非常有用。
您還可以設定多代理路由，透過對等繫結讓不同的 AI 代理處理不同的對話。例如，一個代理處理私訊，另一個處理群組聊天，或不同代理服務不同的飛書群組。
openclaw.json
{
"channels": {
"feishu": {
"accounts": {
"support": {
"appId": "cli_aaa",
"appSecret": "secret_a",
"botName": "Support Bot"
},
"hr": {
"appId": "cli_bbb",
"appSecret": "secret_b",
"botName": "HR Bot"
}
}
}
}
}常用指令
OpenClaw 提供多個內建指令來管理飛書機器人：
• /status — 顯示目前機器人狀態和連線資訊
• /reset — 重設目前對話工作階段
• /model — 顯示或切換目前 AI 模型
• openclaw gateway status — 檢查 Gateway 連線狀態
• openclaw gateway restart — 重新啟動 Gateway 服務
• openclaw logs --follow — 檢視即時 Gateway 日誌
• openclaw pairing list feishu — 列出所有已核准和待處理的配對
• openclaw pairing approve feishu <code> — 核准待處理的配對請求
Feishu / Lark 設定參考
| Key | Type | Default | Description |
|---|---|---|---|
| enabled | boolean | true | 啟用或停用飛書頻道 |
| domain | string | "feishu" | API 網域：'feishu' 用於國內版（feishu.cn），'lark' 用於國際版（larksuite.com） |
| dmPolicy | string | "pairing" | 控制誰可以私訊機器人。選項：pairing、allowlist、open、disabled |
| allowFrom | string[] | [] | 當 dmPolicy 為 'allowlist' 時允許私訊的 Open ID（ou_xxx）清單 |
| groupPolicy | string | "open" | 群組策略。選項：open、allowlist、disabled |
| requireMention | boolean | true | 機器人在群組中是否需要 @提及才回應 |
| streaming | boolean | true | 啟用透過互動卡片的串流 AI 回覆 |
| textChunkLimit | number | 2000 | 每則文字訊息的最大字元數 |
| mediaMaxMb | number | 30 | 上傳和下載的最大媒體檔案大小（MB） |
| accounts.<id>.appId | string | "" | 飛書 App ID（格式：cli_xxx），從開放平台主控台取得 |
| accounts.<id>.appSecret | string | "" | 飛書 App Secret，從開放平台主控台取得 |
| accounts.<id>.botName | string | "" | 機器人在飛書聊天中的顯示名稱 |
| historyLimit | number | 50 | 作為 AI 脈絡包含的最近訊息數量 |
enabled
Type: booleanDefault: true
啟用或停用飛書頻道
domain
Type: stringDefault: "feishu"
API 網域：'feishu' 用於國內版（feishu.cn），'lark' 用於國際版（larksuite.com）
dmPolicy
Type: stringDefault: "pairing"
控制誰可以私訊機器人。選項：pairing、allowlist、open、disabled
allowFrom
Type: string[]Default: []
當 dmPolicy 為 'allowlist' 時允許私訊的 Open ID（ou_xxx）清單
groupPolicy
Type: stringDefault: "open"
群組策略。選項：open、allowlist、disabled
requireMention
Type: booleanDefault: true
機器人在群組中是否需要 @提及才回應
streaming
Type: booleanDefault: true
啟用透過互動卡片的串流 AI 回覆
textChunkLimit
Type: numberDefault: 2000
每則文字訊息的最大字元數
mediaMaxMb
Type: numberDefault: 30
上傳和下載的最大媒體檔案大小（MB）
accounts.<id>.appId
Type: stringDefault: ""
飛書 App ID（格式：cli_xxx），從開放平台主控台取得
accounts.<id>.appSecret
Type: stringDefault: ""
飛書 App Secret，從開放平台主控台取得
accounts.<id>.botName
Type: stringDefault: ""
機器人在飛書聊天中的顯示名稱
historyLimit
Type: numberDefault: 50
作為 AI 脈絡包含的最近訊息數量
Feishu / Lark 常見問題
Feishu / Lark 故障排除
機器人在群組中無回應
機器人可能未被加入群組，@提及未生效，或 groupPolicy 設為 'disabled'。
確認機器人已加入群組。檢查 groupPolicy 是否為 'disabled'。嘗試透過名稱 @提及機器人。透過 'openclaw logs --follow' 檢查 Gateway 日誌。
未收到任何訊息 — 機器人完全靜默
應用程式可能未發布，事件訂閱未設定，或權限缺失。
確認應用程式已在版本管理與發布中發布並審批通過。驗證事件訂閱中已選擇「使用長連線」且新增了 im.message.receive_v1 事件。檢查所有必需權限已匯入。確保 Gateway 正在執行：openclaw gateway status。
訊息傳送失敗
可能未授予 im:message:send_as_bot 權限，或應用程式未發布。
確保在應用程式權限管理中已授予 im:message:send_as_bot 權限。如果最近新增了權限，需要重新發布應用程式。查看 Gateway 日誌取得具體錯誤訊息。
App Secret 洩露或被盜
App Secret 被意外提交至版本控制系統或以不安全方式共享。
立即在飛書開放平台主控台（憑證頁面）重設 App Secret。使用新金鑰更新 OpenClaw 設定或環境變數。透過 'openclaw gateway restart' 重新啟動 Gateway。
WebSocket 連線頻繁中斷
網路不穩定或防火牆干擾長連線 WebSocket。
檢查伺服器網路穩定性。確保防火牆允許出站 WebSocket 連線。Gateway 會自動重連，但頻繁斷線可能表示網路問題。查看日誌了解重連模式。