ACP

Jalankan jembatan Agent Client Protocol (ACP) yang berbicara dengan OpenClaw Gateway.

Perintah ini berbicara ACP melalui stdio untuk IDE dan meneruskan prompt ke Gateway melalui WebSocket. Perintah ini menjaga sesi ACP tetap dipetakan ke kunci sesi Gateway.

openclaw acp adalah jembatan ACP yang didukung Gateway, bukan runtime editor ACP-native penuh. Perintah ini berfokus pada perutean sesi, pengiriman prompt, dan pembaruan streaming dasar.

Jika Anda ingin klien MCP eksternal berbicara langsung dengan percakapan channel OpenClaw alih-alih menghosting sesi harness ACP, gunakan openclaw mcp serve sebagai gantinya.

Ini bukan apa

Halaman ini sering tertukar dengan sesi harness ACP.

openclaw acp berarti:

• OpenClaw bertindak sebagai server ACP
• IDE atau klien ACP terhubung ke OpenClaw
• OpenClaw meneruskan pekerjaan itu ke dalam sesi Gateway

Ini berbeda dari ACP Agents, tempat OpenClaw menjalankan harness eksternal seperti Codex atau Claude Code melalui acpx.

Aturan cepat:

• editor/klien ingin berbicara ACP ke OpenClaw: gunakan openclaw acp
• OpenClaw harus meluncurkan Codex/Claude/Gemini sebagai harness ACP: gunakan /acp spawn dan ACP Agents

Matriks Kompatibilitas

Batasan yang Diketahui

• loadSession dapat memutar ulang riwayat ledger peristiwa ACP lengkap hanya untuk sesi yang dibuat jembatan. Sesi lama/tanpa ledger masih menggunakan fallback transkrip dan tidak merekonstruksi panggilan tool historis atau pemberitahuan sistem.
• Jika beberapa klien ACP berbagi kunci sesi Gateway yang sama, perutean peristiwa dan pembatalan bersifat upaya terbaik, bukan terisolasi ketat per klien. Pilih sesi default terisolasi acp-bridge:<uuid> saat Anda membutuhkan putaran editor-lokal yang bersih.
• Status berhenti Gateway diterjemahkan menjadi alasan berhenti ACP, tetapi pemetaan itu kurang ekspresif dibanding runtime ACP-native penuh.
• Kontrol sesi awal saat ini menampilkan subset knob Gateway yang terfokus: tingkat pemikiran, verbositas tool, reasoning, detail penggunaan, dan tindakan elevated. Pemilihan model dan kontrol exec-host belum diekspos sebagai opsi konfigurasi ACP.
• session_info_update dan usage_update diturunkan dari snapshot sesi Gateway, bukan akuntansi runtime ACP-native langsung. Penggunaan bersifat perkiraan, tidak membawa data biaya, dan hanya dipancarkan saat Gateway menandai data total token sebagai segar.
• Data mengikuti tool bersifat upaya terbaik. Jembatan dapat menampilkan path file yang muncul dalam argumen/hasil tool yang dikenal, tetapi belum memancarkan terminal ACP atau diff file terstruktur.
• Relay persetujuan exec dibatasi pada putaran prompt ACP aktif; persetujuan dari sesi Gateway lain diabaikan.

Penggunaan

openclaw acp # Remote Gatewayopenclaw 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 keyopenclaw acp --session agent:main:main # Attach by label (must already exist)openclaw acp --session-label "support inbox" # Reset the session key before the first promptopenclaw acp --session agent:main:main --reset-session

Klien ACP (debug)

Gunakan klien ACP bawaan untuk memeriksa kewarasan jembatan tanpa IDE. Klien ini menjalankan jembatan ACP dan memungkinkan Anda mengetik prompt secara interaktif.

openclaw acp client # Point the spawned bridge at a remote Gatewayopenclaw 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

Model izin (mode debug klien):

