Agen ACP — penyiapan

Untuk ikhtisar, runbook operator, dan konsep, lihat agen ACP. Halaman ini membahas konfigurasi harness acpx, penyiapan plugin untuk bridge MCP, dan konfigurasi izin. Gunakan halaman ini hanya saat 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:

Rute	Konfigurasi/perintah	Halaman penyiapan
App-server Codex native	`/codex ...`, referensi agen `openai/gpt-*`	Harness Codex
Adaptor ACP Codex eksplisit	`/acp spawn codex`, `runtime: "acp", agentId: "codex"`	Halaman ini

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

Dukungan harness acpx (saat ini)

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

Alias	Membungkus
`claude`	Claude Code
`codex`	CLI Codex
`copilot`	CLI GitHub Copilot
`cursor`	CLI Cursor (`cursor-agent acp`)
`droid`	Factory Droid
`fast-agent`	fast-agent
`gemini`	CLI Gemini
`iflow`	CLI iFlow
`kilocode`	Kilocode
`kimi`	CLI Kimi
`kiro`	CLI Kiro
`mux`	Mux
`opencode`	OpenCode
`openclaw`	Bridge ACP OpenClaw (`openclaw acp` native)
`pi`	Agen Pengodean Pi
`qoder`	CLI Qoder
`qwen`	Qwen Code
`trae`	CLI Trae

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 mengekspos ACP sebagai agent acp, timpa perintah agen cursor dalam konfigurasi acpx Anda alih-alih mengubah nilai bawaan. Penggunaan langsung CLI acpx juga dapat menargetkan adaptor apa pun melalui --agent <command>, tetapi jalur keluar mentah tersebut merupakan fitur CLI acpx (bukan jalur agentId OpenClaw yang normal). Kontrol model bergantung pada kapabilitas adaptor. Referensi model ACP Codex dinormalisasi oleh OpenClaw sebelum dimulai. Harness lain memerlukan models ACP beserta dukungan session/set_model; jika harness tidak mengekspos kapabilitas ACP tersebut maupun flag model startup-nya sendiri, OpenClaw/acpx tidak dapat memaksakan pemilihan model.

Konfigurasi wajib

Baseline ACP inti:

{
  acp: {
    enabled: true,
    // Opsional. Nilai bawaan 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",
    ],
    stream: {
      deliveryMode: "live",
    },
  },
}

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 bawannya sudah true; ditampilkan secara eksplisit di sini.
        spawnSessions: true,
      },
    },
  },
}

Jika pemunculan ACP yang terikat utas tidak berfungsi, periksa flag fitur adaptor terlebih dahulu:

Discord: channels.discord.threadBindings.spawnSessions=true

Pengikatan percakapan saat ini tidak memerlukan pembuatan utas turunan. Pengikatan tersebut memerlukan konteks percakapan aktif dan adaptor kanal yang mengekspos pengikatan percakapan ACP. Lihat Referensi Konfigurasi.

Penyiapan plugin untuk backend acpx

Instalasi terpaket menggunakan plugin runtime resmi @openclaw/acpx untuk ACP. Instal dan aktifkan plugin tersebut sebelum menggunakan sesi harness ACP:

openclaw plugins install @openclaw/acpx
openclaw 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 terpaket, gunakan jalur paket eksplisit:

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

Instalasi ruang kerja lokal selama pengembangan:

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

Kemudian periksa kesehatan backend:

/acp doctor

Probe startup runtime acpx

Plugin acpx menyematkan runtime ACP secara langsung (tanpa biner atau versi acpx terpisah yang perlu dikonfigurasi). Secara default, plugin ini mendaftarkan backend tertanam selama startup Gateway dan menunggu probe startup sebelum sinyal ready gateway. Atur OPENCLAW_ACPX_RUNTIME_STARTUP_PROBE=0 atau OPENCLAW_SKIP_ACPX_RUNTIME_PROBE=1 hanya untuk skrip atau lingkungan yang secara sengaja mempertahankan probe startup tetap dinonaktifkan. Jalankan /acp doctor untuk probe eksplisit sesuai permintaan. Timpa perintah agen ACP individual dengan argumen terstruktur ketika 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 array diberi tanda kutip shell sebelum OpenClaw meneruskannya melalui registri string perintah acpx saat ini.

Lihat Plugin.

Pengunduhan adaptor otomatis

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

Bridge MCP alat plugin

Secara default, sesi ACPX tidak mengekspos alat yang didaftarkan oleh plugin OpenClaw ke harness ACP. Jika Anda ingin agen ACP seperti Codex atau Claude Code memanggil alat plugin OpenClaw yang terinstal, seperti pengambilan/penyimpanan memori, aktifkan bridge khusus:

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

Tindakan ini:

Menyuntikkan server MCP bawaan bernama openclaw-plugin-tools ke dalam bootstrap sesi ACPX.
Mengekspos alat plugin yang telah didaftarkan oleh plugin OpenClaw yang terinstal dan diaktifkan.
Meneruskan identitas sesi ACP aktif ke factory alat plugin, sehingga alat dengan cakupan agen tetap berada dalam namespace agen tersebut.
Mempertahankan fitur ini sebagai fitur eksplisit dan nonaktif secara default.

Catatan keamanan dan kepercayaan:

