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

適切な 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 経由で公開します。

クライアントモードを選択する

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

ブリッジツール

イベントモデル

ブリッジは接続中、メモリ内にイベントキューを保持します。

現在のイベントタイプ:

• 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 <id> または no <id>（<id> は l を除く 5 文字のリクエスト ID）を送信すると、ブリッジはそれを 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 を stdio 子プロセスとして生成し、MCP クライアントとして操作します。実際の stdio MCP ブリッジを介して、会話の検出、トランスクリプトの読み取り、添付ファイルメタデータの読み取り、ライブイベントキューの動作、Claude 形式のチャネル通知および権限通知を検証します。送信ルーティング（保存済みの会話ルートを再利用する messages_send）は、src/mcp/channel-server.test.ts のユニットテストで個別に検証されます。

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

より広範なテストの背景については、テストを参照してください。

トラブルシューティング

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

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

これらのコマンドは、OpenClaw を MCP 経由で公開するものではありません。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 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、並列ツール呼び出しのヒントを更新します。保存前に更新後のサーバーを検証するには、--probe を追加します。
• tools はサーバーごとのツールフィルターを更新します。include/exclude の各エントリには、MCP ツール名および単純な * グロブを指定します。
• login は、auth: "oauth" で設定された HTTP サーバーの OAuth フローを実行します。初回実行時に認可 URL が出力されます。承認後に --code を指定して再実行してください。
• logout は、保存済みのサーバー定義を削除せずに、指定したサーバーの保存済み OAuth 認証情報を消去します。
• reload は、現在の CLI プロセスにおけるキャッシュ済みのインプロセス 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": true,  "path": "/home/user/.openclaw/openclaw.json",  "servers": [    {      "name": "docs",      "ok": true,      "issues": [        {          "level": "warning",          "message": "OAuth 認証情報が承認されていません。openclaw mcp login docs を実行してください"        }      ]    }  ]}