• Persetujuan otomatis berbasis allowlist dan hanya berlaku untuk ID tool inti tepercaya.
• Persetujuan otomatis read dibatasi ke direktori kerja saat ini (--cwd saat disetel).
• ACP hanya menyetujui otomatis kelas readonly yang sempit: panggilan read tercakup di bawah cwd aktif ditambah tool pencarian readonly (search, web_search, memory_search). Tool yang tidak dikenal/non-inti, pembacaan di luar cakupan, tool berkemampuan exec, tool control-plane, tool yang memutasi, dan alur interaktif selalu memerlukan persetujuan prompt eksplisit.
• toolCall.kind yang disediakan server diperlakukan sebagai metadata tidak tepercaya (bukan sumber otorisasi).
• Kebijakan jembatan ACP ini terpisah dari izin harness ACPX. Jika Anda menjalankan OpenClaw melalui backend acpx, plugins.entries.acpx.config.permissionMode=approve-all adalah sakelar "yolo" darurat untuk sesi harness tersebut.

Pengujian smoke protokol

Untuk debugging tingkat protokol, mulai Gateway dengan status terisolasi dan kendalikan openclaw acp melalui stdio dengan klien JSON-RPC ACP. Cakup initialize, session/new, session/list dengan cwd absolut, session/resume, session/close, close duplikat, dan resume yang hilang.

Bukti harus menyertakan kemampuan siklus hidup yang diiklankan, baris sesi yang didukung Gateway, notifikasi pembaruan, dan log sessions.list Gateway:

{  "initialize": {    "protocolVersion": 1,    "agentCapabilities": {      "sessionCapabilities": {        "list": {},        "resume": {},        "close": {}      }    }  },  "listSessions": {    "sessions": [      {        "sessionId": "agent:main:acp-smoke",        "cwd": "/path/to/workspace",        "_meta": {          "sessionKey": "agent:main:acp-smoke",          "kind": "direct"        }      }    ],    "nextCursor": null  },  "notifications": ["session_info_update", "available_commands_update", "usage_update"],  "gatewayLogTail": ["[gateway] ready", "[ws] ⇄ res ✓ sessions.list 305ms"]}

Hindari menggunakan openclaw gateway call sessions.list sebagai satu-satunya bukti ACP. Path CLI itu dapat meminta peningkatan cakupan operator fresh-token; kebenaran jembatan ACP dibuktikan oleh frame stdio ACP ditambah log sessions.list Gateway.

Cara menggunakan ini

Gunakan ACP saat IDE (atau klien lain) berbicara Agent Client Protocol dan Anda ingin klien tersebut mengendalikan sesi OpenClaw Gateway.

1. Pastikan Gateway berjalan (lokal atau jarak jauh).
2. Konfigurasikan target Gateway (konfigurasi atau flag).
3. Arahkan IDE Anda untuk menjalankan openclaw acp melalui stdio.

Contoh konfigurasi (dipersistenkan):

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

Contoh jalankan langsung (tanpa penulisan konfigurasi):

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

Memilih agen

ACP tidak memilih agen secara langsung. ACP merutekan berdasarkan kunci sesi Gateway.

Gunakan kunci sesi bercakupan agen untuk menargetkan agen tertentu:

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

Setiap sesi ACP dipetakan ke satu kunci sesi Gateway. Satu agen dapat memiliki banyak sesi; ACP secara default menggunakan sesi acp-bridge:<uuid> yang terisolasi kecuali Anda menimpa kunci atau labelnya.

mcpServers per sesi tidak didukung dalam mode bridge. Jika klien ACP mengirimkannya selama newSession atau loadSession, bridge mengembalikan kesalahan yang jelas alih-alih mengabaikannya secara diam-diam.

Jika Anda ingin sesi yang didukung ACPX melihat alat Plugin OpenClaw atau alat bawaan tertentu seperti cron, aktifkan bridge ACPX MCP di sisi Gateway alih-alih mencoba meneruskan mcpServers per sesi. Lihat ACP Agents dan bridge MCP alat OpenClaw.

Gunakan dari acpx (Codex, Claude, klien ACP lainnya)

Jika Anda ingin agen pengodean seperti Codex atau Claude Code berbicara dengan bot OpenClaw Anda melalui ACP, gunakan acpx dengan target openclaw bawaannya.

Alur umum:

1. Jalankan Gateway dan pastikan bridge ACP dapat menjangkaunya.
2. Arahkan acpx openclaw ke openclaw acp.
3. Targetkan kunci sesi OpenClaw yang Anda ingin digunakan oleh agen pengodean.

Contoh:

