OpenClaw MCPサーバー構築ガイド：外部クライアントと連携

OpenClaw を MCP サーバーとして使用する

これは openclaw mcp serve を実行する際のパスです。

`serve` を使用するタイミング

以下のようなケースでは openclaw mcp serve を使用してください。

Codex や Claude Code などの MCP クライアントを OpenClaw のチャネルと直接連携させたい場合や、すでにローカルまたはリモートでセッションがルーティングされた OpenClaw Gateway を運用している場合
チャネルごとに個別のブリッジを起動するのではなく、一つの MCP サーバーで OpenClaw の全チャネルバックエンドをまとめて扱いたい場合

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

仕組み

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

ライフサイクルは以下の通りです。

MCP クライアントが openclaw mcp serve を起動します。
ブリッジが Gateway に接続します。
ルーティングされたセッションが MCP の会話および transcript/history ツールになります。
ブリッジの接続中、ライブイベントがメモリ内にキューイングされます。
Claude チャネルモードが有効な場合、同じセッションで Claude 固有のプッシュ通知を受け取ることも可能です。

重要な動作仕様：

ライブキューの状態保持は、ブリッジが接続した時点から開始されます。
過去の transcript 履歴は messages_read で読み取ります。
Claude のプッシュ通知は、MCP セッションが有効な間のみ存在します。
クライアントが切断されるとブリッジは終了し、ライブキューは消失します。

クライアントモードの選択

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

一般的な MCP クライアント：標準的な MCP ツールのみを使用します。conversations_list、messages_read、events_poll、events_wait、messages_send、および承認ツールが利用可能です。
Claude Code：標準的な MCP ツールに加えて、Claude 固有のチャネルアダプターを使用します。--claude-channel-mode on を有効にするか、デフォルトの auto のままにしてください。

現時点では、auto は on と同じ動作をします。クライアントの機能を自動検知する機能はまだ実装されていません。

`serve`コマンドが提供するもの

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

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

これにより、MCP クライアントは以下の操作を一つの場所で行えるようになります。

最近のルートされた会話のリスト表示
最近のトランスクリプト履歴の読み取り
新しいインバウンドイベントの待機
同じルートを通じた返信の送信
ブリッジ接続中に届いた承認リクエストの確認

使い方

# Local Gateway
openclaw mcp serve

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

# Remote Gateway with password auth
openclaw mcp serve --url wss://gateway-host:18789 --password-file ~/.openclaw/gateway.password

# Enable verbose bridge logs
openclaw mcp serve --verbose

# Disable Claude-specific push notifications
openclaw mcp serve --claude-channel-mode off

ブリッジツール

現在のブリッジは、以下の MCP ツールを公開しています。

conversations_list
conversation_get
messages_read
attachments_fetch
events_poll
events_wait
messages_send
permissions_list_open
permissions_respond

`conversations_list`

Gateway のセッション状態にルートメタデータが既に存在する、最近のセッションベースの会話をリスト表示します。

便利なフィルター：

limit
search
channel
includeDerivedTitles
includeLastMessage

`conversation_get`

session_key を指定して、一つの会話を返します。

`messages_read`

セッションベースの一つの会話について、最近のトランスクリプトメッセージを読み取ります。

`attachments_fetch`

一つのトランスクリプトメッセージから、テキスト以外のメッセージコンテンツブロックを抽出します。これはトランスクリプトの内容に対するメタデータビューであり、独立した永続的なアタッチメント用のストレージではありません。

`events_poll`

数値カーソル以降のキューに入ったライブイベントを読み取ります。

`events_wait`

次の一致するイベントが到着するか、タイムアウトになるまでロングポーリングを行います。

Claude 固有のプッシュプロトコルを使用せずに、一般的な MCP クライアントでリアルタイムに近い配信が必要な場合に使用してください。

`messages_send`

セッションに記録されているのと同じルートを通じてテキストを返信します。

現在の動作：

既存の会話ルートが必要
セッションのチャネル、受信者、アカウント ID、スレッド ID を使用
テキストのみを送信

`permissions_list_open`

ブリッジが Gateway に接続してから確認した、保留中の exec/plugin 承認リクエストをリスト表示します。

`permissions_respond`

保留中の exec/plugin 承認リクエストを以下のいずれかで解決します。

allow-once
allow-always
deny

イベントモデル

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

現在のイベントタイプ：

message
exec_approval_requested
exec_approval_resolved
plugin_approval_requested
plugin_approval_resolved
claude_permission_request

重要な制限事項：

キューはライブのみです。MCP ブリッジが開始された時から開始されます。
events_poll と events_wait は、それ自体で Gateway の過去の履歴を再生することはありません。
永続的なバックログは messages_read で読み取る必要があります。

Claude チャンネル通知

このブリッジでは、Claude 特有のチャンネル通知を利用することもできます。これは OpenClaw における Claude Code チャンネルアダプターのような機能です。標準的な MCP ツールはそのまま利用可能ですが、リアルタイムの受信メッセージも Claude 特有の MCP 通知として届くようになります。

使用できるフラグは以下の通りです：

--claude-channel-mode off: 標準的な MCP ツールのみを使用します
--claude-channel-mode on: Claude チャンネル通知を有効にします
--claude-channel-mode auto: 現在のデフォルト設定です。on と同じ動作をします

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 では、以下のオプションをサポートしています。

