​

Agen ACP

​

Halaman mana yang saya perlukan?

​

Apakah ini bekerja langsung tanpa penyiapan tambahan?

• Instalasi baru sekarang dikirim dengan plugin runtime acpx bawaan yang aktif secara default.
• Plugin acpx bawaan lebih memilih biner acpx yang dipatok lokal pada plugin.
• Saat startup, OpenClaw memeriksa biner tersebut dan memperbaikinya sendiri jika diperlukan.
• Mulailah dengan /acp doctor jika Anda ingin pemeriksaan kesiapan yang cepat.

• Adapter harness target dapat diambil sesuai kebutuhan dengan npx saat pertama kali Anda menggunakan harness tersebut.
• Auth vendor tetap harus ada pada host untuk harness tersebut.
• Jika host tidak memiliki akses npm/jaringan, pengambilan adapter saat pertama kali dapat gagal sampai cache dipanaskan terlebih dahulu atau adapter diinstal dengan cara lain.

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

​

Alur operator cepat

1. Spawn sesi:
   • /acp spawn codex --bind here
   • /acp spawn codex --mode persistent --thread auto
2. Bekerja di percakapan atau thread yang terikat (atau targetkan session key tersebut 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. Dorong 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

• “Bind this Discord channel to Codex.”
• “Start a persistent Codex session in a thread here and keep it focused.”
• “Run this as a one-shot Claude Code ACP session and summarize the result.”
• “Bind this iMessage chat to Codex and keep follow-ups in the same workspace.”
• “Use Gemini CLI for this task in a thread, then keep follow-ups in that same thread.”

1. Pilih runtime: "acp".
2. Resolusikan target harness yang diminta (agentId, misalnya codex).
3. Jika binding ke percakapan saat ini diminta dan channel aktif mendukungnya, ikat sesi ACP ke percakapan itu.
4. Jika tidak, bila binding thread diminta dan channel saat ini mendukungnya, ikat sesi ACP ke thread tersebut.
5. Rutekan pesan lanjutan yang terikat ke sesi ACP yang sama sampai fokus dilepas/ditutup/kedaluwarsa.

​

ACP versus sub-agen

​

Cara ACP menjalankan Claude Code

1. Control plane sesi ACP OpenClaw
2. Plugin runtime acpx bawaan
3. Adapter Claude ACP
4. Mesin runtime/sesi sisi Claude

• ACP Claude tidak sama dengan runtime fallback langsung claude-cli/....
• ACP Claude adalah sesi harness dengan kontrol ACP, resume sesi, pelacakan tugas latar belakang, dan binding percakapan/thread opsional.
• claude-cli/... adalah backend CLI lokal teks saja. Lihat Backend CLI.

• 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 backend CLI

​

Sesi terikat

​

Binding percakapan saat ini

• OpenClaw tetap memiliki transport channel, auth, keamanan, dan pengiriman.
• Percakapan saat ini dipatok ke session key ACP yang di-spawn.
• Pesan lanjutan dalam 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, channel saat ini tetap channel yang sama.
• --bind here tetap dapat membuat sesi ACP baru jika Anda sedang memulai pekerjaan baru. Binding tersebut menautkan sesi itu ke percakapan saat ini.
• --bind here tidak dengan sendirinya membuat child thread Discord atau topik Telegram.
• Runtime ACP tetap dapat memiliki working directory (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 yang berbeda dan tidak memberikan --cwd, OpenClaw mewarisi workspace agen target secara default, bukan workspace peminta.
• Jika path workspace turunan itu hilang (ENOENT/ENOTDIR), OpenClaw kembali ke cwd default backend alih-alih diam-diam memakai 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 tetap berbicara (Discord channel, Telegram topic, iMessage chat)
• sesi ACP: status runtime Codex/Claude/Gemini yang tahan lama yang menjadi tujuan routing OpenClaw
• child thread/topic: 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 hubungkan sesi ACP Codex, dan rutekan pesan mendatang di sini ke sesi itu
• /acp spawn codex --thread auto: OpenClaw dapat membuat child thread/topic 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

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

• --bind here dan --thread ... saling eksklusif pada /acp spawn.
• Di Discord, --bind here mengikat channel atau thread saat ini di tempat. spawnAcpSessions hanya diperlukan saat OpenClaw perlu membuat child thread untuk --thread auto|here.
• Jika channel aktif tidak mengekspos binding ACP percakapan saat ini, OpenClaw mengembalikan pesan unsupported yang jelas.
• Pertanyaan resume dan “new session” adalah pertanyaan sesi ACP, bukan pertanyaan channel. 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 lanjutan di thread tersebut dirutekan ke sesi ACP yang terikat.
• Output ACP dikirim kembali ke thread yang sama.
• Pelepasan fokus/penutupan/pengarsipan/timeout idle atau kedaluwarsa usia maksimum menghapus binding.

• acp.enabled=true
• acp.dispatch.enabled aktif secara default (set false untuk menjeda dispatch ACP)
• Flag spawn thread ACP adapter channel diaktifkan (spesifik adapter)
  • Discord: channels.discord.threadBindings.spawnAcpSessions=true
  • Telegram: channels.telegram.threadBindings.spawnAcpSessions=true

​

Channel yang mendukung thread

• Setiap adapter channel yang mengekspos kemampuan binding sesi/thread.
• Dukungan bawaan saat ini:
  • Thread/channel Discord
  • Topik Telegram (forum topic di grup/supergrup dan topik DM)
• Plugin channel dapat menambahkan dukungan melalui antarmuka binding yang sama.

​

Setelan khusus channel

​

Model binding

• bindings[].type="acp" menandai binding percakapan ACP persisten.
• bindings[].match mengidentifikasi percakapan target:
  • Channel 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:*>" Lebih 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:*>" Lebih pilih chat_id:* untuk binding grup yang stabil.
• bindings[].agentId adalah id agen OpenClaw pemiliknya.
• Override ACP opsional berada di 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 pada channel atau topik tersebut dirutekan ke sesi ACP yang dikonfigurasi.
• Dalam percakapan terikat, /new dan /reset mereset session key ACP yang sama di tempat.
• Binding runtime sementara (misalnya yang dibuat oleh alur fokus thread) tetap berlaku jika ada.
• Untuk spawn ACP lintas agen tanpa cwd eksplisit, OpenClaw mewarisi workspace agen target dari konfigurasi agen.
• Path workspace turunan yang hilang kembali ke cwd default backend; kegagalan akses pada path yang tidak hilang akan ditampilkan 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 ke subagent, jadi setel runtime: "acp" secara eksplisit untuk sesi ACP.
• Jika agentId dihilangkan, OpenClaw menggunakan acp.defaultAgent bila dikonfigurasi.
• mode: "session" memerlukan thread: true untuk mempertahankan percakapan terikat yang persisten.

• task (wajib): prompt awal yang dikirim ke sesi ACP.
• runtime (wajib untuk ACP): harus "acp".
• agentId (opsional): id harness ACP target. Fallback ke acp.defaultAgent jika disetel.
• thread (opsional, default false): minta alur binding thread jika didukung.
• mode (opsional): run (sekali jalan) 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): working directory runtime yang diminta (divalidasi oleh kebijakan backend/runtime). Jika dihilangkan, spawn ACP mewarisi workspace agen target bila dikonfigurasi; path turunan yang hilang akan fallback ke default backend, sedangkan error akses yang nyata dikembalikan.
• label (opsional): label yang menghadap operator dan 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 event sistem.
  • Saat tersedia, respons yang diterima mencakup streamLogPath yang menunjuk ke log JSONL berlingkup sesi (<sessionId>.acp-stream.jsonl) yang dapat Anda tail untuk riwayat relay penuh.

​

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 Anda ke ponsel — beri tahu agen Anda untuk melanjutkan dari titik terakhir
• Lanjutkan sesi coding yang Anda mulai secara interaktif di CLI, sekarang tanpa kepala melalui agen Anda
• Lanjutkan pekerjaan yang terputus oleh restart gateway atau timeout idle

• resumeSessionId memerlukan runtime: "acp" — mengembalikan error jika digunakan dengan runtime sub-agen.
• 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.
• Agen target harus mendukung session/load (Codex dan Claude Code mendukung).
• 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) pada jpclawhq).
4. Minta agen tersebut 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 error validator
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 sengaja menguji sesi ACP persisten yang terikat thread.
• Jangan mensyaratkan streamTo: "parent" untuk gate dasar. Jalur itu bergantung pada kemampuan requester/sesi dan merupakan pemeriksaan integrasi terpisah.
• Perlakukan pengujian mode: "session" yang terikat thread sebagai pass integrasi kedua yang lebih kaya dari thread Discord atau topik Telegram yang nyata.

