Agen ACP

• Jika plugins.allow diatur, itu adalah inventaris plugin yang restriktif dan harus menyertakan acpx; jika tidak, backend ACP yang terpasang sengaja diblokir dan /acp doctor melaporkan entri allowlist yang hilang.
• Adapter Codex ACP disiapkan bersama plugin acpx dan diluncurkan secara lokal jika memungkinkan.
• Codex ACP berjalan dengan CODEX_HOME yang terisolasi; OpenClaw menyalin entri proyek tepercaya plus konfigurasi routing model/penyedia yang aman dari konfigurasi Codex host, sementara autentikasi, notifikasi, dan hook tetap berada pada konfigurasi host.
• Adapter harness target lain mungkin masih diambil sesuai permintaan dengan npx saat pertama kali Anda menggunakannya.
• Autentikasi vendor tetap harus ada pada host untuk harness tersebut.
• Jika host tidak memiliki npm atau akses jaringan, pengambilan adapter pertama kali gagal hingga cache dipanaskan lebih dulu atau adapter dipasang dengan cara lain.

ACP meluncurkan proses harness eksternal nyata. OpenClaw memiliki routing, status tugas latar belakang, pengiriman, binding, dan kebijakan; harness memiliki login penyedia, katalog model, perilaku sistem berkas, dan alat native-nya sendiri.

Sebelum menyalahkan OpenClaw, verifikasi:

• /acp doctor melaporkan backend yang aktif dan sehat.
• ID target diizinkan oleh acp.allowedAgents saat allowlist tersebut diatur.
• Perintah harness dapat dimulai pada host Gateway.
• Autentikasi penyedia tersedia untuk harness tersebut (claude, codex, gemini, opencode, droid, dll.).
• Model yang dipilih ada untuk harness tersebut - ID model tidak portabel antar-harness.
• cwd yang diminta ada dan dapat diakses, atau hilangkan cwd dan biarkan backend menggunakan default-nya.
• Mode izin cocok dengan pekerjaannya. Sesi non-interaktif tidak dapat mengeklik prompt izin native, jadi run pengodean yang banyak menulis/mengeksekusi biasanya memerlukan profil izin ACPX yang dapat berjalan headless.

• Spawn membuat atau melanjutkan sesi runtime ACP, mencatat metadata ACP di penyimpanan sesi OpenClaw, dan dapat membuat tugas latar belakang saat run dimiliki induk.
• Sesi ACP yang dimiliki induk diperlakukan sebagai pekerjaan latar belakang bahkan saat sesi runtime bersifat persisten; penyelesaian dan pengiriman lintas permukaan melalui notifier tugas induk, bukan bertindak seperti sesi chat normal yang terlihat pengguna.
• Pemeliharaan tugas menutup sesi ACP one-shot yang terminal atau yatim dan dimiliki induk. Sesi ACP persisten dipertahankan selama binding percakapan aktif masih ada; sesi persisten lama tanpa binding aktif ditutup agar tidak dapat dilanjutkan diam-diam setelah tugas pemilik selesai atau catatan tugasnya hilang.
• Pesan tindak lanjut terikat langsung masuk ke sesi ACP hingga binding ditutup, tidak difokuskan, direset, atau kedaluwarsa.
• Perintah Gateway tetap lokal. /acp ..., /status, dan /unfocus tidak pernah dikirim sebagai teks prompt normal ke harness ACP terikat.
• cancel membatalkan giliran aktif saat backend mendukung pembatalan; ini tidak menghapus binding atau metadata sesi.
• close mengakhiri sesi ACP dari sudut pandang OpenClaw dan menghapus binding. Harness mungkin tetap menyimpan riwayat upstream-nya sendiri jika mendukung resume.
• Plugin acpx membersihkan pohon proses wrapper dan adapter milik OpenClaw setelah close, dan menuai yatim ACPX milik OpenClaw yang lama saat startup Gateway.
• Worker runtime idle memenuhi syarat untuk dibersihkan setelah acp.runtime.ttlMinutes; metadata sesi yang disimpan tetap tersedia untuk /acp sessions.

Pemicu bahasa alami yang harus dirouting ke plugin Codex native saat diaktifkan:

• "Bind this Discord channel to Codex."
• "Attach this chat to Codex thread <id>."
• "Show Codex threads, then bind this one."

Pengikatan percakapan Codex native adalah jalur kontrol obrolan default. Alat dinamis OpenClaw tetap dieksekusi melalui OpenClaw, sedangkan alat Codex-native seperti shell/apply-patch dieksekusi di dalam Codex. Untuk peristiwa alat Codex-native, OpenClaw menyuntikkan relay hook native per giliran sehingga hook plugin dapat memblokir before_tool_call, mengamati after_tool_call, dan merutekan peristiwa Codex PermissionRequest melalui persetujuan OpenClaw. Hook Codex Stop direlay ke OpenClaw before_agent_finalize, tempat plugin dapat meminta satu pass model lagi sebelum Codex memfinalisasi jawabannya. Relay tetap sengaja konservatif: relay ini tidak memutasi argumen alat Codex-native atau menulis ulang rekaman thread Codex. Gunakan ACP eksplisit hanya saat Anda menginginkan model runtime/sesi ACP. Batas dukungan Codex tertanam didokumentasikan dalam Kontrak dukungan Codex harness v1.

• referensi model Codex legacy - rute model OAuth/langganan Codex legacy yang diperbaiki oleh doctor.
• openai/* - runtime tertanam server aplikasi Codex native untuk giliran agen OpenAI.
• /codex ... - kontrol percakapan Codex native.
• /acp ... atau runtime: "acp" - kontrol ACP/acpx eksplisit.

Pemicu yang seharusnya dirutekan ke runtime ACP:

• "Jalankan ini sebagai sesi Claude Code ACP sekali jalan dan ringkas hasilnya."
• "Gunakan Gemini CLI untuk tugas ini dalam sebuah thread, lalu pertahankan tindak lanjut dalam thread yang sama."
• "Jalankan Codex melalui ACP dalam thread latar belakang."

OpenClaw memilih runtime: "acp", menyelesaikan harness agentId, mengikat ke percakapan atau thread saat ini bila didukung, dan merutekan tindak lanjut ke sesi tersebut hingga ditutup/kedaluwarsa. Codex hanya mengikuti jalur ini saat ACP/acpx eksplisit atau Plugin Codex native tidak tersedia untuk operasi yang diminta.

Untuk sessions_spawn, runtime: "acp" diiklankan hanya saat ACP diaktifkan, peminta tidak berada dalam sandbox, dan backend runtime ACP dimuat. acp.dispatch.enabled=false menjeda dispatch thread ACP otomatis tetapi tidak menyembunyikan atau memblokir panggilan sessions_spawn({ runtime: "acp" }) eksplisit. Ini menargetkan id harness ACP seperti codex, claude, droid, gemini, atau opencode. Jangan meneruskan id agen konfigurasi OpenClaw biasa dari agents_list kecuali entri itu dikonfigurasi secara eksplisit dengan agents.list[].runtime.type="acp"; jika tidak, gunakan runtime sub-agen default. Saat agen OpenClaw dikonfigurasi dengan runtime.type="acp", OpenClaw menggunakan runtime.acp.agent sebagai id harness yang mendasarinya.

• --bind here dan --thread ... saling eksklusif.
• --bind here hanya berfungsi pada kanal yang mengiklankan pengikatan percakapan saat ini; OpenClaw mengembalikan pesan tidak didukung yang jelas jika tidak. Pengikatan bertahan lintas restart gateway.
• Di Discord, spawnSessions membatasi pembuatan thread anak untuk --thread auto|here - bukan --bind here.
• Jika Anda spawn ke agen ACP berbeda tanpa --cwd, OpenClaw mewarisi workspace agen target secara default. Path warisan yang hilang (ENOENT/ENOTDIR) fallback ke default backend; kesalahan akses lain (mis. EACCES) muncul sebagai kesalahan spawn.
• Perintah manajemen Gateway tetap lokal dalam percakapan terikat - perintah /acp ... ditangani oleh OpenClaw bahkan ketika teks tindak lanjut normal dirutekan ke sesi ACP terikat; /status dan /unfocus juga tetap lokal kapan pun penanganan perintah diaktifkan untuk permukaan tersebut.

Saat pengikatan thread diaktifkan untuk adapter kanal:

• OpenClaw mengikat thread ke sesi ACP target.
• Pesan tindak lanjut dalam thread tersebut dirutekan ke sesi ACP terikat.
• Output ACP dikirim kembali ke thread yang sama.
• Unfocus/tutup/arsip/timeout idle atau kedaluwarsa usia maksimum menghapus pengikatan.
• /acp close, /acp cancel, /acp status, /status, dan /unfocus adalah perintah Gateway, bukan prompt ke harness ACP.

Flag fitur yang diperlukan untuk ACP terikat thread:

• acp.enabled=true
• acp.dispatch.enabled aktif secara default (atur false untuk menjeda dispatch thread ACP otomatis; panggilan sessions_spawn({ runtime: "acp" }) eksplisit tetap berfungsi).
• Spawn sesi thread adapter kanal diaktifkan (default: true):
  • Discord: channels.discord.threadBindings.spawnSessions=true
  • Telegram: channels.telegram.threadBindings.spawnSessions=true

Dukungan pengikatan thread bersifat spesifik adapter. Jika adapter kanal aktif tidak mendukung pengikatan thread, OpenClaw mengembalikan pesan tidak didukung/tidak tersedia yang jelas.

• Adapter kanal apa pun yang mengekspos kapabilitas pengikatan sesi/thread.
• Dukungan bawaan saat ini: thread/kanal Discord, topik Telegram (topik forum dalam grup/supergrup dan topik DM).
• Kanal Plugin dapat menambahkan dukungan melalui antarmuka pengikatan yang sama.

Sesi interaktif dimaksudkan untuk terus berbicara pada permukaan obrolan yang terlihat:

• /acp spawn ... --bind here mengikat percakapan saat ini ke sesi ACP.
• /acp spawn ... --thread ... mengikat thread/topik kanal ke sesi ACP.
• bindings[].type="acp" persisten mengarahkan percakapan yang cocok ke sesi ACP yang sama.

Pesan lanjutan dalam percakapan terikat diarahkan langsung ke sesi ACP, dan output ACP dikirim kembali ke kanal/thread/topik yang sama.

Yang dikirim OpenClaw ke harness:

• Lanjutan terikat normal dikirim sebagai teks prompt, ditambah lampiran hanya saat harness/backend mendukungnya.
• Perintah manajemen /acp dan perintah Gateway lokal dicegat sebelum pengiriman ACP.
• Peristiwa penyelesaian yang dibuat runtime dimaterialisasi per target. Agen OpenClaw mendapatkan amplop konteks runtime internal OpenClaw; harness ACP eksternal mendapatkan prompt biasa dengan hasil anak dan instruksi. Amplop mentah <<&lt;BEGIN_OPENCLAW_INTERNAL_CONTEXT&gt;>> tidak boleh pernah dikirim ke harness eksternal atau dipersistenkan sebagai teks transkrip pengguna ACP.
• Entri transkrip ACP menggunakan teks pemicu yang terlihat oleh pengguna atau prompt penyelesaian biasa. Metadata peristiwa internal tetap terstruktur di OpenClaw jika memungkinkan dan tidak diperlakukan sebagai konten obrolan yang ditulis pengguna.

Sesi ACP sekali jalan yang di-spawn oleh run agen lain adalah anak latar belakang, mirip dengan subagen:

• Induk meminta pekerjaan dengan sessions_spawn({ runtime: "acp", mode: "run" }).
• Anak berjalan di sesi harness ACP-nya sendiri.
• Giliran anak berjalan pada lane latar belakang yang sama dengan yang digunakan oleh spawn subagen native, sehingga harness ACP yang lambat tidak memblokir pekerjaan sesi utama yang tidak terkait.
• Laporan penyelesaian kembali melalui jalur pengumuman penyelesaian tugas. OpenClaw mengonversi metadata penyelesaian internal menjadi prompt ACP biasa sebelum mengirimkannya ke harness eksternal, sehingga harness tidak melihat penanda konteks runtime khusus OpenClaw.
• Induk menulis ulang hasil anak dengan suara asisten normal saat balasan yang terlihat oleh pengguna berguna.

Jangan perlakukan jalur ini sebagai obrolan peer-to-peer antara induk dan anak. Anak sudah memiliki kanal penyelesaian kembali ke induk.

sessions_send dapat menargetkan sesi lain setelah spawn. Untuk sesi peer normal, OpenClaw menggunakan jalur lanjutan agen-ke-agen (A2A) setelah menyuntikkan pesan:

• Tunggu balasan sesi target.
• Secara opsional izinkan peminta dan target bertukar sejumlah giliran lanjutan yang dibatasi.
• Minta target menghasilkan pesan pengumuman.
• Kirim pengumuman tersebut ke kanal atau thread yang terlihat.

Jalur A2A tersebut adalah fallback untuk pengiriman peer ketika pengirim memerlukan lanjutan yang terlihat. Jalur ini tetap aktif ketika sesi yang tidak terkait dapat melihat dan mengirim pesan ke target ACP, misalnya di bawah pengaturan tools.sessions.visibility yang luas.

OpenClaw melewati tindak lanjut A2A hanya ketika peminta adalah induk dari anak ACP sekali-jalan milik induknya sendiri. Dalam kasus itu, menjalankan A2A di atas penyelesaian tugas dapat membangunkan induk dengan hasil anak, meneruskan balasan induk kembali ke anak, dan membuat loop gema induk/anak. Hasil sessions_send melaporkan delivery.status="skipped" untuk kasus anak-dimiliki tersebut karena jalur penyelesaian sudah bertanggung jawab atas hasilnya.

Gunakan resumeSessionId untuk melanjutkan sesi ACP sebelumnya alih-alih memulai dari awal. Agen memutar ulang riwayat percakapannya melalui session/load, sehingga melanjutkan dengan konteks penuh dari yang terjadi sebelumnya.

{  "task": "Continue where we left off - fix the remaining test failures",  "runtime": "acp",  "agentId": "codex",  "resumeSessionId": "<previous-session-id>"}

Kasus penggunaan umum:

• Serahkan sesi Codex dari laptop Anda ke ponsel Anda - beri tahu agen Anda untuk melanjutkan dari tempat terakhir Anda berhenti.
• Lanjutkan sesi pengodean yang Anda mulai secara interaktif di CLI, sekarang tanpa antarmuka melalui agen Anda.
• Lanjutkan pekerjaan yang terputus oleh mulai ulang gateway atau batas waktu idle.

Catatan:

• resumeSessionId hanya berlaku ketika runtime: "acp"; runtime sub-agen default mengabaikan bidang khusus ACP ini.
• streamTo hanya berlaku ketika runtime: "acp"; runtime sub-agen default mengabaikan bidang khusus ACP ini.
• resumeSessionId adalah id lanjutan ACP/harness lokal-host, bukan kunci sesi kanal OpenClaw; OpenClaw tetap memeriksa kebijakan spawn ACP dan kebijakan agen target sebelum dispatch, sementara backend ACP atau harness memiliki otorisasi untuk memuat id upstream tersebut.
• resumeSessionId memulihkan riwayat percakapan ACP upstream; thread dan mode tetap berlaku normal untuk sesi OpenClaw baru yang Anda buat, sehingga mode: "session" tetap memerlukan thread: true.
• Agen target harus mendukung session/load (Codex dan Claude Code mendukungnya).
• Jika id sesi tidak ditemukan, spawn gagal dengan galat yang jelas - tanpa fallback diam-diam ke sesi baru.

Setelah deploy gateway, jalankan pemeriksaan end-to-end langsung alih-alih memercayai uji unit:

1. Verifikasi versi gateway dan commit yang dideploy pada host target.
2. Buka sesi bridge ACPX sementara ke agen langsung.
3. Minta agen tersebut memanggil sessions_spawn dengan runtime: "acp", agentId: "codex", mode: "run", dan tugas Reply with exactly LIVE-ACP-SPAWN-OK.
4. Verifikasi accepted=yes, childSessionKey nyata, dan tidak ada galat validator.
5. Bersihkan sesi bridge sementara.

Pertahankan gate pada mode: "run" dan lewati streamTo: "parent" - mode: "session" yang terikat thread dan jalur stream-relay adalah lintasan integrasi lebih kaya yang terpisah.