​

Agen ACP

​

Halaman mana yang saya butuhkan?

​

Apakah ini bekerja langsung tanpa konfigurasi tambahan?

• Instalasi baru kini dikirim dengan plugin runtime acpx terbundel yang aktif secara default.
• Plugin acpx terbundel memprioritaskan biner acpx lokal plugin yang dipatok versinya.
• Saat startup, OpenClaw memeriksa biner itu dan memperbaikinya sendiri jika diperlukan.
• Mulailah dengan /acp doctor jika Anda ingin pemeriksaan kesiapan yang cepat.

• Adaptor harness target mungkin diambil sesuai kebutuhan dengan npx saat pertama kali Anda menggunakan harness itu.
• Auth vendor tetap harus ada di host untuk harness tersebut.
• Jika host tidak memiliki akses npm/jaringan, pengambilan adaptor pertama kali dapat gagal sampai cache dipanaskan sebelumnya atau adaptor diinstal dengan cara lain.

• /acp spawn codex: OpenClaw seharusnya siap mem-bootstrap acpx, tetapi adaptor ACP Codex mungkin masih memerlukan pengambilan pertama kali.
• /acp spawn claude: cerita yang sama untuk adaptor ACP Claude, ditambah auth sisi Claude pada host tersebut.

​

Alur operator cepat

1. Spawn sebuah sesi:
   • /acp spawn codex --bind here
   • /acp spawn codex --mode persistent --thread auto
2. Bekerja di percakapan atau thread yang terikat (atau targetkan kunci sesi itu secara eksplisit).
3. Periksa status runtime:
   • /acp status
4. Sesuaikan opsi runtime sesuai kebutuhan:
   • /acp model <provider/model>
   • /acp permissions <profile>
   • /acp timeout <seconds>
5. Beri arahan pada sesi aktif tanpa mengganti konteks:
   • /acp steer tighten logging and continue
6. Hentikan pekerjaan:
   • /acp cancel (hentikan giliran saat ini), atau
   • /acp close (tutup sesi + hapus binding)

​

Mulai cepat untuk manusia

• “Ikat saluran Discord ini ke Codex.”
• “Mulai sesi Codex persisten di thread di sini dan tetap fokus.”
• “Jalankan ini sebagai sesi ACP Claude Code one-shot dan ringkas hasilnya.”
• “Ikat chat iMessage ini ke Codex dan pertahankan tindak lanjut di workspace yang sama.”
• “Gunakan Gemini CLI untuk tugas ini di thread, lalu pertahankan tindak lanjut di thread yang sama.”

1. Pilih runtime: "acp".
2. Selesaikan target harness yang diminta (agentId, misalnya codex).
3. Jika binding percakapan saat ini diminta dan saluran aktif mendukungnya, ikat sesi ACP ke percakapan tersebut.
4. Jika tidak, jika binding thread diminta dan saluran saat ini mendukungnya, ikat sesi ACP ke thread.
5. Rutekan pesan tindak lanjut yang terikat ke sesi ACP yang sama sampai di-unfocus/ditutup/kedaluwarsa.

​

ACP versus sub-agent

​

Cara ACP menjalankan Claude Code

1. Control plane sesi ACP OpenClaw
2. plugin runtime acpx terbundel
3. adaptor ACP Claude
4. mesin runtime/sesi sisi Claude

• ACP Claude adalah sesi harness dengan kontrol ACP, resume sesi, pelacakan tugas latar belakang, dan binding percakapan/thread opsional.
• CLI backend adalah runtime fallback lokal terpisah yang hanya berbasis teks. Lihat CLI Backends.

• ingin /acp spawn, sesi yang bisa di-bind, kontrol runtime, atau pekerjaan harness persisten: gunakan ACP
• ingin fallback teks lokal sederhana melalui CLI mentah: gunakan CLI backends

​

Sesi terikat

​

Binding percakapan saat ini