​

Kompatibilitas sandbox

• Jika sesi peminta berada dalam sandbox, spawn ACP diblokir 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 channel atau chat ini didukung Codex.”
• --bind here tidak membuat child thread.
• --bind here hanya tersedia pada channel yang mengekspos dukungan binding percakapan saat ini.
• --bind dan --thread tidak dapat digabungkan dalam panggilan /acp spawn yang sama.

​

Mode thread spawn

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

​

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 menghapus 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

​

Konfigurasi yang diperlukan

{
  acp: {
    enabled: true,
    // Opsional. Default adalah true; set false untuk menjeda dispatch 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",
      "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. Saat startup, backend ACP langsung didaftarkan sebagai belum siap.
4. Tugas ensure latar belakang memverifikasi acpx --version.
5. Jika biner lokal plugin hilang atau tidak cocok, plugin 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 diresolusikan dari direktori workspace OpenClaw.
• expectedVersion: "any" menonaktifkan pencocokan versi ketat.
• Saat command menunjuk ke biner/path kustom, instalasi otomatis 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

• Menyisipkan 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 nonaktif secara default.

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

​

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, penulisan atau exec apa pun yang memicu prompt izin dapat gagal dengan AcpRuntimeError: Permission prompt unavailable in non-interactive mode. Jika Anda perlu membatasi izin, setel nonInteractivePermissions ke deny agar sesi mengalami degradasi secara anggun alih-alih crash.

​

Pemecahan masalah