OpenClawをFeishu (Lark) ボットと連携させる方法

Feishu（Lark）は、メッセージングやコラボレーションに使用されるチームチャットプラットフォームです。このプラグインは、プラットフォームの WebSocket イベント購読を使用して OpenClaw を Feishu/Lark bot に接続します。これにより、パブリックな Webhook URL を公開することなくメッセージを受信できます。

同梱プラグイン

Feishu は現在の OpenClaw リリースに同梱されているため、個別のプラグインインストールは不要です。

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

openclaw plugins install @openclaw/feishu

クイックスタート

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

方法 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

ステップ 1：Feishu アプリの作成

1. Feishu Open Platform を開く

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

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

2. アプリを作成する

Create enterprise app をクリックします
アプリ名と説明を入力します
アプリのアイコンを選択します

Create enterprise app

3. 認証情報をコピーする

Credentials & Basic Info から、以下をコピーしてください：

App ID（形式：cli_xxx）
App Secret

❗ 重要： App Secret は厳重に管理し、公開しないでください。

Get credentials

4. 権限（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. bot 機能を有効にする

App Capability > Bot にて：

bot 機能を有効（Enable）にします
bot 名を設定します

Enable bot capability

6. イベント購読（Event Subscription）を設定する

⚠️ 重要： イベント購読を設定する前に、以下を確認してください：

すでに Feishu に対して openclaw channels add を実行済みであること
Gateway が実行中であること（openclaw gateway status）

Event Subscription にて：

Use long connection to receive events（WebSocket）を選択します
イベントを追加します：im.message.receive_v1
（任意）Drive のコメントワークフローを使用する場合は、drive.notice.comment_add_v1 も追加します

⚠️ Gateway が実行されていないと、長期間接続（long-connection）の設定保存に失敗することがあります。

Configure event subscription

7. アプリを公開する

Version Management & Release でバージョンを作成します
レビューを申請して公開します
管理者の承認を待ちます（企業アプリの場合は通常、自動承認されます）

ステップ 2：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 Open Platform でアプリを開きます
Development → Events & Callbacks（开发配置 → 事件与回调）に移動します
Encryption タブ（加密策略）を開きます
Verification Token と Encrypt Key をコピーします

下のスクリーンショットは Verification Token の場所を示しています。Encrypt Key も同じ Encryption セクションに記載されています。

Verification Token location

環境変数で設定する

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

クォータ最適化フラグ

2つのオプションフラグを使用して、Feishu API の使用量を削減できます：

typingIndicator（デフォルト true）：false にすると、入力中（typing）のリアクション呼び出しをスキップします。
resolveSenderNames（デフォルト true）：false にすると、送信者のプロフィール取得呼び出しをスキップします。

これらはトップレベル、またはアカウントごとに設定可能です：

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

ステップ 3：起動とテスト

1. Gateway を起動する

まずは Gateway を起動しましょう。

openclaw gateway

2. テストメッセージを送信する

Feishu を開き、作成したボットを見つけてメッセージを送信してください。

3. ペアリングを承認する

デフォルト設定では、ボットからペアリングコードが返信されます。以下のコマンドで承認を行ってください。

openclaw pairing approve feishu <CODE>

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

概要

Feishu ボットの動作仕様についてまとめました。

Feishu bot channel: Gateway によって管理される Feishu ボットです。
Deterministic routing: 返信は常に送信元の Feishu チャットへ正確に戻ります。
Session isolation: ダイレクトメッセージ（DM）はメインセッションを共有しますが、グループチャットはそれぞれ独立したセッションとして扱われます。
WebSocket connection: Feishu SDK を利用した常時接続（Long Connection）を使用するため、パブリック URL を用意する必要はありません。

アクセス制御

ダイレクトメッセージ

デフォルト設定: dmPolicy: "pairing"（未登録のユーザーにはペアリングコードが送信されます）

ペアリングの承認方法:

openclaw pairing list feishu
openclaw pairing approve feishu <CODE>

Allowlist モード: 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"],
    },
  },
}

グループ内での送信者を制限する（送信者 Allowlist）

特定のグループ自体を許可するだけでなく、そのグループ内ですべてのメッセージを送信者単位で制限できます。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"],
        },
      },
    },
  },
}

AI Setup Assistant

次のステップ

グループ/ユーザーIDの取得

グループID (chat_id)

グループIDは oc_xxx のような形式をしています。

方法 1 (おすすめ)

Gateway を起動し、グループ内で bot を @メンションします。
openclaw logs --follow を実行して、ログの中から chat_id を探します。

方法 2

Feishu API デバッガーを使用して、グループチャットの一覧を取得します。

ユーザーID (open_id)

ユーザーIDは ou_xxx のような形式をしています。

方法 1 (おすすめ)

Gateway を起動し、bot にダイレクトメッセージ（DM）を送ります。
openclaw logs --follow を実行して、ログの中から open_id を探します。

方法 2

ユーザーの Open ID を確認するために、ペアリングリクエストをチェックします。

openclaw pairing list feishu

よく使うコマンド

コマンド	説明
`/status`	bot のステータスを表示します
`/reset`	セッションをリセットします
`/model`	モデルの表示・切り替えを行います

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

Gatewayの管理コマンド

Gatewayの状態確認や操作を行うための主要なコマンドは以下の通りです。

コマンド	説明
`openclaw gateway status`	Gatewayの状態を表示します
`openclaw gateway install`	Gatewayサービスのインストールと起動を行います
`openclaw gateway stop`	Gatewayサービスを停止します
`openclaw gateway restart`	Gatewayサービスを再起動します
`openclaw logs --follow`	Gatewayのログをリアルタイムで確認します