# Permintaan sekali jalan ke sesi ACP OpenClaw default Andaacpx openclaw exec "Summarize the active OpenClaw session state." # Sesi bernama persisten untuk giliran lanjutanacpx openclaw sessions ensure --name codex-bridgeacpx openclaw -s codex-bridge --cwd /path/to/repo \  "Ask my OpenClaw work agent for recent context relevant to this repo."

Jika Anda ingin acpx openclaw menargetkan Gateway dan kunci sesi tertentu setiap saat, timpa perintah agen openclaw di ~/.acpx/config.json:

{  "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"    }  }}

Untuk checkout OpenClaw lokal repo, gunakan entrypoint CLI langsung alih-alih runner dev agar stream ACP tetap bersih. Misalnya:

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

Ini adalah cara termudah untuk memungkinkan Codex, Claude Code, atau klien lain yang paham ACP menarik informasi kontekstual dari agen OpenClaw tanpa melakukan scraping terminal.

Penyiapan editor Zed

Tambahkan agen ACP kustom di ~/.config/zed/settings.json (atau gunakan UI Settings Zed):

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

Untuk menargetkan Gateway atau agen tertentu:

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

Di Zed, buka panel Agent dan pilih "OpenClaw ACP" untuk memulai thread.

Pemetaan sesi

Secara default, sesi bridge ACP mendapatkan kunci sesi Gateway terisolasi dengan prefiks acp-bridge:. Sesi bridge model normal ini bersifat sintetis dan tunduk pada pemangkasan entri usang serta batas jumlah entri. Untuk menggunakan kembali sesi yang diketahui, teruskan kunci atau label sesi:

• --session <key>: gunakan kunci sesi Gateway tertentu.
• --session-label <label>: selesaikan sesi yang sudah ada berdasarkan label.
• --reset-session: buat id sesi baru untuk kunci tersebut (kunci yang sama, transkrip baru).

Jika klien ACP Anda mendukung metadata, Anda dapat menimpa per sesi:

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

Pelajari selengkapnya tentang kunci sesi di /concepts/session.

Opsi

• --url <url>: URL WebSocket Gateway (default ke gateway.remote.url saat dikonfigurasi).
• --token <token>: token autentikasi Gateway.
• --token-file <path>: baca token autentikasi Gateway dari file.
• --password <password>: kata sandi autentikasi Gateway.
• --password-file <path>: baca kata sandi autentikasi Gateway dari file.
• --session <key>: kunci sesi default.
• --session-label <label>: label sesi default untuk diselesaikan.
• --require-existing: gagal jika kunci/label sesi tidak ada.
• --reset-session: reset kunci sesi sebelum penggunaan pertama.
• --no-prefix-cwd: jangan awali prompt dengan direktori kerja.
• --provenance <off|meta|meta+receipt>: sertakan metadata atau tanda terima provenance ACP.
• --verbose, -v: logging verbose ke stderr.

Catatan keamanan:

• --token dan --password dapat terlihat dalam daftar proses lokal pada beberapa sistem.
• Utamakan --token-file/--password-file atau variabel lingkungan (OPENCLAW_GATEWAY_TOKEN, OPENCLAW_GATEWAY_PASSWORD).
• Resolusi autentikasi Gateway mengikuti kontrak bersama yang digunakan oleh klien Gateway lainnya:
  • mode lokal: env (OPENCLAW_GATEWAY_*) -> gateway.auth.* -> fallback gateway.remote.* hanya saat gateway.auth.* tidak disetel (SecretRefs lokal yang dikonfigurasi tetapi tidak terselesaikan gagal tertutup)
  • mode remote: gateway.remote.* dengan fallback env/config sesuai aturan prioritas remote
  • --url aman sebagai override dan tidak menggunakan ulang kredensial config/env implisit; teruskan --token/--password eksplisit (atau varian file)
• Proses anak backend runtime ACP menerima OPENCLAW_SHELL=acp, yang dapat digunakan untuk aturan shell/profil khusus konteks.
• openclaw acp client menyetel OPENCLAW_SHELL=acp-client pada proses bridge yang di-spawn.

Opsi acp client

• --cwd <dir>: direktori kerja untuk sesi ACP.
• --server <command>: perintah server ACP (default: openclaw).
• --server-args <args...>: argumen tambahan yang diteruskan ke server ACP.
• --server-verbose: aktifkan logging verbose pada server ACP.
• --verbose, -v: logging klien verbose.

Terkait

• referensi CLI
• agen ACP