Agen ACP — penyiapan

Untuk ikhtisar, panduan operasional operator, dan konsep, lihat agen ACP.

Halaman ini membahas konfigurasi harness acpx, penyiapan plugin untuk jembatan MCP, dan konfigurasi izin.

Gunakan halaman ini hanya saat Anda menyiapkan rute ACP/acpx. Untuk konfigurasi runtime app-server Codex native, gunakan harness Codex. Untuk kunci API OpenAI atau konfigurasi penyedia model OAuth Codex, gunakan OpenAI.

Codex memiliki dua rute OpenClaw:

Utamakan rute native kecuali Anda secara eksplisit memerlukan perilaku ACP/acpx.

Dukungan harness acpx (saat ini)

Alias harness acpx bawaan (dari dependensi acpx yang versinya disematkan):

factory-droid dan factorydroid juga diresolusikan ke adaptor droid bawaan.

Saat OpenClaw menggunakan backend acpx, utamakan nilai-nilai ini untuk agentId, kecuali konfigurasi acpx Anda mendefinisikan alias agen khusus. Jika instalasi Cursor lokal Anda masih menyediakan ACP sebagai agent acp, timpa perintah agen cursor dalam konfigurasi acpx Anda alih-alih mengubah nilai default bawaan.

Penggunaan CLI acpx secara langsung juga dapat menargetkan adaptor arbitrer melalui --agent <command>, tetapi mekanisme akses langsung tersebut merupakan fitur CLI acpx (bukan jalur agentId OpenClaw yang normal).

Kontrol model bergantung pada kemampuan adaptor. Referensi model ACP Codex dinormalisasi oleh OpenClaw sebelum dimulai. Harness lain memerlukan dukungan models ACP beserta session/set_model; jika suatu harness tidak menyediakan kemampuan ACP tersebut maupun flag model saat dimulai miliknya sendiri, OpenClaw/acpx tidak dapat memaksakan pemilihan model.

Konfigurasi wajib

Dasar ACP inti:

