OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Agent coordination

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?

You want to... Use this Notes
Bind or control Codex in the current conversation /codex bind, /codex threads Native Codex app-server path when the codex plugin is enabled: bound chat replies, image forwarding, model/fast/permissions, stop, and steer. ACP is an explicit fallback
Run Claude Code, Gemini CLI, explicit Codex ACP, or another external harness through OpenClaw This page Chat-bound sessions, /acp spawn, sessions_spawn({ runtime: "acp" }), background tasks, runtime controls
Expose an OpenClaw Gateway session as an ACP server for an editor or client openclaw acp Bridge mode: an IDE/client speaks 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

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.

Page Read it when
ACP agents quickstart You are installing the ACP runtime plugin or choosing a harness target id.
ACP agents operator runbook You run /acp from chat and need the flow, lifecycle, and routing rules.
ACP agents bindings You are binding a conversation, thread, or configured bindings[] entry.
ACP agents sessions You need sessions_spawn parameters or the --bind and --thread modes.
ACP agents delivery model You are debugging completion delivery, resume, or the sandbox boundary.
ACP agents controls You need the /acp command reference and runtime option mapping.
ACP agents troubleshooting You hit an ACP error message and need the likely cause and fix.

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.

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)

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.

Was this useful?
On this page

On this page