MCP

openclaw mcp には 2 つの役割があります。

• openclaw mcp serve で OpenClaw を MCP サーバーとして実行する
• list、show、status、doctor、probe、add、set、configure、tools、login、logout、reload、unset で、OpenClaw 管理のアウトバウンド MCP サーバー定義を管理する

言い換えると:

• serve は OpenClaw が MCP サーバーとして動作するものです
• その他のサブコマンドは、OpenClaw のランタイムが後で利用する可能性のある MCP サーバーについて、OpenClaw が MCP クライアント側レジストリとして動作するものです

OpenClaw 自身がコーディングハーネスセッションをホストし、そのランタイムを ACP 経由でルーティングする必要がある場合は openclaw acp を使用してください。

適切な MCP パスを選ぶ

OpenClaw には複数の MCP サーフェスがあります。エージェントランタイムの所有者とツールの所有者に一致するものを選んでください。

MCP サーバーとしての OpenClaw

これは openclaw mcp serve パスです。

serve を使う場合

次の場合は openclaw mcp serve を使用してください。

• Codex、Claude Code、または別の MCP クライアントが OpenClaw バックのチャンネル会話と直接通信する必要がある
• ルーティング済みセッションを持つローカルまたはリモートの OpenClaw Gateway がすでにある
• チャンネルごとに別々のブリッジを実行する代わりに、OpenClaw のチャンネルバックエンド全体で動作する 1 つの MCP サーバーが必要である

OpenClaw がコーディングランタイム自体をホストし、エージェントセッションを OpenClaw 内に保持する必要がある場合は、代わりに openclaw acp を使用してください。

仕組み

openclaw mcp serve は stdio MCP サーバーを起動します。そのプロセスは MCP クライアントが所有します。クライアントが stdio セッションを開いたままにしている間、ブリッジは WebSocket 経由でローカルまたはリモートの OpenClaw Gateway に接続し、ルーティング済みチャンネル会話を MCP 経由で公開します。

クライアントモードを選ぶ

同じブリッジを 2 つの異なる方法で使用できます。

serve が公開するもの

ブリッジは既存の Gateway セッションルートメタデータを使用して、チャンネルバックの会話を公開します。OpenClaw に、次のような既知のルートを持つセッション状態がすでにある場合、会話が表示されます。

• channel
• 受信者または宛先メタデータ
• 任意の accountId
• 任意の threadId

これにより、MCP クライアントは 1 か所で次のことができます。

• 最近のルーティング済み会話を一覧表示する
• 最近のトランスクリプト履歴を読む
• 新しい受信イベントを待つ
• 同じルートを通じて返信を送信する
• ブリッジ接続中に到着した承認リクエストを確認する

使用方法

openclaw mcp serve

openclaw mcp serve --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

openclaw mcp serve --url wss://gateway-host:18789 --password-file ~/.openclaw/gateway.password

openclaw mcp serve --verboseopenclaw mcp serve --claude-channel-mode off

ブリッジツール

現在のブリッジは次の MCP ツールを公開します。

イベントモデル

ブリッジは接続されている間、メモリ内イベントキューを保持します。

現在のイベントタイプ:

• message
• exec_approval_requested
• exec_approval_resolved
• plugin_approval_requested
• plugin_approval_resolved
• claude_permission_request

Claude チャンネル通知

ブリッジは Claude 固有のチャンネル通知も公開できます。これは Claude Code チャンネルアダプターに相当する OpenClaw の機能です。標準 MCP ツールは引き続き使用できますが、ライブ受信メッセージを Claude 固有の MCP 通知として受け取ることもできます。

Claude チャンネルモードが有効な場合、サーバーは Claude 実験的ケイパビリティを広告し、次を送出できます。

• notifications/claude/channel
• notifications/claude/channel/permission

現在のブリッジ動作:

• 受信 user トランスクリプトメッセージは notifications/claude/channel として転送されます
• MCP 経由で受信した Claude 権限リクエストはメモリ内で追跡されます
• 紐づく会話内のコマンド所有者が後で yes abcde または no abcde を送信した場合、ブリッジはそれを notifications/claude/channel/permission に変換します
• これらの通知はライブセッション専用です。MCP クライアントが切断すると、プッシュ先はありません

これは意図的にクライアント固有です。汎用 MCP クライアントは標準のポーリングツールに依存してください。

MCP クライアント設定

stdio クライアント設定の例:

{  "mcpServers": {    "openclaw": {      "command": "openclaw",      "args": [        "mcp",        "serve",        "--url",        "wss://gateway-host:18789",        "--token-file",        "/path/to/gateway.token"      ]    }  }}

ほとんどの汎用 MCP クライアントでは、標準ツールサーフェスから始め、Claude モードは無視してください。Claude 固有の通知メソッドを実際に理解するクライアントに限り、Claude モードをオンにしてください。

オプション

openclaw mcp serve は次をサポートします。

セキュリティと信頼境界

ブリッジはルーティングを作り出しません。Gateway がすでにルーティング方法を知っている会話だけを公開します。

つまり、次のようになります。

• 送信者の許可リスト、ペアリング、チャネルレベルの信頼は、引き続き基盤となる OpenClaw チャネル設定に属します
• messages_send は、既存の保存済みルートを通じてのみ返信できます
• 承認状態は現在のブリッジセッションに対してのみライブかつインメモリです
• ブリッジ認証には、他のリモート Gateway クライアントで信頼するものと同じ Gateway トークンまたはパスワード制御を使用してください

会話が conversations_list にない場合、通常の原因は MCP 設定ではありません。基盤となる Gateway セッションのルートメタデータが欠落しているか不完全です。

テスト

OpenClaw は、このブリッジ向けに決定的な Docker スモークを同梱しています。

pnpm test:docker:mcp-channels

このスモークは次を行います。

• シード済みの Gateway コンテナを起動します
• openclaw mcp serve を生成する 2 つ目のコンテナを起動します
• 会話の検出、トランスクリプト読み取り、添付メタデータ読み取り、ライブイベントキューの挙動、送信ルーティングを検証します
• 実際の stdio MCP ブリッジ経由で、Claude 形式のチャネル通知と権限通知を検証します

これは、実際の Telegram、Discord、または iMessage アカウントをテスト実行に接続せずに、ブリッジが動作することを証明する最速の方法です。

より広いテストのコンテキストについては、テスト を参照してください。

トラブルシューティング

MCP クライアントレジストリとしての OpenClaw

これは openclaw mcp list、show、status、doctor、probe、add、set、 configure、tools、login、logout、reload、および unset のパスです。

これらのコマンドは MCP 経由で OpenClaw を公開しません。OpenClaw 設定内の mcp.servers 配下にある OpenClaw 管理の MCP サーバー定義を管理します。config/mcporter.json から mcporter サーバーを読み取りません。

保存されたこれらの定義は、組み込み OpenClaw や他のランタイムアダプターなど、OpenClaw が後で起動または設定するランタイム向けです。OpenClaw は定義を一元的に保存するため、それらのランタイムが重複した独自の MCP サーバーリストを保持する必要はありません。

ランタイムアダプターは、この共有レジストリを下流クライアントが期待する形状に正規化する場合があります。たとえば、組み込み OpenClaw は OpenClaw の transport 値を直接消費しますが、Claude Code と Gemini は http、sse、stdio などの CLI ネイティブな type 値を受け取ります。

Codex app-server は、各サーバー上の省略可能な codex ブロックも尊重します。これは Codex app-server スレッド専用の OpenClaw 投影メタデータです。ACP セッション、汎用 Codex ハーネス設定、または他のランタイムアダプターは変更しません。 空でない codex.agents を使用すると、サーバーを特定の OpenClaw エージェント ID のみに投影できます。空、空白、または無効なエージェントリストは設定 検証で拒否され、グローバルになるのではなくランタイム投影パスで省略されます。 信頼済みサーバーに対して Codex ネイティブの default_tools_approval_mode を出力するには、codex.defaultToolsApprovalMode（auto、prompt、または approve）を使用します。 OpenClaw は、ネイティブの mcp_servers 設定を Codex に渡す前に codex メタデータを取り除きます。

