【最新版】FeishuでOpenClawを使う方法（Bot連携・WebSocketイベント購読）

Feishu

Feishu bot

Feishu（Lark）は、企業でメッセージングとコラボレーションに使われるチームチャットプラットフォームです。 このプラグインは、Feishu/Lark のBotをプラットフォームの WebSocket イベント購読（ロングコネクション）で接続し、公開Webhook URLを露出せずにメッセージを受信できるようにします。

Bundled plugin

Feishu は現行の OpenClaw リリースに同梱されているため、別途プラグインをインストールする必要はありません。

もし古いビルドや、同梱 Feishu を含まないカスタムインストールを使っている場合は、手動でインストールしてください。

openclaw plugins install @openclaw/feishu

Quickstart

Feishu チャネルを追加する方法は2つあります。

Method 1: onboarding（推奨）

OpenClaw をインストールしたばかりなら、オンボーディングを実行します。

openclaw onboard

ウィザードが次の作業を案内します。

• Feishu アプリの作成と、認証情報の収集
• OpenClaw へのアプリ認証情報の設定
• Gateway の起動

✅ 設定後は、Gateway の状態を確認します。

• openclaw gateway status
• openclaw logs --follow

Method 2: CLI setup

初期インストールがすでに完了している場合は、CLIからチャネルを追加します。

openclaw channels add

一覧から Feishu を選び、App ID と App Secret を入力します。

✅ 設定後は、Gateway を管理します。

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

Step 1: Create a Feishu app

1. Open Feishu Open Platform

Feishu Open Platformにアクセスしてサインインします。

Lark（グローバル）テナントの場合はhttps://open.larksuite.com/appを使い、Feishu の設定で domain: "lark" を設定してください。

2. Create an app

1. Create enterprise app をクリック
2. アプリ名と説明を入力
3. アプリアイコンを選択

参考画像：Create enterprise app

3. Copy credentials

Credentials & Basic Info から次をコピーします。

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

❗ 重要: App Secret は必ず非公開で管理してください。

参考画像：Get credentials

4. Configure permissions

Permissions で Batch import をクリックし、次を貼り付けます。

