Agen ACP

• Jika plugins.allow diatur, itu adalah inventaris Plugin yang membatasi dan harus mencakup acpx; jika tidak, backend ACP yang dipasang sengaja diblokir dan /acp doctor melaporkan entri allowlist yang hilang.
• Adapter ACP Codex dipersiapkan dengan Plugin acpx dan diluncurkan secara lokal bila memungkinkan.
• Adapter harness target lain mungkin masih diambil sesuai permintaan dengan npx saat pertama kali Anda menggunakannya.
• Autentikasi vendor tetap harus ada di host untuk harness tersebut.
• Jika host tidak memiliki npm atau akses jaringan, pengambilan adapter pertama kali akan gagal sampai cache dipanaskan lebih dulu atau adapter dipasang dengan cara lain.

ACP meluncurkan proses harness eksternal nyata. 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 allowlist tersebut diatur.
• Perintah harness dapat dimulai di 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 pekerjaan. Sesi noninteraktif tidak dapat mengeklik prompt izin native, jadi proses pengodean yang banyak menulis/mengeksekusi biasanya memerlukan profil izin ACPX yang dapat berjalan tanpa pengawasan.

• 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 melewati notifier tugas induk, bukan bertindak seperti sesi chat normal yang menghadap pengguna.
• Pemeliharaan tugas menutup sesi ACP one-shot yang terminal atau yatim dan dimiliki induk. Sesi ACP persisten dipertahankan selama pengikatan percakapan aktif masih ada; sesi persisten kedaluwarsa tanpa pengikatan aktif ditutup agar tidak dapat dilanjutkan diam-diam setelah tugas pemilik selesai atau catatan tugasnya hilang.
• Pesan tindak lanjut terikat langsung menuju sesi ACP sampai pengikatan 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; itu tidak menghapus metadata pengikatan atau sesi.
• close mengakhiri sesi ACP dari sudut pandang OpenClaw dan menghapus pengikatan. Harness mungkin masih mempertahankan riwayat upstream-nya sendiri jika mendukung resume.
• Worker runtime idle dapat dibersihkan setelah acp.runtime.ttlMinutes; metadata sesi yang disimpan tetap tersedia untuk /acp sessions.

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

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

Pengikatan percakapan Codex native adalah jalur kontrol chat default. Alat dinamis OpenClaw tetap dieksekusi melalui OpenClaw, sedangkan alat native Codex seperti shell/apply-patch dieksekusi di dalam Codex. Untuk peristiwa alat native Codex, 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 diteruskan ke OpenClaw before_agent_finalize, tempat Plugin dapat meminta satu lintasan model lagi sebelum Codex memfinalisasi jawabannya. Relay tetap sengaja konservatif: ia tidak memutasi argumen alat native Codex atau menulis ulang catatan thread Codex. Gunakan ACP eksplisit hanya saat Anda menginginkan model runtime/sesi ACP. Batas dukungan Codex tertanam didokumentasikan dalam Kontrak dukungan harness Codex v1.

• openai-codex/* - rute OAuth/langganan PI Codex.
• openai/* plus agentRuntime.id: "codex" - runtime tersemat app-server Codex native.
• /codex ... - kontrol percakapan Codex native.
• /acp ... or runtime: "acp" - kontrol ACP/acpx eksplisit.

Pemicu yang harus diarahkan ke runtime ACP:

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

OpenClaw memilih runtime: "acp", menyelesaikan harness agentId, mengikat ke percakapan atau thread saat ini jika didukung, dan mengarahkan tindak lanjut ke sesi itu 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 otomatis thread ACP 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 agent konfigurasi OpenClaw normal dari agents_list kecuali entri itu dikonfigurasi secara eksplisit dengan agents.list[].runtime.type="acp"; jika tidak, gunakan runtime sub-agent default. Saat agent 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 channel yang mengiklankan pengikatan percakapan saat ini; OpenClaw mengembalikan pesan tidak didukung yang jelas jika tidak. Pengikatan bertahan melewati restart gateway.
• Di Discord, spawnSessions membatasi pembuatan thread anak untuk --thread auto|here - bukan --bind here.
• Jika Anda melakukan spawn ke agent ACP berbeda tanpa --cwd, OpenClaw mewarisi workspace agent target secara default. Jalur warisan yang hilang (ENOENT/ENOTDIR) fallback ke default backend; error akses lain (mis. EACCES) muncul sebagai error spawn.
• Perintah manajemen Gateway tetap lokal dalam percakapan terikat - perintah /acp ... ditangani oleh OpenClaw bahkan saat teks tindak lanjut normal diarahkan ke sesi ACP terikat; /status dan /unfocus juga tetap lokal kapan pun penanganan perintah diaktifkan untuk permukaan tersebut.

Saat pengikatan thread diaktifkan untuk adapter channel:

• OpenClaw mengikat thread ke sesi ACP target.
• Pesan tindak lanjut dalam thread itu diarahkan ke sesi ACP terikat.
• Output ACP dikirim kembali ke thread yang sama.
• Unfocus/close/archive/idle-timeout atau kedaluwarsa max-age menghapus pengikatan.
• /acp close, /acp cancel, /acp status, /status, dan /unfocus adalah perintah Gateway, bukan prompt ke harness ACP.

Feature flag yang diperlukan untuk ACP terikat thread:

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

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

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

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

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

Pesan lanjutan dalam percakapan terikat dirutekan langsung ke sesi ACP, dan output ACP dikirim kembali ke channel/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 dispatch ACP.
• Peristiwa penyelesaian yang dihasilkan runtime diwujudkan per target. Agent OpenClaw mendapatkan envelope runtime-context internal OpenClaw; harness ACP eksternal mendapatkan prompt polos dengan hasil child dan instruksi. Envelope 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 pengguna atau prompt penyelesaian polos. Metadata peristiwa internal tetap terstruktur di OpenClaw jika memungkinkan dan tidak diperlakukan sebagai konten chat yang ditulis pengguna.

Sesi ACP sekali jalan yang di-spawn oleh run agent lain adalah child latar belakang, mirip dengan sub-agent:

• Parent meminta pekerjaan dengan sessions_spawn({ runtime: "acp", mode: "run" }).
• Child berjalan dalam sesi harness ACP sendiri.
• Giliran child berjalan pada lane latar belakang yang sama yang digunakan oleh spawn sub-agent native, sehingga harness ACP yang lambat tidak memblokir pekerjaan sesi utama yang tidak terkait.
• Laporan penyelesaian kembali melalui jalur pengumuman task-completion. OpenClaw mengonversi metadata penyelesaian internal menjadi prompt ACP polos sebelum mengirimnya ke harness eksternal, sehingga harness tidak melihat marker konteks runtime khusus OpenClaw.
• Parent menulis ulang hasil child dengan suara asisten normal saat balasan yang terlihat pengguna berguna.

Jangan perlakukan jalur ini sebagai chat peer-to-peer antara parent dan child. Child sudah memiliki channel penyelesaian kembali ke parent.

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

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

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

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

Gunakan resumeSessionId untuk melanjutkan sesi ACP sebelumnya alih-alih memulai dari awal. Agent 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 agent Anda untuk melanjutkan dari tempat Anda berhenti.
• Lanjutkan sesi coding yang Anda mulai secara interaktif di CLI, sekarang secara headless melalui agent Anda.
• Lanjutkan pekerjaan yang terputus oleh restart gateway atau timeout idle.

Catatan:

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

Setelah deploy gateway, jalankan pemeriksaan end-to-end live alih-alih memercayai pengujian unit:

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

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