Feishu

OpenClaw 透過官方 @openclaw/feishu 外掛連線至 Feishu/Lark（多合一協作平台）：機器人私訊、群組聊天、串流卡片回覆，以及 Feishu 文件／知識庫／雲端硬碟／多維表格工具。

**狀態：**機器人私訊與群組聊天已可用於正式環境。WebSocket 是預設的事件傳輸方式（不需要公開 URL）；亦可選用網路鉤子模式。

快速開始

openclaw channels login --channel feishu

openclaw gateway restart

傳入事件持久性

OpenClaw 會在分派給代理程式前，將已驗證身分的 im.message.receive_v1 和 drive.notice.comment_add_v1 封套持久排入佇列。待處理或可重試的事件會在閘道重新啟動後保留、依每個聊天或文件維持序列化，並在現用或保留的完成記錄存在期間，使用 Feishu 的事件 ID 防止產生重複的佇列項目。

若 WebSocket 事件在有限次重試後仍無法持久儲存，OpenClaw 會關閉該通訊端並強制建立新的已驗證連線，而不會略過未提交的回合繼續處理。其他 Feishu 事件類型（包括表情回應和視訊會議邀請）會使用其一般事件路徑，且不享有此持久佇列保證。

存取控制

私訊

設定 channels.feishu.dmPolicy（預設值：pairing）以控制哪些人可以私訊機器人：

核准配對要求：

openclaw pairing list feishuopenclaw pairing approve feishu <CODE>

群組聊天

群組政策（channels.feishu.groupPolicy，預設值：allowlist）：

提及要求（channels.feishu.requireMention）：

• 預設：必須 @提及，但有效群組政策為 "open" 時除外；在該政策下，預設值為 false，讓無法包含提及的訊息（例如圖片）仍能傳送至代理程式。
• 明確設定 true 或 false 以覆寫；各群組的覆寫設定：channels.feishu.groups.<chat_id>.requireMention。
• 僅限廣播的 @all 和 @_all 不會視為提及機器人。同時提及 @all 並直接提及機器人的訊息，仍視為提及機器人。

群組設定範例

允許所有群組，不要求 @提及

