跳轉到主要內容
OpenClaw 透過官方 @openclaw/feishu 外掛連接 Feishu/Lark（整合式協作平台）：機器人私訊、群組聊天、串流卡片回覆，以及 Feishu 文件/wiki/雲端硬碟/Bitable 工具。 狀態： 機器人私訊與群組聊天已可用於生產環境。WebSocket 是預設事件傳輸方式（不需要公開 URL）；網路鉤子模式為選用。

​
快速開始

需要 OpenClaw 2026.5.29 或以上版本。執行 openclaw --version 檢查。使用 openclaw update 升級。
1

執行通道設定精靈

openclaw channels login --channel feishu
如果缺少 @openclaw/feishu 外掛，這會先安裝它，然後逐步完成設定：
  • 手動設定：貼上來自 Feishu Open Platform (https://open.feishu.cn) 或 Lark Developer (https://open.larksuite.com) 的 App ID 和 App Secret。
  • QR 設定：在 Feishu 應用程式中掃描 QR code，自動建立機器人。此流程會將私訊鎖定為你自己的帳號（dmPolicy: "allowlist" 搭配你的 open_id）。
精靈也會詢問 API 網域（Feishu 或 Lark）以及群組政策。如果中國版 Feishu 行動應用程式對 QR code 沒有反應，請重新執行設定並選擇手動設定。
2

設定完成後，重新啟動閘道以套用變更

openclaw gateway restart

​
存取控制

​
私訊

設定 channels.feishu.dmPolicy（預設：pairing）來控制誰可以向機器人傳送私訊：
值行為
"pairing"未知使用者會收到配對碼；透過命令列介面核准
"allowlist"只有列在 allowFrom 中的使用者可以聊天
"open"公開私訊；設定驗證要求 allowFrom 包含 "*"。非萬用字元項目仍會縮小存取範圍
核准配對請求： 
openclaw pairing list feishu
openclaw pairing approve feishu <CODE>

​
群組聊天

群組政策（channels.feishu.groupPolicy，預設：allowlist）：
值行為
"open"回應群組中的所有訊息
"allowlist"只回應 groupAllowFrom 中的群組，或明確設定於 groups.<chat_id> 下的群組
"disabled"停用所有群組訊息；明確的 groups.<chat_id> 項目不會覆寫此設定
提及要求（channels.feishu.requireMention）：
  • 預設：需要 @mention，但有效群組政策為 "open" 時除外；在該情況下預設為 false，因此無法帶有提及的訊息（例如圖片）仍可送達代理程式。
  • 明確設定 true 或 false 可覆寫；逐群組覆寫：channels.feishu.groups.<chat_id>.requireMention。
  • 僅廣播的 @all 和 @_all 不會被視為機器人提及。若訊息同時提及 @all 並直接提及機器人，仍會算作機器人提及。

​
群組設定範例

​
允許所有群組，不需要 @mention

{
  channels: {
    feishu: {
      groupPolicy: "open", // requireMention defaults to false under "open"
    },
  },
}

​
允許所有群組，仍需要 @mention

{
  channels: {
    feishu: {
      groupPolicy: "open",
      requireMention: true,
    },
  },
}

​
只允許特定群組

{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      // Group IDs look like: oc_xxx
      groupAllowFrom: ["oc_xxx", "oc_yyy"],
    },
  },
}
在 allowlist 模式中，你也可以加入明確的 groups.<chat_id> 項目來允許某個群組。明確項目不會覆寫 groupPolicy: "disabled"。groups.* 下的萬用字元預設值會設定相符群組，但它們本身不會允許群組。 
{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      groups: {
        oc_xxx: {
          requireMention: false,
        },
      },
    },
  },
}

​
限制群組內的傳送者

{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["oc_xxx"],
      groups: {
        oc_xxx: {
          // User open_ids look like: ou_xxx
          allowFrom: ["ou_user1", "ou_user2"],
        },
      },
    },
  },
}
channels.feishu.groupSenderAllowFrom 會為所有群組設定相同的傳送者允許清單；逐群組的 allowFrom 優先。

