agen ACP

• Jika plugins.allow ditetapkan, nilainya menjadi inventaris Plugin yang membatasi dan harus menyertakan acpx; jika tidak, backend ACP yang terpasang sengaja diblokir (/acp doctor melaporkan entri daftar izin yang tidak ada).
• Adaptor Codex ACP disertakan bersama Plugin acpx dan diluncurkan 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 hos; autentikasi, notifikasi, dan kait tetap hanya berada dalam konfigurasi hos.
• Adaptor lingkungan eksekusi target lain dapat diambil sesuai permintaan dengan npx saat pertama kali digunakan.
• Autentikasi vendor harus sudah tersedia pada hos untuk lingkungan eksekusi tersebut.
• Jika hos tidak memiliki npm atau akses jaringan, pengambilan adaptor saat penggunaan pertama akan gagal hingga tembolok dipanaskan sebelumnya atau adaptor dipasang dengan cara lain.

ACP meluncurkan proses lingkungan eksekusi eksternal yang sebenarnya. OpenClaw menangani perutean, status tugas latar belakang, pengiriman, ikatan, dan kebijakan; lingkungan eksekusi menangani proses masuk penyedia, katalog model, perilaku sistem berkas, dan alat natifnya.

Sebelum menyalahkan OpenClaw, pastikan:

• /acp doctor melaporkan backend yang aktif dan sehat.
• ID target diizinkan oleh acp.allowedAgents ketika daftar izin tersebut ditetapkan.
• Perintah lingkungan eksekusi dapat dimulai pada hos Gateway.
• Autentikasi penyedia tersedia untuk lingkungan eksekusi tersebut (claude, codex, gemini, opencode, droid, dan sebagainya).
• Model yang dipilih tersedia untuk lingkungan eksekusi tersebut—ID model tidak dapat dipindahkan antarlingkungan eksekusi.
• cwd yang diminta tersedia dan dapat diakses, atau hilangkan cwd dan biarkan backend menggunakan nilai bawaannya.
• Mode izin sesuai dengan pekerjaan. Sesi noninteraktif tidak dapat mengeklik permintaan izin natif, sehingga proses pengodean yang banyak melakukan penulisan/eksekusi biasanya memerlukan profil izin ACPX yang dapat berjalan tanpa antarmuka interaktif.

• Peluncuran membuat atau melanjutkan sesi runtime ACP, mencatat metadata ACP dalam penyimpanan sesi OpenClaw, dan dapat membuat tugas latar belakang ketika proses dimiliki induk.
• Sesi ACP yang dimiliki induk diperlakukan sebagai pekerjaan latar belakang bahkan ketika sesi runtime bersifat persisten; penyelesaian dan pengiriman lintas permukaan dilakukan melalui pemberi notifikasi tugas induk, bukan bertindak seperti sesi obrolan normal yang terlihat oleh pengguna.
• Pemeliharaan tugas menutup sesi ACP sekali jalan yang terminal atau yatim dan dimiliki induk. Sesi ACP persisten dipertahankan selama ikatan percakapan aktif masih ada; sesi persisten kedaluwarsa tanpa ikatan 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 ikatan ditutup, kehilangan fokus, diatur ulang, atau kedaluwarsa.
• Perintah Gateway tetap diproses secara lokal. /acp ..., /status, dan /unfocus tidak pernah dikirim sebagai teks perintah biasa ke lingkungan eksekusi ACP yang terikat.
• cancel membatalkan giliran aktif ketika backend mendukung pembatalan; perintah ini tidak menghapus ikatan atau metadata sesi.
• close mengakhiri sesi ACP dari sudut pandang OpenClaw dan menghapus ikatan. Lingkungan eksekusi mungkin masih 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 kedaluwarsa saat Gateway dimulai.
• Pekerja runtime yang tidak aktif dapat dibersihkan setelah acp.runtime.ttlMinutes; metadata sesi yang tersimpan tetap tersedia untuk /acp sessions.

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

• "Ikat kanal Discord ini ke Codex."
• "Hubungkan obrolan ini ke utas Codex <id>."
• "Tampilkan utas Codex, lalu ikat utas 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 lintasan model lagi sebelum Codex menyelesaikan jawabannya. Relai ini sengaja tetap konservatif: relai tidak mengubah argumen alat native Codex atau menulis ulang catatan utas Codex. Gunakan ACP eksplisit hanya jika Anda menginginkan model runtime/sesi ACP. Batas dukungan Codex tersemat didokumentasikan dalam kontrak dukungan harness Codex v1.