トラブルシューティング

設定がうまくいかない場合は、以下のチェックリストを確認してみてください。

グループチャットでBotが反応しない

Botが対象のグループに追加されているか確認してください。
Botを @メンションしているか確認してください（これがデフォルトの動作です）。
groupPolicy が "disabled" に設定されていないか確認してください。
ログを確認しましょう： openclaw logs --follow

Botがメッセージを受信できない

アプリが公開され、承認済みであることを確認してください。
イベント購読の設定に im.message.receive_v1 が含まれているか確認してください。
long connection（長接続）が有効になっているか確認してください。
アプリの権限設定がすべて完了しているか確認してください。
Gatewayが正常に動作しているか確認します： openclaw gateway status
ログで詳細を確認しましょう： openclaw logs --follow

App Secretが漏洩した場合

Feishu Open Platformで App Secret をリセットしてください。
設定ファイル内の App Secret を新しい値に更新します。
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 に設定してください。

ACP セッション

Feishu は以下の ACP をサポートしています：

DM（ダイレクトメッセージ）
グループトピックの会話

Feishu の ACP はテキストコマンド駆動です。ネイティブのスラッシュコマンドメニューは用意されていないため、会話の中で直接 /acp ... メッセージを入力して使用してください。

永続的な ACP バインディング

トップレベルで型指定された ACP バインディングを使用すると、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" },
    },
  ],
}

チャットからのスレッド固定 ACP 起動

Feishu の DM またはトピックの会話の中で、その場で ACP セッションを起動してバインドすることができます。

/acp spawn codex --thread here

注意点：

--thread here は DM および Feishu トピックで動作します。
バインドされた DM やトピックでのその後のメッセージは、その ACP セッションに直接ルーティングされます。
v1 では、トピック形式ではない一般的なグループチャットはサポートしていません。

マルチエージェントルーティング

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

ルーティングフィールド：

match.channel: "feishu"
match.peer.kind: "direct" または "group"
match.peer.id: ユーザーの Open ID (ou_xxx) またはグループ ID (oc_xxx)

ID の調べ方については、グループ/ユーザー 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`	DM ポリシー	`pairing`
`channels.feishu.allowFrom`	DM 許可リスト (open_id のリスト)	-
`channels.feishu.groupPolicy`	グループポリシー	`allowlist`
`channels.feishu.groupAllowFrom`	グループ許可リスト	-
`channels.feishu.requireMention`	デフォルトで @メンションを必須にするか	条件による
`channels.feishu.groups.<chat_id>.requireMention`	グループごとの @メンション必須設定のオーバーライド	継承
`channels.feishu.groups.<chat_id>.enabled`	グループの有効化	`true`
`channels.feishu.textChunkLimit`	メッセージのチャンクサイズ	`2000`
`channels.feishu.mediaMaxMb`	メディアのサイズ制限	`30`
`channels.feishu.streaming`	ストリーミングカード出力を有効化	`true`
`channels.feishu.blockStreaming`	ブロックストリーミングを有効化	`true`

dmPolicy リファレンス

DM（ダイレクトメッセージ）の動作を制御するための設定項目です。用途に合わせて以下の 4 つのオプションから選択できます。

値	動作
`"pairing"`	デフォルト設定。未登録のユーザーにはペアリングコードが表示され、管理者の承認が必要になります。
`"allowlist"`	`allowFrom` に指定されたユーザーのみがチャットを利用できます。
`"open"`	すべてのユーザーを許可します（`allowFrom` に `"*"` を設定する必要があります）。
`"disabled"`	DM 機能を無効にします。

サポートされているメッセージタイプ

やり取りできるメッセージの種類についてまとめました。受信と送信で対応状況が異なります。

受信

✅ テキスト
✅ リッチテキスト (post)
✅ 画像
✅ ファイル
✅ 音声
✅ ビデオ/メディア
✅ ステッカー

送信

✅ テキスト
✅ 画像
✅ ファイル
✅ 音声
✅ ビデオ/メディア
✅ インタラクティブカード
⚠️ リッチテキスト (post 形式のフォーマットとカードに対応しています。Feishu 独自の高度な編集機能すべてには対応していません)

スレッドと返信

✅ インライン返信
✅ Feishu が reply_in_thread を公開しているトピック型スレッドへの返信
✅ スレッドやトピックメッセージへの返信時、メディア返信もスレッドのコンテキストを維持します
✅ 既存の会話の流れを壊さずにメッセージを継続できます

Drive コメント

Feishu Drive のドキュメント（Docs や Sheets など）に誰かがコメントを追加したとき、エージェントを起動できます。エージェントはコメントのテキスト、ドキュメントのコンテキスト、およびコメントスレッドを受け取るため、スレッド内で返信したり、ドキュメントを編集したりできます。

必要な設定：

Feishu アプリのイベント購読設定で、既存の im.message.receive_v1 に加えて drive.notice.comment_add_v1 を購読してください。
Drive ツールはデフォルトで有効になっています。無効にする場合は channels.feishu.tools.drive: false を設定してください。

feishu_drive ツールでは、以下のコメントアクションが利用可能です。

Action	Description
`list_comments`	ドキュメント上のコメントを一覧表示します
`list_comment_replies`	コメントスレッド内の返信を一覧表示します
`add_comment`	新しいトップレベルのコメントを追加します
`reply_comment`	既存のコメントスレッドに返信します

エージェントが Drive のコメントイベントを処理する際、以下の情報を受け取ります。

コメントのテキスト、送信者、およびスレッド内返信用のコンテキスト
ドキュメントのメタデータ（タイトル、タイプ、URL）

ドキュメントを編集した後、エージェントは 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に直接質問してください。