​
取得群組/使用者 ID

​
群組 ID（chat_id，格式：oc_xxx）

在 Feishu/Lark 中開啟群組，點擊右上角的選單圖示，然後前往 設定。群組 ID（chat_id）會列在設定頁面上。 取得群組 ID

​
使用者 ID（open_id，格式：ou_xxx）

啟動閘道，向機器人傳送私訊，然後檢查日誌： 
openclaw logs --follow
在日誌輸出中尋找 open_id。你也可以檢查待處理的配對請求： 
openclaw pairing list feishu

​
常用命令

命令說明
/status顯示機器人狀態
/reset重設目前工作階段
/model顯示或切換 AI 模型
Feishu/Lark 不支援原生斜線命令選單，因此請將這些命令以純文字訊息傳送。

​
疑難排解

​
機器人在群組聊天中沒有回應

  1. 確認機器人已加入群組
  2. 確認你有 @mention 機器人（預設需要）
  3. 確認 groupPolicy 不是 "disabled"
  4. 檢查日誌：openclaw logs --follow

​
機器人沒有收到訊息

  1. 確認機器人已在 Feishu Open Platform / Lark Developer 發布並核准
  2. 確認事件訂閱包含 im.message.receive_v1
  3. 確認已選取 持久連線（WebSocket）
  4. 確認已授予所有必要的權限範圍
  5. 確認閘道正在執行：openclaw gateway status
  6. 檢查日誌：openclaw logs --follow

​
QR 設定在 Feishu 行動應用程式中沒有反應

  1. 重新執行設定：openclaw channels login --channel feishu
  2. 選擇手動設定
  3. 在 Feishu Open Platform 中建立自建應用程式，並複製其 App ID 和 App Secret
  4. 將這些認證貼到設定精靈中

​
App Secret 外洩

  1. 在 Feishu Open Platform / Lark Developer 中重設 App Secret
  2. 更新設定中的值
  3. 重新啟動閘道：openclaw gateway restart

​
進階設定

​
多個帳號

{
  channels: {
    feishu: {
      defaultAccount: "main",
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "xxx",
          name: "Primary bot",
          tts: {
            providers: {
              openai: { voice: "shimmer" },
            },
          },
        },
        backup: {
          appId: "cli_yyy",
          appSecret: "yyy",
          name: "Backup bot",
          enabled: false,
        },
      },
    },
  },
}
defaultAccount 控制當外送 API 未指定 accountId 時要使用哪個帳號。帳號項目會繼承頂層設定；大多數頂層鍵都可以在每個帳號中覆寫。 accounts.<id>.tts 使用與 messages.tts 相同的形狀，並會深度合併到全域 TTS 設定之上，因此多機器人的 Feishu 設定可以在全域保留共用的提供者認證，同時只針對每個帳號覆寫語音、模型、角色設定或自動模式。

​
訊息限制

  • textChunkLimit - 外送文字區塊大小（預設：4000 個字元）
  • chunkMode - "length"（預設）會在限制處分割；"newline" 優先使用換行邊界
  • mediaMaxMb - 媒體上傳/下載限制（預設：30 MB）

​
串流

Feishu/Lark 支援透過互動卡片進行串流回覆（Card Kit streaming API）。啟用後，機器人會在產生文字時即時更新卡片。 
{
  channels: {
    feishu: {
      streaming: true, // enable streaming card output (default: true)
      blockStreaming: true, // opt into completed-block streaming
    },
  },
}
設定 streaming: false 會以單一訊息傳送完整回覆；renderMode: "raw"（純文字而非卡片）也會停用串流卡片。blockStreaming 預設為關閉；只有在你想於最終回覆前先送出已完成的助理區塊時才啟用。

​
配額最佳化

使用兩個選用旗標減少 Feishu/Lark API 呼叫次數：
  • typingIndicator（預設 true）：設定為 false 以略過輸入中反應呼叫
  • resolveSenderNames（預設 true）：設定為 false 以略過傳送者個人檔案查詢
{
  channels: {
    feishu: {
      typingIndicator: false,
      resolveSenderNames: false,
    },
  },
}

