Integrate External Coding Harnesses with OpenClaw ACP

Agent Client Protocol (ACP) sessions let you run external coding harnesses like Pi, Claude Code, Codex, OpenCode, and Gemini CLI through an ACP backend plugin.

When you ask OpenClaw in plain language to “run this in Codex” or “start Claude Code in a thread”, it routes that request to the ACP runtime instead of the native sub-agent runtime.

Fast operator flow

Use this when you want a practical /acp runbook:

1. Spawn a session:

• /acp spawn codex --mode persistent --thread auto

2. Work in the bound thread (or target that session key explicitly).
3. Check runtime state:

• /acp status

4. Tune runtime options as needed:

• /acp model <provider/model>
• /acp permissions <profile>
• /acp timeout <seconds>

5. Nudge an active session without replacing context:

• /acp steer tighten logging and continue

6. Stop work:

• /acp cancel (stop current turn), or
• /acp close (close session + remove bindings)

Quick start for humans

You can use natural requests like these:

• “Start a persistent Codex session in a thread here and keep it focused.”
• “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.”

Here is what OpenClaw does behind the scenes:

1. It picks runtime: "acp".
2. It resolves the harness target you requested (the agentId, such as codex).
3. If you asked for thread binding and the current channel supports it, it binds the ACP session to the thread.
4. It routes follow-up thread messages to that same ACP session until it is unfocused, closed, or expired.

ACP versus sub-agents

Pick ACP when you want an external harness runtime. 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	agent:<agentId>:acp:<uuid>	agent:<agentId>:subagent:<uuid>
Main commands	/acp ...	/subagents ...
Spawn tool	sessions_spawn with runtime:"acp"	sessions_spawn (default runtime)

You can also see Sub-agents.

Thread-bound sessions (channel-agnostic)

When you enable thread bindings for a channel adapter, you can bind ACP sessions to threads:

• OpenClaw binds a thread to a target

Channel specific settings

If you are working on non-ephemeral workflows, you need to configure persistent ACP bindings. You do this in the top-level bindings[] entries of your configuration.

Binding model

To set up a persistent ACP conversation binding, use bindings[].type="acp". You identify your target conversation using the match object:

• For Discord channels or threads: Use match.channel="discord" and match.peer.id="<channelOrThreadId>".
• For Telegram forum topics: Use match.channel="telegram" and match.peer.id="<chatId>:topic:<topicId>".

You must also specify the agentId for the OpenClaw agent that owns the binding. If you need to override specific ACP settings like the mode (persistent or oneshot), label, cwd, or backend, you can place those under bindings[].acp.

Runtime defaults per agent

You can define ACP defaults once per agent using agents.list[].runtime. This keeps your configuration clean. You can set the type="acp", the agent (harness id, such as codex or claude), and other settings like backend, mode, or cwd.

When OpenClaw resolves settings for an ACP bound session, it follows this order of precedence:

1. Settings in bindings[].acp.*
2. Settings in agents.list[].runtime.acp.*
3. Global ACP defaults (like acp.backend)

Here is an example of how this looks in practice:

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

When you use this setup, OpenClaw ensures the ACP session exists before it is used. Messages in the configured channel or topic are automatically routed to that session. In these bound conversations, using /new or /reset will reset the same ACP session key in place. Any temporary runtime bindings, like those created by thread-focus flows, will still apply if they are present.

Start ACP sessions (interfaces)

From sessions_spawn

You can start an ACP session directly from an agent turn or a tool call by using runtime: "acp".

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

Keep in mind that runtime defaults to subagent, so you must explicitly set it to "acp". If you omit the agentId, OpenClaw will use the acp.defaultAgent if you have one configured. Also, mode: "session" requires you to set thread: true to maintain a persistent bound conversation.

The interface includes several parameters:

• task (required): The initial prompt for the ACP session.
• runtime (required for ACP): This must be "acp".
• agentId (optional): The ACP target harness id.
• thread (optional): Set to true to request a thread binding flow.
• mode (optional): Choose run for one-shot or session for persistent work.
• cwd (optional): The requested working directory.
• label (optional): A label for the session.
• resumeSessionId (optional): Use this to pick up an existing session.
• streamTo (optional): Set to "parent" to stream progress summaries back to the requester.

Resume an existing session

If you want to continue where you left off, use resumeSessionId. This tells the agent to replay its conversation history using session/load, so it has the full context of the previous work.

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

This is useful for handing off a session from your laptop to your phone, or continuing a CLI session headlessly. Just remember that the target agent must support session/load (like Codex or Claude Code). If the session ID is not found, the spawn will fail with an error rather than starting a new session.

Operator smoke test

After deploying a gateway, you should run a smoke test to verify that ACP spawning works end-to-end.

Follow these steps:

1. Verify the gateway version on the host.
2. Confirm the source includes ACP lineage acceptance in src/gateway/sessions-patch.ts.
3. Open a temporary ACPX bridge session to a live agent.
4. Ask that agent to call sessions_spawn with the following details:

• runtime: "acp"
• agentId: "codex"
• mode: "run"
• task: Reply with exactly LIVE-ACP-SPAWN-OK

5. Check that the agent reports accepted=yes and a real childSessionKey.
6. Clean up the temporary bridge session.

You can use this prompt for the live agent:

Use the sessions_spawn tool now with runtime: "acp", agentId: "codex", and mode: "run".
Set the task to: "Reply with exactly LIVE-ACP-SPAWN-OK".
Then report only: accepted=<yes/no>; childSessionKey=<value or none>; error=<exact text or none>.

Stick to mode: "run" for basic checks. You don’t need streamTo: "parent" for this initial gate.

Sandbox compatibility

You should know that ACP sessions currently run on the host runtime. They do not run inside the OpenClaw sandbox.

This leads to a few limitations:

• If your requester session is sandboxed, ACP spawns are blocked. You will see an error suggesting you use runtime: "subagent".
• You cannot use sandbox: "require" with sessions_spawn when using runtime: "acp".

If you need execution enforced by a sandbox, use runtime: "subagent".

From /acp command

For manual control from chat, you can use the /acp spawn command.

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

You can use flags like --mode, --thread, --cwd, and --label. You can find more details in the Slash Commands documentation.

Session target resolution

Most /acp actions let you specify a session target using a key, ID, or label. OpenClaw resolves the target in this specific order:

1. An explicit target argument (or --session for /acp steer). It checks the key, then the UUID, then the label.
2. The current thread binding, if the conversation is already bound to an ACP session.
3. The current requester session fallback.

If no target is found, you will receive a clear error message.

AI Setup Assistant

Spawn thread modes

When you use /acp spawn, you can control how the session handles threading with the --thread auto|here|off flag.

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, the default behavior is effectively off.
• Thread-bound spawn requires specific channel policy support:
• Discord: channels.discord.threadBindings.spawnAcpSessions=true
• Telegram: channels.telegram.threadBindings.spawnAcpSessions=true

ACP controls

You have a full family of commands available to manage your work:

• /acp spawn
• /acp cancel
• /acp steer
• /acp close
• /acp status
• /acp set-mode
• /acp set
• /acp cwd
• /acp permissions
• /acp timeout
• /acp model
• /acp reset-options
• /acp sessions
• /acp doctor
• /acp install

When you run /acp status, you can see the effective runtime options. If they are available, the command shows both runtime-level and backend-level session identifiers.

Some of these controls depend on what your backend can do. If a backend does not support a control, OpenClaw returns a clear unsupported-control error so you know exactly what happened.

ACP command cookbook

When you are working with ACP, you need a quick way to find the right command for the job. This reference table helps you manage your sessions and configurations without searching through help menus.

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

Runtime options mapping

The /acp tool includes several convenience commands that act as shortcuts. Instead of using a generic setter every time, you can use these direct commands to update your runtime configuration.

Here is how these operations map to the underlying config keys:

• /acp model <id> maps to runtime config key model.
• /acp permissions <profile> maps to runtime config key approval_policy.
• /acp timeout <seconds> maps to runtime config key timeout.
• /acp cwd <path> updates runtime cwd override directly.
• /acp set <key> <value> is the generic path.
• Special case: key=cwd uses the cwd override path.
• /acp reset-options clears all runtime overrides for target session.

acpx harness support (current)

You have several built-in harness aliases available right now when using acpx. These include:

• pi
• claude
• codex
• opencode
• gemini
• kimi

When you set up OpenClaw to use the acpx backend, you should use these values for your agentId. The only exception is if your specific acpx configuration defines its own custom agent aliases.

You might notice that direct acpx CLI usage allows you to target any adapter with the --agent <command> flag. Just remember that this is a raw escape hatch specific to the CLI and doesn’t follow the standard OpenClaw agentId path.

Required config

To get started, you need to set up the core ACP baseline in your configuration. Use this structure:

{
  acp: {
    enabled: true,
    // Optional. Default is true; set false to pause ACP dispatch while keeping /acp controls.
    dispatch: { enabled: true },
    backend: "acpx",
    defaultAgent: "codex",
    allowedAgents: ["pi", "claude", "codex", "opencode", "gemini", "kimi"],
    maxConcurrentSessions: 8,
    stream: {
      coalesceIdleMs: 300,
      maxChunkChars: 1200,
    },
    runtime: {
      ttlMinutes: 120,
    },
  },
}

Configuring thread binding depends on your specific channel adapter. If you are using Discord, here is how you handle that setup:

{
  session: {
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0,
    },
  },
  channels: {
    discord: {
      threadBindings: {
        enabled: true,
        spawnAcpSessions: true,
      },
    },
  },
}

If your thread-bound ACP sessions fail to spawn, you should check the adapter feature flag first. For Discord users, verify this specific setting:

• Discord: channels.discord.threadBindings.spawnAcpSessions=true

For more details, check the Configuration Reference.

Plugin setup for acpx backend

You can get the acpx backend up and running by installing and enabling the plugin. It only takes two commands to get started:

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

