OpenClaw ACPブリッジ設定ガイド：IDEとGatewayを接続

互換性マトリックス

ACP 領域	ステータス	備考
`initialize`, `newSession`, `prompt`, `cancel`	実装済み	stdio を介して Gateway の chat/send + abort につなぐコアなブリッジフローです。
`listSessions`, スラッシュコマンド	実装済み	セッションリストは Gateway のセッション状態に対して機能します。コマンドは `available_commands_update` を通じて通知されます。
`loadSession`	部分的	ACP セッションを Gateway のセッションキーに再バインドし、保存されたユーザーとアシスタントのテキスト履歴を再生します。ツールやシステムの履歴はまだ再構築されません。
プロンプトの内容（`text`, 埋め込み `resource`, 画像）	部分的	テキストやリソースはチャット入力にフラット化され、画像は Gateway の添付ファイルになります。
セッションモード	部分的	`session/set_mode` をサポートしており、ブリッジは思考レベル、ツールの冗長性、推論、使用状況の詳細、昇格されたアクションなど、Gateway ベースの初期セッションコントロールを公開します。より広範な ACP ネイティブのモードや設定はまだ対象外です。
セッション情報と使用状況の更新	部分的	ブリッジは、キャッシュされた Gateway セッションのスナップショットから `session_info_update` と、ベストエフォートでの `usage_update` 通知を発行します。使用状況は概算であり、Gateway のトークン合計が最新とマークされた場合にのみ送信されます。
ツールストリーミング	部分的	`tool_call` / `tool_call_update` イベントには、生の I/O、テキストコンテンツ、および Gateway のツールの引数や結果から判明した場合にはベストエフォートでファイルパスが含まれます。埋め込みターミナルや、よりリッチな diff ネイティブの出力はまだ公開されていません。
セッションごとの MCP サーバー（`mcpServers`）	未サポート	ブリッジモードでは、セッションごとの MCP サーバーリクエストを拒否します。MCP は OpenClaw Gateway またはエージェント側で設定してください。
クライアントファイルシステムメソッド（`fs/read_text_file`, `fs/write_text_file`）	未サポート	ブリッジは ACP クライアントのファイルシステムメソッドを呼び出しません。
クライアントターミナルメソッド（`terminal/*`）	未サポート	ブリッジは ACP クライアントのターミナルを作成したり、ツール呼び出しを通じてターミナル ID をストリーミングしたりしません。
セッションプラン / 思考ストリーミング	未サポート	ブリッジは現在、出力テキストとツールのステータスを出力しますが、ACP のプランや思考（thought）の更新は出力しません。

既知の制限事項

loadSession は保存されたユーザーとアシスタントのテキスト履歴を再生しますが、過去のツール呼び出し、システム通知、またはよりリッチな ACP ネイティブのイベントタイプは再構築しません。
複数の ACP クライアントが同じ Gateway セッションキーを共有している場合、イベントとキャンセルのルーティングは厳密にクライアントごとに分離されるのではなく、ベストエフォートで行われます。エディタごとにクリーンなターンが必要な場合は、デフォルトの分離された acp:<uuid> セッションを使用することをお勧めします。
Gateway の停止状態は ACP の停止理由に変換されますが、そのマッピングは完全に ACP ネイティブなランタイムほど表現力は高くありません。
初期セッションコントロールは現在、Gateway の設定項目のうち、思考レベル、ツールの冗長性、推論、使用状況の詳細、昇格されたアクションという特定のサブセットのみを提示します。モデルの選択や実行ホストの制御は、まだ ACP の設定オプションとして公開されていません。
session_info_update と usage_update は、ライブの ACP ネイティブなランタイムの集計ではなく、Gateway セッションのスナップショットから派生しています。使用状況は概算であり、コストデータは含まれず、Gateway がトークンデータの合計を最新とマークしたときにのみ発行されます。
ツールの追跡データはベストエフォートです。ブリッジは、既知のツールの引数や結果に現れるファイルパスを表示することはできますが、ACP ターミナルや構造化されたファイル diff はまだ出力しません。

使い方

開発を進める中で、ツールが正しく動いているか確認したい場面は多いですよね。openclaw acp コマンドを使えば、簡単にブリッジを起動できます。基本的な使い方は以下の通りです。

openclaw acp

# Remote Gateway
openclaw acp --url wss://gateway-host:18789 --token <token>

# Remote Gateway (token from file)
openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

# Attach to an existing session key
openclaw acp --session agent:main:main

# Attach by label (must already exist)
openclaw acp --session-label "support inbox"

# Reset the session key before the first prompt
openclaw acp --session agent:main:main --reset-session

