ACP Agents: Launch External Coding Harnesses via ACP Backend

Agent Client Protocol (ACP) sessions allow OpenClaw to launch external coding harnesses (Claude Code, Cursor, Copilot, Droid, OpenClaw ACP, OpenCode, Gemini CLI, and other compatible ACPX harnesses) through an ACP backend plugin. Each launched process is recorded as a background task.

Note

ACP is the external harness pathway, not the standard Codex route. The built-in Codex app-server plugin manages /codex ... controls and the default openai/gpt-* embedded runtime for agent turns; ACP handles /acp ... controls and sessions_spawn({ runtime: "acp" }) sessions.

To allow Codex or Claude Code to attach directly as an external MCP client 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, once the official ACP runtime plugin is installed:

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

Source checkouts can make use of the local extensions/acpx workspace plugin following pnpm install. Execute /acp doctor to verify readiness.

OpenClaw only reveals ACP spawning capabilities to agents when ACP is fully operational: ACP must be enabled, dispatch must remain active, the current session must not be sandbox-blocked, and a runtime backend must be loaded and healthy. If any of these conditions are not met, ACP skills and sessions_spawn ACP guidance stay hidden so the agent cannot propose an unavailable backend.

First-run gotchas

• When plugins.allow is configured, it acts as a restrictive plugin inventory and must contain acpx, otherwise the installed ACP backend is deliberately blocked (/acp doctor reports the missing allowlist entry).
• The Codex ACP adapter is bundled with the acpx plugin and launches locally when feasible.
• Codex ACP operates with an isolated CODEX_HOME. OpenClaw copies trusted project trust entries plus safe model/provider routing config (model, model_provider, model_reasoning_effort, sandbox_mode, and safe model_providers.<name> fields) from the host Codex config; auth, notifications, and hooks remain on the host config only.
• Other target harness adapters may be fetched on demand with npx on first use.
• Vendor auth must already exist on the host for that harness.
• If the host lacks npm or network access, first-run adapter fetches fail until caches are pre-warmed or the adapter is installed through another method.

Runtime prerequisites

ACP launches a real external harness process. OpenClaw handles routing, background-task state, delivery, bindings, and policy; the harness manages its provider login, model catalog, filesystem behavior, and native tools.

Before attributing issues to OpenClaw, check:

• /acp doctor reports an enabled, healthy backend.
• The target id is permitted by acp.allowedAgents when that allowlist is configured.
• The harness command can start on the Gateway host.
• Provider auth exists for that harness (claude, codex, gemini, opencode, droid, etc.).
• The chosen model is available for that harness - model ids are not interchangeable across harnesses.
• The requested cwd exists and is reachable, or omit cwd and allow the backend to use its default.
• Permission mode matches the task. Non-interactive sessions cannot respond to native permission prompts, so write/exec-heavy coding runs typically need an ACPX permission profile that can operate headlessly.

OpenClaw plugin tools and built-in OpenClaw tools are not made available to ACP harnesses by default. Enable the explicit MCP bridges in ACP agents - setup only when the harness should invoke 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, though it does not function as a coding harness in the same way the entries above do.

Custom acpx agent aliases can be set up within acpx itself, but OpenClaw policy still evaluates acp.allowedAgents and any agents.entries.*.runtime.acp.agent mapping prior to dispatch.

Operator runbook

Quick /acp flow from chat:

Spawn

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

Work

Stay within the bound conversation or thread, or target the session key directly.

Check state

/acp status

Tune

/acp model <provider/model>, /acp permissions <profile>, /acp timeout <seconds>.

Steer

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

Stop

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

Lifecycle details

• Spawn starts or resumes an ACP runtime session, logs ACP metadata in the OpenClaw session store, and may launch a background task when the run is owned by a parent.
• ACP sessions owned by a parent are handled as background work even if the runtime session is persistent; completion and cross-surface delivery use the parent task notifier rather than behaving like a standard user-facing chat session.
• Task maintenance terminates terminal or orphaned parent-owned one-shot ACP sessions. Persistent ACP sessions are kept while an active conversation binding exists; stale persistent sessions without an active binding are closed so they cannot be silently resumed after the owning task finishes or its task record is removed.
• Bound follow-up messages are sent directly to the ACP session until the binding is closed, unfocused, reset, or expired.
• Gateway commands stay local. /acp ..., /status, and /unfocus are never transmitted as normal prompt text to a bound ACP harness.
• cancel cancels the active turn if the backend supports cancellation; it does not remove the binding or session metadata.
• close terminates the ACP session from OpenClaw's perspective and removes the binding. A harness may retain its own upstream history if resume is supported.
• The acpx plugin cleans up OpenClaw-owned wrapper and adapter process trees after close, and removes stale OpenClaw-owned ACPX orphans during Gateway startup.
• Idle runtime workers become eligible for cleanup after the built-in idle period; stored session metadata remains accessible for /acp sessions.

