飛書

Feishu/Lark 是一套一體化協作平台，團隊可在其中聊天、分享文件、管理行事曆並共同完成工作。

狀態： 可正式用於機器人私訊 + 群組聊天。WebSocket 是預設模式；webhook 模式為選用。

快速開始

openclaw channels login --channel feishu

openclaw gateway restart

存取控制

私訊

設定 dmPolicy 來控制誰可以私訊機器人：

• "pairing" - 未知使用者會收到配對碼；透過 CLI 核准
• "allowlist" - 只有列在 allowFrom 中的使用者可以聊天（預設：僅機器人擁有者）
• "open" - 只有在 allowFrom 包含 "*" 時才允許公開私訊；若有嚴格限制項目，只有相符的使用者可以聊天
• "disabled" - 停用所有私訊

核准配對要求：

openclaw pairing list feishuopenclaw pairing approve feishu <CODE>

群組聊天

群組政策（channels.feishu.groupPolicy）：

預設值：allowlist

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

• true - 需要 @提及（預設）
• false - 不需 @提及即可回應
• 每個群組覆寫：channels.feishu.groups.<chat_id>.requireMention
• 僅廣播用的 @all 和 @_all 不會被視為機器人提及。同時提及 @all 和直接提及機器人的訊息，仍會計為機器人提及。

群組設定範例

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

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

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

{  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"],        },      },    },  },}

取得群組/使用者 ID

群組 ID（chat_id，格式：oc_xxx）

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

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

啟動 Gateway，向機器人傳送私訊，然後檢查記錄：

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. 確認已選取持久連線（WebSocket）
4. 確認所有必要的權限範圍都已授予
5. 確認 Gateway 正在執行：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. 重新啟動 Gateway：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 設定可以將共用 provider 憑證保留在全域，同時只針對每個帳號覆寫語音、模型、persona 或自動模式。

訊息限制

• textChunkLimit - 對外文字分段大小（預設：2000 個字元）
• mediaMaxMb - 媒體上傳/下載限制（預設：30 MB）

串流

Feishu/Lark 支援透過互動卡片提供串流回覆。啟用後，機器人會在產生文字時即時更新卡片。

{  channels: {    feishu: {      streaming: true, // enable streaming card output (default: true)      blockStreaming: true, // opt into completed-block streaming    },  },}

設定 streaming: false 可用一則訊息傳送完整回覆。blockStreaming 預設為關閉；只有在你希望於最終回覆前先送出已完成的 assistant 區塊時才啟用。

配額最佳化

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

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

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

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 工作階段。

多 Agent 路由

使用 bindings 將 Feishu/Lark 私訊或群組路由至不同 Agent。

{  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 取得查詢提示。

設定參考

完整設定：Gateway 設定

支援的訊息類型

接收

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

傳入的 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 會退回使用檔案附件並記錄原因。

執行緒與回覆

• ✅ 行內回覆
• ✅ 執行緒回覆
• ✅ 回覆執行緒訊息時，媒體回覆會保持執行緒感知

對於 groupSessionScope: "group_topic" 和 "group_topic_sender"，原生 Feishu/Lark 主題群組會使用事件 thread_id（omt_*）作為標準主題工作階段鍵。如果原生主題起始事件省略 thread_id，OpenClaw 會在路由該回合前從 Feishu 補齊。OpenClaw 轉換為執行緒的一般群組回覆會繼續使用回覆根訊息 ID（om_*），因此第一個回合和後續回合會留在同一個工作階段中。

相關

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