串接 Feishu 機器人教學

Feishu (Lark) 是企業常用的團隊聊天平台，用於訊息溝通與協作。這個外掛透過平台的 WebSocket 事件訂閱將 OpenClaw 連接到 Feishu/Lark 機器人，讓你在不需要公開 webhook URL 的情況下也能接收訊息。

內建外掛

Feishu 已經內建在目前的 OpenClaw 版本中，所以不需要另外安裝外掛。

如果你使用的是舊版本或不包含內建 Feishu 的自定義安裝，請手動安裝：

openclaw plugins install @openclaw/feishu

快速上手

有兩種方式可以新增 Feishu 頻道：

方法 1：引導流程（推薦）

如果你剛安裝完 OpenClaw，請執行引導流程：

openclaw onboard

設定精靈會引導你完成：

建立 Feishu 應用程式並取得憑證
在 OpenClaw 中設定應用程式憑證
啟動 Gateway

✅ 設定完成後，檢查 Gateway 狀態：

openclaw gateway status
openclaw logs --follow

方法 2：CLI 設定

如果你已經完成了初始安裝，可以透過 CLI 新增頻道：

openclaw channels add

選擇 Feishu，然後輸入 App ID 和 App Secret。

✅ 設定完成後，管理你的 Gateway：

openclaw gateway status
openclaw gateway restart
openclaw logs --follow

第一步：建立 Feishu 應用程式

1. 開啟 Feishu 開放平台

訪問 Feishu 開放平台並登入。

Lark（全球版）租戶應使用 https://open.larksuite.com/app，並在 Feishu 設定中將 domain 設為 "lark"。

2. 建立應用程式

點擊 建立企業自建應用
填寫應用程式名稱 + 描述
選擇應用程式圖示

Create enterprise app

3. 複製憑證

從 憑證與基礎資訊 中，複製：

App ID (格式為：cli_xxx)
App Secret

❗ 重要： 請務必私密保存 App Secret。

Get credentials

4. 設定權限

在 權限管理 頁面，點擊 批量匯入 並貼上：

{
  "scopes": {
    "tenant": [
      "aily:file:read",
      "aily:file:write",
      "application:application.app_message_stats.overview:readonly",
      "application:application:self_manage",
      "application:bot.menu:write",
      "cardkit:card:read",
      "cardkit:card:write",
      "contact:user.employee_id:readonly",
      "corehr:file:download",
      "event:ip_list",
      "im:chat.access_event.bot_p2p_chat:read",
      "im:chat.members:bot_access",
      "im:message",
      "im:message.group_at_msg:readonly",
      "im:message.p2p_msg:readonly",
      "im:message:readonly",
      "im:message:send_as_bot",
      "im:resource"
    ],
    "user": ["aily:file:read", "aily:file:write", "im:chat.access_event.bot_p2p_chat:read"]
  }
}

Configure permissions

5. 啟用機器人功能

在 應用功能 > 機器人 中：

啟用機器人功能
設定機器人名稱

Enable bot capability

6. 設定事件訂閱

⚠️ 重要： 在設定事件訂閱之前，請確保：

你已經為 Feishu 執行了 openclaw channels add
Gateway 正在執行中 (openclaw gateway status)

在 事件訂閱 中：

選擇 使用長連接接收事件 (WebSocket)
新增事件：im.message.receive_v1
(選填) 如果需要雲端文件評論工作流，也請新增：drive.notice.comment_add_v1

⚠️ 如果 Gateway 沒有執行，長連接設定可能會儲存失敗。

Configure event subscription

7. 發佈應用程式

在 版本管理與發佈 中建立一個版本
提交審核並發佈
等待管理員審核（企業自建應用通常會自動通過）

第二步：設定 OpenClaw

使用精靈設定（推薦）

openclaw channels add

選擇 Feishu 並貼上你的 App ID + App Secret。

透過設定檔設定

編輯 ~/.openclaw/openclaw.json：

{
  channels: {
    feishu: {
      enabled: true,
      dmPolicy: "pairing",
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "xxx",
          name: "My AI assistant",
        },
      },
    },
  },
}

如果你使用 connectionMode: "webhook"，請同時設定 verificationToken 和 encryptKey。Feishu webhook 伺服器預設綁定到 127.0.0.1；只有在你明確需要不同的綁定地址時才設定 webhookHost。