保存済み MCP サーバー定義

OpenClaw は、OpenClaw 管理の MCP 定義を必要とするサーフェス向けに、軽量な MCP サーバーレジストリも設定内に保存します。

コマンド:

• openclaw mcp list
• openclaw mcp show [name]
• openclaw mcp status [--verbose]
• openclaw mcp doctor [name] [--probe]
• openclaw mcp probe [name]
• openclaw mcp add <name> [flags]
• openclaw mcp set <name> <json>
• openclaw mcp configure <name> [flags]
• openclaw mcp tools <name> [--include csv] [--exclude csv] [--clear]
• openclaw mcp login <name> [--code code]
• openclaw mcp logout <name>
• openclaw mcp reload
• openclaw mcp unset <name>

注記:

• list はサーバー名をソートします。
• 名前なしの show は、設定済み MCP サーバーオブジェクト全体を出力します。
• status は接続せずに設定済みトランスポートを分類します。--verbose には、解決済みの起動、タイムアウト、OAuth、フィルター、並列呼び出しの詳細が含まれます。
• doctor は接続せずに静的チェックを実行します。有効化されたサーバーが接続できることも検証したい場合は、--probe を追加してください。
• probe は接続し、ツール数、リソース/プロンプトのサポート、リスト変更サポート、診断を報告します。
• add は、--command、--arg、--env、--cwd などの stdio フラグ、または --url、--transport、--header、--auth oauth、TLS、タイムアウト、ツール選択フラグなどの HTTP フラグを受け付けます。
• set はコマンドライン上で 1 つの JSON オブジェクト値を期待します。
• configure は、サーバー定義全体を置き換えずに、有効化、ツールフィルター、タイムアウト、OAuth、TLS、並列ツール呼び出しのヒントを更新します。
• tools はサーバーごとのツールフィルターを更新します。include/exclude エントリは MCP ツール名と単純な * glob です。
• login は、auth: "oauth" で設定された HTTP サーバーに対して OAuth フローを実行します。初回実行時には認可 URL が出力されます。承認後に --code 付きで再実行してください。
• logout は、保存済みサーバー定義を削除せずに、指定されたサーバーの保存済み OAuth 認証情報を消去します。
• reload は、キャッシュされたプロセス内 MCP ランタイムを破棄します。別プロセス内の Gateway またはエージェントプロセスには、引き続きそれぞれのリロードまたは再起動パスが必要です。
• Streamable HTTP MCP サーバーには transport: "streamable-http" を使用してください。openclaw mcp set は、互換性のために CLI ネイティブの type: "http" も同じ正規設定形状に正規化します。
• unset は、指定されたサーバーが存在しない場合に失敗します。

例:

openclaw mcp listopenclaw mcp show context7 --jsonopenclaw mcp status --verboseopenclaw mcp doctor --probeopenclaw mcp probe context7 --jsonopenclaw mcp add memory --command npx --arg -y --arg @modelcontextprotocol/server-memoryopenclaw mcp set context7 '{"command":"uvx","args":["context7-mcp"]}'openclaw mcp tools context7 --include 'resolve-library-id,get-library-docs'openclaw mcp set docs '{"url":"https://mcp.example.com","transport":"streamable-http"}'openclaw mcp configure docs --timeout 20 --connect-timeout 5 --include 'search,read_*'openclaw mcp configure docs --auth oauth --oauth-scope 'docs.read'openclaw mcp login docsopenclaw mcp logout docsopenclaw mcp unset context7

一般的なサーバーレシピ

これらの例はサーバー定義だけを保存します。その後で openclaw mcp doctor --probe を実行し、サーバーが起動してツールを公開することを証明してください。