リモートの Gateway に接続する場合は、URL とトークンを指定します。セキュリティを考慮して、トークンをファイルから読み込む方法がおすすめです。また、既存のセッションを再開したり、特定のラベルが付いたセッションにアタッチしたりすることも可能です。

ACP client (デバッグ)

IDE を立ち上げることなく、ブリッジの動作確認（サニティチェック）を行いたい場合は、内蔵の ACP client が便利です。これを使えば ACP ブリッジが起動し、対話形式でプロンプトを入力してテストできます。

openclaw acp client

# Point the spawned bridge at a remote Gateway
openclaw acp client --server-args --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

# Override the server command (default: openclaw)
openclaw acp client --server "node" --server-args openclaw.mjs acp --url ws://127.0.0.1:19001

デバッグモードでのパーミッションモデル（権限モデル）についても理解しておきましょう。安全に利用するための重要なルールがあります。

自動承認は許可リスト（allowlist）に基づいており、信頼されたコアツールの ID にのみ適用されます。
read の自動承認は、現在の作業ディレクトリ（--cwd で設定された範囲）に限定されます。
ACP が自動承認するのは、範囲内の read 呼び出しや、読み取り専用の検索ツール（search, web_search, memory_search）といった、影響範囲の狭い読み取り専用クラスのみです。
未知のツールやコア以外のツール、範囲外の読み取り、実行権限を持つツール、コントロールプレーンを操作するツール、状態を変更するツール、およびインタラクティブなフローでは、常に明示的な承認が必要です。
サーバーから提供される toolCall.kind は、信頼できないメタデータとして扱われます（認可の判断材料にはなりません）。

この ACP ブリッジのポリシーは、ACPX ハーネスの権限とは独立している点に注意してください。もし acpx バックエンド経由で OpenClaw を実行している場合、plugins.entries.acpx.config.permissionMode=approve-all を設定すれば、そのセッションのすべての制限を解除できます。これは緊急時や完全に信頼できる環境でのみ使用する設定です。

使い方

IDE（またはその他のクライアント）が Agent Client Protocol を使用しており、OpenClaw Gateway セッションを操作したい場合に ACP を使用します。

Gateway が実行されていることを確認します（ローカルまたはリモート）。
Gateway のターゲットを設定します（config または flags）。
IDE が stdio 経由で openclaw acp を実行するように設定します。

設定例（永続化する場合）:

openclaw config set gateway.remote.url wss://gateway-host:18789
openclaw config set gateway.remote.token <token>

直接実行の例（設定を保存しない場合）:

openclaw acp --url wss://gateway-host:18789 --token <token>
# preferred for local process safety
openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

エージェントの選択

ACP はエージェントを直接選択しません。Gateway のセッションキーに基づいてルーティングを行います。

特定のエージェントをターゲットにするには、エージェントスコープのセッションキーを使用してください。

openclaw acp --session agent:main:main
openclaw acp --session agent:design:main
openclaw acp --session agent:qa:bug-123

各 ACP セッションは、単一の Gateway セッションキーにマッピングされます。1つのエージェントは多くのセッションを持つことができます。キーやラベルを上書きしない限り、ACP はデフォルトで独立した acp:<uuid> セッションを使用します。

ブリッジモードでは、セッションごとの mcpServers はサポートされていません。ACP クライアントが newSession または loadSession の実行中にこれらを送信した場合、ブリッジは黙って無視するのではなく、明確なエラーを返します。

ACPX ベースのセッションで OpenClaw プラグインツールを表示したい場合は、セッションごとに mcpServers を渡そうとするのではなく、Gateway 側の ACPX プラグインブリッジを有効にしてください。詳細は ACP Agents を参照してください。

`acpx`（Codex、Claude、その他の ACP クライアント）からの利用

Codex や Claude Code などのコーディングエージェントを、ACP 経由で OpenClaw ボットと連携させたい場合は、acpx の組み込みターゲットである openclaw を使うのがおすすめです。

一般的な流れは次の通りです：

Gateway を起動し、ACP ブリッジからアクセスできることを確認します。
acpx openclaw を openclaw acp に向けます。
コーディングエージェントに使用させたい OpenClaw のセッションキーを指定します。

例：

# One-shot request into your default OpenClaw ACP session
acpx openclaw exec "Summarize the active OpenClaw session state."

# Persistent named session for follow-up turns
acpx openclaw sessions ensure --name codex-bridge
acpx openclaw -s codex-bridge --cwd /path/to/repo \
  "Ask my OpenClaw work agent for recent context relevant to this repo."

もし acpx openclaw が常に特定の Gateway やセッションキーを指すようにしたい場合は、~/.acpx/config.json で openclaw エージェントのコマンドを上書きしてください。

{
  "agents": {
    "openclaw": {
      "command": "env OPENCLAW_HIDE_BANNER=1 OPENCLAW_SUPPRESS_NOTES=1 openclaw acp --url ws://127.0.0.1:18789 --token-file ~/.openclaw/gateway.token --session agent:main:main"
    }
  }
}