Verification Token 與 Encrypt Key (webhook 模式)

使用 webhook 模式時，請在設定中填寫 channels.feishu.verificationToken 和 channels.feishu.encryptKey。取得這些值的方法：

在 Feishu 開放平台開啟你的應用程式
前往 開發配置 → 事件與回调
開啟 加密策略 頁籤
複製 Verification Token 和 Encrypt Key

下圖顯示了 Verification Token 的位置。Encrypt Key 也在同一個 加密策略 區塊中。

Verification Token location

透過環境變數設定

export FEISHU_APP_ID="cli_xxx"
export FEISHU_APP_SECRET="xxx"

Lark (全球版) 網域

如果你的租戶在 Lark（國際版），請將 domain 設為 lark（或完整的網域字串）。你可以在 channels.feishu.domain 進行全域設定，或在每個帳號 (channels.feishu.accounts.<id>.domain) 中單獨設定。

{
  channels: {
    feishu: {
      domain: "lark",
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "xxx",
        },
      },
    },
  },
}

配額優化標記

你可以透過兩個選填標記來減少 Feishu API 的使用量：

typingIndicator (預設為 true)：設為 false 時，跳過「正在輸入」的狀態呼叫。
resolveSenderNames (預設為 true)：設為 false 時，跳過發送者個人資料的查詢呼叫。

你可以在頂層或針對每個帳號進行設定：

{
  channels: {
    feishu: {
      typingIndicator: false,
      resolveSenderNames: false,
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "xxx",
          typingIndicator: true,
          resolveSenderNames: false,
        },
      },
    },
  },
}

步驟 3：啟動與測試

1. 啟動 Gateway

openclaw gateway

2. 傳送測試訊息

在 Feishu 中找到你的機器人並傳送一則訊息。

3. 核准配對

預設情況下，機器人會回覆一個配對碼。請核准它：

openclaw pairing approve feishu <CODE>

核准之後，你就可以正常聊天了。

概覽

Feishu 機器人頻道：由 Gateway 管理的 Feishu 機器人
確定性路由：回覆總是會回到 Feishu
會話隔離：私訊共用一個主會話；群組則是獨立的
WebSocket 連線：透過 Feishu SDK 建立長連線，不需要公開 URL

存取控制

私訊

預設：dmPolicy: "pairing"（未知使用者會收到配對碼）

核准配對：

openclaw pairing list feishu
openclaw pairing approve feishu <CODE>

白名單模式：在 channels.feishu.allowFrom 設定允許的 Open ID

群組聊天

1. 群組策略 (channels.feishu.groupPolicy)：

"open" = 允許群組內的所有人
"allowlist" = 僅允許 groupAllowFrom 中的對象
"disabled" = 停用群組訊息

預設值：allowlist

2. 提及要求 (channels.feishu.requireMention，可透過 channels.feishu.groups.<chat_id>.requireMention 覆蓋)：

明確設為 true = 需要 @提及
明確設為 false = 不需提及即可回應
未設定且 groupPolicy: "open" = 預設為 false
未設定且 groupPolicy 不是 "open" = 預設為 true

群組設定範例

允許所有群組，不需 @提及（公開群組的預設值）

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

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

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

僅允許特定群組

{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      // Feishu group IDs (chat_id) look like: oc_xxx
      groupAllowFrom: ["oc_xxx", "oc_yyy"],
    },
  },
}

限制群組內的傳送者（傳送者白名單）

除了允許群組本身之外，該群組內的所有訊息都會受到傳送者 open_id 的限制：只有列在 groups.<chat_id>.allowFrom 中的使用者訊息才會被處理；其他成員的訊息將被忽略（這是完整的傳送者層級過濾，不只是針對 /reset 或 /new 等控制指令）。

{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["oc_xxx"],
      groups: {
        oc_xxx: {
          // Feishu user IDs (open_id) look like: ou_xxx
          allowFrom: ["ou_user1", "ou_user2"],
        },
      },
    },
  },
}

獲取群組/使用者 ID

群組 ID (chat_id)

群組 ID 的格式通常是 oc_xxx。

方法 1（推薦）

啟動 Gateway 並在群組中 @ 機器人
執行 openclaw logs --follow 並尋找 chat_id

方法 2

使用 Feishu API 除錯工具來列出群組對話。

使用者 ID (open_id)

使用者 ID 的格式通常是 ou_xxx。

