diff --git a/docs/tools/acp-agents.md b/docs/tools/acp-agents.md index bea7cd7252e..7b0f1c82c70 100644 --- a/docs/tools/acp-agents.md +++ b/docs/tools/acp-agents.md @@ -1,62 +1,90 @@ --- -summary: "Use ACP runtime sessions for Claude Code, Cursor, Gemini CLI, explicit Codex ACP fallback, OpenClaw ACP, and other harness agents" +summary: "Run external coding harnesses (Claude Code, Cursor, Gemini CLI, explicit Codex ACP, OpenClaw ACP, OpenCode) through the ACP backend" read_when: - Running coding harnesses through ACP - Setting up conversation-bound ACP sessions on messaging channels - - Binding a message channel conversation to a persistent ACP session - - Troubleshooting ACP backend and plugin wiring - - Debugging ACP completion delivery or agent-to-agent loops + - Binding a message-channel conversation to a persistent ACP session + - Troubleshooting ACP backend, plugin wiring, or completion delivery - Operating /acp commands from chat title: "ACP agents" +sidebarTitle: "ACP agents" --- -[Agent Client Protocol (ACP)](https://agentclientprotocol.com/) sessions let OpenClaw run external coding harnesses (for example Pi, Claude Code, Cursor, Copilot, Droid, OpenClaw ACP, OpenCode, Gemini CLI, and other supported ACPX harnesses) through an ACP backend plugin. +[Agent Client Protocol (ACP)](https://agentclientprotocol.com/) sessions +let OpenClaw run external coding harnesses (for example Pi, Claude Code, +Cursor, Copilot, Droid, OpenClaw ACP, OpenCode, Gemini CLI, and other +supported ACPX harnesses) through an ACP backend plugin. -If you ask OpenClaw in plain language to bind or control Codex in the current conversation and the bundled `codex` plugin is enabled, OpenClaw should use the native Codex app-server plugin (`/codex bind`, `/codex threads`, `/codex resume`, `/codex steer`, `/codex stop`) instead of ACP. If you ask for `/acp`, ACP, acpx, or an ACP adapter test explicitly, OpenClaw can still route Codex through ACP. Each ACP session spawn is tracked as a [background task](/automation/tasks). +Each ACP session spawn is tracked as a [background task](/automation/tasks). -If you ask OpenClaw in plain language to "start Claude Code in a thread" or use another external harness, OpenClaw should route that request to the ACP runtime (not the native sub-agent runtime). - -If you want Codex or Claude Code to connect as an external MCP client directly -to existing OpenClaw channel conversations, use [`openclaw mcp serve`](/cli/mcp) -instead of ACP. - -ACP is not the default Codex path. It is the external-harness path. The native -Codex app-server plugin owns `/codex ...` controls and the + +**ACP is the external-harness path, not the default Codex path.** The +native Codex app-server plugin owns `/codex ...` controls and the `embeddedHarness.runtime: "codex"` embedded runtime; ACP owns `/acp ...` controls and `sessions_spawn({ runtime: "acp" })` sessions. +If you want Codex or Claude Code to connect as an external MCP client +directly to existing OpenClaw channel conversations, use +[`openclaw mcp serve`](/cli/mcp) instead of ACP. + + ## Which page do I want? -There are three nearby surfaces that are easy to confuse: - -| You want to... | Use this | Notes | +| You want to… | Use this | Notes | | ----------------------------------------------------------------------------------------------- | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Bind or control Codex in the current conversation | `/codex bind`, `/codex threads` | Native Codex app-server path when the `codex` plugin is enabled; includes bound chat replies, image forwarding, model/fast/permissions, stop, and steer controls. ACP is an explicit fallback | -| Run Claude Code, Gemini CLI, explicit Codex ACP, or another external harness _through_ OpenClaw | This page: ACP agents | Chat-bound sessions, `/acp spawn`, `sessions_spawn({ runtime: "acp" })`, background tasks, runtime controls | +| Run Claude Code, Gemini CLI, explicit Codex ACP, or another external harness _through_ OpenClaw | This page | Chat-bound sessions, `/acp spawn`, `sessions_spawn({ runtime: "acp" })`, background tasks, runtime controls | | Expose an OpenClaw Gateway session _as_ an ACP server for an editor or client | [`openclaw acp`](/cli/acp) | Bridge mode. IDE/client talks ACP to OpenClaw over stdio/WebSocket | | Reuse a local AI CLI as a text-only fallback model | [CLI Backends](/gateway/cli-backends) | Not ACP. No OpenClaw tools, no ACP controls, no harness runtime | ## Does this work out of the box? -Usually, yes. Fresh installs ship the bundled `acpx` runtime plugin enabled by default, with a plugin-local pinned `acpx` binary that OpenClaw probes and self-repairs on startup. Run `/acp doctor` for a readiness check. +Usually yes. Fresh installs ship the bundled `acpx` runtime plugin enabled +by default with a plugin-local pinned `acpx` binary that OpenClaw probes +and self-repairs on startup. Run `/acp doctor` for a readiness check. -OpenClaw only teaches agents about ACP spawning when ACP is truly usable: ACP -must be enabled, dispatch must not be disabled, the current session must not be -sandbox-blocked, and a runtime backend must be loaded. If those conditions are -not met, ACP plugin skills and `sessions_spawn` ACP guidance stay hidden so the -agent does not suggest an unavailable backend. +OpenClaw only teaches agents about ACP spawning when ACP is **truly +usable**: ACP must be enabled, dispatch must not be disabled, the current +session must not be sandbox-blocked, and a runtime backend must be +loaded. If those conditions are not met, ACP plugin skills and +`sessions_spawn` ACP guidance stay hidden so the agent does not suggest +an unavailable backend. -First-run gotchas: + + + - If `plugins.allow` is set, it is a restrictive plugin inventory and **must** include `acpx`; otherwise the bundled default is intentionally blocked and `/acp doctor` reports the missing allowlist entry. + - Target harness adapters (Codex, Claude, etc.) may be fetched on demand with `npx` the first time you use them. + - Vendor auth still has to exist on the host for that harness. + - If the host has no npm or network access, first-run adapter fetches fail until caches are pre-warmed or the adapter is installed another way. + + + ACP launches a real external harness process. OpenClaw owns routing, + background-task state, delivery, bindings, and policy; the harness + owns its provider login, model catalog, filesystem behavior, and + native tools. -- If `plugins.allow` is set, it is a restrictive plugin inventory and must include `acpx`; otherwise the bundled default is intentionally blocked and `/acp doctor` reports the missing allowlist entry. -- Target harness adapters (Codex, Claude, etc.) may be fetched on demand with `npx` the first time you use them. -- Vendor auth still has to exist on the host for that harness. -- If the host has no npm or network access, first-run adapter fetches fail until caches are pre-warmed or the adapter is installed another way. + Before blaming OpenClaw, verify: + + - `/acp doctor` reports an enabled, healthy backend. + - The target id is allowed by `acp.allowedAgents` when that allowlist is set. + - The harness command can start on the Gateway host. + - Provider auth is present for that harness (`claude`, `codex`, `gemini`, `opencode`, `droid`, etc.). + - The selected model exists for that harness — model ids are not portable across harnesses. + - The requested `cwd` exists and is accessible, or omit `cwd` and let the backend use its default. + - Permission mode matches the work. Non-interactive sessions cannot click native permission prompts, so write/exec-heavy coding runs usually need an ACPX permission profile that can proceed headlessly. + + + + +OpenClaw plugin tools and built-in OpenClaw tools are **not** exposed to +ACP harnesses by default. Enable the explicit MCP bridges in +[ACP agents — setup](/tools/acp-agents-setup) only when the harness +should call those tools directly. ## Supported harness targets -With the bundled `acpx` backend, use these harness ids as `/acp spawn ` or -`sessions_spawn({ runtime: "acp", agentId: "" })` targets: +With the bundled `acpx` backend, use these harness ids as `/acp spawn ` +or `sessions_spawn({ runtime: "acp", agentId: "" })` targets: | Harness id | Typical backend | Notes | | ---------- | ---------------------------------------------- | ----------------------------------------------------------------------------------- | @@ -66,121 +94,120 @@ With the bundled `acpx` backend, use these harness ids as `/acp spawn ` or | `cursor` | Cursor CLI ACP (`cursor-agent acp`) | Override the acpx command if a local install exposes a different ACP entrypoint. | | `droid` | Factory Droid CLI | Requires Factory/Droid auth or `FACTORY_API_KEY` in the harness environment. | | `gemini` | Gemini CLI ACP adapter | Requires Gemini CLI auth or API key setup. | -| `opencode` | OpenCode ACP adapter | Requires OpenCode CLI/provider auth. | -| `openclaw` | OpenClaw Gateway bridge through `openclaw acp` | Lets an ACP-aware harness talk back to an OpenClaw Gateway session. | -| `pi` | Pi/embedded OpenClaw runtime | Used for OpenClaw-native harness experiments. | | `iflow` | iFlow CLI | Adapter availability and model control depend on the installed CLI. | | `kilocode` | Kilo Code CLI | Adapter availability and model control depend on the installed CLI. | | `kimi` | Kimi/Moonshot CLI | Requires Kimi/Moonshot auth on the host. | | `kiro` | Kiro CLI | Adapter availability and model control depend on the installed CLI. | +| `opencode` | OpenCode ACP adapter | Requires OpenCode CLI/provider auth. | +| `openclaw` | OpenClaw Gateway bridge through `openclaw acp` | Lets an ACP-aware harness talk back to an OpenClaw Gateway session. | +| `pi` | Pi/embedded OpenClaw runtime | Used for OpenClaw-native harness experiments. | | `qwen` | Qwen Code / Qwen CLI | Requires Qwen-compatible auth on the host. | -Custom acpx agent aliases can be configured in acpx itself, but OpenClaw policy -still checks `acp.allowedAgents` and any `agents.list[].runtime.acp.agent` -mapping before dispatch. - -## Runtime prerequisites - -ACP launches a real external harness process. OpenClaw owns routing, -background-task state, delivery, bindings, and policy; the harness owns its -provider login, model catalog, filesystem behavior, and native tools. - -Before blaming OpenClaw, verify: - -- `/acp doctor` reports an enabled, healthy backend. -- The target id is allowed by `acp.allowedAgents` when that allowlist is set. -- The harness command can start on the Gateway host. -- Provider auth is present for that harness (`claude`, `codex`, `gemini`, - `opencode`, `droid`, etc.). -- The selected model exists for that harness. Model ids are not portable across - harnesses. -- The requested `cwd` exists and is accessible, or omit `cwd` and let the - backend use its default. -- Permission mode matches the work. Non-interactive sessions cannot click - native permission prompts, so write/exec-heavy coding runs usually need an - ACPX permission profile that can proceed headlessly. - -OpenClaw plugin tools and built-in OpenClaw tools are not exposed to ACP -harnesses by default. Enable the explicit MCP bridges in -[ACP agents — setup](/tools/acp-agents-setup) only when the harness should call -those tools directly. +Custom acpx agent aliases can be configured in acpx itself, but OpenClaw +policy still checks `acp.allowedAgents` and any +`agents.list[].runtime.acp.agent` mapping before dispatch. ## Operator runbook Quick `/acp` flow from chat: -1. **Spawn** — `/acp spawn claude --bind here`, `/acp spawn gemini --mode persistent --thread auto`, or explicit `/acp spawn codex --bind here` -2. **Work** in the bound conversation or thread (or target the session key explicitly). -3. **Check state** — `/acp status` -4. **Tune** — `/acp model `, `/acp permissions `, `/acp timeout ` -5. **Steer** without replacing context — `/acp steer tighten logging and continue` -6. **Stop** — `/acp cancel` (current turn) or `/acp close` (session + bindings) + + + `/acp spawn claude --bind here`, + `/acp spawn gemini --mode persistent --thread auto`, or explicit + `/acp spawn codex --bind here`. + + + Continue in the bound conversation or thread (or target the session + key explicitly). + + + `/acp status` + + + `/acp model `, + `/acp permissions `, + `/acp timeout `. + + + Without replacing context: `/acp steer tighten logging and continue`. + + + `/acp cancel` (current turn) or `/acp close` (session + bindings). + + -Lifecycle details: + + + - Spawn creates or resumes an ACP runtime session, records ACP metadata in the OpenClaw session store, and may create a background task when the run is parent-owned. + - Bound follow-up messages go directly to the ACP session until the binding is closed, unfocused, reset, or expired. + - Gateway commands stay local. `/acp ...`, `/status`, and `/unfocus` are never sent as normal prompt text to a bound ACP harness. + - `cancel` aborts the active turn when the backend supports cancellation; it does not delete the binding or session metadata. + - `close` ends the ACP session from OpenClaw's point of view and removes the binding. A harness may still keep its own upstream history if it supports resume. + - Idle runtime workers are eligible for cleanup after `acp.runtime.ttlMinutes`; stored session metadata remains available for `/acp sessions`. + + + Natural-language triggers that should route to the **native Codex + plugin** when it is enabled: -- Spawn creates or resumes an ACP runtime session, records ACP metadata in the - OpenClaw session store, and may create a background task when the run is - parent-owned. -- Bound follow-up messages go directly to the ACP session until the binding is - closed, unfocused, reset, or expired. -- Gateway commands stay local. `/acp ...`, `/status`, and `/unfocus` are never - sent as normal prompt text to a bound ACP harness. -- `cancel` aborts the active turn when the backend supports cancellation; it - does not delete the binding or session metadata. -- `close` ends the ACP session from OpenClaw's point of view and removes the - binding. A harness may still keep its own upstream history if it supports - resume. -- Idle runtime workers are eligible for cleanup after `acp.runtime.ttlMinutes`; - stored session metadata remains available for `/acp sessions`. + - "Bind this Discord channel to Codex." + - "Attach this chat to Codex thread ``." + - "Show Codex threads, then bind this one." -Natural-language triggers that should route to the native Codex plugin when it -is enabled: + Native Codex conversation binding is the default chat-control path. + OpenClaw dynamic tools still execute through OpenClaw, while + Codex-native tools such as shell/apply-patch execute inside Codex. + For Codex-native tool events, OpenClaw injects a per-turn native + hook relay so plugin hooks can block `before_tool_call`, observe + `after_tool_call`, and route Codex `PermissionRequest` events + through OpenClaw approvals. Codex `Stop` hooks are relayed to + OpenClaw `before_agent_finalize`, where plugins can request one more + model pass before Codex finalizes its answer. The relay remains + deliberately conservative: it does not mutate Codex-native tool + arguments or rewrite Codex thread records. Use explicit ACP only + when you want the ACP runtime/session model. The embedded Codex + support boundary is documented in the + [Codex harness v1 support contract](/plugins/codex-harness#v1-support-contract). -- "Bind this Discord channel to Codex." -- "Attach this chat to Codex thread ``." -- "Show Codex threads, then bind this one." + + + - `openai-codex/*` — PI Codex OAuth/subscription route. + - `openai/*` plus `embeddedHarness.runtime: "codex"` — native Codex app-server embedded runtime. + - `/codex ...` — native Codex conversation control. + - `/acp ...` or `runtime: "acp"` — explicit ACP/acpx control. + + + Triggers that should route to the ACP runtime: -Native Codex conversation binding is the default chat-control path. OpenClaw -dynamic tools still execute through OpenClaw, while Codex-native tools such as -shell/apply-patch execute inside Codex. For Codex-native tool events, OpenClaw -injects a per-turn native hook relay so plugin hooks can block -`before_tool_call`, observe `after_tool_call`, and route Codex -`PermissionRequest` events through OpenClaw approvals. Codex `Stop` hooks are -relayed to OpenClaw `before_agent_finalize`, where plugins can request one more -model pass before Codex finalizes its answer. The relay remains deliberately -conservative: it does not mutate Codex-native tool arguments or rewrite Codex -thread records. Use explicit ACP only when you want the ACP runtime/session -model. The embedded Codex support boundary is documented in the -[Codex harness v1 support contract](/plugins/codex-harness#v1-support-contract). + - "Run this as a one-shot Claude Code ACP session and summarize the result." + - "Use Gemini CLI for this task in a thread, then keep follow-ups in that same thread." + - "Run Codex through ACP in a background thread." -For model/provider/runtime selection, remember: + OpenClaw picks `runtime: "acp"`, resolves the harness `agentId`, + binds to the current conversation or thread when supported, and + routes follow-ups to that session until close/expiry. Codex only + follows this path when ACP/acpx is explicit or the native Codex + plugin is unavailable for the requested operation. -- `openai-codex/*` is the PI Codex OAuth/subscription route. -- `openai/*` plus `embeddedHarness.runtime: "codex"` is the native Codex - app-server embedded runtime route. -- `/codex ...` is native Codex conversation control. -- `/acp ...` or `runtime: "acp"` is explicit ACP/acpx control. + For `sessions_spawn`, `runtime: "acp"` is advertised only when ACP + is enabled, the requester is not sandboxed, and an ACP runtime + backend is loaded. It targets ACP harness ids such as `codex`, + `claude`, `droid`, `gemini`, or `opencode`. Do not pass a normal + OpenClaw config agent id from `agents_list` unless that entry is + explicitly configured with `agents.list[].runtime.type="acp"`; + otherwise use the default sub-agent runtime. When an OpenClaw agent + is configured with `runtime.type="acp"`, OpenClaw uses + `runtime.acp.agent` as the underlying harness id. -Natural-language triggers that should route to the ACP runtime: - -- "Run this as a one-shot Claude Code ACP session and summarize the result." -- "Use Gemini CLI for this task in a thread, then keep follow-ups in that same thread." -- "Run Codex through ACP in a background thread." - -OpenClaw picks `runtime: "acp"`, resolves the harness `agentId`, binds to the current conversation or thread when supported, and routes follow-ups to that session until close/expiry. Codex only follows this path when ACP/acpx is explicit or the native Codex plugin is unavailable for the requested operation. - -For `sessions_spawn`, `runtime: "acp"` is advertised only when ACP is enabled, -the requester is not sandboxed, and an ACP runtime backend is loaded. It targets -ACP harness ids such as `codex`, `claude`, `droid`, `gemini`, or `opencode`. Do not pass -a normal OpenClaw config agent id from `agents_list` unless that entry is -explicitly configured with `agents.list[].runtime.type="acp"`; otherwise use -the default sub-agent runtime. When an OpenClaw agent is configured with -`runtime.type="acp"`, OpenClaw uses `runtime.acp.agent` as the underlying -harness id. + + ## ACP versus sub-agents -Use ACP when you want an external harness runtime. Use native Codex app-server for Codex conversation binding/control when the `codex` plugin is enabled. Use sub-agents when you want OpenClaw-native delegated runs. +Use ACP when you want an external harness runtime. Use **native Codex +app-server** for Codex conversation binding/control when the `codex` +plugin is enabled. Use **sub-agents** when you want OpenClaw-native +delegated runs. | Area | ACP session | Sub-agent run | | ------------- | ------------------------------------- | ---------------------------------- | @@ -195,121 +222,138 @@ See also [Sub-agents](/tools/subagents). For Claude Code through ACP, the stack is: -1. OpenClaw ACP session control plane -2. bundled `acpx` runtime plugin -3. Claude ACP adapter -4. Claude-side runtime/session machinery +1. OpenClaw ACP session control plane. +2. Bundled `acpx` runtime plugin. +3. Claude ACP adapter. +4. Claude-side runtime/session machinery. -Important distinction: +ACP Claude is a **harness session** with ACP controls, session resume, +background-task tracking, and optional conversation/thread binding. -- ACP Claude is a harness session with ACP controls, session resume, background-task tracking, and optional conversation/thread binding. -- CLI backends are separate text-only local fallback runtimes. See [CLI Backends](/gateway/cli-backends). +CLI backends are separate text-only local fallback runtimes — see +[CLI Backends](/gateway/cli-backends). For operators, the practical rule is: -- want `/acp spawn`, bindable sessions, runtime controls, or persistent harness work: use ACP -- want simple local text fallback through the raw CLI: use CLI backends +- **Want `/acp spawn`, bindable sessions, runtime controls, or persistent harness work?** Use ACP. +- **Want simple local text fallback through the raw CLI?** Use CLI backends. ## Bound sessions +### Mental model + +- **Chat surface** — where people keep talking (Discord channel, Telegram topic, iMessage chat). +- **ACP session** — the durable Codex/Claude/Gemini runtime state OpenClaw routes to. +- **Child thread/topic** — an optional extra messaging surface created only by `--thread ...`. +- **Runtime workspace** — the filesystem location (`cwd`, repo checkout, backend workspace) where the harness runs. Independent of the chat surface. + ### Current-conversation binds -`/acp spawn --bind here` pins the current conversation to the spawned ACP session — no child thread, same chat surface. OpenClaw keeps owning transport, auth, safety, and delivery; follow-up messages in that conversation route to the same session; `/new` and `/reset` reset the session in place; `/acp close` removes the binding. - -Mental model: - -- **chat surface** — where people keep talking (Discord channel, Telegram topic, iMessage chat). -- **ACP session** — the durable Codex/Claude/Gemini runtime state OpenClaw routes to. -- **child thread/topic** — an optional extra messaging surface created only by `--thread ...`. -- **runtime workspace** — the filesystem location (`cwd`, repo checkout, backend workspace) where the harness runs. Independent of the chat surface. +`/acp spawn --bind here` pins the current conversation to the +spawned ACP session — no child thread, same chat surface. OpenClaw keeps +owning transport, auth, safety, and delivery. Follow-up messages in that +conversation route to the same session; `/new` and `/reset` reset the +session in place; `/acp close` removes the binding. Examples: -- `/codex bind` — keep this chat, spawn or attach native Codex app-server, route future messages here. -- `/codex model gpt-5.4`, `/codex fast on`, `/codex permissions yolo` — tune the bound native Codex thread from chat. -- `/codex stop` or `/codex steer focus on the failing tests first` — control the active native Codex turn. -- `/acp spawn codex --bind here` — explicit ACP fallback for Codex. -- `/acp spawn codex --thread auto` — OpenClaw may create a child thread/topic and bind there. -- `/acp spawn codex --bind here --cwd /workspace/repo` — same chat binding, Codex runs in `/workspace/repo`. +```text +/codex bind # native Codex bind, route future messages here +/codex model gpt-5.4 # tune the bound native Codex thread +/codex stop # control the active native Codex turn +/acp spawn codex --bind here # explicit ACP fallback for Codex +/acp spawn codex --thread auto # may create a child thread/topic and bind there +/acp spawn codex --bind here --cwd /workspace/repo # same chat binding, Codex runs in /workspace/repo +``` -Notes: + + + - `--bind here` and `--thread ...` are mutually exclusive. + - `--bind here` only works on channels that advertise current-conversation binding; OpenClaw returns a clear unsupported message otherwise. Bindings persist across gateway restarts. + - On Discord, `spawnAcpSessions` is only required when OpenClaw needs to create a child thread for `--thread auto|here` — not for `--bind here`. + - If you spawn to a different ACP agent without `--cwd`, OpenClaw inherits the **target agent's** workspace by default. Missing inherited paths (`ENOENT`/`ENOTDIR`) fall back to the backend default; other access errors (e.g. `EACCES`) surface as spawn errors. + - Gateway management commands stay local in bound conversations — `/acp ...` commands are handled by OpenClaw even when normal follow-up text routes to the bound ACP session; `/status` and `/unfocus` also stay local whenever command handling is enabled for that surface. + + + When thread bindings are enabled for a channel adapter: -- `--bind here` and `--thread ...` are mutually exclusive. -- `--bind here` only works on channels that advertise current-conversation binding; OpenClaw returns a clear unsupported message otherwise. Bindings persist across gateway restarts. -- On Discord, `spawnAcpSessions` is only required when OpenClaw needs to create a child thread for `--thread auto|here` — not for `--bind here`. -- If you spawn to a different ACP agent without `--cwd`, OpenClaw inherits the **target agent's** workspace by default. Missing inherited paths (`ENOENT`/`ENOTDIR`) fall back to the backend default; other access errors (e.g. `EACCES`) surface as spawn errors. -- Gateway management commands stay local in bound conversations. In - particular, `/acp ...` commands are handled by OpenClaw even when normal - follow-up text routes to the bound ACP session; `/status` and `/unfocus` also - stay local whenever command handling is enabled for that surface. + - OpenClaw binds a thread to a target ACP session. + - Follow-up messages in that thread route to the bound ACP session. + - ACP output is delivered back to the same thread. + - Unfocus/close/archive/idle-timeout or max-age expiry removes the binding. + - `/acp close`, `/acp cancel`, `/acp status`, `/status`, and `/unfocus` are Gateway commands, not prompts to the ACP harness. -### Thread-bound sessions + Required feature flags for thread-bound ACP: -When thread bindings are enabled for a channel adapter, ACP sessions can be bound to threads: + - `acp.enabled=true` + - `acp.dispatch.enabled` is on by default (set `false` to pause ACP dispatch). + - Channel-adapter ACP thread-spawn flag enabled (adapter-specific): + - Discord: `channels.discord.threadBindings.spawnAcpSessions=true` + - Telegram: `channels.telegram.threadBindings.spawnAcpSessions=true` -- OpenClaw binds a thread to a target ACP session. -- Follow-up messages in that thread route to the bound ACP session. -- ACP output is delivered back to the same thread. -- Unfocus/close/archive/idle-timeout or max-age expiry removes the binding. -- `/acp close`, `/acp cancel`, `/acp status`, `/status`, and `/unfocus` are - Gateway commands, not prompts to the ACP harness. + Thread binding support is adapter-specific. If the active channel + adapter does not support thread bindings, OpenClaw returns a clear + unsupported/unavailable message. -Thread binding support is adapter-specific. If the active channel adapter does not support thread bindings, OpenClaw returns a clear unsupported/unavailable message. + + + - Any channel adapter that exposes session/thread binding capability. + - Current built-in support: **Discord** threads/channels, **Telegram** topics (forum topics in groups/supergroups and DM topics). + - Plugin channels can add support through the same binding interface. + + -Required feature flags for thread-bound ACP: +## Persistent channel bindings -- `acp.enabled=true` -- `acp.dispatch.enabled` is on by default (set `false` to pause ACP dispatch) -- Channel-adapter ACP thread-spawn flag enabled (adapter-specific) - - Discord: `channels.discord.threadBindings.spawnAcpSessions=true` - - Telegram: `channels.telegram.threadBindings.spawnAcpSessions=true` - -### Thread supporting channels - -- Any channel adapter that exposes session/thread binding capability. -- Current built-in support: - - Discord threads/channels - - Telegram topics (forum topics in groups/supergroups and DM topics) -- Plugin channels can add support through the same binding interface. - -## Channel specific settings - -For non-ephemeral workflows, configure persistent ACP bindings in top-level `bindings[]` entries. +For non-ephemeral workflows, configure persistent ACP bindings in +top-level `bindings[]` entries. ### Binding model -- `bindings[].type="acp"` marks a persistent ACP conversation binding. -- `bindings[].match` identifies the target conversation: - - Discord channel or thread: `match.channel="discord"` + `match.peer.id=""` - - Telegram forum topic: `match.channel="telegram"` + `match.peer.id=":topic:"` - - BlueBubbles DM/group chat: `match.channel="bluebubbles"` + `match.peer.id=""` - Prefer `chat_id:*` or `chat_identifier:*` for stable group bindings. - - iMessage DM/group chat: `match.channel="imessage"` + `match.peer.id=""` - Prefer `chat_id:*` for stable group bindings. -- `bindings[].agentId` is the owning OpenClaw agent id. -- Optional ACP overrides live under `bindings[].acp`: - - `mode` (`persistent` or `oneshot`) - - `label` - - `cwd` - - `backend` + + Marks a persistent ACP conversation binding. + + + Identifies the target conversation. Per-channel shapes: + +- **Discord channel/thread:** `match.channel="discord"` + `match.peer.id=""` +- **Telegram forum topic:** `match.channel="telegram"` + `match.peer.id=":topic:"` +- **BlueBubbles DM/group:** `match.channel="bluebubbles"` + `match.peer.id=""`. Prefer `chat_id:*` or `chat_identifier:*` for stable group bindings. +- **iMessage DM/group:** `match.channel="imessage"` + `match.peer.id=""`. Prefer `chat_id:*` for stable group bindings. + + + The owning OpenClaw agent id. + + + Optional ACP override. + + + Optional operator-facing label. + + + Optional runtime working directory. + + + Optional backend override. + ### Runtime defaults per agent Use `agents.list[].runtime` to define ACP defaults once per agent: - `agents.list[].runtime.type="acp"` -- `agents.list[].runtime.acp.agent` (harness id, for example `codex` or `claude`) +- `agents.list[].runtime.acp.agent` (harness id, e.g. `codex` or `claude`) - `agents.list[].runtime.acp.backend` - `agents.list[].runtime.acp.mode` - `agents.list[].runtime.acp.cwd` -Override precedence for ACP bound sessions: +**Override precedence for ACP bound sessions:** 1. `bindings[].acp.*` 2. `agents.list[].runtime.acp.*` -3. global ACP defaults (for example `acp.backend`) +3. Global ACP defaults (e.g. `acp.backend`) -Example: +### Example ```json5 { @@ -389,7 +433,7 @@ Example: } ``` -Behavior: +### Behavior - OpenClaw ensures the configured ACP session exists before use. - Messages in that channel or topic route to the configured ACP session. @@ -398,234 +442,299 @@ Behavior: - For cross-agent ACP spawns without an explicit `cwd`, OpenClaw inherits the target agent workspace from agent config. - Missing inherited workspace paths fall back to the backend default cwd; non-missing access failures surface as spawn errors. -## Start ACP sessions (interfaces) +## Start ACP sessions -### From `sessions_spawn` +Two ways to start an ACP session: -Use `runtime: "acp"` to start an ACP session from an agent turn or tool call. + + + Use `runtime: "acp"` to start an ACP session from an agent turn or + tool call. -```json -{ - "task": "Open the repo and summarize failing tests", - "runtime": "acp", - "agentId": "codex", - "thread": true, - "mode": "session" -} -``` + ```json + { + "task": "Open the repo and summarize failing tests", + "runtime": "acp", + "agentId": "codex", + "thread": true, + "mode": "session" + } + ``` -Notes: + + `runtime` defaults to `subagent`, so set `runtime: "acp"` explicitly + for ACP sessions. If `agentId` is omitted, OpenClaw uses + `acp.defaultAgent` when configured. `mode: "session"` requires + `thread: true` to keep a persistent bound conversation. + -- `runtime` defaults to `subagent`, so set `runtime: "acp"` explicitly for ACP sessions. -- If `agentId` is omitted, OpenClaw uses `acp.defaultAgent` when configured. -- `mode: "session"` requires `thread: true` to keep a persistent bound conversation. + + + Use `/acp spawn` for explicit operator control from chat. -Interface details: + ```text + /acp spawn codex --mode persistent --thread auto + /acp spawn codex --mode oneshot --thread off + /acp spawn codex --bind here + /acp spawn codex --thread here + ``` -- `task` (required): initial prompt sent to the ACP session. -- `runtime` (required for ACP): must be `"acp"`. -- `agentId` (optional): ACP target harness id. Falls back to `acp.defaultAgent` if set. -- `thread` (optional, default `false`): request thread binding flow where supported. -- `mode` (optional): `run` (one-shot) or `session` (persistent). - - default is `run` - - if `thread: true` and mode omitted, OpenClaw may default to persistent behavior per runtime path - - `mode: "session"` requires `thread: true` -- `cwd` (optional): requested runtime working directory (validated by backend/runtime policy). If omitted, ACP spawn inherits the target agent workspace when configured; missing inherited paths fall back to backend defaults, while real access errors are returned. -- `label` (optional): operator-facing label used in session/banner text. -- `resumeSessionId` (optional): resume an existing ACP session instead of creating a new one. The agent replays its conversation history via `session/load`. Requires `runtime: "acp"`. -- `streamTo` (optional): `"parent"` streams initial ACP run progress summaries back to the requester session as system events. - - When available, accepted responses include `streamLogPath` pointing to a session-scoped JSONL log (`.acp-stream.jsonl`) you can tail for full relay history. -- `runTimeoutSeconds` (optional): aborts the ACP child turn after N seconds. `0` keeps the turn on the gateway's no-timeout path. The same value is applied to the Gateway run and ACP runtime so stalled/quota-exhausted harnesses do not occupy the parent agent lane indefinitely. -- `model` (optional): explicit model override for the ACP child session. Codex ACP spawns normalize OpenClaw Codex refs such as `openai-codex/gpt-5.4` to Codex ACP startup config before `session/new`; slash forms such as `openai-codex/gpt-5.4/high` also set Codex ACP reasoning effort. Other harnesses must advertise ACP `models` and support `session/set_model`; otherwise OpenClaw/acpx fails clearly instead of silently falling back to the target agent default. -- `thinking` (optional): explicit thinking/reasoning effort for the ACP child session. For Codex ACP, `minimal` maps to low effort, `low`/`medium`/`high`/`xhigh` map directly, and `off` omits the reasoning-effort startup override. + Key flags: + + - `--mode persistent|oneshot` + - `--bind here|off` + - `--thread auto|here|off` + - `--cwd ` + - `--label ` + + See [Slash commands](/tools/slash-commands). + + + + +### `sessions_spawn` parameters + + + Initial prompt sent to the ACP session. + + + Must be `"acp"` for ACP sessions. + + + ACP target harness id. Falls back to `acp.defaultAgent` if set. + + + Request thread binding flow where supported. + + + `"run"` is one-shot; `"session"` is persistent. If `thread: true` and + `mode` is omitted, OpenClaw may default to persistent behaviour per + runtime path. `mode: "session"` requires `thread: true`. + + + Requested runtime working directory (validated by backend/runtime + policy). If omitted, ACP spawn inherits the target agent workspace + when configured; missing inherited paths fall back to backend + defaults, while real access errors are returned. + + + Operator-facing label used in session/banner text. + + + Resume an existing ACP session instead of creating a new one. The + agent replays its conversation history via `session/load`. Requires + `runtime: "acp"`. + + + `"parent"` streams initial ACP run progress summaries back to the + requester session as system events. Accepted responses include + `streamLogPath` pointing to a session-scoped JSONL log + (`.acp-stream.jsonl`) you can tail for full relay history. + + + Aborts the ACP child turn after N seconds. `0` keeps the turn on the + gateway's no-timeout path. The same value is applied to the Gateway + run and ACP runtime so stalled/quota-exhausted harnesses do not + occupy the parent agent lane indefinitely. + + + Explicit model override for the ACP child session. Codex ACP spawns + normalize OpenClaw Codex refs such as `openai-codex/gpt-5.4` to Codex + ACP startup config before `session/new`; slash forms such as + `openai-codex/gpt-5.4/high` also set Codex ACP reasoning effort. + Other harnesses must advertise ACP `models` and support + `session/set_model`; otherwise OpenClaw/acpx fails clearly instead of + silently falling back to the target agent default. + + + Explicit thinking/reasoning effort. For Codex ACP, `minimal` maps to + low effort, `low`/`medium`/`high`/`xhigh` map directly, and `off` + omits the reasoning-effort startup override. + + +## Spawn bind and thread modes + + + + | Mode | Behavior | + | ------ | ---------------------------------------------------------------------- | + | `here` | Bind the current active conversation in place; fail if none is active. | + | `off` | Do not create a current-conversation binding. | + + Notes: + + - `--bind here` is the simplest operator path for "make this channel or chat Codex-backed." + - `--bind here` does not create a child thread. + - `--bind here` is only available on channels that expose current-conversation binding support. + - `--bind` and `--thread` cannot be combined in the same `/acp spawn` call. + + + + | Mode | Behavior | + | ------ | --------------------------------------------------------------------------------------------------- | + | `auto` | In an active thread: bind that thread. Outside a thread: create/bind a child thread when supported. | + | `here` | Require current active thread; fail if not in one. | + | `off` | No binding. Session starts unbound. | + + Notes: + + - On non-thread binding surfaces, default behavior is effectively `off`. + - Thread-bound spawn requires channel policy support: + - Discord: `channels.discord.threadBindings.spawnAcpSessions=true` + - Telegram: `channels.telegram.threadBindings.spawnAcpSessions=true` + - Use `--bind here` when you want to pin the current conversation without creating a child thread. + + + ## Delivery model -ACP sessions can be either interactive workspaces or parent-owned background work. The delivery path depends on that shape. +ACP sessions can be either interactive workspaces or parent-owned +background work. The delivery path depends on that shape. -### Interactive ACP sessions + + + Interactive sessions are meant to keep talking on a visible chat + surface: -Interactive sessions are meant to keep talking on a visible chat surface: + - `/acp spawn ... --bind here` binds the current conversation to the ACP session. + - `/acp spawn ... --thread ...` binds a channel thread/topic to the ACP session. + - Persistent configured `bindings[].type="acp"` route matching conversations to the same ACP session. -- `/acp spawn ... --bind here` binds the current conversation to the ACP session. -- `/acp spawn ... --thread ...` binds a channel thread/topic to the ACP session. -- Persistent configured `bindings[].type="acp"` route matching conversations to the same ACP session. + Follow-up messages in the bound conversation route directly to the + ACP session, and ACP output is delivered back to that same + channel/thread/topic. -Follow-up messages in the bound conversation route directly to the ACP session, and ACP output is delivered back to that same channel/thread/topic. + What OpenClaw sends to the harness: -What OpenClaw sends to the harness: + - Normal bound follow-ups are sent as prompt text, plus attachments only when the harness/backend supports them. + - `/acp` management commands and local Gateway commands are intercepted before ACP dispatch. + - Runtime-generated completion events are materialized per target. OpenClaw agents get OpenClaw's internal runtime-context envelope; external ACP harnesses get a plain prompt with the child result and instruction. The raw `<<>>` envelope should never be sent to external harnesses or persisted as ACP user transcript text. + - ACP transcript entries use the user-visible trigger text or the plain completion prompt. Internal event metadata stays structured in OpenClaw where possible and is not treated as user-authored chat content. -- Normal bound follow-ups are sent as prompt text, plus attachments only when - the harness/backend supports them. -- `/acp` management commands and local Gateway commands are intercepted before - ACP dispatch. -- Runtime-generated completion events are materialized per target. OpenClaw - agents get OpenClaw's internal runtime-context envelope; external ACP - harnesses get a plain prompt with the child result and instruction. The raw - `<<>>` envelope should never be sent to - external harnesses or persisted as ACP user transcript text. -- ACP transcript entries use the user-visible trigger text or the plain - completion prompt. Internal event metadata stays structured in OpenClaw where - possible and is not treated as user-authored chat content. + + + One-shot ACP sessions spawned by another agent run are background + children, similar to sub-agents: -### Parent-owned one-shot ACP sessions + - The parent asks for work with `sessions_spawn({ runtime: "acp", mode: "run" })`. + - The child runs in its own ACP harness session. + - Child turns run on the same background lane used by native sub-agent spawns, so a slow ACP harness does not block unrelated main-session work. + - Completion reports back through the task-completion announce path. OpenClaw converts internal completion metadata into a plain ACP prompt before sending it to an external harness, so harnesses do not see OpenClaw-only runtime context markers. + - The parent rewrites the child result in normal assistant voice when a user-facing reply is useful. -One-shot ACP sessions spawned by another agent run are background children, similar to sub-agents: + Do **not** treat this path as a peer-to-peer chat between parent + and child. The child already has a completion channel back to the + parent. -- The parent asks for work with `sessions_spawn({ runtime: "acp", mode: "run" })`. -- The child runs in its own ACP harness session. -- Child turns run on the same background lane used by native sub-agent spawns, so a slow ACP harness does not block unrelated main-session work. -- Completion reports back through the task-completion announce path. OpenClaw converts internal completion metadata into a plain ACP prompt before sending it to an external harness, so harnesses do not see OpenClaw-only runtime context markers. -- The parent rewrites the child result in normal assistant voice when a user-facing reply is useful. + + + `sessions_send` can target another session after spawn. For normal + peer sessions, OpenClaw uses an agent-to-agent (A2A) follow-up path + after injecting the message: -Do not treat this path as a peer-to-peer chat between parent and child. The child already has a completion channel back to the parent. + - Wait for the target session's reply. + - Optionally let requester and target exchange a bounded number of follow-up turns. + - Ask the target to produce an announce message. + - Deliver that announce to the visible channel or thread. -### `sessions_send` and A2A delivery + That A2A path is a fallback for peer sends where the sender needs a + visible follow-up. It stays enabled when an unrelated session can + see and message an ACP target, for example under broad + `tools.sessions.visibility` settings. -`sessions_send` can target another session after spawn. For normal peer sessions, OpenClaw uses an agent-to-agent (A2A) follow-up path after injecting the message: + OpenClaw skips the A2A follow-up only when the requester is the + parent of its own parent-owned one-shot ACP child. In that case, + running A2A on top of task completion can wake the parent with the + child's result, forward the parent's reply back into the child, and + create a parent/child echo loop. The `sessions_send` result reports + `delivery.status="skipped"` for that owned-child case because the + completion path is already responsible for the result. -- wait for the target session's reply -- optionally let requester and target exchange a bounded number of follow-up turns -- ask the target to produce an announce message -- deliver that announce to the visible channel or thread + + + Use `resumeSessionId` to continue a previous ACP session instead of + starting fresh. The agent replays its conversation history via + `session/load`, so it picks up with full context of what came before. -That A2A path is a fallback for peer sends where the sender needs a visible follow-up. It stays enabled when an unrelated session can see and message an ACP target, for example under broad `tools.sessions.visibility` settings. + ```json + { + "task": "Continue where we left off — fix the remaining test failures", + "runtime": "acp", + "agentId": "codex", + "resumeSessionId": "" + } + ``` -OpenClaw skips the A2A follow-up only when the requester is the parent of its own parent-owned one-shot ACP child. In that case, running A2A on top of task completion can wake the parent with the child's result, forward the parent's reply back into the child, and create a parent/child echo loop. The `sessions_send` result reports `delivery.status="skipped"` for that owned-child case because the completion path is already responsible for the result. + Common use cases: -### Resume an existing session + - Hand off a Codex session from your laptop to your phone — tell your agent to pick up where you left off. + - Continue a coding session you started interactively in the CLI, now headlessly through your agent. + - Pick up work that was interrupted by a gateway restart or idle timeout. -Use `resumeSessionId` to continue a previous ACP session instead of starting fresh. The agent replays its conversation history via `session/load`, so it picks up with full context of what came before. + Notes: -```json -{ - "task": "Continue where we left off — fix the remaining test failures", - "runtime": "acp", - "agentId": "codex", - "resumeSessionId": "" -} -``` + - `resumeSessionId` requires `runtime: "acp"` — returns an error if used with the sub-agent runtime. + - `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`. + - The target agent must support `session/load` (Codex and Claude Code do). + - If the session id is not found, the spawn fails with a clear error — no silent fallback to a new session. -Common use cases: + + + After a gateway deploy, run a live end-to-end check rather than + trusting unit tests: -- Hand off a Codex session from your laptop to your phone — tell your agent to pick up where you left off -- Continue a coding session you started interactively in the CLI, now headlessly through your agent -- Pick up work that was interrupted by a gateway restart or idle timeout + 1. Verify the deployed gateway version and commit on the target host. + 2. Open a temporary ACPX bridge session to a live agent. + 3. Ask that agent to call `sessions_spawn` with `runtime: "acp"`, `agentId: "codex"`, `mode: "run"`, and task `Reply with exactly LIVE-ACP-SPAWN-OK`. + 4. Verify `accepted=yes`, a real `childSessionKey`, and no validator error. + 5. Clean up the temporary bridge session. -Notes: + Keep the gate on `mode: "run"` and skip `streamTo: "parent"` — + thread-bound `mode: "session"` and stream-relay paths are separate + richer integration passes. -- `resumeSessionId` requires `runtime: "acp"` — returns an error if used with the sub-agent runtime. -- `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`. -- The target agent must support `session/load` (Codex and Claude Code do). -- If the session ID isn't found, the spawn fails with a clear error — no silent fallback to a new session. - - - -After a gateway deploy, run a live end-to-end check rather than trusting unit tests: - -1. Verify the deployed gateway version and commit on the target host. -2. Open a temporary ACPX bridge session to a live agent. -3. Ask that agent to call `sessions_spawn` with `runtime: "acp"`, `agentId: "codex"`, `mode: "run"`, and task `Reply with exactly LIVE-ACP-SPAWN-OK`. -4. Verify `accepted=yes`, a real `childSessionKey`, and no validator error. -5. Clean up the temporary bridge session. - -Keep the gate on `mode: "run"` and skip `streamTo: "parent"` — thread-bound `mode: "session"` and stream-relay paths are separate richer integration passes. - - + + ## Sandbox compatibility -ACP sessions currently run on the host runtime, not inside the OpenClaw sandbox. +ACP sessions currently run on the host runtime, **not** inside the +OpenClaw sandbox. -Security boundary: + +**Security boundary:** -- The external harness can read/write according to its own CLI permissions and - the selected `cwd`. -- OpenClaw's sandbox policy does not wrap ACP harness execution. -- OpenClaw still enforces ACP feature gates, allowed agents, session ownership, - channel bindings, and Gateway delivery policy. +- The external harness can read/write according to its own CLI permissions and the selected `cwd`. +- OpenClaw's sandbox policy does **not** wrap ACP harness execution. +- OpenClaw still enforces ACP feature gates, allowed agents, session ownership, channel bindings, and Gateway delivery policy. - Use `runtime: "subagent"` for sandbox-enforced OpenClaw-native work. + Current limitations: - If the requester session is sandboxed, ACP spawns are blocked for both `sessions_spawn({ runtime: "acp" })` and `/acp spawn`. - - Error: `Sandboxed sessions cannot spawn ACP sessions because runtime="acp" runs on the host. Use runtime="subagent" from sandboxed sessions.` - `sessions_spawn` with `runtime: "acp"` does not support `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".` - -Use `runtime: "subagent"` when you need sandbox-enforced execution. - -### From `/acp` command - -Use `/acp spawn` for explicit operator control from chat when needed. - -```text -/acp spawn codex --mode persistent --thread auto -/acp spawn codex --mode oneshot --thread off -/acp spawn codex --bind here -/acp spawn codex --thread here -``` - -Key flags: - -- `--mode persistent|oneshot` -- `--bind here|off` -- `--thread auto|here|off` -- `--cwd ` -- `--label ` - -See [Slash Commands](/tools/slash-commands). ## Session target resolution -Most `/acp` actions accept an optional session target (`session-key`, `session-id`, or `session-label`). +Most `/acp` actions accept an optional session target (`session-key`, +`session-id`, or `session-label`). -Resolution order: +**Resolution order:** 1. Explicit target argument (or `--session` for `/acp steer`) - tries key - then UUID-shaped session id - then label -2. Current thread binding (if this conversation/thread is bound to an ACP session) -3. Current requester session fallback +2. Current thread binding (if this conversation/thread is bound to an ACP session). +3. Current requester session fallback. -Current-conversation bindings and thread bindings both participate in step 2. +Current-conversation bindings and thread bindings both participate in +step 2. -If no target resolves, OpenClaw returns a clear error (`Unable to resolve session target: ...`). - -## Spawn bind modes - -`/acp spawn` supports `--bind here|off`. - -| Mode | Behavior | -| ------ | ---------------------------------------------------------------------- | -| `here` | Bind the current active conversation in place; fail if none is active. | -| `off` | Do not create a current-conversation binding. | - -Notes: - -- `--bind here` is the simplest operator path for "make this channel or chat Codex-backed." -- `--bind here` does not create a child thread. -- `--bind here` is only available on channels that expose current-conversation binding support. -- `--bind` and `--thread` cannot be combined in the same `/acp spawn` call. - -## Spawn thread modes - -`/acp spawn` supports `--thread auto|here|off`. - -| Mode | Behavior | -| ------ | --------------------------------------------------------------------------------------------------- | -| `auto` | In an active thread: bind that thread. Outside a thread: create/bind a child thread when supported. | -| `here` | Require current active thread; fail if not in one. | -| `off` | No binding. Session starts unbound. | - -Notes: - -- On non-thread binding surfaces, default behavior is effectively `off`. -- Thread-bound spawn requires channel policy support: - - Discord: `channels.discord.threadBindings.spawnAcpSessions=true` - - Telegram: `channels.telegram.threadBindings.spawnAcpSessions=true` -- Use `--bind here` when you want to pin the current conversation without creating a child thread. +If no target resolves, OpenClaw returns a clear error +(`Unable to resolve session target: ...`). ## ACP controls @@ -647,27 +756,34 @@ Notes: | `/acp doctor` | Backend health, capabilities, actionable fixes. | `/acp doctor` | | `/acp install` | Print deterministic install and enable steps. | `/acp install` | -`/acp status` shows the effective runtime options plus runtime-level and backend-level session identifiers. Unsupported-control errors surface clearly when a backend lacks a capability. `/acp sessions` reads the store for the current bound or requester session; target tokens (`session-key`, `session-id`, or `session-label`) resolve through gateway session discovery, including custom per-agent `session.store` roots. +`/acp status` shows the effective runtime options plus runtime-level and +backend-level session identifiers. Unsupported-control errors surface +clearly when a backend lacks a capability. `/acp sessions` reads the +store for the current bound or requester session; target tokens +(`session-key`, `session-id`, or `session-label`) resolve through +gateway session discovery, including custom per-agent `session.store` +roots. -## Runtime options mapping +### Runtime options mapping -`/acp` has convenience commands and a generic setter. +`/acp` has convenience commands and a generic setter. Equivalent +operations: -Equivalent operations: - -- `/acp model ` maps to runtime config key `model`. For Codex ACP, OpenClaw normalizes `openai-codex/` to the adapter model id and maps slash reasoning suffixes such as `openai-codex/gpt-5.4/high` to Codex ACP `reasoning_effort`. For other harnesses, model control depends on adapter support for ACP `models` and `session/set_model`. -- `/acp set thinking ` maps to runtime config key `thinking`. For Codex ACP, OpenClaw sends the corresponding `reasoning_effort` where the adapter supports one. -- `/acp permissions ` maps to runtime config key `approval_policy`. -- `/acp timeout ` maps to runtime config key `timeout`. -- `/acp cwd ` updates runtime cwd override directly. -- `/acp set ` is the generic path. - - Special case: `key=cwd` uses the cwd override path. -- `/acp reset-options` clears all runtime overrides for target session. +| Command | Maps to | Notes | +| ---------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `/acp model ` | runtime config key `model` | For Codex ACP, OpenClaw normalizes `openai-codex/` to the adapter model id and maps slash reasoning suffixes such as `openai-codex/gpt-5.4/high` to `reasoning_effort`. | +| `/acp set thinking ` | runtime config key `thinking` | For Codex ACP, OpenClaw sends the corresponding `reasoning_effort` where the adapter supports one. | +| `/acp permissions ` | runtime config key `approval_policy` | — | +| `/acp timeout ` | runtime config key `timeout` | — | +| `/acp cwd ` | runtime cwd override | Direct update. | +| `/acp set ` | generic | `key=cwd` uses the cwd override path. | +| `/acp reset-options` | clears all runtime overrides | — | ## acpx harness, plugin setup, and permissions -For acpx harness configuration (Claude Code / Codex / Gemini CLI aliases), the -plugin-tools and OpenClaw-tools MCP bridges, and ACP permission modes, see +For acpx harness configuration (Claude Code / Codex / Gemini CLI +aliases), the plugin-tools and OpenClaw-tools MCP bridges, and ACP +permission modes, see [ACP agents — setup](/tools/acp-agents-setup). ## Troubleshooting @@ -699,6 +815,10 @@ plugin-tools and OpenClaw-tools MCP bridges, and ACP permission modes, see ## Related -- [Sub-agents](/tools/subagents) -- [Multi-agent sandbox tools](/tools/multi-agent-sandbox-tools) +- [ACP agents — setup](/tools/acp-agents-setup) - [Agent send](/tools/agent-send) +- [CLI Backends](/gateway/cli-backends) +- [Codex harness](/plugins/codex-harness) +- [Multi-agent sandbox tools](/tools/multi-agent-sandbox-tools) +- [`openclaw acp` (bridge mode)](/cli/acp) +- [Sub-agents](/tools/subagents)