acp

OpenClaw Gatewayと通信するAgent Client Protocol (ACP)ブリッジを起動します。

このコマンドはIDE向けにstdio経由でACPを話し、プロンプトをWebSocket経由でGatewayに転送します。ACPセッションをGatewayセッションキーにマッピングして管理します。

openclaw acpはGateway連携型のACPブリッジであり、完全なACP対応エディタランタイムではありません。セッションルーティング、プロンプト配信、基本的なストリーミング更新に特化しています。

互換性マトリクス

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またはAgentで設定してください。
クライアントファイルシステムメソッド (fs/read_text_file, fs/write_text_file)未対応ブリッジはACPクライアントのファイルシステムメソッドを呼び出しません。
クライアントターミナルメソッド (terminal/*)未対応ブリッジはACPクライアントターミナルの作成やツールコール経由でのターミナルIDストリーミングを行いません。
セッションプラン / 思考ストリーミング未対応ブリッジは出力テキストとツールステータスを送信しますが、ACPプランや思考の更新は送信しません。

既知の制限事項

  • loadSessionは保存済みのユーザーおよびアシスタントテキスト履歴を再生しますが、過去のツールコール、システム通知、その他のリッチなACP固有イベントタイプは復元しません。
  • 複数のACPクライアントが同じGatewayセッションキーを共有する場合、イベントとキャンセルのルーティングは厳密なクライアント分離ではなくベストエフォートになります。クリーンなエディタローカルターンが必要な場合は、デフォルトの分離されたacp:<uuid>セッションを使用してください。
  • Gatewayの停止状態はACPの停止理由に変換されますが、完全なACP対応ランタイムと比べると表現力が限定的です。
  • 初期セッション制御は現在、Gatewayの一部の設定のみを公開しています：思考レベル、ツール詳細度、推論、使用量詳細、昇格アクション。モデル選択やexec-host制御はACPの設定オプションとしてまだ公開されていません。
  • session_info_updateとusage_updateはGatewayセッションスナップショットから導出されたもので、ACP固有ランタイムのリアルタイム計測ではありません。使用量は近似値でコストデータを含まず、Gatewayがトークン合計を最新とマークした場合のみ送信されます。
  • ツール追跡データはベストエフォートです。ブリッジは既知のツール引数/結果に含まれるファイルパスを検出できますが、ACPターミナルや構造化されたファイルdiffの送信にはまだ対応していません。

使い方

openclaw acp

# リモートGateway
openclaw acp --url wss://gateway-host:18789 --token <token>

# リモートGateway（ファイルからトークンを読み込み）
openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

# 既存のセッションキーに接続
openclaw acp --session agent:main:main

# ラベルで接続（事前に存在している必要あり）
openclaw acp --session-label "support inbox"

# 最初のプロンプト前にセッションキーをリセット
openclaw acp --session agent:main:main --reset-session

ACPクライアント（デバッグ）

IDEなしでブリッジの動作を確認するための組み込みACPクライアントです。 ACPブリッジを起動し、対話的にプロンプトを入力できます。

openclaw acp client

# 起動したブリッジをリモートGatewayに接続
openclaw acp client --server-args --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

# サーバーコマンドを上書き（デフォルト: openclaw）
openclaw acp client --server "node" --server-args openclaw.mjs acp --url ws://127.0.0.1:19001

パーミッションモデル（クライアントデバッグモード）：

  • 自動承認はホワイトリスト方式で、信頼済みのコアツールIDにのみ適用されます。
  • readの自動承認は現在の作業ディレクトリ（--cwd設定時）にスコープされます。
  • 不明/非コアのツール名、スコープ外の読み取り、危険なツールは常に明示的なプロンプト承認が必要です。
  • サーバー提供のtoolCall.kindは信頼されないメタデータとして扱われます（認可ソースではありません）。

使用方法

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

  1. Gatewayが起動していることを確認（ローカルまたはリモート）。
  2. Gatewayの接続先を設定（設定ファイルまたはフラグ）。
  3. IDEでopenclaw acpをstdio経由で実行するよう設定。

設定例（永続化）：

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>
# ローカルプロセスの安全性のため推奨
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セッションは1つのGatewayセッションキーに対応します。1つのエージェントが複数のセッションを持つことができます。キーまたはラベルを上書きしない限り、ACPはデフォルトで分離されたacp:<uuid>セッションを使用します。

セッション単位のmcpServersはブリッジモードでは対応していません。ACPクライアントがnewSessionやloadSessionでこれを送信した場合、ブリッジはサイレントに無視するのではなく明確なエラーを返します。

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

Codex やClaude CodeなどのコーディングエージェントにACP経由でOpenClawボットと通信させたい場合は、組み込みのopenclawターゲットを持つacpxを使用してください。

一般的な手順：

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

例：

# デフォルトのOpenClaw ACPセッションへのワンショットリクエスト
acpx openclaw exec "Summarize the active OpenClaw session state."

# フォローアップターン用の永続的な名前付きセッション
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ランナーではなく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でAgentパネルを開き、「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クライアントと共通の規約に従います：
    • ローカルモード: env (OPENCLAW_GATEWAY_*) -> gateway.auth.* -> gateway.remote.*フォールバック（gateway.auth.*が未設定の場合のみ。設定済みだが未解決のローカルSecretRefは閉鎖的に失敗）
    • リモートモード: gateway.remote.*（リモート優先順位ルールに基づくenv/configフォールバック付き）
    • --urlはオーバーライド安全で、暗黙のconfig/env認証情報を再利用しません。明示的に--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: クライアントの詳細ログ。
arrow_back
前へ
Cli
次へ
Agent
arrow_forward