• referensi model Codex lama - rute model OAuth/langganan Codex lama yang diperbaiki oleh doctor.
• openai/* - runtime tersemat 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 utas, lalu pertahankan tindak lanjut dalam utas yang sama."
• "Jalankan Codex melalui ACP dalam utas latar belakang."

OpenClaw memilih runtime: "acp", menentukan agentId harness, mengikatnya ke percakapan atau utas saat ini jika didukung, dan merutekan tindak lanjut ke sesi tersebut hingga ditutup/kedaluwarsa. Codex hanya mengikuti jalur ini jika 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 otomatis utas ACP tetapi tidak menyembunyikan atau memblokir pemanggilan eksplisit sessions_spawn({ runtime: "acp" }). Ini menargetkan id harness ACP seperti codex, claude, droid, gemini, atau opencode. Jangan meneruskan id agen konfigurasi OpenClaw biasa dari agents_list kecuali entri tersebut secara eksplisit dikonfigurasi 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 ... saling eksklusif.
• --bind here hanya berfungsi pada kanal 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 mengatur pembuatan utas turunan untuk --thread auto|here - bukan --bind here.
• Jika Anda memunculkan sesi untuk agen ACP yang berbeda tanpa --cwd, OpenClaw secara default mewarisi ruang kerja agen target. Jalur warisan yang tidak ada (ENOENT/ENOTDIR) akan menggunakan default backend; kesalahan akses lainnya (misalnya EACCES) ditampilkan sebagai kesalahan pemunculan.
• Perintah pengelolaan Gateway tetap ditangani secara lokal dalam percakapan terikat - perintah /acp ... ditangani oleh OpenClaw meskipun teks tindak lanjut biasa dirutekan ke sesi ACP terikat; /status dan /unfocus juga tetap ditangani secara lokal setiap kali penanganan perintah diaktifkan untuk permukaan tersebut.

Ketika pengikatan utas diaktifkan untuk adaptor kanal:

• OpenClaw mengikat utas ke sesi ACP target.
• Pesan tindak lanjut dalam utas tersebut dirutekan ke sesi ACP terikat.
• Keluaran ACP dikirim kembali ke utas yang sama.
• Pelepasan fokus/penutupan/pengarsipan/batas waktu tidak aktif atau kedaluwarsa usia maksimum 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 terikat utas:

• acp.enabled=true
• acp.dispatch.enabled aktif secara default (atur ke false untuk menjeda pengiriman otomatis utas ACP; pemanggilan eksplisit sessions_spawn({ runtime: "acp" }) tetap berfungsi).
• Pemunculan sesi utas adaptor kanal diaktifkan (default: true):
  • Discord: channels.discord.threadBindings.spawnSessions=true
  • Telegram: channels.telegram.threadBindings.spawnSessions=true

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

• Semua adaptor kanal yang menyediakan kemampuan pengikatan sesi/utas.
• Dukungan bawaan saat ini: utas/kanal Discord, topik Telegram (topik forum dalam grup/supergrup dan topik pesan langsung).
• Kanal 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 saluran ke sesi ACP.
• bindings[].type="acp" terkonfigurasi yang persisten 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 saluran/utas/topik yang sama.

Yang dikirim OpenClaw ke harness:

• Pesan lanjutan terikat normal dikirim sebagai teks prompt, ditambah lampiran hanya jika harness/backend mendukungnya.
• Perintah pengelolaan /acp dan perintah Gateway lokal dicegat sebelum pengiriman ACP.
• Peristiwa penyelesaian yang dihasilkan runtime diwujudkan per target. Agen OpenClaw menerima pembungkus konteks runtime internal OpenClaw; harness ACP eksternal menerima prompt biasa berisi hasil turunan dan instruksi. Pembungkus 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 obrolan yang ditulis pengguna.

Sesi ACP satu kali yang dimunculkan oleh proses 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 pemunculan 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 khusus OpenClaw.
• Induk menulis ulang hasil turunan dengan gaya asisten normal jika balasan yang ditampilkan kepada pengguna bermanfaat.

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

sessions_send dapat menargetkan sesi lain setelah pemunculan. Untuk sesi rekan normal, OpenClaw menggunakan jalur lanjutan agen-ke-agen (A2A) setelah memasukkan pesan:

• Tunggu balasan sesi target.
• Secara opsional, izinkan peminta dan target bertukar sejumlah terbatas giliran lanjutan.
• Minta target menghasilkan pesan pengumuman.
• Kirimkan pengumuman tersebut ke saluran atau utas yang terlihat.

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

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

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

Kasus penggunaan umum:

• Alihkan sesi Codex dari laptop ke ponsel Anda—beri tahu agen untuk melanjutkan pekerjaan terakhir Anda.
• Lanjutkan sesi pengodean yang Anda mulai secara interaktif di CLI, kini secara headless melalui agen Anda.
• Lanjutkan pekerjaan yang terputus akibat dimulainya ulang Gateway atau batas waktu menganggur.

Catatan:

• resumeSessionId hanya berlaku ketika runtime: "acp"; runtime subagen bawaan mengabaikan bidang khusus ACP ini.
• streamTo hanya berlaku ketika runtime: "acp"; runtime subagen bawaan mengabaikan bidang khusus ACP ini.
• resumeSessionId adalah ID pelanjutan ACP/harness yang bersifat lokal pada host, bukan kunci sesi kanal OpenClaw; OpenClaw tetap memeriksa kebijakan pemunculan ACP dan kebijakan agen target sebelum mengirimkan tugas, sedangkan backend ACP atau harness menangani otorisasi untuk memuat ID upstream tersebut.
• resumeSessionId memulihkan riwayat percakapan ACP upstream; thread dan mode tetap berlaku seperti biasa 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, pemunculan gagal dengan galat yang jelas—tanpa fallback diam-diam ke sesi baru.

Setelah menerapkan Gateway, jalankan pemeriksaan langsung menyeluruh alih-alih 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 ada galat validator.
5. Bersihkan sesi jembatan sementara.

Pertahankan gerbang pada mode: "run" dan lewati streamTo: "parent"— mode: "session" yang terikat utas dan jalur relai aliran merupakan tahap integrasi terpisah yang lebih lengkap.