acp.backend<\/code>)<\/li>\n<\/ol>\nExample:<\/p>\n
“`json5 theme={“theme”:{“light”:”min-light”,”dark”:”min-dark”}}
\n{
\n agents: {
\n list: [
\n {
\n id: “codex”,
\n runtime: {
\n type: “acp”,
\n acp: {
\n agent: “codex”,
\n backend: “acpx”,
\n mode: “persistent”,
\n cwd: “\/workspace\/openclaw”,
\n },
\n },
\n },
\n {
\n id: “claude”,
\n runtime: {
\n type: “acp”,
\n acp: { agent: “claude”, backend: “acpx”, mode: “persistent” },
\n },
\n },
\n ],
\n },
\n bindings: [
\n {
\n type: “acp”,
\n agentId: “codex”,
\n match: {
\n channel: “discord”,
\n accountId: “default”,
\n peer: { kind: “channel”, id: “222222222222222222” },
\n },
\n acp: { label: “codex-main” },
\n },
\n {
\n type: “acp”,
\n agentId: “claude”,
\n match: {
\n channel: “telegram”,
\n accountId: “default”,
\n peer: { kind: “group”, id: “-1001234567890:topic:42” },
\n },
\n acp: { cwd: “\/workspace\/repo-b” },
\n },
\n {
\n type: “route”,
\n agentId: “main”,
\n match: { channel: “discord”, accountId: “default” },
\n },
\n {
\n type: “route”,
\n agentId: “main”,
\n match: { channel: “telegram”, accountId: “default” },
\n },
\n ],
\n channels: {
\n discord: {
\n guilds: {
\n “111111111111111111”: {
\n channels: {
\n “222222222222222222”: { requireMention: false },
\n },
\n },
\n },
\n },
\n telegram: {
\n groups: {
\n “-1001234567890”: {
\n topics: { “42”: { requireMention: false } },
\n },
\n },
\n },
\n },
\n}<\/p>\n
\nBehavior:\n\n* OpenClaw ensures the configured ACP session exists before use.\n* Messages in that channel or topic route to the configured ACP session.\n* In bound conversations, `\/new` and `\/reset` reset the same ACP session key in place.\n* Temporary runtime bindings (for example created by thread-focus flows) still apply where present.\n\n## Start ACP sessions (interfaces)\n\n### From `sessions_spawn`\n\nUse `runtime: \"acp\"` to start an ACP session from an agent turn or tool call.\n\n```json theme={\"theme\":{\"light\":\"min-light\",\"dark\":\"min-dark\"}}\n{\n \"task\": \"Open the repo and summarize failing tests\",\n \"runtime\": \"acp\",\n \"agentId\": \"codex\",\n \"thread\": true,\n \"mode\": \"session\"\n}\n<\/code><\/pre>\nNotes:<\/p>\n
\nruntime<\/code> defaults to subagent<\/code>, so set runtime: \"acp\"<\/code> explicitly for ACP sessions.<\/li>\n- If
agentId<\/code> is omitted, OpenClaw uses acp.defaultAgent<\/code> when configured.<\/li>\nmode: \"session\"<\/code> requires thread: true<\/code> to keep a persistent bound conversation.<\/li>\n<\/ul>\nInterface details:<\/p>\n
\ntask<\/code> (required): initial prompt sent to the ACP session.<\/li>\nruntime<\/code> (required for ACP): must be \"acp\"<\/code>.<\/li>\nagentId<\/code> (optional): ACP target harness id. Falls back to acp.defaultAgent<\/code> if set.<\/li>\nthread<\/code> (optional, default false<\/code>): request thread binding flow where supported.<\/li>\nmode<\/code> (optional): run<\/code> (one-shot) or session<\/code> (persistent).<\/li>\n- default is
run<\/code><\/li>\n- if
thread: true<\/code> and mode omitted, OpenClaw may default to persistent behavior per runtime path<\/li>\nmode: \"session\"<\/code> requires thread: true<\/code><\/li>\ncwd<\/code> (optional): requested runtime working directory (validated by backend\/runtime policy).<\/li>\nlabel<\/code> (optional): operator-facing label used in session\/banner text.<\/li>\nresumeSessionId<\/code> (optional): resume an existing ACP session instead of creating a new one. The agent replays its conversation history via session\/load<\/code>. Requires runtime: \"acp\"<\/code>.<\/li>\nstreamTo<\/code> (optional): \"parent\"<\/code> streams initial ACP run progress summaries back to the requester session as system events.<\/li>\n- When available, accepted responses include
streamLogPath<\/code> pointing to a session-scoped JSONL log (<sessionId>.acp-stream.jsonl<\/code>) you can tail for full relay history.<\/li>\n<\/ul>\nResume an existing session<\/h3>\n
Use resumeSessionId<\/code> to continue a previous ACP session instead of starting fresh. The agent replays its conversation history via session\/load<\/code>, so it picks up with full context of what came before.<\/p>\n“`json theme={“theme”:{“light”:”min-light”,”dark”:”min-dark”}}
\n{
\n “task”: “Continue where we left off \u2014 fix the remaining test failures”,
\n “runtime”: “acp”,
\n “agentId”: “codex”,
\n “resumeSessionId”: “”
\n}<\/p>\n
\nCommon use cases:\n\n* Hand off a Codex session from your laptop to your phone \u2014 tell your agent to pick up where you left off\n* Continue a coding session you started interactively in the CLI, now headlessly through your agent\n* Pick up work that was interrupted by a gateway restart or idle timeout\n\nNotes:\n\n* `resumeSessionId` requires `runtime: \"acp\"` \u2014 returns an error if used with the sub-agent runtime.\n* `resumeSessionId` restores the upstream ACP conversation history; `thread` and `mode` still apply normally to the new OpenClaw session you are creating, so `mode: \"session\"` still requires `thread: true`.\n* The target agent must support `session\/load` (Codex and Claude Code do).\n* If the session ID isn't found, the spawn fails with a clear error \u2014 no silent fallback to a new session.\n\n### Operator smoke test\n\nUse this after a gateway deploy when you want a quick live check that ACP spawn\nis actually working end-to-end, not just passing unit tests.\n\nRecommended gate:\n\n1. Verify the deployed gateway version\/commit on the target host.\n2. Confirm the deployed source includes the ACP lineage acceptance in\n `src\/gateway\/sessions-patch.ts` (`subagent:* or acp:* sessions`).\n3. Open a temporary ACPX bridge session to a live agent (for example\n `razor(main)` on `jpclawhq`).\n4. Ask that agent to call `sessions_spawn` with:\n * `runtime: \"acp\"`\n * `agentId: \"codex\"`\n * `mode: \"run\"`\n * task: `Reply with exactly LIVE-ACP-SPAWN-OK`\n5. Verify the agent reports:\n * `accepted=yes`\n * a real `childSessionKey`\n * no validator error\n6. Clean up the temporary ACPX bridge session.\n\nExample prompt to the live agent:\n\n```text theme={\"theme\":{\"light\":\"min-light\",\"dark\":\"min-dark\"}}\nUse the sessions_spawn tool now with runtime: \"acp\", agentId: \"codex\", and mode: \"run\".\nSet the task to: \"Reply with exactly LIVE-ACP-SPAWN-OK\".\nThen report only: accepted=<yes\/no>; childSessionKey=<value or none>; error=<exact text or none>.\n<\/code><\/pre>\nNotes:<\/p>\n
\n- Keep this smoke test on
mode: \"run\"<\/code> unless you are intentionally testing
\n thread-bound persistent ACP sessions.<\/li>\n- Do not require
streamTo: \"parent\"<\/code> for the basic gate. That path depends on
\n requester\/session capabilities and is a separate integration check.<\/li>\n- Treat thread-bound
mode: \"session\"<\/code> testing as a second, richer integration
\n pass from a real Discord thread or Telegram topic.<\/li>\n<\/ul>\nSandbox compatibility<\/h2>\n
ACP sessions currently run on the host runtime, not inside the OpenClaw sandbox.<\/p>\n
Current limitations:<\/p>\n
\n- If the requester session is sandboxed, ACP spawns are blocked for both
sessions_spawn({ runtime: \"acp\" })<\/code> and \/acp spawn<\/code>.<\/li>\n- Error:
Sandboxed sessions cannot spawn ACP sessions because runtime=\"acp\" runs on the host. Use runtime=\"subagent\" from sandboxed sessions.<\/code><\/li>\nsessions_spawn<\/code> with runtime: \"acp\"<\/code> does not support sandbox: \"require\"<\/code>.<\/li>\n- Error:
sessions_spawn sandbox=\"require\" is unsupported for runtime=\"acp\" because ACP sessions run outside the sandbox. Use runtime=\"subagent\" or sandbox=\"inherit\".<\/code><\/li>\n<\/ul>\nUse runtime: \"subagent\"<\/code> when you need sandbox-enforced execution.<\/p>\nFrom \/acp<\/code> command<\/h3>\nUse \/acp spawn<\/code> for explicit operator control from chat when needed.<\/p>\n“`text theme={“theme”:{“light”:”min-light”,”dark”:”min-dark”}}
\n\/acp spawn codex –mode persistent –thread auto
\n\/acp spawn codex –mode oneshot –thread off
\n\/acp spawn codex –thread here<\/p>\n
\nKey flags:\n\n* `--mode persistent|oneshot`\n* `--thread auto|here|off`\n* `--cwd <absolute-path>`\n* `--label <name>`\n\nSee [Slash Commands](\/tools\/slash-commands).\n\n## Session target resolution\n\nMost `\/acp` actions accept an optional session target (`session-key`, `session-id`, or `session-label`).\n\nResolution order:\n\n1. Explicit target argument (or `--session` for `\/acp steer`)\n * tries key\n * then UUID-shaped session id\n * then label\n2. Current thread binding (if this conversation\/thread is bound to an ACP session)\n3. Current requester session fallback\n\nIf no target resolves, OpenClaw returns a clear error (`Unable to resolve session target: ...`).\n\n## Spawn thread modes\n\n`\/acp spawn` supports `--thread auto|here|off`.\n\n| Mode | Behavior |\n| ------ | --------------------------------------------------------------------------------------------------- |\n| `auto` | In an active thread: bind that thread. Outside a thread: create\/bind a child thread when supported. |\n| `here` | Require current active thread; fail if not in one. |\n| `off` | No binding. Session starts unbound. |\n\nNotes:\n\n* On non-thread binding surfaces, default behavior is effectively `off`.\n* Thread-bound spawn requires channel policy support:\n * Discord: `channels.discord.threadBindings.spawnAcpSessions=true`\n * Telegram: `channels.telegram.threadBindings.spawnAcpSessions=true`\n\n## ACP controls\n\nAvailable command family:\n\n* `\/acp spawn`\n* `\/acp cancel`\n* `\/acp steer`\n* `\/acp close`\n* `\/acp status`\n* `\/acp set-mode`\n* `\/acp set`\n* `\/acp cwd`\n* `\/acp permissions`\n* `\/acp timeout`\n* `\/acp model`\n* `\/acp reset-options`\n* `\/acp sessions`\n* `\/acp doctor`\n* `\/acp install`\n\n`\/acp status` shows the effective runtime options and, when available, both runtime-level and backend-level session identifiers.\n\nSome controls depend on backend capabilities. If a backend does not support a control, OpenClaw returns a clear unsupported-control error.\n\n## ACP command cookbook\n\n| Command | What it does | Example |\n| -------------------- | --------------------------------------------------------- | -------------------------------------------------------------- |\n| `\/acp spawn` | Create ACP session; optional thread bind. | `\/acp spawn codex --mode persistent --thread auto --cwd \/repo` |\n| `\/acp cancel` | Cancel in-flight turn for target session. | `\/acp cancel agent:codex:acp:<uuid>` |\n| `\/acp steer` | Send steer instruction to running session. | `\/acp steer --session support inbox prioritize failing tests` |\n| `\/acp close` | Close session and unbind thread targets. | `\/acp close` |\n| `\/acp status` | Show backend, mode, state, runtime options, capabilities. | `\/acp status` |\n| `\/acp set-mode` | Set runtime mode for target session. | `\/acp set-mode plan` |\n| `\/acp set` | Generic runtime config option write. | `\/acp set model openai\/gpt-5.2` |\n| `\/acp cwd` | Set runtime working directory override. | `\/acp cwd \/Users\/user\/Projects\/repo` |\n| `\/acp permissions` | Set approval policy profile. | `\/acp permissions strict` |\n| `\/acp timeout` | Set runtime timeout (seconds). | `\/acp timeout 120` |\n| `\/acp model` | Set runtime model override. | `\/acp model anthropic\/claude-opus-4-6` |\n| `\/acp reset-options` | Remove session runtime option overrides. | `\/acp reset-options` |\n| `\/acp sessions` | List recent ACP sessions from store. | `\/acp sessions` |\n| `\/acp doctor` | Backend health, capabilities, actionable fixes. | `\/acp doctor` |\n| `\/acp install` | Print deterministic install and enable steps. | `\/acp install` |\n\n`\/acp sessions` reads the store for the current bound or requester session. Commands that accept `session-key`, `session-id`, or `session-label` tokens resolve targets through gateway session discovery, including custom per-agent `session.store` roots.\n\n## Runtime options mapping\n\n`\/acp` has convenience commands and a generic setter.\n\nEquivalent operations:\n\n* `\/acp model <id>` maps to runtime config key `model`.\n* `\/acp permissions <profile>` maps to runtime config key `approval_policy`.\n* `\/acp timeout <seconds>` maps to runtime config key `timeout`.\n* `\/acp cwd <path>` updates runtime cwd override directly.\n* `\/acp set <key> <value>` is the generic path.\n * Special case: `key=cwd` uses the cwd override path.\n* `\/acp reset-options` clears all runtime overrides for target session.\n\n## acpx harness support (current)\n\nCurrent acpx built-in harness aliases:\n\n* `pi`\n* `claude`\n* `codex`\n* `opencode`\n* `gemini`\n* `kimi`\n\nWhen OpenClaw uses the acpx backend, prefer these values for `agentId` unless your acpx config defines custom agent aliases.\n\nDirect acpx CLI usage can also target arbitrary adapters via `--agent <command>`, but that raw escape hatch is an acpx CLI feature (not the normal OpenClaw `agentId` path).\n\n## Required config\n\nCore ACP baseline:\n\n```json5 theme={\"theme\":{\"light\":\"min-light\",\"dark\":\"min-dark\"}}\n{\n acp: {\n enabled: true,\n \/\/ Optional. Default is true; set false to pause ACP dispatch while keeping \/acp controls.\n dispatch: { enabled: true },\n backend: \"acpx\",\n defaultAgent: \"codex\",\n allowedAgents: [\"pi\", \"claude\", \"codex\", \"opencode\", \"gemini\", \"kimi\"],\n maxConcurrentSessions: 8,\n stream: {\n coalesceIdleMs: 300,\n maxChunkChars: 1200,\n },\n runtime: {\n ttlMinutes: 120,\n },\n },\n}\n<\/code><\/pre>\nThread binding config is channel-adapter specific. Example for Discord:<\/p>\n
“`json5 theme={“theme”:{“light”:”min-light”,”dark”:”min-dark”}}
\n{
\n session: {
\n threadBindings: {
\n enabled: true,
\n idleHours: 24,
\n maxAgeHours: 0,
\n },
\n },
\n channels: {
\n discord: {
\n threadBindings: {
\n enabled: true,
\n spawnAcpSessions: true,
\n },
\n },
\n },
\n}<\/p>\n
\nIf thread-bound ACP spawn does not work, verify the adapter feature flag first:\n\n* Discord: `channels.discord.threadBindings.spawnAcpSessions=true`\n\nSee [Configuration Reference](\/gateway\/configuration-reference).\n\n## Plugin setup for acpx backend\n\nInstall and enable plugin:\n\n```bash theme={\"theme\":{\"light\":\"min-light\",\"dark\":\"min-dark\"}}\nopenclaw plugins install acpx\nopenclaw config set plugins.entries.acpx.enabled true\n<\/code><\/pre>\nLocal workspace install during development:<\/p>\n
“`bash theme={“theme”:{“light”:”min-light”,”dark”:”min-dark”}}
\nopenclaw plugins install .\/extensions\/acpx<\/p>\n
\nThen verify backend health:\n\n```text theme={\"theme\":{\"light\":\"min-light\",\"dark\":\"min-dark\"}}\n\/acp doctor\n<\/code><\/pre>\nacpx command and version configuration<\/h3>\n
By default, the acpx plugin (published as @openclaw\/acpx<\/code>) uses the plugin-local pinned binary:<\/p>\n\n- Command defaults to
extensions\/acpx\/node_modules\/.bin\/acpx<\/code>.<\/li>\n- Expected version defaults to the extension pin.<\/li>\n
- Startup registers ACP backend immediately as not-ready.<\/li>\n
- A background ensure job verifies
acpx --version<\/code>.<\/li>\n- If the plugin-local binary is missing or mismatched, it runs:
\n npm install --omit=dev --no-save acpx@<pinned><\/code> and re-verifies.<\/li>\n<\/ol>\nYou can override command\/version in plugin config:<\/p>\n
“`json theme={“theme”:{“light”:”min-light”,”dark”:”min-dark”}}
\n{
\n “plugins”: {
\n “entries”: {
\n “acpx”: {
\n “enabled”: true,
\n “config”: {
\n “command”: “..\/acpx\/dist\/cli.js”,
\n “expectedVersion”: “any”
\n }
\n }
\n }
\n }
\n}<\/p>\n
\nNotes:\n\n* `command` accepts an absolute path, relative path, or command name (`acpx`).\n* Relative paths resolve from OpenClaw workspace directory.\n* `expectedVersion: \"any\"` disables strict version matching.\n* When `command` points to a custom binary\/path, plugin-local auto-install is disabled.\n* OpenClaw startup remains non-blocking while the backend health check runs.\n\nSee [Plugins](\/tools\/plugin).\n\n## Permission configuration\n\nACP sessions run non-interactively \u2014 there is no TTY to approve or deny file-write and shell-exec permission prompts. The acpx plugin provides two config keys that control how permissions are handled:\n\n### `permissionMode`\n\nControls which operations the harness agent can perform without prompting.\n\n| Value | Behavior |\n| --------------- | --------------------------------------------------------- |\n| `approve-all` | Auto-approve all file writes and shell commands. |\n| `approve-reads` | Auto-approve reads only; writes and exec require prompts. |\n| `deny-all` | Deny all permission prompts. |\n\n### `nonInteractivePermissions`\n\nControls what happens when a permission prompt would be shown but no interactive TTY is available (which is always the case for ACP sessions).\n\n| Value | Behavior |\n| ------ | ----------------------------------------------------------------- |\n| `fail` | Abort the session with `AcpRuntimeError`. **(default)** |\n| `deny` | Silently deny the permission and continue (graceful degradation). |\n\n### Configuration\n\nSet via plugin config:\n\n```bash theme={\"theme\":{\"light\":\"min-light\",\"dark\":\"min-dark\"}}\nopenclaw config set plugins.entries.acpx.config.permissionMode approve-all\nopenclaw config set plugins.entries.acpx.config.nonInteractivePermissions fail\n<\/code><\/pre>\nRestart the gateway after changing these values.<\/p>\n
\nImportant:<\/strong> OpenClaw currently defaults to permissionMode=approve-reads<\/code> and nonInteractivePermissions=fail<\/code>. In non-interactive ACP sessions, any write or exec that triggers a permission prompt can fail with AcpRuntimeError: Permission prompt unavailable in non-interactive mode<\/code>.<\/p>\nIf you need to restrict permissions, set nonInteractivePermissions<\/code> to deny<\/code> so sessions degrade gracefully instead of crashing.<\/p>\n<\/blockquote>\nTroubleshooting<\/h2>\n
\n\n\n| Symptom<\/th>\n | Likely cause<\/th>\n | Fix<\/th>\n<\/tr>\n<\/thead>\n |
\n\nACP runtime backend is not configured<\/code><\/td>\n| Backend plugin missing or disabled.<\/td>\n | Install and enable backend plugin, then run \/acp doctor<\/code>.<\/td>\n<\/tr>\n\nACP is disabled by policy (acp.enabled=false)<\/code><\/td>\n| ACP globally disabled.<\/td>\n | Set acp.enabled=true<\/code>.<\/td>\n<\/tr>\n\nACP dispatch is disabled by policy (acp.dispatch.enabled=false)<\/code><\/td>\n| Dispatch from normal thread messages disabled.<\/td>\n | Set acp.dispatch.enabled=true<\/code>.<\/td>\n<\/tr>\n\nACP agent \"<id>\" is not allowed by policy<\/code><\/td>\n| Agent not in allowlist.<\/td>\n | Use allowed agentId<\/code> or update acp.allowedAgents<\/code>.<\/td>\n<\/tr>\n\nUnable to resolve session target: ...<\/code><\/td>\n| Bad key\/id\/label token.<\/td>\n | Run \/acp sessions<\/code>, copy exact key\/label, retry.<\/td>\n<\/tr>\n\n--thread here requires running \/acp spawn inside an active ... thread<\/code><\/td>\n--thread here<\/code> used outside a thread context.<\/td>\nMove to target thread or use --thread auto<\/code>\/off<\/code>.<\/td>\n<\/tr>\n | | | | | | | | | | | | |