• OpenClaw tetap memiliki transport, auth, keamanan, dan pengiriman saluran.
• Percakapan saat ini dipasang ke kunci sesi ACP yang di-spawn.
• Pesan tindak lanjut di percakapan itu dirutekan ke sesi ACP yang sama.
• /new dan /reset mereset sesi ACP terikat yang sama di tempat.
• /acp close menutup sesi dan menghapus binding percakapan saat ini.

• --bind here mempertahankan permukaan chat yang sama. Di Discord, saluran saat ini tetap menjadi saluran saat ini.
• --bind here tetap dapat membuat sesi ACP baru jika Anda sedang melakukan spawn pekerjaan baru. Binding menempelkan sesi itu ke percakapan saat ini.
• --bind here tidak membuat thread anak Discord atau topik Telegram dengan sendirinya.
• Runtime ACP tetap dapat memiliki direktori kerja (cwd) sendiri atau workspace yang dikelola backend di disk. Workspace runtime itu terpisah dari permukaan chat dan tidak menyiratkan thread pesan baru.
• Jika Anda spawn ke agen ACP lain dan tidak memberikan --cwd, OpenClaw mewarisi workspace agen target, bukan milik peminta.
• Jika path workspace turunan itu hilang (ENOENT/ENOTDIR), OpenClaw fallback ke cwd default backend alih-alih diam-diam menggunakan tree yang salah.
• Jika workspace turunan itu ada tetapi tidak dapat diakses (misalnya EACCES), spawn mengembalikan error akses yang sebenarnya alih-alih membuang cwd.

• permukaan chat: tempat orang terus berbicara (saluran Discord, topik Telegram, chat iMessage)
• sesi ACP: status runtime Codex/Claude/Gemini tahan lama yang dirutekan oleh OpenClaw
• thread/topik anak: permukaan pesan tambahan opsional yang dibuat hanya oleh --thread ...
• workspace runtime: lokasi filesystem tempat harness berjalan (cwd, checkout repo, workspace backend)

• /acp spawn codex --bind here: pertahankan chat ini, spawn atau lampirkan sesi ACP Codex, dan rutekan pesan mendatang di sini ke sesi itu
• /acp spawn codex --thread auto: OpenClaw dapat membuat thread/topik anak dan mengikat sesi ACP di sana
• /acp spawn codex --bind here --cwd /workspace/repo: binding chat yang sama seperti di atas, tetapi Codex berjalan di /workspace/repo

• Saluran chat/pesan yang mengiklankan dukungan binding percakapan saat ini dapat menggunakan --bind here melalui jalur conversation-binding bersama.
• Saluran dengan semantik thread/topik kustom tetap dapat menyediakan kanonisasi khusus saluran di balik antarmuka bersama yang sama.
• --bind here selalu berarti “ikat percakapan saat ini di tempat”.
• Binding percakapan saat ini generik menggunakan penyimpanan binding bersama OpenClaw dan tetap bertahan setelah restart gateway normal.

• --bind here dan --thread ... saling eksklusif pada /acp spawn.
• Di Discord, --bind here mengikat saluran atau thread saat ini di tempat. spawnAcpSessions hanya diperlukan ketika OpenClaw perlu membuat thread anak untuk --thread auto|here.
• Jika saluran aktif tidak mengekspos binding ACP percakapan saat ini, OpenClaw mengembalikan pesan unsupported yang jelas.
• resume dan pertanyaan “sesi baru” adalah pertanyaan sesi ACP, bukan pertanyaan saluran. Anda dapat menggunakan kembali atau mengganti status runtime tanpa mengubah permukaan chat saat ini.

​

Sesi terikat thread

• OpenClaw mengikat thread ke sesi ACP target.
• Pesan tindak lanjut di thread itu dirutekan ke sesi ACP yang terikat.
• Output ACP dikirim kembali ke thread yang sama.
• Unfocus/tutup/arsip/idle-timeout atau kedaluwarsa max-age menghapus binding.

