Agent Client Protocol (ACP) sessions let OpenClaw run external coding harnesses (Claude Code, Cursor, Copilot, Droid, OpenClaw ACP, OpenCode, Gemini CLI, and other supported ACPX harnesses) through an ACP backend plugin. Each spawn is tracked as a background task.

To let Codex or Claude Code connect as an external MCP client directly to existing OpenClaw channel conversations, use openclaw mcp serve instead of ACP.

Which page do I want?

Does this work out of the box?

Yes, after installing the official ACP runtime plugin:

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

Source checkouts can use the local extensions/acpx workspace plugin after pnpm install. 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 and healthy. If any condition fails, ACP skills and sessions_spawn ACP guidance stay hidden so the agent does not suggest an unavailable backend.

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

Supported harness targets

With the acpx backend, use these ids as /acp spawn <id> or sessions_spawn({ runtime: "acp", agentId: "<id>" }) targets:

pi (pi-acp) is also registered in the acpx backend but is not a coding harness in the same sense as the others above.

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:

- "Bind this Discord channel to Codex."
- "Attach this chat to Codex thread `<id>`."
- "Show Codex threads, then bind this one."

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 stays
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-runtime#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."

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. `acp.dispatch.enabled=false` pauses automatic ACP thread dispatch
but does not hide or block explicit `sessions_spawn({ runtime: "acp" })`
calls. 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.

See also Sub-agents.

How ACP runs Claude Code

For Claude Code through ACP, the stack is:

1. OpenClaw ACP session control plane.
2. Official @openclaw/acpx runtime plugin.
3. Claude ACP adapter.
4. 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 /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 <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; /new and /reset reset the session in place; /acp close removes the binding.

Examples:

/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

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

Required feature flags for thread-bound ACP:

- `acp.enabled=true`
- `acp.dispatch.enabled` is on by default (set `false` to pause automatic ACP thread dispatch; explicit `sessions_spawn({ runtime: "acp" })` calls still work).
- Channel-adapter thread session spawns enabled (default: `true`):
  - Discord: `channels.discord.threadBindings.spawnSessions=true`
  - Telegram: `channels.telegram.threadBindings.spawnSessions=true`

Thread binding support is adapter-specific. If the active channel adapter
does not support thread bindings, OpenClaw returns a clear
unsupported/unavailable message.

Persistent channel bindings

For non-ephemeral workflows, configure persistent ACP bindings in top-level bindings[] entries.

Binding model

• Discord channel/thread: match.channel="discord" + match.peer.id="<channelOrThreadId>"
• Slack channel/DM: match.channel="slack" + match.peer.id="<channelId|channel:<channelId>|#<channelId>|userId|user:<userId>|slack:<userId>|<@userId>>". Prefer stable Slack ids; channel bindings also match replies inside that channel's threads.
• Telegram forum topic: match.channel="telegram" + match.peer.id="<chatId>:topic:<topicId>"
• WhatsApp DM/group: match.channel="whatsapp" + match.peer.id="<E.164|group JID>". Use E.164 numbers such as +15555550123 for direct chats and WhatsApp group JIDs such as 120363424282127706@g.us for groups.
• iMessage DM/group: match.channel="imessage" + match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>". Prefer chat_id:* for stable group bindings.

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, 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:

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

Example

{
  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 after channel-specific admission and before use.
• Messages in that channel, topic, or chat route to the configured ACP session.
• Configured ACP bindings own their session route. Channel broadcast fan-out does not replace the configured ACP session for a matched binding.
• In bound conversations, /new and /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 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:

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

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

sessions_spawn parameters

ACP sessions_spawn runs use agents.defaults.subagents.runTimeoutSeconds for their default child turn limit. The tool does not accept per-call timeout overrides (runTimeoutSeconds/timeoutSeconds are rejected with a config-the-default error).

Spawn bind and thread modes

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.

Notes:

- On non-thread binding surfaces, default behavior is effectively `off`.
- Thread-bound spawn requires channel policy support:
  - Discord: `channels.discord.threadBindings.spawnSessions=true`
  - Telegram: `channels.telegram.threadBindings.spawnSessions=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 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.

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

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

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.

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.

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.

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

Common use cases:

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

Notes:

- `resumeSessionId` only applies when `runtime: "acp"`; the default sub-agent runtime ignores this ACP-only field.
- `streamTo` only applies when `runtime: "acp"`; the default sub-agent runtime ignores this ACP-only field.
- `resumeSessionId` is a host-local ACP/harness resume id, not an OpenClaw channel session key; OpenClaw still checks ACP spawn policy and target agent policy before dispatch, while the ACP backend or harness owns authorization for loading that upstream id.
- `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.

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.

• 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.
• sessions_spawn with runtime: "acp" does not support sandbox: "require".

Session target resolution

Most /acp actions accept an optional session target (session-key, session-id, or session-label).

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.

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: ...).

ACP controls

Runtime controls (spawn, cancel, steer, close, status, set-mode, set, cwd, permissions, timeout, model, and reset-options) require owner identity from external channels and operator.admin from internal Gateway clients. Authorized non-owner senders can still use sessions, doctor, install, and help.

/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

/acp has convenience commands and a generic setter. Equivalent operations:

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

Related

• ACP agents - setup
• Agent send
• CLI Backends
• Codex harness
• Codex harness runtime
• Multi-agent sandbox tools
• openclaw acp (bridge mode)
• Sub-agents

Source: docs/tools/acp-agents.md