ACP agents

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.

​

Which page do I want?

​

ACP agents documentation pages

This page is an index. ACP agents is documented on seven pages, one per reader job. Open the page that matches your task.

​

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.

​

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.

​

Where each section moved

Every section heading from the previous single-page version keeps its anchor here, so an existing link such as /tools/acp-agents#persistent-channel-bindings still resolves. Each entry points at the page that now holds the content.

• Does this work out of the box?
• First-run gotchas
• Runtime prerequisites
• Supported harness targets
• Operator runbook
• Spawn
• Work
• Check state
• Tune
• Steer
• Stop
• Lifecycle details
• Native Codex routing rules
• Model / provider / runtime selection cheat sheet
• ACP-routing natural-language triggers
• Bound sessions
• Mental model
• Current-conversation binds
• Binding rules and exclusivity
• Thread-bound sessions
• Thread-supporting channels
• Persistent channel bindings
• Binding model
• bindings[].type
• bindings[].match
• bindings[].agentId
• bindings[].acp.mode
• bindings[].acp.label
• bindings[].acp.cwd
• bindings[].acp.backend
• Runtime defaults per agent
• Example
• Behavior
• Start ACP sessions
• From sessions_spawn
• From /acp command
• sessions_spawn parameters
• task
• runtime
• agentId
• thread
• mode
• cwd
• label
• resumeSessionId
• streamTo
• model
• thinking
• Spawn bind and thread modes
• --bind here|off
• --thread auto|here|off
• Delivery model
• Interactive ACP sessions
• Parent-owned one-shot ACP sessions
• sessions_send and A2A delivery
• Resume an existing session
• Post-deploy smoke test
• Sandbox compatibility
• Session target resolution
• Session owner and harness
• ACP controls
• Runtime options mapping
• Troubleshooting

​

Related

• ACP agents - setup
• Agent bindings
• Agent send
• CLI Backends
• Codex harness
• Codex harness runtime
• Multi-agent sandbox tools
• openclaw acp (bridge mode)
• Sub-agents
• Steer — redirect a running agent mid-task