Agen ACP

• Jika plugins.allow ditetapkan, nilai tersebut merupakan inventaris plugin yang restriktif dan harus menyertakan acpx, atau backend ACP yang terinstal sengaja diblokir (/acp doctor melaporkan entri daftar izin yang tidak ada).
• Adaptor Codex ACP disertakan bersama plugin acpx dan dijalankan secara lokal jika memungkinkan.
• Codex ACP berjalan dengan CODEX_HOME yang terisolasi. OpenClaw menyalin entri kepercayaan proyek tepercaya beserta konfigurasi perutean model/penyedia yang aman (model, model_provider, model_reasoning_effort, sandbox_mode, dan bidang model_providers.<name> yang aman) dari konfigurasi Codex host; autentikasi, notifikasi, dan hook hanya tetap berada dalam konfigurasi host.
• Adaptor harness target lainnya dapat diambil sesuai permintaan dengan npx saat pertama kali digunakan.
• Autentikasi vendor harus sudah tersedia pada host untuk harness tersebut.
• Jika host tidak memiliki npm atau akses jaringan, pengambilan adaptor saat pertama kali dijalankan akan gagal hingga cache dipanaskan terlebih dahulu atau adaptor diinstal dengan cara lain.

ACP menjalankan proses harness eksternal yang sebenarnya. OpenClaw memiliki perutean, status tugas latar belakang, pengiriman, pengikatan, 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 daftar izin tersebut ditetapkan.
• Perintah harness dapat dimulai pada host Gateway.
• Autentikasi penyedia tersedia untuk harness tersebut (claude, codex, gemini, opencode, droid, dan sebagainya).
• Model yang dipilih tersedia untuk harness tersebut—ID model tidak portabel antar-harness.
• cwd yang diminta tersedia dan dapat diakses, atau hilangkan cwd dan biarkan backend menggunakan nilai default-nya.
• Mode izin sesuai dengan pekerjaan. Sesi noninteraktif tidak dapat mengeklik prompt izin native, sehingga proses pengodean yang banyak melakukan penulisan/eksekusi biasanya memerlukan profil izin ACPX yang dapat berjalan tanpa interaksi.

• Spawn membuat atau melanjutkan sesi runtime ACP, mencatat metadata ACP di penyimpanan sesi OpenClaw, dan dapat membuat tugas latar belakang ketika proses dijalankan dengan kepemilikan induk.
• Sesi ACP dengan kepemilikan induk diperlakukan sebagai pekerjaan latar belakang meskipun sesi runtime bersifat persisten; penyelesaian dan pengiriman lintas permukaan dilakukan melalui pemberi tahu tugas induk, bukan bertindak seperti sesi percakapan normal yang ditampilkan kepada pengguna.
• Pemeliharaan tugas menutup sesi ACP sekali jalan dengan kepemilikan induk yang telah berakhir atau menjadi yatim. Sesi ACP persisten dipertahankan selama pengikatan percakapan aktif masih ada; sesi persisten usang tanpa pengikatan aktif ditutup agar tidak dapat dilanjutkan secara diam-diam setelah tugas pemilik selesai atau catatan tugasnya hilang.
• Pesan lanjutan yang terikat dikirim langsung ke sesi ACP hingga pengikatan ditutup, kehilangan fokus, diatur ulang, atau kedaluwarsa.
• Perintah Gateway tetap ditangani secara lokal. /acp ..., /status, dan /unfocus tidak pernah dikirim sebagai teks prompt biasa ke harness ACP yang terikat.
• cancel membatalkan giliran aktif ketika backend mendukung pembatalan; tindakan ini tidak menghapus pengikatan atau metadata sesi.
• close mengakhiri sesi ACP dari sudut pandang OpenClaw dan menghapus pengikatan. Harness mungkin tetap menyimpan riwayat upstream-nya sendiri jika mendukung pelanjutan.
• Plugin acpx membersihkan pohon proses pembungkus dan adaptor milik OpenClaw setelah close, serta membersihkan proses yatim ACPX milik OpenClaw yang usang saat Gateway dimulai.
• Worker runtime yang menganggur dapat dibersihkan setelah periode menganggur bawaan; metadata sesi yang tersimpan tetap tersedia untuk /acp sessions.

Pemicu bahasa alami yang harus dirutekan ke Plugin Codex native ketika diaktifkan:

• "Ikat channel Discord ini ke Codex."
• "Lampirkan percakapan ini ke thread Codex <id>."
• "Tampilkan thread Codex, lalu ikat yang ini."