• acp.enabled=true
• acp.dispatch.enabled aktif secara default (set false untuk menjeda dispatch ACP)
• Feature flag spawn thread ACP adaptor saluran aktif (spesifik adaptor)
  • Discord: channels.discord.threadBindings.spawnAcpSessions=true
  • Telegram: channels.telegram.threadBindings.spawnAcpSessions=true

​

Saluran yang mendukung thread

• Adaptor saluran apa pun yang mengekspos capability binding sesi/thread.
• Dukungan bawaan saat ini:
  • thread/saluran Discord
  • topik Telegram (forum topic di grup/supergroup dan topik DM)
• Plugin saluran dapat menambahkan dukungan melalui antarmuka binding yang sama.

​

Pengaturan khusus saluran

​

Model binding

• bindings[].type="acp" menandai binding percakapan ACP persisten.
• bindings[].match mengidentifikasi percakapan target:
  • saluran atau thread Discord: match.channel="discord" + match.peer.id="<channelOrThreadId>"
  • topik forum Telegram: match.channel="telegram" + match.peer.id="<chatId>:topic:<topicId>"
  • chat DM/grup BlueBubbles: match.channel="bluebubbles" + match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"
    Pilih chat_id:* atau chat_identifier:* untuk binding grup yang stabil.
  • chat DM/grup iMessage: match.channel="imessage" + match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"
    Pilih chat_id:* untuk binding grup yang stabil.
• bindings[].agentId adalah id agen OpenClaw pemilik.
• Override ACP opsional berada di bawah bindings[].acp:
  • mode (persistent atau oneshot)
  • label
  • cwd
  • backend

​

Default runtime per agen

• agents.list[].runtime.type="acp"
• agents.list[].runtime.acp.agent (id harness, misalnya codex atau claude)
• agents.list[].runtime.acp.backend
• agents.list[].runtime.acp.mode
• agents.list[].runtime.acp.cwd

1. bindings[].acp.*
2. agents.list[].runtime.acp.*
3. default ACP global (misalnya acp.backend)

{
  agents: {
    list: [
      {
        id: "codex",
        runtime: {
          type: "acp",
          acp: {
            agent: "codex",
            backend: "acpx",
            mode: "persistent",
            cwd: "/workspace/openclaw",
          },
        },
      },
      {
        id: "claude",
        runtime: {
          type: "acp",
          acp: { agent: "claude", backend: "acpx", mode: "persistent" },
        },
      },
    ],
  },
  bindings: [
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "discord",
        accountId: "default",
        peer: { kind: "channel", id: "222222222222222222" },
      },
      acp: { label: "codex-main" },
    },
    {
      type: "acp",
      agentId: "claude",
      match: {
        channel: "telegram",
        accountId: "default",
        peer: { kind: "group", id: "-1001234567890:topic:42" },
      },
      acp: { cwd: "/workspace/repo-b" },
    },
    {
      type: "route",
      agentId: "main",
      match: { channel: "discord", accountId: "default" },
    },
    {
      type: "route",
      agentId: "main",
      match: { channel: "telegram", accountId: "default" },
    },
  ],
  channels: {
    discord: {
      guilds: {
        "111111111111111111": {
          channels: {
            "222222222222222222": { requireMention: false },
          },
        },
      },
    },
    telegram: {
      groups: {
        "-1001234567890": {
          topics: { "42": { requireMention: false } },
        },
      },
    },
  },
}

• OpenClaw memastikan sesi ACP yang dikonfigurasi ada sebelum digunakan.
• Pesan di saluran atau topik itu dirutekan ke sesi ACP yang dikonfigurasi.
• Dalam percakapan terikat, /new dan /reset mereset kunci sesi ACP yang sama di tempat.
• Binding runtime sementara (misalnya dibuat oleh alur thread-focus) tetap berlaku jika ada.
• Untuk spawn ACP lintas agen tanpa cwd eksplisit, OpenClaw mewarisi workspace agen target dari config agen.
• Path workspace turunan yang hilang fallback ke cwd default backend; kegagalan akses pada path yang ada akan muncul sebagai error spawn.

