Use this file to discover all available pages before exploring further.

ACP agents

Agent Client Protocol (ACP) 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.

Each ACP session spawn is tracked as a background task.

note

**ACP is the external-harness path, not the default Codex path.** The native Codex app-server plugin owns `/codex ...` controls and the `agentRuntime.id: "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

text

openclaw mcp serve

instead of ACP.

Which page do I want?

You want to…	Use this	Notes
Bind or control Codex in the current conversation	text `/codex bind` , text `/codex threads`	Native Codex app-server path when the text `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	Chat-bound sessions, text `/acp spawn` , text `sessions_spawn({ runtime: "acp" })` , background tasks, runtime controls
Expose an OpenClaw Gateway session as an ACP server for an editor or client	text `openclaw 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	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

text

acpx

runtime plugin enabled by default with a plugin-local pinned

text

acpx

binary that OpenClaw probes and self-repairs on startup. Run

text

/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

text

sessions_spawn

ACP guidance stay hidden so the agent does not suggest an unavailable backend.

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 only when the harness should call those tools directly.

Supported harness targets

With the bundled

text

acpx

backend, use these harness ids as

text

/acp spawn <id>

text

sessions_spawn({ runtime: "acp", agentId: "<id>" })

targets:

Harness id	Typical backend	Notes
text `claude`	Claude Code ACP adapter	Requires Claude Code auth on the host.
text `codex`	Codex ACP adapter	Explicit ACP fallback only when native text `/codex` is unavailable or ACP is requested.
text `copilot`	GitHub Copilot ACP adapter	Requires Copilot CLI/runtime auth.
text `cursor`	Cursor CLI ACP ( text `cursor-agent acp` )	Override the acpx command if a local install exposes a different ACP entrypoint.
text `droid`	Factory Droid CLI	Requires Factory/Droid auth or text `FACTORY_API_KEY` in the harness environment.
text `gemini`	Gemini CLI ACP adapter	Requires Gemini CLI auth or API key setup.
text `iflow`	iFlow CLI	Adapter availability and model control depend on the installed CLI.
text `kilocode`	Kilo Code CLI	Adapter availability and model control depend on the installed CLI.
text `kimi`	Kimi/Moonshot CLI	Requires Kimi/Moonshot auth on the host.
text `kiro`	Kiro CLI	Adapter availability and model control depend on the installed CLI.
text `opencode`	OpenCode ACP adapter	Requires OpenCode CLI/provider auth.
text `openclaw`	OpenClaw Gateway bridge through text `openclaw acp`	Lets an ACP-aware harness talk back to an OpenClaw Gateway session.
text `pi`	Pi/embedded OpenClaw runtime	Used for OpenClaw-native harness experiments.
text `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

text

acp.allowedAgents

and any

text

agents.list[].runtime.acp.agent

mapping before dispatch.

Operator runbook

Quick

text

/acp

flow from chat:

Spawn

`/acp spawn claude --bind here`, `/acp spawn gemini --mode persistent --thread auto`, or explicit `/acp spawn codex --bind here`.

Work

Continue in the bound conversation or thread (or target the session key explicitly).

Check state

`/acp status`

Tune

`/acp model `, `/acp permissions `, `/acp timeout `.

Steer

Without replacing context: `/acp steer tighten logging and continue`.

Stop

`/acp cancel` (current turn) or `/acp close` (session + bindings).

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

text

codex

plugin is enabled. Use sub-agents when you want OpenClaw-native delegated runs.

Area	ACP session	Sub-agent run
Runtime	ACP backend plugin (for example acpx)	OpenClaw native sub-agent runtime
Session key	text `agent:<agentId>:acp:<uuid>`	text `agent:<agentId>:subagent:<uuid>`
Main commands	text `/acp ...`	text `/subagents ...`
Spawn tool	text `sessions_spawn` with text `runtime:"acp"`	text `sessions_spawn` (default runtime)

How ACP runs Claude Code

For Claude Code through ACP, the stack is:

OpenClaw ACP session control plane.
Bundled
text
acpx
runtime plugin.
Claude ACP adapter.
Claude-side runtime/session machinery.

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.

For operators, the practical rule is:

Want
text
/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
text
--thread ...
.
Runtime workspace — the filesystem location (
text
cwd
, repo checkout, backend workspace) where the harness runs. Independent of the chat surface.

Current-conversation binds

text

/acp spawn <harness> --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;

text

/new

and

text

/reset

reset the session in place;

text

/acp close

removes the binding.

Examples:


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

Persistent channel bindings

For non-ephemeral workflows, configure persistent ACP bindings in top-level

text

bindings[]

entries.

Binding model

Marks a persistent ACP conversation binding. Identifies the target conversation. Per-channel shapes:

Discord channel/thread:
text
match.channel="discord"
+
text
match.peer.id="<channelOrThreadId>"
Telegram forum topic:
text
match.channel="telegram"
+
text
match.peer.id="<chatId>:topic:<topicId>"
BlueBubbles DM/group:
text
match.channel="bluebubbles"
+
text
match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"
. Prefer
text
chat_id:*
or
text
chat_identifier:*
for stable group bindings.
iMessage DM/group:
text
match.channel="imessage"
+
text
match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"
. Prefer
text
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

text

agents.list[].runtime

to define ACP defaults once per agent:

text
agents.list[].runtime.type="acp"
text
agents.list[].runtime.acp.agent
(harness id, e.g.
text
codex
or
text
claude
)
text
agents.list[].runtime.acp.backend
text
agents.list[].runtime.acp.mode
text
agents.list[].runtime.acp.cwd

Override precedence for ACP bound sessions:

text
bindings[].acp.*
text
agents.list[].runtime.acp.*
Global ACP defaults (e.g.
text
acp.backend
)

Example


json5
{
  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 } },
        },
      },
    },
  },
}

Behavior

OpenClaw ensures the configured ACP session exists before use.
Messages in that channel or topic route to the configured ACP session.
In bound conversations,
text
/new
and
text
/reset
reset the same ACP session key in place.
Temporary runtime bindings (for example created by thread-focus flows) still apply where present.
For cross-agent ACP spawns without an explicit
text
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

Two ways to start an ACP session:

Use `runtime: "acp"` to start an ACP session from an agent turn or tool call.


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

<Note>
  `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.
</Note>

Use `/acp spawn` for explicit operator control from chat.


text
```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 <absolute-path>`
* `--label <name>`

See [Slash commands](/tools/slash-commands).

text
`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. |


text
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. |


text
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.

Sandbox compatibility

ACP sessions currently run on the host runtime, not inside the OpenClaw sandbox.

warning

**Security boundary:**

The external harness can read/write according to its own CLI permissions and the selected
text
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
text
runtime: "subagent"
for sandbox-enforced OpenClaw-native work.

Current limitations:

If the requester session is sandboxed, ACP spawns are blocked for both
text
sessions_spawn({ runtime: "acp" })
and
text
/acp spawn
.
text
sessions_spawn
with
text
runtime: "acp"
does not support
text
sandbox: "require"
.

Session target resolution

Most

text

/acp