方法 1（推薦）

啟動 Gateway 並私訊機器人
執行 openclaw logs --follow 並尋找 open_id

方法 2

檢查配對請求來獲取使用者的 Open ID：

openclaw pairing list feishu

常見指令

指令	說明
`/status`	顯示機器人狀態
`/reset`	重設對話
`/model`	顯示/切換模型

注意：Feishu 目前還不支援原生的指令選單，所以指令必須以文字形式發送。

Gateway 管理指令

指令	描述
`openclaw gateway status`	顯示 Gateway 狀態
`openclaw gateway install`	安裝/啟動 Gateway 服務
`openclaw gateway stop`	停止 Gateway 服務
`openclaw gateway restart`	重啟 Gateway 服務
`openclaw logs --follow`	即時查看 Gateway 日誌

故障排除

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

確認機器人已加入群組
確認你有 @ 機器人（這是預設行為）
檢查 groupPolicy 並未設定為 "disabled"
查看日誌：openclaw logs --follow

機器人收不到訊息

確認應用程式已發佈並通過審核
確認事件訂閱包含 im.message.receive_v1
確認已開啟 long connection
確認應用程式權限完整
確認 Gateway 正在運行：openclaw gateway status
查看日誌：openclaw logs --follow

App Secret 洩漏

在飛書開放平台重置 App Secret
更新你的 config 並重啟 Gateway

訊息發送失敗

確認應用程式已發佈並具備 im:message:send_as_bot 權限
查看日誌以獲取詳細錯誤資訊

進階配置

多個帳號

{
  channels: {
    feishu: {
      defaultAccount: "main",
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "xxx",
          name: "Primary bot",
        },
        backup: {
          appId: "cli_yyy",
          appSecret: "yyy",
          name: "Backup bot",
          enabled: false,
        },
      },
    },
  },
}

defaultAccount 用來控制當傳出 API 沒有明確指定 accountId 時，預設使用哪個 Feishu 帳號。

訊息限制

textChunkLimit: 傳出文字的分段大小（預設：2000 字）
mediaMaxMb: 媒體檔案上傳/下載限制（預設：30MB）

串流

Feishu 支援透過互動式卡片進行串流回覆。開啟後，機器人在生成文字時會同步更新卡片內容。

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

將 streaming: false 設為 false 可以等待完整回覆生成後再發送。

ACP 會話

Feishu 支援 ACP 於：

私聊 (DMs)
群組話題對話 (group topic conversations)

Feishu ACP 是由文字指令驅動的。目前沒有原生的 slash-command 選單，所以請直接在對話中使用 /acp ... 訊息。

持久化 ACP 綁定

使用頂層的類型化 ACP 綁定，將 Feishu 私聊或話題對話固定到持久的 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 私聊或話題對話中，你可以就地啟動並綁定一個 ACP 會話：

/acp spawn codex --thread here

注意：

--thread here 適用於私聊和 Feishu 話題。
在已綁定的私聊/話題中發送的後續訊息會直接路由到該 ACP 會話。
v1 版本不支援一般非話題類型的群組聊天。

多 Agent 路由

使用 bindings 將 Feishu 私聊或群組路由到不同的 Agent。