{
  "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

App Capability > Bot で次を行います。

1. Bot capability を有効化
2. Bot 名を設定

参考画像：Enable bot capability

6. Configure event subscription

⚠️ 重要: イベント購読を設定する前に、次を満たしていることを確認してください。

1. Feishu を openclaw channels add で追加済みであること
2. Gateway が稼働中であること（openclaw gateway status）

Event Subscription で次を設定します。

1. Use long connection to receive events（WebSocket）を選択
2. イベント im.message.receive_v1 を追加

⚠️ Gateway が動いていないと、ロングコネクションの設定が保存できないことがあります。

参考画像：Configure event subscription

7. Publish the app

1. Version Management & Release でバージョンを作成
2. レビューに提出し、公開
3. 管理者承認を待つ（Enterprise app は通常自動承認）

Step 2: Configure OpenClaw

Configure with the wizard（推奨）

openclaw channels add

一覧から Feishu を選び、App ID と App Secret を貼り付けます。

Configure via config file

~/.openclaw/openclaw.json を編集します。

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

connectionMode: "webhook" を使う場合は、verificationToken と encryptKey の両方を設定してください。 Feishu の webhook サーバーはデフォルトで 127.0.0.1 に bind します。 意図的に別の bind アドレスが必要な場合のみ webhookHost を設定してください。

Verification Token と Encrypt Key（webhook mode）

Webhook mode を使う場合、設定で次の2つを両方指定します。

• channels.feishu.verificationToken
• channels.feishu.encryptKey

値の取得手順：

1. Feishu Open Platform でアプリを開く
2. Development → Events & Callbacks（开发配置 → 事件与回调）へ移動
3. Encryption タブ（加密策略）を開く
4. Verification Token と Encrypt Key をコピー

以下の画像は Verification Token の場所を示しています（Encrypt Key も同じ Encryption セクションにあります）。

参考画像：Verification Token location

Configure via environment variables

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

Lark（global）domain

テナントが Lark（国際）にある場合は、domain を lark（または完全なドメイン文字列）に設定します。channels.feishu.domain もしくはアカウント単位（channels.feishu.accounts.<id>.domain）で設定できます。

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

Quota optimization flags

Feishu API の利用量を減らすために、2つの任意フラグを使用できます。

• typingIndicator（デフォルト true）：false の場合、typing reaction の呼び出しをスキップします。
• resolveSenderNames（デフォルト true）：false の場合、送信者プロフィールのルックアップ呼び出しをスキップします。

トップレベル、またはアカウント単位で設定します。

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

Step 3: Start + test

1. Start the gateway

openclaw gateway

2. Send a test message

Feishu でボットを見つけて、メッセージを送ります。

3. Approve pairing

デフォルトでは、ボットはペアリングコードを返信します。次で承認します。

openclaw pairing approve feishu <CODE>

承認後、通常のチャットができるようになります。

Overview

• Feishu bot channel: Gateway によって管理される Feishu bot
• Deterministic routing: 返信は常に Feishu に戻る
• Session isolation: DM はメインセッションを共有し、グループは分離される
• WebSocket connection: Feishu SDK によるロングコネクションで、公開URL不要

Access control

Direct messages

• デフォルト: dmPolicy: "pairing"（不明なユーザーにはペアリングコードを返す）

ペアリング承認：

openclaw pairing list feishu
openclaw pairing approve feishu <CODE>

Allowlist mode：許可する Open ID を channels.feishu.allowFrom に設定します。

Group chats

1. Group policy（channels.feishu.groupPolicy）：

• "open" = グループ内の全員を許可（デフォルト）
• "allowlist" = groupAllowFrom のみ許可
• "disabled" = グループメッセージを無効化

2. メンション必須（channels.feishu.groups.<chat_id>.requireMention）：

• true = @メンションが必要（デフォルト）
• false = メンションなしで応答

Group configuration examples

Allow all groups, require @mention（デフォルト）

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

Allow all groups, no @mention required

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

Allow specific groups only

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

Restrict which senders can message in a group（送信者 allowlist）

グループ自体を許可することに加えて、そのグループ内の全メッセージを送信者 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"],
        },
      },
    },
  },
}

Get group/user IDs

Group IDs（chat_id）

Group ID は oc_xxx のような形です。

Method 1（推奨）

1. Gateway を起動して、グループで bot を @メンションする
2. openclaw logs --follow を実行し、chat_id を探す

Method 2

Feishu API デバッガーでグループチャット一覧を取得します。

User IDs（open_id）

User ID は ou_xxx のような形です。

Method 1（推奨）

1. Gateway を起動して bot にDMを送る
2. openclaw logs --follow を実行し、open_id を探す

Method 2

ペアリング要求から、ユーザーの Open ID を確認します。

openclaw pairing list feishu

Common commands

• /status：ボット状態を表示
• /reset：セッションをリセット
• /model：モデルの表示/切り替え

注：Feishu はネイティブのコマンドメニューに未対応のため、コマンドはテキストとして送信する必要があります。

Gateway management commands

• openclaw gateway status：Gateway の状態表示
• openclaw gateway install：Gateway サービスのインストール/起動
• openclaw gateway stop：Gateway サービス停止
• openclaw gateway restart：Gateway サービス再起動
• openclaw logs --follow：Gateway ログを追跡

Troubleshooting

Bot does not respond in group chats

1. Bot がグループに追加されていることを確認
2. Bot を @メンションする（デフォルト挙動）
3. groupPolicy が "disabled" になっていないことを確認
4. ログを確認：openclaw logs --follow

Bot does not receive messages

1. アプリが公開され、承認されていることを確認
2. イベント購読に im.message.receive_v1 が含まれていることを確認
3. long connection が有効になっていることを確認
4. アプリ権限が揃っていることを確認
5. Gateway が稼働中であることを確認：openclaw gateway status
6. ログを確認：openclaw logs --follow

App Secret leak

1. Feishu Open Platform で App Secret をリセット
2. 設定の App Secret を更新
3. Gateway を再起動

Message send failures

1. アプリに im:message:send_as_bot 権限があることを確認
2. アプリが公開されていることを確認
3. 詳細なエラーはログで確認