​

Memulai sesi ACP (antarmuka)

​

Dari sessions_spawn

{
  "task": "Open the repo and summarize failing tests",
  "runtime": "acp",
  "agentId": "codex",
  "thread": true,
  "mode": "session"
}

• runtime default-nya adalah subagent, jadi tetapkan runtime: "acp" secara eksplisit untuk sesi ACP.
• Jika agentId dihilangkan, OpenClaw menggunakan acp.defaultAgent jika dikonfigurasi.
• mode: "session" memerlukan thread: true agar tetap mempertahankan percakapan persisten yang terikat.

• task (wajib): prompt awal yang dikirim ke sesi ACP.
• runtime (wajib untuk ACP): harus "acp".
• agentId (opsional): id harness target ACP. Fallback ke acp.defaultAgent jika ditetapkan.
• thread (opsional, default false): minta alur binding thread jika didukung.
• mode (opsional): run (one-shot) atau session (persisten).
  • default adalah run
  • jika thread: true dan mode dihilangkan, OpenClaw dapat default ke perilaku persisten per jalur runtime
  • mode: "session" memerlukan thread: true
• cwd (opsional): direktori kerja runtime yang diminta (divalidasi oleh kebijakan backend/runtime). Jika dihilangkan, spawn ACP mewarisi workspace agen target jika dikonfigurasi; path turunan yang hilang fallback ke default backend, sedangkan error akses nyata dikembalikan.
• label (opsional): label untuk operator yang digunakan dalam teks sesi/banner.
• resumeSessionId (opsional): lanjutkan sesi ACP yang sudah ada alih-alih membuat yang baru. Agen memutar ulang riwayat percakapannya melalui session/load. Memerlukan runtime: "acp".
• streamTo (opsional): "parent" mengalirkan ringkasan progres eksekusi ACP awal kembali ke sesi peminta sebagai system event.
  • Jika tersedia, respons yang diterima mencakup streamLogPath yang menunjuk ke log JSONL bercakupan sesi (<sessionId>.acp-stream.jsonl) yang dapat Anda tail untuk riwayat relay lengkap.

​

Melanjutkan sesi yang sudah ada

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

• Serahkan sesi Codex dari laptop ke ponsel Anda — minta agen Anda untuk melanjutkan dari tempat terakhir
• Lanjutkan sesi coding yang Anda mulai secara interaktif di CLI, kini secara headless melalui agen Anda
• Lanjutkan pekerjaan yang terhenti karena restart gateway atau idle timeout

• resumeSessionId memerlukan runtime: "acp" — akan mengembalikan error jika digunakan dengan runtime sub-agent.
• resumeSessionId memulihkan riwayat percakapan ACP upstream; thread dan mode tetap berlaku normal untuk sesi OpenClaw baru yang sedang 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, spawn gagal dengan error yang jelas — tidak ada fallback diam-diam ke sesi baru.

​

Smoke test operator

1. Verifikasi versi/commit gateway yang dideploy pada host target.
2. Konfirmasikan source yang dideploy mencakup penerimaan lineage ACP di src/gateway/sessions-patch.ts (subagent:* or acp:* sessions).
3. Buka sesi bridge ACPX sementara ke agen live (misalnya razor(main) di jpclawhq).
4. Minta agen itu memanggil sessions_spawn dengan:
   • runtime: "acp"
   • agentId: "codex"
   • mode: "run"
   • task: Reply with exactly LIVE-ACP-SPAWN-OK
5. Verifikasi agen melaporkan:
   • accepted=yes
   • childSessionKey yang nyata
   • tidak ada validator error