--url <url>: Gateway WebSocket URL
--token <token>: Gateway トークン
--token-file <path>: ファイルからトークンを読み込む
--password <password>: Gateway パスワード
--password-file <path>: ファイルからパスワードを読み込む
--claude-channel-mode <auto|on|off>: Claude 通知モード
-v, --verbose: 標準エラー出力（stderr）に詳細ログを出力

セキュリティの観点から、シークレットを直接コマンドラインに記述するのではなく、可能な限り --token-file または --password-file を使用することをおすすめします。

セキュリティと信頼の境界線

このブリッジが独自のルーティングを生成することはありません。Gateway がすでにルーティング方法を認識している会話のみを公開します。

これは以下のことを意味します：

送信者の許可リスト（allowlists）、ペアリング、およびチャンネルレベルの信頼設定は、引き続き基盤となる 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アカウントをテストに接続することなく、ブリッジが動作することを証明する最短の方法です。

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

トラブルシューティング

会話が返されない

通常、Gatewayセッションがまだルーティング可能になっていないことを意味します。基盤となるセッションに、チャネル/プロバイダー、受信者、およびオプションのアカウント/スレッドルートのメタデータが保存されていることを確認してください。

`events_poll` または `events_wait` で古いメッセージが表示されない

これは期待通りの動作です。ライブキューはブリッジが接続されたときに開始されます。古いトランスクリプトの履歴を確認するには、messages_readを使用してください。

Claudeの通知が表示されない

以下の項目をすべて確認してください：

クライアントがstdio MCPセッションを開いたままにしている
--claude-channel-modeがonまたはautoに設定されている
クライアントがClaude固有の通知メソッドを正しく理解している
ブリッジが接続された後にインバウンドメッセージが発生した

承認リクエストが見当たらない

permissions_list_openは、ブリッジの接続中に観察された承認リクエストのみを表示します。これは永続的な承認履歴APIではありません。

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

ここでは、openclaw mcp list、show、set、unset コマンドについて説明します。

これらのコマンドは、OpenClaw 自体を MCP 経由で公開するものではありません。OpenClaw の設定ファイル内にある mcp.servers セクションで、OpenClaw が管理する MCP サーバー定義を操作するためのものです。

保存された定義は、埋め込みの Pi やその他のランタイムアダプターなど、OpenClaw が後で起動または設定するランタイムで使用されます。OpenClaw が定義を一括管理することで、それぞれのランタイムで MCP サーバーリストを重複して持つ必要がなくなります。

重要な動作仕様：

これらのコマンドは OpenClaw の設定の読み書きのみを行います
ターゲットとなる MCP サーバーへの接続は行いません
コマンド、URL、またはリモートトランスポートが現在利用可能かどうかは検証しません
実行時にどのトランスポート形式を実際にサポートするかは、各ランタイムアダプターが判断します

保存された MCP サーバー定義

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

使用するコマンド：

openclaw mcp list
openclaw mcp show [name]
openclaw mcp set <name> <json>
openclaw mcp unset <name>

実行例：

openclaw mcp list
openclaw mcp show context7 --json
openclaw mcp set context7 '{"command":"uvx","args":["context7-mcp"]}'
openclaw mcp set docs '{"url":"https://mcp.example.com"}'
openclaw mcp unset context7

設定ファイルの構造例：

{
  "mcp": {
    "servers": {
      "context7": {
        "command": "uvx",
        "args": ["context7-mcp"]
      },
      "docs": {
        "url": "https://mcp.example.com"
      }
    }
  }
}

Stdio トランスポート

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

フィールド	説明
`command`	起動する実行ファイル (必須)
`args`	コマンドライン引数の配列
`env`	追加の環境変数
`cwd` / `workingDirectory`	プロセスの作業ディレクトリ

SSE / HTTP トランスポート

HTTP Server-Sent Events を使用して、リモートの MCP サーバーに接続します。

フィールド	説明
`url`	リモートサーバーの HTTP または HTTPS URL (必須)
`headers`	HTTP ヘッダーのオプションのキーバリューマップ (認証トークンなど)
`connectionTimeout`	サーバーごとの接続タイムアウト（ミリ秒、任意）

例：

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

url 内の機密情報（ユーザー情報）や headers の値は、ログやステータス出力では伏せ字（redacted）になります。

Streamable HTTP トランスポート

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

フィールド	説明
`url`	リモートサーバーの HTTP または HTTPS URL (必須)
`transport`	このトランスポートを選択するには `"streamable-http"` を指定
`headers`	HTTP ヘッダーのオプションのキーバリューマップ (認証トークンなど)
`connectionTimeout`	サーバーごとの接続タイムアウト（ミリ秒、任意）

例：

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

これらのコマンドは保存された設定を管理するだけです。チャネルブリッジを開始したり、ライブの MCP クライアントセッションを開いたり、ターゲットサーバーへの到達性を確認したりすることはありません。

現在の制限事項

このページでは、現在提供されているブリッジの仕様について記載しています。

現在の制限事項：

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

AI Setup Assistant

OpenClaw Expert

まだ解決しませんか？

このページで解決しない場合は、OpenClaw Expertに直接質問してください。