actions accept an optional session target (

text

session-key

text

session-id

, or

text

session-label

Resolution order:

Explicit target argument (or
text
--session
for
text
/acp steer
)
- tries key
- then UUID-shaped session id
- then label
Current thread binding (if this conversation/thread is bound to an ACP session).
Current requester session fallback.

Current-conversation bindings and thread bindings both participate in step 2.

If no target resolves, OpenClaw returns a clear error (

text

Unable to resolve session target: ...

ACP controls

Command	What it does	Example
text `/acp spawn`	Create ACP session; optional current bind or thread bind.	text `/acp spawn codex --bind here --cwd /repo`
text `/acp cancel`	Cancel in-flight turn for target session.	text `/acp cancel agent:codex:acp:<uuid>`
text `/acp steer`	Send steer instruction to running session.	text `/acp steer --session support inbox prioritize failing tests`
text `/acp close`	Close session and unbind thread targets.	text `/acp close`
text `/acp status`	Show backend, mode, state, runtime options, capabilities.	text `/acp status`
text `/acp set-mode`	Set runtime mode for target session.	text `/acp set-mode plan`
text `/acp set`	Generic runtime config option write.	text `/acp set model openai/gpt-5.4`
text `/acp cwd`	Set runtime working directory override.	text `/acp cwd /Users/user/Projects/repo`
text `/acp permissions`	Set approval policy profile.	text `/acp permissions strict`
text `/acp timeout`	Set runtime timeout (seconds).	text `/acp timeout 120`
text `/acp model`	Set runtime model override.	text `/acp model anthropic/claude-opus-4-6`
text `/acp reset-options`	Remove session runtime option overrides.	text `/acp reset-options`
text `/acp sessions`	List recent ACP sessions from store.	text `/acp sessions`
text `/acp doctor`	Backend health, capabilities, actionable fixes.	text `/acp doctor`
text `/acp install`	Print deterministic install and enable steps.	text `/acp install`

text

/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.

text

/acp sessions

reads the store for the current bound or requester session; target tokens (

text

session-key

text

session-id

, or

text

session-label

) resolve through gateway session discovery, including custom per-agent

text

session.store

roots.

Runtime options mapping

text

/acp

has convenience commands and a generic setter. Equivalent operations:

Command	Maps to	Notes
text `/acp model <id>`	runtime config key text `model`	For Codex ACP, OpenClaw normalizes text `openai-codex/<model>` to the adapter model id and maps slash reasoning suffixes such as text `openai-codex/gpt-5.4/high` to text `reasoning_effort` .
text `/acp set thinking <level>`	runtime config key text `thinking`	For Codex ACP, OpenClaw sends the corresponding text `reasoning_effort` where the adapter supports one.
text `/acp permissions <profile>`	runtime config key text `approval_policy`	—
text `/acp timeout <seconds>`	runtime config key text `timeout`	—
text `/acp cwd <path>`	runtime cwd override	Direct update.
text `/acp set <key> <value>`	generic	text `key=cwd` uses the cwd override path.
text `/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 ACP agents — setup.

Troubleshooting

Symptom	Likely cause	Fix
text `ACP runtime backend is not configured`	Backend plugin missing, disabled, or blocked by text `plugins.allow` .	Install and enable backend plugin, include text `acpx` in text `plugins.allow` when that allowlist is set, then run text `/acp doctor` .
text `ACP is disabled by policy (acp.enabled=false)`	ACP globally disabled.	Set text `acp.enabled=true` .
text `ACP dispatch is disabled by policy (acp.dispatch.enabled=false)`	Automatic dispatch from normal thread messages disabled.	Set text `acp.dispatch.enabled=true` to resume automatic thread routing; explicit text `sessions_spawn({ runtime: "acp" })` calls still work.
text `ACP agent "<id>" is not allowed by policy`	Agent not in allowlist.	Use allowed text `agentId` or update text `acp.allowedAgents` .
text `/acp doctor` reports backend not ready right after startup	Plugin dependency probe or self-repair is still running.	Wait briefly and rerun text `/acp doctor` ; if it stays unhealthy, inspect the backend install error and plugin allow/deny policy.
Harness command not found	Adapter CLI is not installed, staged plugin deps are missing, or first-run text `npx` fetch failed for a non-Codex adapter.	Run text `/acp doctor` , repair plugin dependencies, install/prewarm the adapter on the Gateway host, or configure the acpx agent command explicitly.
Model-not-found from the harness	Model id is valid for another provider/harness but not this ACP target.	Use a model listed by that harness, configure the model in the harness, or omit the override.
Vendor auth error from the harness	OpenClaw is healthy, but the target CLI/provider is not logged in.	Log in or provide the required provider key on the Gateway host environment.
text `Unable to resolve session target: ...`	Bad key/id/label token.	Run text `/acp sessions` , copy exact key/label, retry.
text `--bind here requires running /acp spawn inside an active ... conversation`	text `--bind here` used without an active bindable conversation.	Move to the target chat/channel and retry, or use unbound spawn.
text `Conversation bindings are unavailable for <channel>.`	Adapter lacks current-conversation ACP binding capability.	Use text `/acp spawn ... --thread ...` where supported, configure top-level text `bindings[]` , or move to a supported channel.
text `--thread here requires running /acp spawn inside an active ... thread`	text `--thread here` used outside a thread context.	Move to target thread or use text `--thread auto` / text `off` .
text `Only <user-id> can rebind this channel/conversation/thread.`	Another user owns the active binding target.	Rebind as owner or use a different conversation or thread.
text `Thread bindings are unavailable for <channel>.`	Adapter lacks thread binding capability.	Use text `--thread off` or move to supported adapter/channel.
text `Sandboxed sessions cannot spawn ACP sessions ...`	ACP runtime is host-side; requester session is sandboxed.	Use text `runtime="subagent"` from sandboxed sessions, or run ACP spawn from a non-sandboxed session.
text `sessions_spawn sandbox="require" is unsupported for runtime="acp" ...`	text `sandbox="require"` requested for ACP runtime.	Use text `runtime="subagent"` for required sandboxing, or use ACP with text `sandbox="inherit"` from a non-sandboxed session.
text `Cannot apply --model ... did not advertise model support`	The target harness does not expose generic ACP model switching.	Use a harness that advertises ACP text `models` / text `session/set_model` , use Codex ACP model refs, or configure the model directly in the harness if it has its own startup flag.
Missing ACP metadata for bound session	Stale/deleted ACP session metadata.	Recreate with text `/acp spawn` , then rebind/focus thread.
text `AcpRuntimeError: Permission prompt unavailable in non-interactive mode`	text `permissionMode` blocks writes/exec in non-interactive ACP session.	Set text `plugins.entries.acpx.config.permissionMode` to text `approve-all` and restart gateway. See Permission configuration.
ACP session fails early with little output	Permission prompts are blocked by text `permissionMode` / text `nonInteractivePermissions` .	Check gateway logs for text `AcpRuntimeError` . For full permissions, set text `permissionMode=approve-all` ; for graceful degradation, set text `nonInteractivePermissions=deny` .
ACP session stalls indefinitely after completing work	Harness process finished but ACP session did not report completion.	Monitor with text `ps aux \| grep acpx` ; kill stale processes manually.
Harness sees text `<<<BEGIN_OPENCLAW_INTERNAL_CONTEXT>>>`	Internal event envelope leaked across the ACP boundary.	Update OpenClaw and rerun the completion flow; external harnesses should receive plain completion prompts only.

OpenClaw Docs

ACP agents

note

Which page do I want?

Does this work out of the box?

Supported harness targets

Operator runbook

Spawn

Work

Check state

Tune

Steer

Stop

ACP versus sub-agents

How ACP runs Claude Code

Bound sessions

Mental model

Current-conversation binds

Persistent channel bindings

Binding model

Runtime defaults per agent

Example

Behavior

Start ACP sessions

text
`sessions_spawn`
parameters

Spawn bind and thread modes

Delivery model

Sandbox compatibility

warning

Session target resolution

ACP controls

Runtime options mapping

acpx harness, plugin setup, and permissions

Troubleshooting

Related

OpenClaw Docs

ACP agents

note

Which page do I want?

Does this work out of the box?

Supported harness targets

Operator runbook

Spawn

Work

Check state

Tune

Steer

Stop

ACP versus sub-agents

How ACP runs Claude Code

Bound sessions

Mental model

Current-conversation binds

Persistent channel bindings

Binding model

Runtime defaults per agent

Example

Behavior

Start ACP sessions

textCopysessions_spawn parameters

Spawn bind and thread modes

Delivery model

Sandbox compatibility

warning

Session target resolution

ACP controls

Runtime options mapping

acpx harness, plugin setup, and permissions

Troubleshooting

Related

text
`sessions_spawn`
parameters