Ini memperluas permukaan alat harness ACP.
Agen ACP hanya mendapatkan akses ke alat plugin yang telah aktif di gateway.
Perlakukan ini sebagai batas kepercayaan yang sama seperti mengizinkan plugin tersebut dieksekusi di OpenClaw itu sendiri.
Tinjau plugin yang terinstal sebelum mengaktifkannya.

mcpServers khusus tetap berfungsi seperti sebelumnya. Bridge alat plugin bawaan merupakan kemudahan tambahan yang dapat diaktifkan, bukan pengganti konfigurasi server MCP generik.

Bridge MCP alat OpenClaw

Secara default, sesi ACPX juga tidak mengekspos alat bawaan OpenClaw melalui MCP. Aktifkan bridge alat inti terpisah ketika agen ACP memerlukan alat bawaan terpilih seperti cron:

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

Tindakan ini:

Menyuntikkan server MCP bawaan bernama openclaw-tools ke dalam bootstrap sesi ACPX.
Mengekspos alat bawaan OpenClaw terpilih. Server awal mengekspos cron.
Mempertahankan eksposur alat inti sebagai fitur eksplisit dan nonaktif secara default.

Konfigurasi batas waktu operasi runtime

Plugin acpx secara default memberikan waktu 120 detik untuk operasi startup dan kontrol runtime tertanam. Hal ini memberi harness yang lebih lambat seperti CLI Gemini cukup waktu untuk menyelesaikan startup 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 penggantian 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 startup memeriksa backend, plugin acpx yang dibundel memeriksa satu agen harness. Jika acp.allowedAgents diatur, nilai bawaannya adalah agen pertama yang diizinkan; jika tidak, nilai bawaannya adalah codex. Jika deployment 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 prompt izin penulisan berkas dan eksekusi shell. Plugin acpx menyediakan dua kunci konfigurasi yang mengontrol cara izin ditangani: Izin harness ACPX ini terpisah dari persetujuan eksekusi OpenClaw dan terpisah dari flag bypass vendor backend CLI seperti Claude CLI --permission-mode bypassPermissions. ACPX approve-all adalah sakelar darurat tingkat harness untuk sesi ACP. Untuk perbandingan yang lebih luas antara OpenClaw tools.exec.mode, persetujuan Codex Guardian, dan izin harness ACPX, lihat Mode izin.

`permissionMode`

Mengontrol operasi yang dapat dilakukan agen harness tanpa meminta konfirmasi.

Nilai	Perilaku
`approve-all`	Menyetujui otomatis semua penulisan file dan perintah shell.
`approve-reads`	Menyetujui otomatis hanya pembacaan; penulisan dan eksekusi memerlukan konfirmasi.
`deny-all`	Menolak semua permintaan izin.

`nonInteractivePermissions`

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

Nilai	Perilaku
`fail`	Menghentikan sesi dengan `PermissionPromptUnavailableError`. (bawaan)
`deny`	Menolak izin secara diam-diam dan melanjutkan (degradasi secara anggun).

Konfigurasi

Atur melalui konfigurasi Plugin:

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

Mulai ulang Gateway setelah mengubah nilai-nilai ini.

OpenClaw secara bawaan menggunakan permissionMode=approve-reads dan nonInteractivePermissions=fail. Dalam sesi ACP noninteraktif, setiap penulisan atau eksekusi yang memicu permintaan izin dapat gagal dengan PermissionPromptUnavailableError: Permission prompt unavailable in non-interactive mode.Jika Anda perlu membatasi izin, atur nonInteractivePermissions ke deny agar sesi mengalami degradasi secara anggun alih-alih mengalami crash.

Terkait

Agen ACP — ringkasan, panduan operasional operator, konsep
Subagen
Perutean multiagen

Overview

Plugins

Plugin guides

Building plugins

Skills

Automation

Tools

Agent coordination

Agen ACP — penyiapan

Dukungan harness acpx (saat ini)

Konfigurasi wajib

Penyiapan plugin untuk backend acpx

Probe startup runtime acpx

Pengunduhan adaptor otomatis

Bridge MCP alat plugin

Bridge MCP alat OpenClaw

Konfigurasi batas waktu operasi runtime

Konfigurasi agen probe kesehatan

Konfigurasi izin

`permissionMode`

`nonInteractivePermissions`

Konfigurasi

Terkait

​Dukungan harness acpx (saat ini)

​Konfigurasi wajib

​Penyiapan plugin untuk backend acpx

​Probe startup runtime acpx

​Pengunduhan adaptor otomatis

​Bridge MCP alat plugin

​Bridge MCP alat OpenClaw

​Konfigurasi batas waktu operasi runtime

​Konfigurasi agen probe kesehatan

​Konfigurasi izin

​permissionMode

​nonInteractivePermissions

​Konfigurasi

​Terkait

Dukungan harness acpx (saat ini)

Konfigurasi wajib

Penyiapan plugin untuk backend acpx

Probe startup runtime acpx

Pengunduhan adaptor otomatis

Bridge MCP alat plugin

Bridge MCP alat OpenClaw

Konfigurasi batas waktu operasi runtime

Konfigurasi agen probe kesehatan

Konfigurasi izin

`permissionMode`

`nonInteractivePermissions`

Konfigurasi

Terkait