Pengikatan percakapan Codex native adalah jalur kontrol percakapan default. Alat dinamis OpenClaw tetap dijalankan melalui OpenClaw, sedangkan alat native Codex seperti shell/apply-patch dijalankan di dalam Codex. Untuk peristiwa alat native Codex, OpenClaw menyuntikkan relai hook native per giliran agar hook Plugin dapat memblokir before_tool_call, mengamati after_tool_call, dan merutekan peristiwa PermissionRequest Codex melalui persetujuan OpenClaw. Hook Stop Codex direlai ke before_agent_finalize OpenClaw, tempat Plugin dapat meminta satu kali lagi proses model sebelum Codex menyelesaikan jawabannya. Relai tersebut sengaja dibuat konservatif: relai tidak mengubah argumen alat native Codex atau menulis ulang catatan thread Codex. Gunakan ACP eksplisit hanya ketika Anda menginginkan model runtime/sesi ACP. Batas dukungan Codex tertanam didokumentasikan dalam kontrak dukungan harness Codex v1.

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

Pemicu yang harus dirutekan ke runtime ACP:

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

OpenClaw memilih runtime: "acp", menentukan harness agentId, mengikatnya ke percakapan atau thread saat ini jika didukung, dan merutekan pesan lanjutan ke sesi tersebut hingga ditutup/kedaluwarsa. Codex hanya mengikuti jalur ini ketika ACP/acpx dinyatakan secara eksplisit atau Plugin Codex native tidak tersedia untuk operasi yang diminta.

Untuk sessions_spawn, runtime: "acp" hanya ditawarkan ketika ACP diaktifkan, peminta tidak berada dalam sandbox, dan backend runtime ACP telah dimuat. acp.dispatch.enabled=false menjeda pengiriman thread ACP otomatis, tetapi tidak menyembunyikan atau memblokir panggilan sessions_spawn({ runtime: "acp" }) eksplisit. Nilai ini menargetkan ID harness ACP seperti codex, claude, droid, gemini, atau opencode. Jangan berikan ID agen konfigurasi OpenClaw biasa dari agents_list kecuali entri tersebut dikonfigurasi secara eksplisit dengan agents.list[].runtime.type="acp"; jika tidak, gunakan runtime subagen default. Ketika agen OpenClaw dikonfigurasi dengan runtime.type="acp", OpenClaw menggunakan runtime.acp.agent sebagai ID harness yang mendasarinya.

• --bind here dan --thread ... bersifat saling eksklusif.
• --bind here hanya berfungsi pada channel yang menawarkan pengikatan percakapan saat ini; jika tidak, OpenClaw mengembalikan pesan yang jelas bahwa fitur tidak didukung. Pengikatan tetap bertahan setelah Gateway dimulai ulang.
• Di Discord, spawnSessions mengendalikan pembuatan thread turunan untuk --thread auto|here - bukan --bind here.
• Jika Anda melakukan spawn ke agen ACP lain tanpa --cwd, secara default OpenClaw mewarisi ruang kerja agen target. Jalur warisan yang tidak ada (ENOENT/ENOTDIR) menggunakan default backend sebagai fallback; kesalahan akses lain (misalnya EACCES) ditampilkan sebagai kesalahan spawn.
• Perintah pengelolaan Gateway tetap ditangani secara lokal dalam percakapan terikat - perintah /acp ... ditangani oleh OpenClaw meskipun teks lanjutan biasa dirutekan ke sesi ACP yang terikat; /status dan /unfocus juga tetap ditangani secara lokal setiap kali penanganan perintah diaktifkan untuk permukaan tersebut.

Ketika pengikatan thread diaktifkan untuk adaptor channel:

• OpenClaw mengikat thread ke sesi ACP target.
• Pesan lanjutan dalam thread tersebut dirutekan ke sesi ACP yang terikat.
• Keluaran ACP dikirim kembali ke thread yang sama.
• Kehilangan fokus/penutupan/pengarsipan/batas waktu menganggur atau kedaluwarsa karena usia maksimum akan menghapus pengikatan.
• /acp close, /acp cancel, /acp status, /status, dan /unfocus adalah perintah Gateway, bukan prompt untuk harness ACP.

Flag fitur yang diperlukan untuk ACP yang terikat ke thread:

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

Dukungan pengikatan thread bergantung pada adaptor. Jika adaptor channel aktif tidak mendukung pengikatan thread, OpenClaw mengembalikan pesan yang jelas bahwa fitur tidak didukung/tidak tersedia.

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

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

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

Pesan lanjutan dalam percakapan terikat dirutekan langsung ke sesi ACP, dan keluaran ACP dikirimkan kembali ke kanal/utas/topik yang sama.

Yang dikirim OpenClaw ke harness:

• Tindak lanjut terikat normal dikirim sebagai teks prompt, beserta lampiran hanya jika harness/backend mendukungnya.
• Perintah pengelolaan /acp dan perintah Gateway lokal dicegat sebelum pengiriman ACP.
• Peristiwa penyelesaian yang dihasilkan runtime diwujudkan untuk setiap target. Agen OpenClaw menerima envelope konteks runtime internal OpenClaw; harness ACP eksternal menerima prompt biasa berisi hasil turunan dan instruksi. Envelope mentah <<&lt;BEGIN_OPENCLAW_INTERNAL_CONTEXT&gt;>> tidak boleh dikirim ke harness eksternal atau disimpan 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 percakapan yang ditulis oleh pengguna.