openclaw mcp add files \  --command npx \  --arg -y \  --arg @modelcontextprotocol/server-filesystem \  --arg "$HOME/Documents" \  --include 'read_file,list_directory,search_files'openclaw mcp doctor files --probe

openclaw mcp add memory \  --command npx \  --arg -y \  --arg @modelcontextprotocol/server-memoryopenclaw mcp probe memory --json

openclaw mcp add local-tools \  --command node \  --arg ./dist/mcp-server.js \  --cwd /srv/openclaw-tools \  --env API_BASE=https://internal.exampleopenclaw mcp status --verbose

openclaw mcp add docs \  --url https://mcp.example.com/mcp \  --transport streamable-http \  --auth oauth \  --oauth-scope docs.read \  --timeout 20 \  --connect-timeout 5 \  --include 'search,read_*'openclaw mcp doctor docs --probe

openclaw mcp set cua-driver '{"command":"cua-driver","args":["mcp"]}'openclaw mcp tools cua-driver --include 'list_apps,observe,click,type'openclaw mcp doctor cua-driver --probe

JSON 出力形状

スクリプトとダッシュボードでは --json を使用します。フィールドセットは時間とともに増える可能性があるため、コンシューマーは未知のキーを無視してください。

{  "path": "/home/user/.openclaw/openclaw.json",  "servers": [    {      "name": "docs",      "configured": true,      "enabled": true,      "ok": true,      "transport": "streamable-http",      "launch": "streamable-http https://mcp.example.com/mcp",      "auth": "oauth",      "authStatus": {        "hasTokens": true,        "hasClientInformation": true,        "hasCodeVerifier": false,        "hasDiscoveryState": true,        "hasLastAuthorizationUrl": false      },      "requestTimeoutMs": 20000,      "connectionTimeoutMs": 5000,      "toolFilter": {        "include": ["search", "read_*"],        "exclude": []      },      "supportsParallelToolCalls": true    }  ]}

{  "ok": false,  "path": "/home/user/.openclaw/openclaw.json",  "servers": [    {      "name": "docs",      "ok": false,      "issues": [        {          "level": "error",          "message": "OAuth credentials are not authorized; run openclaw mcp login docs"        }      ]    }  ]}

{  "path": "/home/user/.openclaw/openclaw.json",  "generatedAt": "2026-05-31T09:00:00.000Z",  "servers": {    "docs": {      "launch": "streamable-http https://mcp.example.com/mcp",      "tools": 2,      "resources": true,      "prompts": false,      "listChanged": {        "tools": true,        "resources": false,        "prompts": false      }    }  },  "tools": ["docs__read_page", "docs__search"],  "diagnostics": []}

設定形状の例:

{  "mcp": {    "servers": {      "context7": {        "command": "uvx",        "args": ["context7-mcp"]      },      "docs": {        "url": "https://mcp.example.com",        "transport": "streamable-http",        "timeout": 20,        "connectTimeout": 5,        "supportsParallelToolCalls": true,        "auth": "oauth",        "oauth": {          "scope": "docs.read"        },        "sslVerify": true,        "clientCert": "/path/to/client.crt",        "clientKey": "/path/to/client.key",        "toolFilter": {          "include": ["search_*"],          "exclude": ["admin_*"]        }      }    }  }}

Stdio トランスポート

ローカルの子プロセスを起動し、stdin/stdout 経由で通信します。

SSE / HTTP トランスポート

HTTP Server-Sent Events 経由でリモート MCP サーバーに接続します。

例:

{  "mcp": {    "servers": {      "remote-tools": {        "url": "https://mcp.example.com",        "auth": "oauth",        "timeout": 20,        "headers": {          "Authorization": "Bearer <token>"        }      }    }  }}

url (userinfo) と headers 内の機密値は、ログとステータス出力で秘匿されます。openclaw mcp doctor は、機密情報に見える headers または env エントリにリテラル値が含まれている場合に警告するため、運用者はそれらの値をコミット済み設定の外へ移動できます。

OAuth ワークフロー