{  channels: {    feishu: {      groupPolicy: "open", // 在 "open" 下，requireMention 預設為 false    },  },}

允許所有群組，仍要求 @提及

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

僅允許特定群組

{  channels: {    feishu: {      groupPolicy: "allowlist",      // 群組 ID 的格式如下：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: {          // 使用者 open_id 的格式如下：ou_xxx          allowFrom: ["ou_user1", "ou_user2"],        },      },    },  },}

channels.feishu.groupSenderAllowFrom 會為所有群組設定相同的傳送者允許清單；各群組的 allowFrom 優先適用。

機器人撰寫的訊息

Feishu 預設會忽略其他機器人撰寫的訊息。若要允許機器人之間進行群組對話，請授予應用程式 im:message.group_at_msg.include_bot:readonly 和 im:message:readonly 權限範圍，然後設定 allowBots：

{  channels: {    feishu: {      allowBots: true,    },  },}

只有在其他機器人提及此機器人時，Feishu 才會傳送由機器人撰寫的群組事件。現有群組政策、傳送者允許清單和提及要求仍會套用。OpenClaw 會捨棄自己撰寫的訊息、在每個文字或卡片回覆中提及對方機器人，並套用共用的 channels.defaults.botLoopProtection 防護機制。

取得群組／使用者 ID

群組 ID（chat_id，格式：oc_xxx）

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

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

啟動閘道、傳送私訊給機器人，然後查看記錄：

openclaw logs --follow

在記錄輸出中尋找 open_id。你也可以查看待處理的配對要求：

openclaw pairing list feishu

常用命令

疑難排解

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

1. 確認機器人已加入群組
2. 確認你已 @提及機器人（預設為必要）
3. 確認 groupPolicy 不是 "disabled"
4. 查看記錄：openclaw logs --follow

機器人未收到訊息

1. 確認機器人已在 Feishu Open Platform / Lark Developer 發布並通過核准
2. 確認事件訂閱包含 im.message.receive_v1
3. 若要自動加入會議邀請，還需訂閱 vc.bot.meeting_invited_v1
4. 確認已選取 persistent connection（WebSocket）
5. 確認已授予所有必要的權限範圍
6. 確認閘道正在執行：openclaw gateway status
7. 查看記錄：openclaw logs --follow

訂閱 vc.bot.meeting_invited_v1 只會傳送事件。自動加入功能預設為關閉。若要全域啟用：

{  channels: {    feishu: {      vcAutoJoin: true,    },  },}

若只要為一個帳號啟用，請省略頂層開關並設定帳號覆寫：

{  channels: {    feishu: {      accounts: {        meetings: { vcAutoJoin: true },      },    },  },}

在代理程式收到加入回合前，邀請者仍會經過一般 Feishu 私訊政策、允許清單／配對、工作階段和回覆路由。加入會議還需要可用的 Feishu VC 加入工具，該工具須設定為使用具有 vc:meeting.bot.join:write 權限範圍的應用程式身分。例如，官方 lark-cli VC 代理程式技能 提供 vc +meeting-join。

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: "主要機器人",          tts: {            providers: {              openai: { voice: "shimmer" },            },          },        },        backup: {          appId: "cli_yyy",          appSecret: "yyy",          name: "備用機器人",          enabled: false,        },      },    },  },}

defaultAccount 控制未由輸出 API 指定 accountId 時要使用的帳號。帳號項目會繼承頂層設定；大多數頂層鍵都可由各帳號覆寫。 accounts.<id>.tts 使用與 tts 相同的結構，並深度合併至全域 TTS 設定，因此多機器人的 Feishu 設定可以在全域共用供應商認證資訊，同時只覆寫各帳號的語音、模型、角色設定或自動模式。

訊息限制

• textChunkLimit - 輸出文字分段大小（預設值：4000 個字元）
• streaming.chunkMode - "length"（預設值）會在限制處分割；"newline" 優先依換行邊界分割
• mediaMaxMb - 媒體上傳／下載限制（預設值：30 MB）

串流

Feishu/Lark 支援透過互動式卡片（Card Kit 串流 API）進行串流回覆。啟用後，機器人會在產生文字時即時更新卡片。

{  channels: {    feishu: {      streaming: {        mode: "partial", // 串流卡片輸出（預設值："partial"）        block: { enabled: true }, // 選擇啟用完整區塊串流      },    },  },}

將 streaming.mode: "off" 設為在單一訊息中傳送完整回覆；renderMode: "raw"（使用純文字而非卡片）也會停用串流卡片。streaming.block.enabled 預設為關閉；只有在你希望於最終回覆前送出已完成的助理區塊時才啟用。舊版布林值 streaming 以及扁平的 blockStreaming / blockStreamingCoalesce / chunkMode 鍵，會透過 openclaw doctor --fix 遷移至此巢狀結構。

配額最佳化

使用兩個選用旗標，減少 Feishu/Lark API 呼叫次數：

• typingIndicator（預設 true）：設為 false 以略過輸入狀態反應呼叫
• resolveSenderNames（預設 true）：設為 false 以略過傳送者個人資料查詢

{  channels: {    feishu: {      typingIndicator: false,      resolveSenderNames: false,    },  },}

群組工作階段範圍與主題討論串

channels.feishu.groupSessionScope（頂層、每個帳號或每個群組）控制群組訊息如何對應至代理程式工作階段：

對於主題範圍，原生 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.base 是 tools.bitable 的別名；兩者皆有設定時，以明確的 bitable 值為準。每個帳號的控管設定位於 accounts.<id>.tools 下。

若要在根目錄之外直接查詢 feishu_drive info，請授予 drive:drive.metadata:readonly， 除非應用程式已具備完整的 drive:drive 範圍。若兩種範圍皆無，info 仍可透過 drive:drive:readonly 使用舊版根目錄查詢。

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 與狀態

若公開機器人需要讓每位使用者擁有各自私密的 AI 助理體驗，這項功能至關重要。

快速設定

{  channels: {    feishu: {      dmPolicy: "open",      allowFrom: ["*"],      dynamicAgentCreation: {        enabled: true,        workspaceTemplate: "~/.openclaw/workspace-{agentId}",        agentDirTemplate: "~/.openclaw/agents/{agentId}/agent",      },    },  },  session: {    // 關鍵：讓每位使用者的私訊成為其「主要工作階段」    // 自動載入 USER.md / SOUL.md / MEMORY.md    // 若需要更強的隔離，請改用 "per-channel-peer"    dmScope: "main",  },}

運作方式

新使用者傳送第一則私訊時：

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

設定選項

範本變數：

• {agentId} - 產生的代理程式 ID（例如 feishu-ou_xxxxxx 或 feishu-support-<identity_digest>）
• {userId} - 傳送者的 Feishu open_id（例如 ou_xxxxxx）

工作階段範圍

session.dmScope 控制直接訊息如何對應至代理程式工作階段。這是會影響所有頻道的全域設定。

取捨：使用 "main" 會啟用自動載入啟動檔案（USER.md、SOUL.md、MEMORY.md），但也表示所有頻道的所有私訊會共用相同的工作階段鍵模式。對於隔離比自動載入啟動檔案更重要的公開多使用者機器人，請考慮使用 "per-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: {    // 根據隔離需求選擇 dmScope：    // "main" 用於自動載入啟動檔案，"per-channel-peer" 用於更強的隔離    dmScope: "main",  },  bindings: [], // 空白 - 動態代理程式會自動繫結}

驗證

檢查閘道記錄，以確認動態建立功能運作正常：

feishu：正在為使用者 ou_xxxxxx 建立動態代理程式 "feishu-ou_xxxxxx"  工作區：/home/user/.openclaw/workspace-feishu-ou_xxxxxx  代理程式目錄：/home/user/.openclaw/agents/feishu-ou_xxxxxx/agent

列出所有已建立的工作區：

ls -la ~/.openclaw/workspace-*

注意事項

• 工作區隔離：每位使用者都有自己的工作區目錄和代理程式執行個體。在一般訊息流程中，使用者無法查看彼此的對話記錄或檔案。
• 安全邊界：這是訊息情境隔離機制，而非針對具敵意共同租戶的安全邊界。代理程式處理程序和主機環境仍為共用。
• 必須保持啟用設定寫入：動態建立代理程式會將代理程式和繫結寫入設定；當 channels.feishu.configWrites 為 false 時會略過此操作（預設：啟用）。
• bindings 應為空白：動態代理程式會自動註冊自己的繫結
• 升級路徑：現有的手動繫結可繼續與動態代理程式搭配運作
• session.dmScope 為全域設定：這會影響所有頻道，不只 Feishu

設定參考

完整設定：閘道設定

支援的訊息類型

接收

• ✅ 文字
• ✅ 富文字（貼文）
• ✅ 圖片
• ✅ 檔案
• ✅ 音訊
• ✅ 影片／媒體
• ✅ 貼圖

傳入的 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 語音留言 回覆），才會使用 ffmpeg 將 MP3/WAV/M4A 及其他可能的音訊格式 轉碼為 48kHz Ogg/Opus。一般 MP3 附件仍會維持為一般檔案。如果缺少 ffmpeg 或 轉換失敗，OpenClaw 會改用檔案附件，並記錄原因。

討論串與回覆

• ✅ 行內回覆
• ✅ 討論串回覆
• ✅ 回覆討論串訊息時，媒體回覆仍會保留討論串脈絡

主題群組的工作階段路由涵蓋於 群組工作階段範圍與主題討論串。

相關內容

• 頻道概覽 - 所有支援的頻道
• 配對 - 私訊驗證與配對流程
• 群組 - 群組聊天行為與提及管控
• 頻道路由 - 訊息的工作階段路由
• 安全性 - 存取模型與強化措施