​
群組工作階段範圍與主題執行緒

channels.feishu.groupSessionScope（頂層、每個帳號或每個群組）控制群組訊息如何對應到代理程式工作階段：
值工作階段
"group"（預設）每個群組聊天一個工作階段
"group_sender"每個（群組 + 傳送者）一個工作階段
"group_topic"每個主題執行緒一個工作階段；退回使用群組工作階段
"group_topic_sender"每個（主題 + 傳送者）一個工作階段；退回使用（群組 + 傳送者）
對於主題範圍，原生 Feishu/Lark 主題群組會使用事件 thread_id（omt_*）作為標準主題工作階段鍵。如果原生主題起始事件省略 thread_id，OpenClaw 會在路由該輪對話前從 Feishu 補齊它。OpenClaw 轉換成執行緒的一般群組回覆會繼續使用回覆根訊息 ID（om_*），因此第一輪與後續輪次會留在同一個工作階段中。 設定 replyInThread: "enabled"（頂層或每個群組）可讓機器人回覆建立或延續 Feishu 主題執行緒，而不是行內回覆。topicSessionMode 是 groupSessionScope 的已棄用前身；請優先使用 groupSessionScope。

​
Feishu 工作區工具

此外掛隨附用於 Feishu 文件、聊天、知識庫、雲端儲存、權限和 Bitable 的代理程式工具，以及相應的 Skills（feishu-doc、feishu-drive、feishu-perm、feishu-wiki）。工具系列由 channels.feishu.tools 控制：
鍵工具預設
tools.docfeishu_doc 文件操作true
tools.chatfeishu_chat 聊天資訊 + 成員查詢true
tools.wikifeishu_wiki 知識庫（需要 doc）true
tools.drivefeishu_drive 雲端儲存true
tools.permfeishu_perm 權限管理false（敏感）
tools.scopesfeishu_app_scopes 應用程式範圍診斷true
tools.bitablefeishu_bitable_* Bitable/Base 操作true
tools.base 是 tools.bitable 的別名；兩者都設定時，以明確的 bitable 值為準。每個帳號的開關位於 accounts.<id>.tools 下。

​
ACP 工作階段

Feishu/Lark 支援私訊和群組執行緒訊息的 ACP。Feishu/Lark ACP 由文字命令驅動 - 沒有原生斜線命令選單，因此請直接在對話中使用 /acp ... 訊息。

​
持久 ACP 綁定

{
  agents: {
    list: [
      {
        id: "codex",
        runtime: {
          type: "acp",
          acp: {
            agent: "codex",
            backend: "acpx",
            mode: "persistent",
            cwd: "/workspace/openclaw",
          },
        },
      },
    ],
  },
  bindings: [
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "feishu",
        accountId: "default",
        peer: { kind: "direct", id: "ou_1234567890" },
      },
    },
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "feishu",
        accountId: "default",
        peer: { kind: "group", id: "oc_group_chat:topic:om_topic_root" },
      },
      acp: { label: "codex-feishu-topic" },
    },
  ],
}

​
從聊天產生 ACP

在 Feishu/Lark 私訊或討論串中： 
/acp spawn codex --thread here
--thread here 適用於私訊和 Feishu/Lark 討論串訊息。已綁定對話中的後續訊息會直接路由到該 ACP 工作階段。

​
多代理路由

使用 bindings 將 Feishu/Lark 私訊或群組路由到不同代理。 
{
  agents: {
    list: [
      { id: "main" },
      { id: "agent-a", workspace: "/home/user/agent-a" },
      { id: "agent-b", workspace: "/home/user/agent-b" },
    ],
  },
  bindings: [
    {
      agentId: "agent-a",
      match: {
        channel: "feishu",
        peer: { kind: "direct", id: "ou_xxx" },
      },
    },
    {
      agentId: "agent-b",
      match: {
        channel: "feishu",
        peer: { kind: "group", id: "oc_zzz" },
      },
    },
  ],
}
路由欄位：
  • match.channel: "feishu"
  • match.peer.kind: "direct"（私訊）或 "group"（群組聊天）
  • match.peer.id: 使用者 Open ID（ou_xxx）或群組 ID（oc_xxx）