6. Bersihkan sesi bridge ACPX sementara.

Use the sessions_spawn tool now with runtime: "acp", agentId: "codex", and mode: "run".
Set the task to: "Reply with exactly LIVE-ACP-SPAWN-OK".
Then report only: accepted=<yes/no>; childSessionKey=<value or none>; error=<exact text or none>.

• Pertahankan smoke test ini pada mode: "run" kecuali Anda memang sedang menguji sesi ACP persisten yang terikat thread.
• Jangan mensyaratkan streamTo: "parent" untuk gate dasar. Jalur itu bergantung pada capability peminta/sesi dan merupakan pemeriksaan integrasi yang terpisah.
• Perlakukan pengujian mode: "session" terikat thread sebagai lintasan integrasi kedua yang lebih kaya dari thread Discord atau topik Telegram yang nyata.

​

Kompatibilitas sandbox

• Jika sesi peminta menggunakan sandbox, spawn ACP diblokir baik untuk sessions_spawn({ runtime: "acp" }) maupun /acp spawn.
  • Error: Sandboxed sessions cannot spawn ACP sessions because runtime="acp" runs on the host. Use runtime="subagent" from sandboxed sessions.
• sessions_spawn dengan runtime: "acp" tidak mendukung sandbox: "require".
  • Error: sessions_spawn sandbox="require" is unsupported for runtime="acp" because ACP sessions run outside the sandbox. Use runtime="subagent" or sandbox="inherit".

​

Dari perintah /acp

/acp spawn codex --mode persistent --thread auto
/acp spawn codex --mode oneshot --thread off
/acp spawn codex --bind here
/acp spawn codex --thread here

• --mode persistent|oneshot
• --bind here|off
• --thread auto|here|off
• --cwd <absolute-path>
• --label <name>

​

Resolusi target sesi

1. Argumen target eksplisit (atau --session untuk /acp steer)
   • mencoba key
   • lalu session id berbentuk UUID
   • lalu label
2. Binding thread saat ini (jika percakapan/thread ini terikat ke sesi ACP)
3. Fallback sesi peminta saat ini

​

Mode bind spawn

• --bind here adalah jalur operator paling sederhana untuk “jadikan saluran atau chat ini didukung Codex.”
• --bind here tidak membuat thread anak.
• --bind here hanya tersedia pada saluran yang mengekspos dukungan binding percakapan saat ini.
• --bind dan --thread tidak dapat digabungkan dalam pemanggilan /acp spawn yang sama.

​

Mode thread spawn

• Pada permukaan non-thread binding, perilaku default secara efektif adalah off.
• Spawn terikat thread memerlukan dukungan kebijakan saluran:
  • Discord: channels.discord.threadBindings.spawnAcpSessions=true
  • Telegram: channels.telegram.threadBindings.spawnAcpSessions=true
• Gunakan --bind here ketika Anda ingin menempelkan percakapan saat ini tanpa membuat thread anak.

​

Kontrol ACP

• /acp spawn
• /acp cancel
• /acp steer
• /acp close
• /acp status
• /acp set-mode
• /acp set
• /acp cwd
• /acp permissions
• /acp timeout
• /acp model
• /acp reset-options
• /acp sessions
• /acp doctor
• /acp install

​

Buku resep perintah ACP

​

Pemetaan opsi runtime

• /acp model <id> dipetakan ke key config runtime model.
• /acp permissions <profile> dipetakan ke key config runtime approval_policy.
• /acp timeout <seconds> dipetakan ke key config runtime timeout.
• /acp cwd <path> memperbarui override cwd runtime secara langsung.
• /acp set <key> <value> adalah jalur generik.
  • Kasus khusus: key=cwd menggunakan jalur override cwd.
• /acp reset-options membersihkan semua override runtime untuk sesi target.

​

Dukungan harness acpx (saat ini)