If you are working on a local workspace during development, you can install the plugin directly from your local path:

openclaw plugins install ./extensions/acpx

Once that is done, you should verify that the backend is healthy:

/acp doctor

acpx command and version configuration

By default, the acpx plugin (published as @openclaw/acpx) uses its own pinned binary. Here is how the process works:

1. The command defaults to extensions/acpx/node_modules/.bin/acpx.
2. The expected version defaults to the extension pin.
3. The ACP backend registers as not-ready immediately during startup.
4. A background job runs to verify acpx --version.
5. If the binary is missing or the version does not match, it runs npm install --omit=dev --no-save acpx@<pinned> and checks again.

You can override the command or version in your plugin configuration if you need a custom setup:

{
  "plugins": {
    "entries": {
      "acpx": {
        "enabled": true,
        "config": {
          "command": "../acpx/dist/cli.js",
          "expectedVersion": "any"
        }
      }
    }
  }
}

A few things to keep in mind:

• The command field accepts absolute paths, relative paths, or a command name like acpx.
• Relative paths are resolved from your OpenClaw workspace directory.
• Setting expectedVersion: "any" stops the plugin from enforcing strict version matching.
• When you point command to a custom binary or path, the auto-install feature is disabled.
• OpenClaw startup remains non-blocking while the backend health check runs.

See Plugins.

Permission configuration

ACP sessions are non-interactive. This means there is no TTY for you to approve or deny requests when the agent wants to write files or execute shell commands. You can control how the plugin handles these permissions using two specific configuration keys.

permissionMode

This setting controls which operations the agent can perform without asking for permission.

Value	Behavior
approve-all	Auto-approve all file writes and shell commands.
approve-reads	Auto-approve reads only; writes and exec require prompts.
deny-all	Deny all permission prompts.

nonInteractivePermissions

This setting determines what happens when a permission prompt is triggered but no interactive TTY is available.

Value	Behavior
fail	Abort the session with AcpRuntimeError. (default)
deny	Silently deny the permission and continue (graceful degradation).

Configuration

You can set these values through the CLI. Remember to restart your gateway after you change these settings.

openclaw config set plugins.entries.acpx.config.permissionMode approve-all
openclaw config set plugins.entries.acpx.config.nonInteractivePermissions fail

Important: OpenClaw currently defaults to permissionMode=approve-reads and nonInteractivePermissions=fail. In non-interactive ACP sessions, any write or exec command that triggers a permission prompt will fail with AcpRuntimeError: Permission prompt unavailable in non-interactive mode.

If you need to restrict permissions, set nonInteractivePermissions to deny so your sessions can degrade gracefully instead of crashing.

Troubleshooting

If you run into issues, check this table for common symptoms and their fixes.

Symptom	Likely cause	Fix
ACP runtime backend is not configured	Backend plugin missing or disabled.	Install and enable backend plugin, then run /acp doctor.
ACP is disabled by policy (acp.enabled=false)	ACP globally disabled.	Set acp.enabled=true.
ACP dispatch is disabled by policy (acp.dispatch.enabled=false)	Dispatch from normal thread messages disabled.	Set acp.dispatch.enabled=true.
ACP agent "<id>" is not allowed by policy	Agent not in allowlist.	Use allowed agentId or update acp.allowedAgents.
Unable to resolve session target: ...	Bad key/id/label token.	Run /acp sessions, copy exact key/label, retry.
--thread here requires running /acp spawn inside an active ... thread	--thread here used outside a thread context.	Move to target thread or use --thread auto/off.
Only <user-id> can rebind this thread.	Another user owns thread binding.	Rebind as owner or use a different thread.
Thread bindings are unavailable for <channel>.	Adapter lacks thread binding capability.	Use --thread off or move to supported adapter/channel.
Sandboxed sessions cannot spawn ACP sessions ...	ACP runtime is host-side; requester session is sandboxed.	Use runtime="subagent" from sandboxed sessions, or run ACP spawn from a non-sandboxed session.
sessions_spawn sandbox="require" is unsupported for runtime="acp" ...	sandbox="require" requested for ACP runtime.	Use runtime="subagent" for required sandboxing, or use ACP with sandbox="inherit" from a non-sandboxed session.
Missing ACP metadata for bound session	Stale/deleted ACP session metadata.	Recreate with /acp spawn, then rebind/focus thread.
AcpRuntimeError: Permission prompt unavailable in non-interactive mode	permissionMode blocks writes/exec in non-interactive ACP session.	Set plugins.entries.acpx.config.permissionMode to approve-all and restart gateway. See Permission configuration.
ACP session fails early with little output	Permission prompts are blocked by permissionMode/nonInteractivePermissions.	Check gateway logs for AcpRuntimeError. For full permissions, set permissionMode=approve-all; for graceful degradation, set nonInteractivePermissions=deny.
ACP session stalls indefinitely after completing work	Harness process finished but ACP session did not report completion.	Monitor with ps aux | grep acpx; kill stale processes manually.

AI Setup Assistant