{  acp: {    enabled: true,    // Opsional. Nilai default adalah true; atur ke false untuk menjeda pengiriman ACP sambil mempertahankan kontrol /acp.    dispatch: { enabled: true },    backend: "acpx",    defaultAgent: "codex",    allowedAgents: [      "claude",      "codex",      "copilot",      "cursor",      "droid",      "gemini",      "iflow",      "kilocode",      "kimi",      "kiro",      "openclaw",      "opencode",      "qwen",    ],    maxConcurrentSessions: 8,    stream: {      // Nilai default adalah coalesceIdleMs: 350, maxChunkChars: 1800; ditampilkan secara eksplisit di sini.      coalesceIdleMs: 350,      maxChunkChars: 1800,    },    runtime: {      ttlMinutes: 120,    },  },}

Konfigurasi pengikatan utas bersifat khusus untuk adaptor kanal. Contoh untuk Discord:

{  session: {    threadBindings: {      enabled: true,      idleHours: 24,      maxAgeHours: 0,    },  },  channels: {    discord: {      threadBindings: {        enabled: true,        // Nilai default sudah true; ditampilkan secara eksplisit di sini.        spawnSessions: true,      },    },  },}

Jika pembuatan ACP yang terikat utas tidak berfungsi, verifikasi flag fitur adaptor terlebih dahulu:

• Discord: channels.discord.threadBindings.spawnSessions=true

Pengikatan percakapan saat ini tidak memerlukan pembuatan utas turunan. Pengikatan ini memerlukan konteks percakapan aktif dan adaptor kanal yang menyediakan pengikatan percakapan ACP.

Lihat Referensi Konfigurasi.

Penyiapan Plugin untuk backend acpx

Instalasi dalam paket menggunakan Plugin runtime resmi @openclaw/acpx untuk ACP. Instal dan aktifkan sebelum menggunakan sesi harness ACP:

openclaw plugins install @openclaw/acpxopenclaw config set plugins.entries.acpx.enabled true

Checkout sumber juga dapat menggunakan Plugin ruang kerja lokal setelah pnpm install.

Mulai dengan:

/acp doctor

Jika Anda menonaktifkan acpx, menolaknya melalui plugins.allow / plugins.deny, atau ingin beralih kembali ke Plugin dalam paket, gunakan jalur paket eksplisit:

openclaw plugins install @openclaw/acpxopenclaw config set plugins.entries.acpx.enabled true

Instalasi ruang kerja lokal selama pengembangan:

openclaw plugins install ./path/to/local/acpx-plugin

Kemudian verifikasi kesehatan backend:

/acp doctor

Probe permulaan runtime acpx

Plugin acpx menyematkan runtime ACP secara langsung (tanpa biner atau versi acpx terpisah yang perlu dikonfigurasi). Secara default, Plugin tersebut mendaftarkan backend tertanam selama permulaan Gateway dan menunggu probe permulaan sebelum sinyal ready gateway. Atur OPENCLAW_ACPX_RUNTIME_STARTUP_PROBE=0 atau OPENCLAW_SKIP_ACPX_RUNTIME_PROBE=1 hanya untuk skrip atau lingkungan yang sengaja menonaktifkan probe permulaan. Jalankan /acp doctor untuk probe eksplisit sesuai permintaan.

Timpa perintah agen ACP individual dengan argumen terstruktur saat suatu jalur atau nilai flag harus tetap menjadi satu token argv:

{  "plugins": {    "entries": {      "acpx": {        "enabled": true,        "config": {          "agents": {            "claude": {              "command": "node",              "args": ["/path/to/custom adapter.mjs", "--verbose"]            }          }        }      }    }  }}

• agents.<id>.command adalah berkas yang dapat dieksekusi atau string perintah yang sudah ada untuk agen ACP tersebut.
• agents.<id>.args bersifat opsional. Setiap item larik diberi tanda kutip shell sebelum OpenClaw meneruskannya melalui registri string perintah acpx saat ini.

Lihat Plugin.

Pengunduhan adaptor otomatis

acpx secara otomatis mengunduh adaptor ACP (misalnya jembatan ACP Claude dan Codex) melalui npx saat pertama kali digunakan. Anda tidak perlu menginstal paket adaptor secara manual, dan tidak ada langkah pascainstalasi terpisah untuk OpenClaw itu sendiri. Jika pengunduhan atau pembuatan proses adaptor gagal, /acp doctor melaporkan kegagalan tersebut.

Jembatan MCP alat Plugin

Secara default, sesi ACPX tidak menyediakan alat yang didaftarkan Plugin OpenClaw kepada harness ACP.

Jika Anda ingin agen ACP seperti Codex atau Claude Code memanggil alat Plugin OpenClaw yang terinstal, seperti pengambilan/penyimpanan memori, aktifkan jembatan khusus:

openclaw config set plugins.entries.acpx.config.pluginToolsMcpBridge true

Fungsi konfigurasi ini:

• Menyuntikkan server MCP bawaan bernama openclaw-plugin-tools ke proses bootstrap sesi ACPX.
• Menyediakan alat Plugin yang sudah didaftarkan oleh Plugin OpenClaw yang terinstal dan aktif.
• Menjaga fitur tetap eksplisit dan nonaktif secara default.

Catatan keamanan dan kepercayaan:

• Ini memperluas cakupan alat harness ACP.
• Agen ACP hanya memperoleh akses ke alat Plugin yang sudah aktif di gateway.
• Perlakukan ini sebagai batas kepercayaan yang sama dengan mengizinkan Plugin tersebut berjalan di OpenClaw itu sendiri.
• Tinjau Plugin yang terinstal sebelum mengaktifkannya.

mcpServers khusus tetap berfungsi seperti sebelumnya. Jembatan alat Plugin bawaan merupakan kemudahan tambahan yang perlu diaktifkan secara eksplisit, bukan pengganti konfigurasi server MCP generik.

Jembatan MCP alat OpenClaw

Secara default, sesi ACPX juga tidak menyediakan alat bawaan OpenClaw melalui MCP. Aktifkan jembatan alat inti yang terpisah saat agen ACP memerlukan alat bawaan tertentu seperti cron:

openclaw config set plugins.entries.acpx.config.openClawToolsMcpBridge true

Fungsi konfigurasi ini:

• Menyuntikkan server MCP bawaan bernama openclaw-tools ke proses bootstrap sesi ACPX.
• Menyediakan alat bawaan OpenClaw tertentu. Server awal menyediakan cron.
• Menjaga penyediaan alat inti tetap eksplisit dan nonaktif secara default.

Konfigurasi batas waktu operasi runtime

Plugin acpx memberikan waktu 120 detik secara default untuk operasi permulaan dan kontrol runtime tertanam. Ini memberikan cukup waktu bagi harness yang lebih lambat seperti Gemini CLI untuk menyelesaikan permulaan dan inisialisasi ACP. Timpa nilai tersebut jika host Anda memerlukan batas operasi yang berbeda:

openclaw config set plugins.entries.acpx.config.timeoutSeconds 180

Giliran runtime menggunakan batas waktu agen/proses OpenClaw, termasuk /acp timeout. sessions_spawn tidak menerima penimpaan batas waktu per panggilan; jalur operatornya adalah agents.defaults.subagents.runTimeoutSeconds. Mulai ulang gateway setelah mengubah timeoutSeconds.

Konfigurasi agen probe kesehatan

Saat /acp doctor atau probe permulaan memeriksa backend, Plugin acpx yang disertakan memeriksa satu agen harness. Jika acp.allowedAgents diatur, nilai defaultnya adalah agen pertama yang diizinkan; jika tidak, nilai defaultnya adalah codex. Jika penerapan Anda memerlukan agen ACP yang berbeda untuk pemeriksaan kesehatan, atur agen probe secara eksplisit:

openclaw config set plugins.entries.acpx.config.probeAgent claude

Mulai ulang gateway setelah mengubah nilai ini.

Konfigurasi izin

Sesi ACP berjalan secara noninteraktif—tidak ada TTY untuk menyetujui atau menolak permintaan izin penulisan berkas dan eksekusi shell. Plugin acpx menyediakan dua kunci konfigurasi yang mengontrol cara penanganan izin:

Izin harness ACPX ini terpisah dari persetujuan eksekusi OpenClaw dan terpisah dari flag penerobosan vendor backend CLI seperti --permission-mode bypassPermissions milik Claude CLI. approve-all ACPX adalah sakelar darurat tingkat harness untuk sesi ACP.

Untuk perbandingan lebih luas antara tools.exec.mode OpenClaw, persetujuan Codex Guardian, dan izin harness ACPX, lihat Mode izin.

permissionMode

Mengontrol operasi yang dapat dilakukan agen harness tanpa meminta konfirmasi.

nonInteractivePermissions

Mengontrol apa yang terjadi ketika permintaan izin seharusnya ditampilkan tetapi TTY interaktif tidak tersedia (yang selalu terjadi pada sesi ACP).

Konfigurasi

Atur melalui konfigurasi Plugin:

openclaw config set plugins.entries.acpx.config.permissionMode approve-allopenclaw config set plugins.entries.acpx.config.nonInteractivePermissions fail

Mulai ulang Gateway setelah mengubah nilai-nilai ini.

Terkait

• Agen ACP — ikhtisar, panduan operasional, konsep
• Subagen
• Perutean multiagen