• claude
• codex
• copilot
• cursor (Cursor CLI: cursor-agent acp)
• droid
• gemini
• iflow
• kilocode
• kimi
• kiro
• openclaw
• opencode
• pi
• qwen

​

Config yang diperlukan

{
  acp: {
    enabled: true,
    // Opsional. Default adalah true; set false untuk menjeda dispatch ACP sambil tetap mempertahankan kontrol /acp.
    dispatch: { enabled: true },
    backend: "acpx",
    defaultAgent: "codex",
    allowedAgents: [
      "claude",
      "codex",
      "copilot",
      "cursor",
      "droid",
      "gemini",
      "iflow",
      "kilocode",
      "kimi",
      "kiro",
      "openclaw",
      "opencode",
      "pi",
      "qwen",
    ],
    maxConcurrentSessions: 8,
    stream: {
      coalesceIdleMs: 300,
      maxChunkChars: 1200,
    },
    runtime: {
      ttlMinutes: 120,
    },
  },
}

{
  session: {
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0,
    },
  },
  channels: {
    discord: {
      threadBindings: {
        enabled: true,
        spawnAcpSessions: true,
      },
    },
  },
}

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

​

Penyiapan plugin untuk backend acpx

/acp doctor

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

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

/acp doctor

​

Konfigurasi perintah dan versi acpx

1. Perintah default ke node_modules/.bin/acpx lokal plugin di dalam paket plugin ACPX.
2. Versi yang diharapkan default ke pin ekstensi.
3. Startup langsung mendaftarkan backend ACP sebagai not-ready.
4. Pekerjaan ensure di latar belakang memverifikasi acpx --version.
5. Jika biner lokal plugin hilang atau tidak cocok, ia menjalankan: npm install --omit=dev --no-save acpx@<pinned> lalu memverifikasi ulang.

{
  "plugins": {
    "entries": {
      "acpx": {
        "enabled": true,
        "config": {
          "command": "../acpx/dist/cli.js",
          "expectedVersion": "any"
        }
      }
    }
  }
}

• command menerima path absolut, path relatif, atau nama perintah (acpx).
• Path relatif diselesaikan dari direktori workspace OpenClaw.
• expectedVersion: "any" menonaktifkan pencocokan versi ketat.
• Ketika command menunjuk ke biner/path kustom, auto-install lokal plugin dinonaktifkan.
• Startup OpenClaw tetap non-blocking saat pemeriksaan kesehatan backend berjalan.

​

Instalasi dependensi otomatis

​

Bridge MCP tool plugin

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

• Menyuntikkan server MCP bawaan bernama openclaw-plugin-tools ke bootstrap sesi ACPX.
• Mengekspos tool plugin yang sudah didaftarkan oleh plugin OpenClaw yang terinstal dan aktif.
• Menjaga fitur ini tetap eksplisit dan default-nya nonaktif.

• Ini memperluas permukaan tool harness ACP.
• Agen ACP mendapatkan akses hanya ke tool plugin yang sudah aktif di gateway.
• Perlakukan ini sebagai batas kepercayaan yang sama seperti membiarkan plugin tersebut mengeksekusi di OpenClaw itu sendiri.
• Tinjau plugin yang terinstal sebelum mengaktifkannya.

​

Konfigurasi timeout runtime

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

​

Konfigurasi izin

​

permissionMode

​

nonInteractivePermissions

​

Konfigurasi

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

Penting: OpenClaw saat ini default ke permissionMode=approve-reads dan nonInteractivePermissions=fail. Dalam sesi ACP non-interaktif, setiap penulisan atau exec yang memicu prompt izin dapat gagal dengan AcpRuntimeError: Permission prompt unavailable in non-interactive mode. Jika Anda perlu membatasi izin, tetapkan nonInteractivePermissions ke deny agar sesi mengalami degradasi dengan baik alih-alih crash.

​

Pemecahan masalah