Native Codex routing rules

Natural-language triggers that should route to the native Codex plugin when it is enabled:

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

Native Codex conversation binding serves as the default chat-control path. OpenClaw dynamic tools still execute through OpenClaw, while Codex-native tools like shell and apply-patch run 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 or session model. The embedded Codex support boundary is documented in the Codex harness v1 support contract.

Model / provider / runtime selection cheat sheet

• Legacy Codex model references: The legacy Codex OAuth/subscription model route has been repaired by the doctor.
• openai/*: The native Codex app-server embedded runtime for handling OpenAI agent turns.
• /codex ...: The native Codex conversation control mechanism.
• /acp ... or runtime: "acp": Explicit ACP/acpx control.

ACP-routing natural-language triggers

Triggers that should be directed to the ACP runtime:

• "Execute this as a one-shot Claude Code ACP session and provide a summary."
• "Use Gemini CLI for this task within a thread, then continue subsequent interactions in that same thread."
• "Run Codex through ACP in a background thread."

OpenClaw selects runtime: "acp", resolves the harness agentId, attaches to the current conversation or thread when that feature is supported, and directs follow-ups to that session until it is closed or expires. Codex only follows this route when ACP/acpx is explicitly specified or the native Codex plugin is unavailable for the operation being requested.

For sessions_spawn, runtime: "acp" is only advertised when ACP is enabled, the requester is not operating within a sandbox, and an ACP runtime backend has been loaded. acp.dispatch.enabled=false suspends automatic ACP thread dispatch but does not conceal or prevent explicit sessions_spawn({ runtime: "acp" }) calls. It targets ACP harness identifiers such as codex, claude, droid, gemini, or opencode. Do not pass a standard OpenClaw config agent id from agents_list unless that entry is explicitly configured with agents.entries.*.runtime.type="acp"; otherwise, the default sub-agent runtime is used. When an OpenClaw agent is configured with runtime.type="acp", OpenClaw employs runtime.acp.agent as the underlying harness identifier.

ACP versus sub-agents

Use ACP when you require an external harness runtime. Use the native Codex app-server for Codex conversation binding and control when the codex plugin is active. Use sub-agents when you need OpenClaw-native delegated runs.

Also refer to Sub-agents.

How ACP runs Claude Code

For Claude Code operating through ACP, the stack consists of:

1. The OpenClaw ACP session control plane.
2. The official @openclaw/acpx runtime plugin.
3. The Claude ACP adapter.
4. The Claude-side runtime and session machinery.

ACP Claude functions as a harness session with ACP controls, session resumption, background task tracking, and optional conversation or thread binding.

CLI backends are separate text-only local fallback runtimes. See CLI Backends.

For operators, the practical guideline is:

• Do you need /acp spawn, bindable sessions, runtime controls, or persistent harness work? Use ACP.
• Do you need a simple local text fallback through the raw CLI? Use CLI backends.

Bound sessions

Mental model

• Chat surface - the location where people continue their conversation (Discord channel, Telegram topic, iMessage chat).
• ACP session - the durable Codex, Claude, or Gemini runtime state that OpenClaw routes to.
• Child thread or topic - an optional additional messaging surface created only by --thread ....
• Runtime workspace - the filesystem location (cwd, repo checkout, backend workspace) where the harness executes. This is independent of the chat surface.

Current-conversation binds

/acp spawn <harness> --bind here attaches the current conversation to the spawned ACP session. No child thread is created, and the same chat surface is used. OpenClaw continues to own transport, authentication, safety, and delivery. Subsequent messages in that conversation are routed to the same session. /new and /reset reset the session in place, while /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

Binding rules and exclusivity

• --bind here and --thread ... are mutually exclusive.
• --bind here only functions on channels that advertise current-conversation binding. OpenClaw returns a clear unsupported message otherwise. Bindings persist across gateway restarts.
• On Discord, spawnSessions controls child thread creation 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 or ENOTDIR) fall back to the backend default. Other access errors, such as EACCES, appear as spawn errors.
• Gateway management commands remain local within bound conversations. /acp ... commands are handled by OpenClaw even when normal follow-up text is routed to the bound ACP session. /status and /unfocus also stay local whenever command handling is enabled for that surface.

Thread-bound sessions

When thread bindings are active for a channel adapter:

• OpenClaw attaches a thread to a specific ACP session.
• Subsequent messages in that thread are forwarded to the attached ACP session.
• ACP responses return to the originating thread.
• Removing the binding happens on unfocus, close, archive, idle timeout, or max age expiry.
• /acp close, /acp cancel, /acp status, /status, and /unfocus are Gateway commands, not instructions sent to the ACP harness.

Required feature flags to enable thread bound ACP:

• acp.enabled=true
• acp.dispatch.enabled is enabled by default (set false to stop automatic ACP thread dispatch; explicit sessions_spawn({ runtime: "acp" }) calls remain functional).
• Channel adapter thread session spawning is enabled (default: true):
  • Discord/Telegram: session.threadBindings.spawnSessions=true

Thread binding support varies by adapter. When the active channel adapter does not offer thread binding, OpenClaw returns a clear message indicating the feature is unsupported or unavailable.

Thread-supporting channels

• Any channel adapter that exposes session or thread binding functionality.
• Built in support currently covers: Discord threads and channels, Telegram topics (forum topics in groups, supergroups, and DM topics).
• Plugin channels can add support by implementing the same binding interface.

Persistent channel bindings

For workflows that are not ephemeral, set up persistent ACP bindings inside top level bindings[] entries.

Binding model

• bindings[].type (acp), Defines a persistent ACP conversation binding.

• bindings[].match (object), Points to the target conversation. Per channel shapes: - 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 identifiers; 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.

• bindings[].agentId (string), The OpenClaw agent id that owns this binding.

• bindings[].acp.mode (persistent" | "oneshot), Optional override for the ACP mode.

• bindings[].acp.label (string), Optional label visible to operators.

• bindings[].acp.cwd (string), Optional runtime working directory.

• bindings[].acp.backend (string), Optional override for the backend.

Runtime defaults per agent

Use agents.entries.*.runtime to set ACP defaults once per agent:

• agents.entries.*.runtime.type="acp"
• agents.entries.*.runtime.acp.agent (harness id, for example codex or claude)
• agents.entries.*.runtime.acp.backend
• agents.entries.*.runtime.acp.mode
• agents.entries.*.runtime.acp.cwd

Precedence order for overriding ACP bound sessions:

1. bindings[].acp.*
2. agents.entries.*.runtime.acp.*
3. Global ACP defaults (for instance 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

• After channel specific admission and before use, OpenClaw ensures the configured ACP session exists.
• Messages sent in that channel, topic, or chat are directed to the configured ACP session.
• Configured ACP bindings control their own 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 those created by thread focus flows) still apply when present.
• For cross agent ACP spawns without an explicit cwd, OpenClaw takes the target agent workspace from agent config.
• When the inherited workspace path is missing, the backend default cwd is used; non missing access failures surface as spawn errors.

Start ACP sessions

Two methods for starting an ACP session:

From sessions_spawn

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

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

Note

The default value for runtime is subagent, so for ACP sessions you need to explicitly configure runtime: "acp". When agentId is not provided, OpenClaw will fall back to acp.defaultAgent during setup. A persistent bound conversation requires mode: "session" and thread: true.

Using /acp

From chat, you can run /acp spawn for direct operator control.

/acp spawn codex --mode persistent --thread auto
/acp spawn codex --mode oneshot --thread off
/acp spawn codex --bind here
/acp spawn codex --thread here

Important flags:

• --mode persistent|oneshot
• --bind here|off
• --thread auto|here|off
• --cwd <absolute-path>
• --label <name>

Refer to the Slash commands documentation.

sessions_spawn parameters

• task (string, required), The initial prompt delivered to the ACP session.

• runtime (acp, required), For ACP sessions, this value must be "acp".

• agentId (string), Identifies the ACP target harness. If acp.defaultAgent is configured, this falls back to that value.

• thread (boolean, default: false), Where supported, requests thread binding flow.

• mode (run" | "session, default: run), A "run" run is one-shot, while "session" runs persist. If thread: true is set and mode is missing, OpenClaw may default to persistent behavior based on the runtime path. mode: "session" requires thread: true.

• cwd (string), The requested runtime working directory, validated by backend and runtime policy. When omitted, the ACP spawn inherits the target agent's workspace if configured; missing inherited paths use backend defaults, and actual access errors are reported back.

• label (string), An operator-facing label shown in session and banner text.

• resumeSessionId (string), Resumes an existing ACP session rather than starting a new one. The agent replays its conversation history through session/load. This option requires runtime: "acp".

• streamTo (parent), Through "parent", initial ACP run progress summaries are streamed back to the requester session as system events. OpenClaw stores the full relay history in the child agent's SQLite state and removes it along with the child session. By default, parent progress streams display assistant commentary and ACP status progress unless streaming.progress.commentary=false is set. On Discord, parent previews also default to progress mode when no stream mode is configured. Status progress still respects acp.stream.tagVisibility, so tags like plan stay hidden unless explicitly enabled.

ACP sessions_spawn runs use agents.defaults.subagents.runTimeoutSeconds as their default child turn limit. Per-call timeout overrides are not accepted by this tool; runTimeoutSeconds and timeoutSeconds are rejected with a config-the-default error.

• model (string), Overrides the model used by the ACP child session. Codex ACP spawns normalize OpenAI references, such as openai/gpt-5.4, to Codex ACP startup config before session/new; slash forms like openai/gpt-5.4/high also set Codex ACP reasoning effort. When omitted, sessions_spawn({ runtime: "acp" }) uses existing subagent model defaults (agents.defaults.subagents.model or agents.entries.*.subagents.model) if configured; otherwise the ACP harness uses its own default model. Other harnesses must advertise ACP models and support session/set_model; otherwise OpenClaw or acpx fails clearly rather than silently falling back to the target agent's default.

• thinking (string), Explicitly sets thinking or reasoning effort. For Codex ACP, minimal maps to low effort, low, medium, high, and xhigh map directly, and off omits the reasoning-effort startup override. When omitted, ACP spawns use existing subagent thinking defaults and per-model agents.defaults.models["provider/model"].params.thinking for the selected model.

Spawn bind and thread modes

--bind here|off

Notes:

• --bind here represents the easiest operator route to "make this channel or chat Codex-backed."
• --bind here does not generate a child thread.
• --bind here works exclusively on channels that support current-conversation binding.
• --bind and --thread are mutually exclusive within a single /acp spawn invocation.

--thread auto|here|off

Notes:

• On surfaces that do not support thread binding, the default behavior matches off.
• Thread-bound spawning depends on channel policy support:
  • Discord/Telegram: session.threadBindings.spawnSessions=true
• Reach for --bind here when you want to fix the current conversation in place without spinning up a child thread.

Delivery model

ACP sessions come in two forms: interactive workspaces or background tasks owned by a parent. The delivery mechanism depends on which shape the session takes.

Interactive ACP sessions

Interactive sessions are designed for ongoing conversation on a visible chat surface:

• /acp spawn ... --bind here ties the current conversation to the ACP session.
• /acp spawn ... --thread ... ties a channel thread or topic to the ACP session.
• A persistent bindings[].type="acp" configuration routes conversations to the same ACP session.

Subsequent messages within the bound conversation go directly to the ACP session, and ACP output is returned to that same channel, thread, or topic.

What OpenClaw passes to the harness:

• Standard bound follow-ups are transmitted as prompt text, with attachments included only when the harness or backend supports them.
• /acp management commands and local Gateway commands are caught before ACP dispatch.
• Completion events generated at runtime are materialized per target. OpenClaw agents receive OpenClaw's internal runtime-context envelope; external ACP harnesses receive a plain prompt containing the child result and instruction. The raw <<<BEGIN_OPENCLAW_INTERNAL_CONTEXT>>> envelope must never be forwarded to external harnesses or stored as ACP user transcript text.
• ACP transcript entries use the user-visible trigger text or the plain completion prompt. Internal event metadata stays structured within OpenClaw where possible and is not treated as user-authored chat content.

Parent-owned one-shot ACP sessions

One-shot ACP sessions spawned by another agent run as background children, much like sub-agents:

• The parent requests work using sessions_spawn({ runtime: "acp", mode: "run" }).
• The child runs inside its own ACP harness session.
• The child's turn executes on the same background lane used by native sub-agent spawns, so a slow ACP harness does not block unrelated main-session work.
• Completion is reported 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 never see OpenClaw-only runtime context markers.
• When a user-facing reply is beneficial, the parent rewrites the child result in a normal assistant voice.

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.

sessions_send and A2A delivery

sessions_send can target another session after spawning. For normal peer sessions, OpenClaw uses an agent-to-agent (A2A) follow-up path after injecting the message:

• Wait for the target session to reply.
• Optionally allow the requester and target to exchange a limited 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 serves as a fallback for peer sends where the sender needs a visible follow-up. It remains 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 scenario, running A2A on top of task completion could 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 already handles the result.

Resume an existing session

Use resumeSessionId to resume a previous ACP session rather than beginning a new one. The agent replays its conversation history via session/load, so it picks up with the full context of what happened before.

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

Common use cases:

• Transfer a Codex session from your laptop to your phone by asking your agent to pick up where you left off.
• Continue a coding session you started interactively in the CLI, now running headlessly through your agent.
• Resume work that was interrupted by a gateway restart or idle timeout.

Notes:

• resumeSessionId applies only when runtime: "acp"; the default sub-agent runtime ignores this ACP-only field.
• streamTo applies only when runtime: "acp"; the default sub-agent runtime ignores this ACP-only field.
• resumeSessionId is a host-local ACP or harness resume identifier, not an OpenClaw channel session key. OpenClaw still checks ACP spawn policy and target agent policy before dispatch, while the ACP backend or harness is responsible for authorizing the loading of that upstream identifier.
• 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 identifier is not found, the spawn fails with a clear error. There is no silent fallback to a new session.

Post-deploy smoke test

After a gateway deployment, run a live end-to-end check instead of relying on unit tests:

1. Confirm 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 the absence of any validator error.
5. Tear down the temporary bridge session.

Keep the gate on mode: "run" and skip streamTo: "parent" because thread-bound mode: "session" and stream-relay paths are separate, richer integration passes.

Sandbox compatibility

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

Warning

Security boundary:

• The external harness can read and 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:

• When the requester session runs in a sandboxed environment, ACP spawn operations are disallowed for both sessions_spawn({ runtime: "acp" }) and /acp spawn.
• sessions_spawn combined with runtime: "acp" offers no support for sandbox: "require".

Session target resolution

An optional session target (session-key, session-id, or session-label) can be provided to most /acp actions.

How resolution works:

1. A direct target argument (or --session for /acp steer)
   • checks a key first
   • then a UUID-formatted session id
   • finally a label
2. The current thread binding (when a conversation or thread is linked to an ACP session).
3. A fallback to the current requester session.

Step 2 includes both conversation bindings and thread bindings.

If no target can be resolved, OpenClaw returns a descriptive 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) demand owner identity from external channels, while internal Gateway clients must supply operator.admin. Even non-owner senders who are authorized may still employ sessions, doctor, install, and help. For senders who are not the owner, /acp sessions shows only the session currently bound or requested; the owner identity and operator.admin clients can view every recent session.

/acp status displays the active runtime options along with session identifiers at both the runtime and backend levels. When a backend lacks a particular capability, unsupported-control errors appear clearly. Commands that accept target tokens (session-key, session-id, or session-label) resolve them using gateway session discovery, including custom per-agent session.store roots. A target token is not accepted by /acp sessions.

Runtime options mapping

/acp provides 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

Note

Command blocked by PreToolUse hook: Native hook relay unavailable belongs to the native Codex hook relay, not to ACP or acpx. In a bound Codex chat, begin a new session with /new or /reset; if it works once and then reappears on the next native tool call, restart the Codex app-server or OpenClaw Gateway instead of repeating /new. See Codex harness troubleshooting.

Related

• Setting up ACP agents
• Sending from an agent
• Backends via CLI
• The Codex harness
• Codex harness at runtime
• Sandbox tools for multiple agents
• openclaw acp (bridge mode)
• Sub-agents