Sesi ACP sekali jalan yang dibuat oleh eksekusi agen lain merupakan turunan latar belakang, serupa dengan subagen:

• Induk meminta pekerjaan dengan sessions_spawn({ runtime: "acp", mode: "run" }).
• Turunan berjalan dalam sesi harness ACP-nya sendiri.
• Giliran turunan berjalan pada jalur latar belakang yang sama dengan yang digunakan oleh pembuatan subagen native, sehingga harness ACP yang lambat tidak memblokir pekerjaan sesi utama yang tidak terkait.
• Penyelesaian dilaporkan kembali melalui jalur pengumuman penyelesaian tugas. OpenClaw mengubah metadata penyelesaian internal menjadi prompt ACP biasa sebelum mengirimkannya ke harness eksternal, sehingga harness tidak melihat penanda konteks runtime yang hanya digunakan OpenClaw.
• Induk menulis ulang hasil turunan dengan gaya asisten normal ketika balasan yang ditujukan kepada pengguna berguna.

Jangan perlakukan jalur ini sebagai percakapan antarrekan antara induk dan turunan. Turunan sudah memiliki saluran penyelesaian kembali ke induk.

sessions_send dapat menargetkan sesi lain setelah pembuatan. Untuk sesi rekan normal, OpenClaw menggunakan jalur tindak lanjut agen-ke-agen (A2A) setelah menyuntikkan pesan:

• Tunggu balasan sesi target.
• Secara opsional, izinkan peminta dan target bertukar sejumlah giliran tindak lanjut yang dibatasi.
• Minta target untuk menghasilkan pesan pengumuman.
• Kirim pengumuman tersebut ke saluran atau utas yang terlihat.

Jalur A2A tersebut merupakan fallback untuk pengiriman ke rekan ketika pengirim memerlukan tindak lanjut yang terlihat. Jalur ini tetap aktif ketika sesi yang tidak terkait dapat melihat dan mengirim pesan ke target ACP, misalnya dalam pengaturan tools.sessions.visibility yang luas.

OpenClaw hanya melewati tindak lanjut A2A ketika peminta merupakan induk dari turunan ACP sekali jalan miliknya sendiri. Dalam kasus tersebut, menjalankan A2A di atas penyelesaian tugas dapat membangunkan induk dengan hasil turunan, meneruskan balasan induk kembali ke turunan, dan membuat loop gema induk/turunan. Hasil sessions_send melaporkan delivery.status="skipped" untuk kasus turunan milik induk 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 agen melanjutkan dengan konteks lengkap dari percakapan sebelumnya.

{  "task": "Lanjutkan dari bagian terakhir - perbaiki kegagalan pengujian yang tersisa",  "runtime": "acp",  "agentId": "codex",  "resumeSessionId": "<previous-session-id>"}

Kasus penggunaan umum:

• Alihkan sesi Codex dari laptop ke ponsel Anda—minta agen melanjutkan dari bagian terakhir.
• Lanjutkan sesi pemrograman yang Anda mulai secara interaktif di CLI, kini tanpa antarmuka melalui agen Anda.
• Lanjutkan pekerjaan yang terputus akibat Gateway dimulai ulang atau batas waktu tidak aktif.

Catatan:

• resumeSessionId hanya berlaku ketika runtime: "acp"; runtime subagen default mengabaikan bidang khusus ACP ini.
• streamTo hanya berlaku ketika runtime: "acp"; runtime subagen default mengabaikan bidang khusus ACP ini.
• resumeSessionId adalah ID pelanjutan ACP/harness lokal host, bukan kunci sesi saluran OpenClaw; OpenClaw tetap memeriksa kebijakan pembuatan ACP dan kebijakan agen target sebelum pengiriman, sedangkan backend atau harness ACP memiliki otorisasi untuk memuat ID upstream tersebut.
• resumeSessionId memulihkan riwayat percakapan ACP upstream; thread dan mode tetap berlaku secara normal pada 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, pembuatan gagal dengan galat yang jelas—tidak ada fallback diam-diam ke sesi baru.

Setelah deployment Gateway, jalankan pemeriksaan langsung menyeluruh, bukan hanya memercayai pengujian unit:

1. Verifikasi versi dan commit Gateway yang diterapkan pada host target.
2. Buka sesi jembatan ACPX sementara ke agen aktif.
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 yang nyata, dan tidak adanya galat validator.
5. Bersihkan sesi jembatan sementara.

Pertahankan gate pada mode: "run" dan lewati streamTo: "parent"— mode: "session" yang terikat utas dan jalur relay stream merupakan tahap integrasi lebih lengkap yang terpisah.