查閱 取得群組/使用者 ID 取得查找提示。

​
每位使用者的代理隔離（動態代理建立）

啟用 dynamicAgentCreation，即可為每位私訊使用者自動建立隔離的代理執行個體。每位使用者都有自己的：
  • 獨立工作區目錄
  • 個別的 USER.md / SOUL.md / MEMORY.md
  • 私人對話歷史
  • 隔離的 Skills 和狀態
這對公開 Bot 很重要，適合你希望每位使用者都有自己的私人 AI 助理體驗時使用。
動態綁定包含正規化後的 Feishu accountId，因此預設帳號和具名帳號會將每位傳送者路由到正確的動態代理。如果具名帳號在較舊版本中建立了未限定範圍的動態代理，該舊版代理仍會計入 maxAgents。移除前，請確認預設帳號未使用它，或暫時提高 maxAgents；OpenClaw 無法安全推斷模糊的舊版狀態屬於哪個帳號。

​
快速設定

{
  channels: {
    feishu: {
      dmPolicy: "open",
      allowFrom: ["*"],
      dynamicAgentCreation: {
        enabled: true,
        workspaceTemplate: "~/.openclaw/workspace-{agentId}",
        agentDirTemplate: "~/.openclaw/agents/{agentId}/agent",
      },
    },
  },
  session: {
    // Critical: makes each user's DM their "main session"
    // Automatically loads USER.md / SOUL.md / MEMORY.md
    // For stronger isolation, use "per-channel-peer" instead
    dmScope: "main",
  },
}

​
運作方式

當新使用者傳送第一則私訊時：
  1. 頻道會產生唯一的 agentId：預設帳號使用 feishu-{user_open_id}，具名帳號則使用有界的帳號前綴身分摘要
  2. 在 workspaceTemplate 路徑建立新的工作區
  3. 註冊代理，並為此使用者建立綁定
  4. 工作區輔助程式會在第一次存取時確保啟動檔案（AGENTS.md、SOUL.md、USER.md 等）存在
  5. 將此使用者之後的所有訊息路由到其專屬代理

​
設定選項

設定說明預設值
channels.feishu.dynamicAgentCreation.enabled啟用自動為每位使用者建立代理false
channels.feishu.dynamicAgentCreation.workspaceTemplate動態代理工作區的路徑範本~/.openclaw/workspace-{agentId}
channels.feishu.dynamicAgentCreation.agentDirTemplate代理目錄名稱範本~/.openclaw/agents/{agentId}/agent
channels.feishu.dynamicAgentCreation.maxAgents可建立的動態代理數量上限無限制
範本變數：
  • {agentId} - 產生的代理 ID（例如 feishu-ou_xxxxxx 或 feishu-support-<identity_digest>）
  • {userId} - 傳送者的 Feishu open_id（例如 ou_xxxxxx）

​
工作階段範圍

session.dmScope 控制直接訊息如何對應到代理工作階段。這是會影響所有頻道的全域設定。
值行為最適合
"main"每位使用者的私訊對應到其代理的主要工作階段你想自動載入 USER.md / SOUL.md 的單使用者 Bot
"per-peer"每個對等端取得個別工作階段（不論頻道為何）僅依傳送者身分隔離
"per-channel-peer"每個（頻道 + 使用者）組合取得個別工作階段需要更強隔離的公開多使用者 Bot
"per-account-channel-peer"每個（帳號 + 頻道 + 使用者）組合取得個別工作階段需要帳號層級工作階段隔離的多帳號 Bot
取捨：使用 "main" 會啟用自動啟動檔案載入（USER.md、SOUL.md、MEMORY.md），但也代表所有頻道中的所有私訊會共用相同的工作階段鍵模式。對於隔離比啟動自動載入更重要的公開多使用者 Bot，請考慮使用 "per-channel-peer"，並手動管理啟動檔案。
當具名 Feishu 帳號應該為同一位傳送者保留不同工作階段時，請使用 "per-account-channel-peer"。動態綁定會保留帳號範圍。