{
  agents: {
    list: [
      { id: "main" },
      {
        id: "clawd-fan",
        workspace: "/home/user/clawd-fan",
        agentDir: "/home/user/.openclaw/agents/clawd-fan/agent",
      },
      {
        id: "clawd-xi",
        workspace: "/home/user/clawd-xi",
        agentDir: "/home/user/.openclaw/agents/clawd-xi/agent",
      },
    ],
  },
  bindings: [
    {
      agentId: "main",
      match: {
        channel: "feishu",
        peer: { kind: "direct", id: "ou_xxx" },
      },
    },
    {
      agentId: "clawd-fan",
      match: {
        channel: "feishu",
        peer: { kind: "direct", id: "ou_yyy" },
      },
    },
    {
      agentId: "clawd-xi",
      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 configuration

關鍵選項：

設定	描述	預設值
`channels.feishu.enabled`	啟用/停用頻道	`true`
`channels.feishu.domain`	API 網域 (`feishu` 或 `lark`)	`feishu`
`channels.feishu.connectionMode`	事件傳輸模式	`websocket`
`channels.feishu.defaultAccount`	傳出路由的預設帳號 ID	`default`
`channels.feishu.verificationToken`	Webhook 模式必填	-
`channels.feishu.encryptKey`	Webhook 模式必填	-
`channels.feishu.webhookPath`	Webhook 路由路徑	`/feishu/events`
`channels.feishu.webhookHost`	Webhook 綁定主機	`127.0.0.1`
`channels.feishu.webhookPort`	Webhook 綁定連接埠	`3000`
`channels.feishu.accounts.<id>.appId`	App ID	-
`channels.feishu.accounts.<id>.appSecret`	App Secret	-
`channels.feishu.accounts.<id>.domain`	每個帳號的 API 網域覆寫	`feishu`
`channels.feishu.dmPolicy`	私聊策略	`pairing`
`channels.feishu.allowFrom`	私聊白名單 (open_id 列表)	-
`channels.feishu.groupPolicy`	群組策略	`allowlist`
`channels.feishu.groupAllowFrom`	群組白名單	-
`channels.feishu.requireMention`	預設需要 @mention	視情況而定
`channels.feishu.groups.<chat_id>.requireMention`	每個群組的 @mention 需求覆寫	繼承預設值
`channels.feishu.groups.<chat_id>.enabled`	啟用群組	`true`
`channels.feishu.textChunkLimit`	訊息分段大小	`2000`
`channels.feishu.mediaMaxMb`	媒體大小限制	`30`
`channels.feishu.streaming`	啟用串流卡片輸出	`true`
`channels.feishu.blockStreaming`	啟用區塊串流	`true`

dmPolicy 參考

值	行為
`"pairing"`	預設值。未知使用者會收到配對碼；必須經過核准
`"allowlist"`	只有在 `allowFrom` 中的使用者可以聊天
`"open"`	允許所有使用者（需要在 `allowFrom` 中設定 `"*"`）
`"disabled"`	停用私訊 (DMs)

支援的訊息類型

接收 (Receive)

✅ 文字 (Text)
✅ 富文本 (Rich text / post)
✅ 圖片 (Images)
✅ 檔案 (Files)
✅ 音訊 (Audio)
✅ 影片/多媒體 (Video/media)
✅ 貼圖 (Stickers)

發送 (Send)

✅ 文字 (Text)
✅ 圖片 (Images)
✅ 檔案 (Files)
✅ 音訊 (Audio)
✅ 影片/多媒體 (Video/media)
✅ 互動式卡片 (Interactive cards)
⚠️ 富文本 (Rich text - 支援 post 樣式的格式化與卡片，但不包含飛書所有的自定義編輯功能)

串文與回覆 (Threads and replies)

✅ 行內回覆 (Inline replies)
✅ 在 Feishu 提供 reply_in_thread 的情況下支援主題串文回覆
✅ 回覆串文或主題訊息時，多媒體回覆會保持串文關聯 (thread-aware)

雲端文件評論

當有人在 Feishu 雲端文件（如 Docs、Sheets 等）新增評論時，Feishu 可以觸發 agent。Agent 會收到評論文字、文件上下文以及評論串（thread），讓它能在串內回覆或直接編輯文件。

需求：

在你的 Feishu app 事件訂閱設定中訂閱 drive.notice.comment_add_v1（與現有的 im.message.receive_v1 並列）
Drive 工具預設為啟用；若要停用請設定 channels.feishu.tools.drive: false

feishu_drive 工具提供以下評論操作：

操作	描述
`list_comments`	列出文件上的評論
`list_comment_replies`	列出評論串中的回覆
`add_comment`	新增一條頂層評論
`reply_comment`	回覆現有的評論串

當 agent 處理 Drive 評論事件時，它會收到：

評論文字
發送者資訊
文件 metadata（標題、類型、URL）
用於串內回覆的評論串上下文

在編輯完文件後，系統會引導 agent 使用 feishu_drive.reply_comment 來通知評論者，接著輸出 NO_REPLY 以避免重複發送。

執行階段操作範圍

Feishu 目前提供以下執行階段操作：

send
read
edit
thread-reply
pin
list-pins
unpin
member-info
channel-info
channel-list
react 與 reactions（當設定中啟用 reactions 時）
feishu_drive 評論操作：list_comments, list_comment_replies, add_comment, reply_comment

還是卡住了？

如果這篇文件沒有解決你的情境，直接問 OpenClaw Expert，拿到可執行步驟。