リポジトリ内のローカルな OpenClaw を使用する場合は、ACP ストリームをクリーンに保つために、dev runner ではなく直接 CLI エントリポイントを使用してください。例えば以下のようになります：

env OPENCLAW_HIDE_BANNER=1 OPENCLAW_SUPPRESS_NOTES=1 node openclaw.mjs acp ...

これが、Codex や Claude Code、あるいはその他の ACP 対応クライアントが、ターミナルをスクレイピングすることなく OpenClaw エージェントからコンテキスト情報を取得するための最も簡単な方法です。

Zed エディタの設定

~/.config/zed/settings.json にカスタム ACP エージェントを追加します（Zed の設定 UI からでも設定可能です）：

{
  "agent_servers": {
    "OpenClaw ACP": {
      "type": "custom",
      "command": "openclaw",
      "args": ["acp"],
      "env": {}
    }
  }
}

特定の Gateway やエージェントを指定する場合は、次のように記述します：

{
  "agent_servers": {
    "OpenClaw ACP": {
      "type": "custom",
      "command": "openclaw",
      "args": [
        "acp",
        "--url",
        "wss://gateway-host:18789",
        "--token",
        "<token>",
        "--session",
        "agent:design:main"
      ],
      "env": {}
    }
  }
}

Zed でエージェントパネルを開き、「OpenClaw ACP」を選択するとスレッドを開始できます。

セッションのマッピング

デフォルトでは、ACP セッションには acp: プレフィックスが付いた、独立した Gateway セッションキーが割り当てられます。既知のセッションを再利用したい場合は、セッションキーまたはラベルを指定してください。

--session <key>: 特定の Gateway セッションキーを使用します。
--session-label <label>: ラベルを使用して既存のセッションを解決します。
--reset-session: そのキーに対して新しいセッション ID を作成します（キーは同じですが、中身は新しいトランスクリプトになります）。

お使いの ACP クライアントがメタデータをサポートしている場合は、セッションごとに設定を上書きできます。

{
  "_meta": {
    "sessionKey": "agent:main:main",
    "sessionLabel": "support inbox",
    "resetSession": true
  }
}

セッションキーの詳細については、/concepts/session を確認してください。

オプション

--url <url>: Gateway の WebSocket URL（設定済みであれば、デフォルトは gateway.remote.url になります）。
--token <token>: Gateway 認証トークン。
--token-file <path>: ファイルから Gateway 認証トークンを読み込みます。
--password <password>: Gateway 認証パスワード。
--password-file <path>: ファイルから Gateway 認証パスワードを読み込みます。
--session <key>: デフォルトのセッションキー。
--session-label <label>: 解決するデフォルトのセッションラベル。
--require-existing: セッションキーやラベルが存在しない場合にエラーにします。
--reset-session: 初回使用前にセッションキーをリセットします。
--no-prefix-cwd: プロンプトに作業ディレクトリのプレフィックスを付けません。
--verbose, -v: stderr に詳細なログを出力します。

セキュリティに関する注意点：

一部のシステムでは、--token や --password がローカルのプロセスリストに表示される可能性があります。
--token-file や --password-file、または環境変数（OPENCLAW_GATEWAY_TOKEN、OPENCLAW_GATEWAY_PASSWORD）の使用を推奨します。
Gateway の認証解決は、他の Gateway クライアントと共通のルールに従います：
- ローカルモード：環境変数 (OPENCLAW_GATEWAY_*) -> gateway.auth.* -> gateway.remote.*（gateway.auth.* が未設定の場合のみフォールバック。設定済みで解決できない SecretRefs はエラーになります）。
- リモートモード：リモートの優先順位ルールに基づき、gateway.remote.* と環境変数や設定のフォールバックを使用します。
- --url は安全に上書き可能で、暗黙的な設定や環境変数の認証情報は再利用されません。明示的に --token/--password（またはファイル版）を渡してください。
ACP ランタイムのバックエンド子プロセスは OPENCLAW_SHELL=acp を受け取ります。これは、コンテキストに応じたシェルやプロファイルの設定に使用できます。
openclaw acp client は、起動されたブリッジプロセスに OPENCLAW_SHELL=acp-client を設定します。

`acp client` オプション

--cwd <dir>: ACP セッションの作業ディレクトリ。
--server <command>: ACP サーバーコマンド（デフォルト：openclaw）。
--server-args <args...>: ACP サーバーに渡す追加の引数。
--server-verbose: ACP サーバーの詳細ログを有効にします。
--verbose, -v: クライアントの詳細ログを出力します。

OpenClaw Expert

まだ解決しませんか？

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