​
典型多使用者部署

{
  channels: {
    feishu: {
      appId: "cli_xxx",
      appSecret: "xxx",
      dmPolicy: "open",
      allowFrom: ["*"],
      groupPolicy: "open",
      requireMention: true,
      dynamicAgentCreation: {
        enabled: true,
        workspaceTemplate: "~/.openclaw/workspace-{agentId}",
        agentDirTemplate: "~/.openclaw/agents/{agentId}/agent",
      },
    },
  },
  session: {
    // Choose dmScope based on your isolation needs:
    // "main" for bootstrap auto-loading, "per-channel-peer" for stronger isolation
    dmScope: "main",
  },
  bindings: [], // Empty - dynamic agents auto-bind
}

​
驗證

檢查閘道記錄，確認動態建立正在運作： 
feishu: creating dynamic agent "feishu-ou_xxxxxx" for user ou_xxxxxx
  workspace: /home/user/.openclaw/workspace-feishu-ou_xxxxxx
  agentDir: /home/user/.openclaw/agents/feishu-ou_xxxxxx/agent
列出所有已建立的工作區： 
ls -la ~/.openclaw/workspace-*

​
注意事項

  • 工作區隔離：每位使用者都有自己的工作區目錄和代理執行個體。在正常訊息流程中，使用者無法看到彼此的對話歷史或檔案。
  • 安全邊界：這是訊息內容脈絡隔離機制，不是敵意共同租戶的安全邊界。代理程序和主機環境是共用的。
  • 設定寫入必須保持啟用：動態代理建立會將代理和綁定寫入設定；當 channels.feishu.configWrites 為 false 時會略過（預設：啟用）。
  • bindings 應為空：動態代理會自動註冊自己的綁定
  • 升級路徑：現有手動綁定會繼續與動態代理並行運作
  • session.dmScope 是全域設定：這會影響所有頻道，不只是 Feishu

​
設定參考

完整設定：閘道設定
設定描述預設值
channels.feishu.enabled啟用/停用頻道true
channels.feishu.domainAPI 網域（feishu、lark，或 https:// 基底 URL）feishu
channels.feishu.connectionMode事件傳輸（websocket 或 webhook）websocket
channels.feishu.defaultAccount外送路由的預設帳號default
channels.feishu.verificationToken網路鉤子模式必填-
channels.feishu.encryptKey網路鉤子模式必填-
channels.feishu.webhookPath網路鉤子路由路徑/feishu/events
channels.feishu.webhookHost網路鉤子繫結主機127.0.0.1
channels.feishu.webhookPort網路鉤子繫結連接埠3000
channels.feishu.accounts.<id>.appIdApp ID-
channels.feishu.accounts.<id>.appSecretApp Secret-
channels.feishu.accounts.<id>.domain個別帳號網域覆寫feishu
channels.feishu.accounts.<id>.tts個別帳號 TTS 覆寫messages.tts
channels.feishu.dmPolicyDM 政策（pairing、allowlist、open）pairing
channels.feishu.allowFromDM 允許清單（open_id 清單）-
channels.feishu.groupPolicy群組政策（open、allowlist、disabled）allowlist
channels.feishu.groupAllowFrom群組允許清單-
channels.feishu.groupSenderAllowFrom套用至所有群組的傳送者允許清單-
channels.feishu.requireMention在群組中要求 @提及true（政策為 open 時為 false）
channels.feishu.groups.<chat_id>.requireMention個別群組 @提及覆寫；明確 ID 也會在允許清單模式中允許該群組繼承
channels.feishu.groups.<chat_id>.enabled啟用/停用特定群組true
channels.feishu.groups.<chat_id>.allowFrom個別群組傳送者允許清單（覆寫 groupSenderAllowFrom）-
channels.feishu.groupSessionScope群組工作階段對應（group、group_sender、group_topic、group_topic_sender）group
channels.feishu.replyInThreadBot 回覆會建立/延續主題執行緒（disabled、enabled）disabled
channels.feishu.reactionNotifications傳入回應事件（off、own、all）own
channels.feishu.dynamicAgentCreation.enabled啟用自動個別使用者代理建立false
channels.feishu.dynamicAgentCreation.workspaceTemplate動態代理工作區的路徑範本~/.openclaw/workspace-{agentId}
channels.feishu.dynamicAgentCreation.agentDirTemplate代理目錄名稱範本~/.openclaw/agents/{agentId}/agent
channels.feishu.dynamicAgentCreation.maxAgents要建立的動態代理數量上限無限制
channels.feishu.textChunkLimit訊息區塊大小4000
channels.feishu.chunkMode區塊分割（length 或 newline）length
channels.feishu.mediaMaxMb媒體大小限制30
channels.feishu.renderMode回覆算繪（auto、raw、card）auto
channels.feishu.streaming串流卡片輸出true
channels.feishu.blockStreaming已完成區塊回覆串流false
channels.feishu.typingIndicator傳送輸入中回應true
channels.feishu.resolveSenderNames解析傳送者顯示名稱true
channels.feishu.configWrites允許頻道發起的設定寫入（動態代理需要）true
channels.feishu.tools.doc啟用文件工具true
channels.feishu.tools.chat啟用聊天資訊工具true
channels.feishu.tools.wiki啟用知識庫工具（需要 doc）true
channels.feishu.tools.drive啟用雲端儲存工具true
channels.feishu.tools.perm啟用權限管理工具false
channels.feishu.tools.scopes啟用 App 範圍診斷工具true
channels.feishu.tools.bitable啟用 Bitable/Base 工具true
channels.feishu.tools.basechannels.feishu.tools.bitable 的別名；兩者皆設定時，明確的 bitable 優先true
channels.feishu.accounts.<id>.tools.bitable個別帳號 Bitable/Base 工具閘門繼承
channels.feishu.accounts.<id>.tools.base個別帳號 tools.bitable 的別名繼承