OAuth は、MCP OAuth フローを通知する HTTP MCP サーバー向けです。auth: "oauth" が有効な間、そのサーバーの静的 Authorization ヘッダーは無視されます。

openclaw mcp set docs '{"url":"https://mcp.example.com/mcp","transport":"streamable-http","auth":"oauth","oauth":{"scope":"docs.read"}}'

openclaw mcp login docs

openclaw mcp login docs --code abc123

openclaw mcp status --verboseopenclaw mcp doctor docs --probe

openclaw mcp logout docs

プロバイダーがトークンをローテーションする場合、または認可状態が詰まった場合は、openclaw mcp logout <name> を実行してから login を繰り返してください。logout は、サーバー名と URL が認証情報ストアのエントリを引き続き識別できる限り、設定から auth: "oauth" が削除された後でも、保存済み HTTP サーバーの認証情報をクリアできます。

Streamable HTTP トランスポート

streamable-http は、sse および stdio と並ぶ追加のトランスポートオプションです。リモート MCP サーバーとの双方向通信に HTTP ストリーミングを使用します。

OpenClaw 設定では、正規の綴りとして transport: "streamable-http" を使用します。CLI ネイティブの MCP type: "http" 値は、openclaw mcp set を通じて保存される場合は受け入れられ、既存設定では openclaw doctor --fix によって修復されますが、埋め込み OpenClaw が直接消費するのは transport です。

例:

{  "mcp": {    "servers": {      "streaming-tools": {        "url": "https://mcp.example.com/stream",        "transport": "streamable-http",        "connectTimeout": 10,        "timeout": 30,        "headers": {          "Authorization": "Bearer <token>"        }      }    }  }}

Control UI

ブラウザーの Control UI には、/mcp に専用の MCP 設定ページが含まれます。設定済みサーバー数、有効化/OAuth/フィルターの概要、サーバーごとのトランスポート行、有効化/無効化コントロール、一般的な CLI コマンド、mcp 設定セクション用のスコープ付きエディターが表示されます。

運用者による編集と簡易インベントリにはこのページを使用してください。ライブサーバーの証明が必要な場合は、openclaw mcp doctor --probe または openclaw mcp probe を使用してください。

運用者ワークフロー:

1. コントロール UI を開き、MCP を選択します。
2. 合計、有効、OAuth、フィルター済みサーバーの概要カードを確認します。
3. 各サーバー行で、トランスポート、認証、フィルター、タイムアウト、コマンドのヒントを確認します。
4. 定義は保持しつつランタイム検出から除外したい場合は、有効化を切り替えます。
5. 新しいサーバー、ヘッダー、TLS、OAuth メタデータ、ツールフィルターなどの構造的な変更には、スコープ付きの mcp config セクションを編集します。
6. config のみを永続化するには 保存 を、Gateway config パス経由で適用するには 保存して公開 を選択します。
7. 編集したサーバーが起動してツールを一覧表示することのライブ証明が必要な場合は、openclaw mcp doctor --probe を実行します。

注記:

• コマンドスニペットではサーバー名を引用符で囲むため、通常と異なる名前でもシェルにコピーできます
• 表示される URL のような値は、埋め込み認証情報を含む場合、レンダリング前に墨消しされます
• このページ自体は MCP トランスポートを開始しません
• アクティブなランタイムでは、どのプロセスが MCP クライアントを所有しているかに応じて、openclaw mcp reload、Gateway config の公開、またはプロセスの再起動が必要になる場合があります

現在の制限

このページは、現在出荷されているブリッジについて説明しています。

現在の制限:

• 会話検出は既存の Gateway セッションルートメタデータに依存します
• Claude 固有のアダプター以外に汎用プッシュプロトコルはありません
• メッセージ編集ツールやリアクションツールはまだありません
• HTTP/SSE/streamable-http トランスポートは単一のリモートサーバーに接続します。多重化されたアップストリームはまだありません
• permissions_list_open には、ブリッジ接続中に観測された承認のみが含まれます

関連

• CLI リファレンス
• Plugin