飛書機器人

飛書（Lark）是企業用於即時通訊與協作的團隊聊天平台。這個外掛透過平台的 WebSocket 事件訂閱將 OpenClaw 連接到飛書/Lark 機器人，因此無需公開 webhook URL 就能接收訊息。

內建外掛

飛書已隨目前的 OpenClaw 版本一同打包，無需另外安裝外掛。

如果你使用的是較舊的版本或未包含飛書的自訂安裝，請手動安裝：

openclaw plugins install @openclaw/feishu

快速開始

有兩種方式新增飛書頻道：

方式 1：引導精靈（建議）

如果你剛安裝 OpenClaw，執行精靈：

openclaw onboard

精靈會引導你完成：

1. 建立飛書應用程式並取得憑證
2. 在 OpenClaw 中設定應用程式憑證
3. 啟動閘道

設定完成後，檢查閘道狀態：

• openclaw gateway status
• openclaw logs --follow

方式 2：CLI 設定

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

openclaw channels add

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

設定完成後，管理閘道：

• openclaw gateway status
• openclaw gateway restart
• openclaw logs --follow

步驟 1：建立飛書應用程式

1. 開啟飛書開放平台

前往飛書開放平台並登入。

Lark（國際版）租戶應使用 https://open.larksuite.com/app，並在飛書設定中設定 domain: "lark"。

2. 建立應用程式

1. 點擊建立企業自建應用
2. 填寫應用程式名稱和描述
3. 選擇應用程式圖示

3. 複製憑證

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

• App ID（格式：cli_xxx）
• App Secret

警告： 請保管好 App Secret。

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

5. 啟用機器人功能

在應用功能 > 機器人中：

1. 啟用機器人功能
2. 設定機器人名稱

6. 設定事件訂閱

警告： 在設定事件訂閱之前，請確保：

1. 你已為飛書執行過 openclaw channels add
2. 閘道正在執行（openclaw gateway status）

在事件訂閱中：

1. 選擇使用長連線接收事件（WebSocket）
2. 新增事件：im.message.receive_v1

警告： 如果閘道未在執行，長連線設定可能無法儲存。

7. 發布應用程式

1. 在版本管理與發布中建立版本
2. 提交審核並發布
3. 等待管理員核准（企業應用通常會自動核准）

步驟 2：設定 OpenClaw

透過精靈設定（建議）

openclaw channels add

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

透過設定檔設定

編輯 ~/.openclaw/openclaw.json：

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

如果你使用 connectionMode: "webhook"，請同時設定 verificationToken 和 encryptKey。飛書 webhook 伺服器預設綁定到 127.0.0.1；僅在你刻意需要不同的綁定位址時才設定 webhookHost。

驗證 Token 和加密金鑰（webhook 模式）

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

1. 在飛書開放平台中開啟你的應用程式
2. 前往開發配置 → 事件與回調
3. 開啟加密策略標籤
4. 複製驗證 Token 和加密金鑰

下方截圖顯示驗證 Token 的位置。加密金鑰列在同一個加密策略區段中。

透過環境變數設定

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

Lark（國際版）網域

如果你的租戶在 Lark（國際版），將網域設定為 lark（或完整的網域字串）。你可以在 channels.feishu.domain 或每帳戶（channels.feishu.accounts.<id>.domain）設定。

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

配額最佳化旗標

你可以透過兩個選填旗標減少飛書 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. 啟動閘道

openclaw gateway

2. 傳送測試訊息

在飛書中找到你的機器人並傳送訊息。

3. 核准配對

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

openclaw pairing approve feishu <CODE>

核准後就可以正常對話了。

概覽

• 飛書機器人頻道：由閘道管理的飛書機器人
• 確定性路由：回覆總是回到飛書
• 工作階段隔離：DM 共享主工作階段；群組隔離
• WebSocket 連線：透過飛書 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" = 停用群組訊息

2. 提及要求（channels.feishu.groups.<chat_id>.requireMention）：

• true = 需要 @提及（預設）
• false = 不需提及即可回應

群組設定範例

允許所有群組，需要 @提及（預設）

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

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

{
  channels: {
    feishu: {
      groups: {
        oc_xxx: { requireMention: false },
      },
    },
  },
}

僅允許特定群組

{
  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（建議）

1. 啟動閘道，在群組中 @提及機器人
2. 執行 openclaw logs --follow 並找到 chat_id

方式 2

使用飛書 API 偵錯工具列出群組聊天。

使用者 ID（open_id）

使用者 ID 格式為 ou_xxx。

方式 1（建議）

1. 啟動閘道，向機器人傳送私訊
2. 執行 openclaw logs --follow 並找到 open_id

方式 2

檢查配對請求以取得使用者 Open ID：

openclaw pairing list feishu

常用指令

注意：飛書尚不支援原生指令選單，因此指令必須以文字方式傳送。

閘道管理指令

疑難排解

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

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

機器人沒有收到訊息

1. 確認應用程式已發布並核准
2. 確認事件訂閱包含 im.message.receive_v1
3. 確認已啟用長連線
4. 確認應用程式權限完整
5. 確認閘道正在執行：openclaw gateway status
6. 檢查記錄：openclaw logs --follow

App Secret 洩露

1. 在飛書開放平台重設 App Secret
2. 更新設定中的 App Secret
3. 重啟閘道

訊息傳送失敗

1. 確認應用程式有 im:message:send_as_bot 權限
2. 確認應用程式已發布
3. 檢查記錄以取得詳細錯誤資訊

進階設定

多帳戶

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

defaultAccount 控制當傳出 API 未明確指定 accountId 時使用哪個飛書帳戶。

訊息限制

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

串流

飛書透過互動式卡片支援串流回覆。啟用後，機器人會在產生文字時更新卡片。

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

設定 streaming: false 可在完整回覆完成後才傳送。

多代理路由

使用 bindings 將飛書 DM 或群組路由到不同代理。

{
  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 了解查詢方法。

設定參考

完整設定：閘道設定

重要選項：

dmPolicy 參考

支援的訊息類型

接收

• ✅ 文字
• ✅ 富文字（post）
• ✅ 圖片
• ✅ 檔案
• ✅ 音訊
• ✅ 影片
• ✅ 貼圖

傳送

• ✅ 文字
• ✅ 圖片
• ✅ 檔案
• ✅ 音訊
• ⚠️ 富文字（部分支援）