{  "generatedAt": "2026-05-31T09:00:00.000Z",  "servers": {    "docs": {      "launch": "streamable-http https://mcp.example.com/mcp",      "tools": 2,      "resources": true,      "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 内の機密値（ユーザー情報）と headers は、ログおよびステータス出力で秘匿化されます。機密情報と思われる headers または env の項目にリテラル値が含まれている場合、openclaw mcp doctor は警告を表示し、運用者がそれらの値をコミット済みの設定から移動できるようにします。

OAuth ワークフロー

OAuth は、MCP OAuth フローを公開する HTTP MCP サーバー向けです。auth: "oauth" が有効な間、そのサーバーでは静的な Authorization ヘッダーは無視されます。openclaw mcp login で保存した認証情報は、組み込み MCP、CLI ランナー、ローカルの Codex app-server で使用できます。

認証情報が利用可能になるまで、OpenClaw はエージェントのターンを失敗させるのではなく、その MCP サーバーのみをエージェントランタイムから除外します。その後、運用者またはシェルアクセス権を持つエージェントが openclaw mcp login <name> を実行し、後続のターンでサーバーを使用できます。

リモート MCP サービスが、更新可能な別の OpenClaw 認証プロファイルによってすでに支えられている場合は、必要に応じて oauth.authProfileId を設定できます。OpenClaw はランタイムへの投影前にいずれかの認証情報ソースを更新し、現在のアクセストークンのみを下流の MCP クライアントに渡します。

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

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

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 を繰り返してください。サーバー名と URL で認証情報ストアのエントリを引き続き識別できる限り、設定から auth: "oauth" を削除した後でも、logout は保存済み HTTP サーバーの認証情報を削除できます。

Streamable HTTP トランスポート

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

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 には、/settings/mcp に専用の MCP 設定ページがあります。以前の /mcp パスもエイリアスとして引き続き使用できます。このページには、設定済みサーバー数、有効化/OAuth/フィルターの概要、サーバーごとのトランスポート行、有効化/無効化コントロール、一般的な CLI コマンド、および mcp 設定セクション専用のエディターが表示されます。

運用者による編集や簡易的な一覧確認には、このページを使用します。稼働中のサーバーによる検証が必要な場合は、openclaw mcp doctor --probe または openclaw mcp probe を使用します。

運用者のワークフロー:

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

注:

• コマンドスニペットではサーバー名を引用符で囲むため、特殊な名前でもシェルにコピーできます
• 表示される URL 形式の値に認証情報が埋め込まれている場合、レンダリング前に秘匿化されます
• このページ自体は MCP トランスポートを起動しません
• MCP クライアントを所有するプロセスに応じて、稼働中のランタイムでは openclaw mcp reload、Gateway 設定の公開、またはプロセスの再起動が必要になる場合があります

MCP Apps

OpenClaw は、安定版の MCP Apps 拡張機能を実装するツールをレンダリングできます。Apps の HTML は設定済みの MCP サーバーから提供され、同じサーバーに対してアプリから参照可能なツールやリソースを要求できるため、Apps はオプトインです。

ホストブリッジを有効にします:

openclaw config set mcp.apps.enabled true --strict-json

この設定を変更した後は、Gateway を再起動します。有効にすると、OpenClaw は Gateway ポートに 1 を加えたポート（デフォルトの Gateway では 18790）で、サンドボックス専用の HTTP(S) リスナーを起動します。Control UI はその別オリジンから Apps を読み込みます。このリスナーが Control UI、認証済みの Gateway ルート、またはユーザーデータを提供することはありません。

Gateway へ直接接続する場合は、両方のポートへのアクセスが必要です。リバースプロキシまたは TLS ターミネーターで Control UI を公開する場合は、Apps に専用のパブリックオリジンを割り当て、そのオリジンだけをサンドボックスリスナーへプロキシします:

{  mcp: {    apps: {      enabled: true,      sandboxOrigin: "https://mcp-apps.example.com",      sandboxPort: 18790,    },  },}

サンドボックスのオリジンは Control UI のオリジンと異なる必要があります。そのオリジンで、認証済みのコンテンツや機密コンテンツをほかにホストしないでください。

たとえば、公式の基本 React デモは次のように設定できます:

{  mcp: {    apps: { enabled: true },    servers: {      "basic-react": {        command: "npx",        args: ["-y", "@modelcontextprotocol/server-basic-react", "--stdio"],      },    },  },}

動作とセキュリティ境界:

• OpenClaw は、Apps が有効な場合にのみ io.modelcontextprotocol/ui 拡張機能を通知します。
• 正確に text/html;profile=mcp-app という MIME タイプを持つ ui:// リソースのみがレンダリングされます。
• UI リソースは 2 MiB に制限され、専用の外側オリジンにある二重 iframe プロキシの背後に配置され、不透明な内側の App オリジンへ読み込まれ、リソースメタデータから生成された CSP によって制約されます。
• App 専用ツール（_meta.ui.visibility: ["app"]）はモデルのツール一覧に含まれません。Apps は、所有元サーバーにあるアプリから参照可能なツールのみを呼び出せます。
• App 間を分離するために内側の App ドキュメントが不透明オリジンを使用している間は、カメラ、マイク、位置情報など、オリジンに紐づく App 権限は付与されません。
• App HTML、完全なツール引数、生の結果は、上限が 10 分のメモリ内ビューリースに保持されます。これらがディスクに書き込まれたり、トランスクリプトのプレビューメタデータにコピーされたりすることはなく、ビューの有効期限が切れても MCP ランタイムは再起動されません。
• ブリッジが有効な間、openclaw security audit は警告を表示します。不要な場合は、openclaw config set mcp.apps.enabled false --strict-json で無効にします。

現在の制限

このページでは、現時点でリリースされているブリッジについて説明します。

現在の制限:

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

関連項目

• CLI リファレンス
• Plugin