OpenClaw ACP Bridge

The clean mental model is this: openclaw acp is a bridge into OpenClaw, not a miniature editor runtime living inside it.

Think of it like a switchboard. Your editor or ACP client calls the bridge, the bridge connects to the OpenClaw Gateway, and the Gateway routes the work into a session. Useful, direct, and much less magical than people assume.

According to the official OpenClaw ACP docs, the bridge speaks ACP over stdio, forwards prompts to the Gateway over WebSocket, and keeps ACP sessions mapped to Gateway session keys. The official MCP docs describe a separate surface again. That split is the whole story here.

What the ACP bridge actually is

In bridge mode, OpenClaw acts as an ACP server. An IDE or another ACP-aware client connects to openclaw acp. OpenClaw then forwards that work into a Gateway session.

That means the bridge is mainly about session routing, prompt delivery, and basic streaming updates. It is not trying to reproduce every editor-native ACP feature. The docs are blunt about that, which is refreshing.

# local Gateway
openclaw acp

# remote Gateway
openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

# attach to a specific session
openclaw acp --session agent:main:main

The three surfaces people keep mixing up

If you remember nothing else, remember the direction of travel. ACP bridge means the client talks inward to OpenClaw. ACP harness mode means OpenClaw talks outward to another runtime. MCP serve is a different protocol and a different operating model again.

ACP bridge vs ACP harness sessions

This is where most wrong setups begin. The words look similar, so people assume the behavior is similar. It is not.

With the bridge, your editor is asking OpenClaw for an ACP session surface. With ACP agents, OpenClaw is launching an external harness through the ACP backend plugin, usually acpx. That harness owns its own provider auth, model catalog, filesystem behavior, and native tools.

• Bridge mode: good when an ACP-aware editor wants to use an OpenClaw agent
• Harness mode: good when OpenClaw should run Claude Code, Gemini CLI, explicit Codex ACP, or another external coding runtime
• Sub-agents: good when you want OpenClaw-native delegation without pulling in an external harness runtime

Another practical difference: the docs explicitly warn that ACP is the external-harness path, not the default Codex path. If native Codex binding is available and that is what you want, ACP is not automatically the winner.

ACP bridge vs openclaw mcp serve

A lot of people ask the wrong question here. They ask, “Which one is better?” The real question is, “Which protocol does my client expect, and who should own the conversation surface?”

Use openclaw acp when the client speaks ACP and wants an ACP session shape. Use openclaw mcp serve when the client speaks MCP and needs conversation tools like reading transcripts, waiting for events, and sending replies back through existing channel routes.

MCP serve is not a drop-in ACP replacement with different branding. The docs describe it as an MCP server that exposes OpenClaw-backed conversations. That is a different contract.

What works well in bridge mode today

The bridge is already useful. The docs list core flow support for session creation, prompts, cancellation, session listing, and slash commands. That covers the main path most people need first.

It also supports some partial surfaces that matter in practice, including loadSession, image attachment handling, session mode controls, best-effort usage updates, and tool streaming. That is enough to feel like a real bridge, not a toy.

What the bridge does not promise

This is the part worth reading before you wire it into an editor and blame the wrong layer later.

• loadSession is partial: text history comes back, but historic tool calls and richer event history are not fully reconstructed
• Per-session mcpServers are unsupported: configure MCP on the gateway or agent side instead
• Client filesystem methods are unsupported: the bridge does not call ACP client file APIs
• Client terminal methods are unsupported: no ACP-native terminal creation or terminal id streaming
• Thought and plan streaming are unsupported: the bridge focuses on output text and tool status, not full ACP-native reasoning UX
• Usage updates are best-effort: they come from cached Gateway snapshots, not perfect ACP-native accounting

None of that makes the bridge bad. It just means you should treat it as a routing surface with a defined support boundary, not as a universal editor emulation layer.

Permission boundaries are different on purpose

Here is a subtle trap. People see ACP in both bridge mode and harness mode and assume the permission model is shared. The docs say otherwise.

Bridge-mode approval policy is its own thing. For example, the ACP client debug mode uses narrow auto-approval rules for trusted read-only classes, while mutating tools and interactive flows still require explicit approval. ACPX harness permissions are separate again. That matters because the bridge is forwarding into Gateway policy, while harness sessions are running a real external runtime with its own behavior and permission profile.

Put differently: same acronym, different trust boundary.

When ACP is the right path for coding-agent work

Use ACP harness sessions when you explicitly want the external harness. That usually means one of three things:

• you want Claude Code, Gemini CLI, Cursor, OpenCode, or another supported ACP harness to do the work
• you want ACP-specific session controls, bindings, or thread behavior
• you want OpenClaw to orchestrate an external coding runtime instead of doing the run natively

If none of those are true, do not force ACP into the picture just because it sounds advanced. Native sub-agents are cleaner for OpenClaw-native delegated work, and native Codex remains the documented default path when that plugin is enabled and you are really asking for Codex binding.

# explicit ACP harness work from chat
/acp spawn claude --bind here

# ACP harness work from tools
sessions_spawn({
  runtime: "acp",
  agentId: "gemini",
  mode: "session",
  thread: true,
})

A simple decision rule

• Your editor wants ACP into OpenClaw → use openclaw acp
• OpenClaw should run an external harness → use ACP agents or runtime: "acp"
• Your external client wants MCP conversations → use openclaw mcp serve

That rule saves an absurd amount of confusion.

The short version

The ACP bridge is a control surface, not a whole editor runtime. It gives ACP-aware clients a clean way into Gateway sessions. ACP harness sessions do the opposite: they let OpenClaw launch an external coding runtime. MCP serve is separate again.

Once you stop treating those three paths like synonyms, the setup choices get much less dramatic.