​
支援的訊息類型

​
接收

  • ✅ 文字
  • ✅ 富文字（貼文）
  • ✅ 圖片
  • ✅ 檔案
  • ✅ 音訊
  • ✅ 影片/媒體
  • ✅ 貼圖
傳入的 Feishu/Lark 音訊訊息會正規化為媒體佔位符，而不是原始 file_key JSON。設定 tools.media.audio 時，OpenClaw 會下載語音記事資源，並在代理回合前執行共用音訊轉錄，讓代理收到語音逐字稿。如果 Feishu 直接在音訊酬載中包含逐字稿文字，則會使用該文字，不會再進行一次 ASR 呼叫。若沒有音訊轉錄提供者，代理仍會收到 <media:audio> 佔位符以及已儲存的附件，而不是原始 Feishu 資源酬載。

​
傳送

  • ✅ 文字
  • ✅ 圖片
  • ✅ 檔案
  • ✅ 音訊
  • ✅ 影片/媒體
  • ✅ 互動式卡片（包含串流更新）
  • ⚠️ 富文字（貼文樣式格式；不支援完整 Feishu/Lark 編寫能力）
原生 Feishu/Lark 音訊泡泡使用 Feishu audio 訊息類型，並需要 Ogg/Opus 上傳媒體（file_type: "opus"）。現有的 .opus 和 .ogg 媒體會直接以原生音訊傳送。只有在回覆要求語音傳遞（audioAsVoice / 訊息工具 asVoice，包含 TTS 語音記事回覆）時，MP3/WAV/M4A 及其他可能的音訊格式才會透過 ffmpeg 轉碼為 48kHz Ogg/Opus。一般 MP3 附件仍會維持一般檔案。如果缺少 ffmpeg 或轉換失敗，OpenClaw 會退回為檔案附件並記錄原因。

​
執行緒與回覆

  • ✅ 內嵌回覆
  • ✅ 執行緒回覆
  • ✅ 回覆執行緒訊息時，媒體回覆會保持執行緒感知
主題群組工作階段路由涵蓋於 群組工作階段範圍與主題執行緒。

​
相關