Advanced configuration

Multiple accounts

{
  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 を指定しない場合に、どの Feishu アカウントを使うかを制御します。

Message limits

• textChunkLimit：送信テキストのチャンクサイズ（デフォルト 2000文字）
• mediaMaxMb：メディアのアップロード/ダウンロード上限（デフォルト 30MB）

Streaming

Feishu はインタラクティブカードを使ったストリーミング返信に対応しています。有効化すると、生成中のテキストに合わせてカードが更新されます。

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

streaming: false を設定すると、全文生成してから送信します。

ACP sessions

Feishu は次に対して ACP をサポートします。

• DM
• グループのトピック会話

Feishu の ACP はテキストコマンド駆動です。ネイティブのスラッシュコマンドメニューがないため、会話に /acp ... を直接送ります。

Persistent ACP bindings

トップレベルの typed ACP binding を使うと、Feishu の DM もしくはトピック会話を永続 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" },
    },
  ],
}

Thread-bound ACP spawn from chat

Feishu の DM またはトピック会話で、ACP セッションをその場で spawn して bind できます。

/acp spawn codex --thread here

補足：

• --thread here は DM と Feishu topics で動作します。
• bind された DM/topic への後続メッセージは、その ACP セッションへ直接ルーティングされます。
• v1 は、一般的な（topic ではない）グループチャットを対象にしません。

Multi-agent routing

bindings を使って、Feishu の 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" },
      },
    },
  ],
}

Routing fields：

• match.channel："feishu"
• match.peer.kind："direct" または "group"
• match.peer.id：ユーザー Open ID（ou_xxx）またはグループ ID（oc_xxx）

取得のヒントは Get group/user IDs を参照してください。

Configuration reference

すべての設定：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 mode に必須
• channels.feishu.encryptKey：webhook mode に必須
• channels.feishu.webhookPath：Webhook のパス（デフォルト /feishu/events）
• channels.feishu.webhookHost：Webhook の bind host（デフォルト 127.0.0.1）
• channels.feishu.webhookPort：Webhook の bind port（デフォルト 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：DM ポリシー（デフォルト pairing）
• channels.feishu.allowFrom：DM allowlist（open_id のリスト）
• channels.feishu.groupPolicy：グループポリシー（デフォルト open）
• channels.feishu.groupAllowFrom：グループ allowlist
• channels.feishu.groups.<chat_id>.requireMention：@メンション必須（デフォルト true）
• channels.feishu.groups.<chat_id>.enabled：グループの有効化（デフォルト true）
• channels.feishu.textChunkLimit：メッセージ分割サイズ（デフォルト 2000文字）
• channels.feishu.mediaMaxMb：メディアサイズ上限（デフォルト 30MB）
• channels.feishu.streaming：ストリーミングカード出力を有効化（デフォルト true）
• channels.feishu.blockStreaming：ブロック単位ストリーミングを有効化（デフォルト true）

dmPolicy reference

• "pairing"：デフォルト。不明なユーザーにペアリングコードを返し、承認が必要
• "allowlist"：allowFrom のユーザーのみチャット可能
• "open"：全ユーザーを許可（allowFrom に "*" が必要）
• "disabled"：DM を無効化

Supported message types

Receive

• ✅ Text
• ✅ Rich text（post）
• ✅ Images
• ✅ Files
• ✅ Audio
• ✅ Video/media
• ✅ Stickers

Send

• ✅ Text
• ✅ Images
• ✅ Files
• ✅ Audio
• ✅ Video/media
• ✅ Interactive cards
• ⚠️ Rich text（post-style formatting and cards。Feishu の任意のオーサリング機能すべてに対応するわけではありません）

Threads and replies

• ✅ Inline replies
• ✅ Feishu が reply_in_thread を公開する topic-thread replies
• ✅ thread/topic メッセージへの返信時、メディア返信も thread-aware を維持

Runtime action surface

Feishu は現在、次の runtime action を公開しています。

• send
• read
• edit
• thread-reply
• pin
• list-pins
• unpin
• member-info
• channel-info
• channel-list
• リアクションが config で有効な場合：react と reactions

参考

• https://docs.openclaw.ai/channels/feishu.md