Internals

ACP & MCP

9 min

Understand OpenClaw's ACP bridge, ACP agents, MCP server paths, and how these protocol surfaces differ in coding-agent workflows.

OpenClaw now sits near several agent protocols. The names are easy to confuse, so start with roles.

Three Different Roles

SurfaceOpenClaw's roleUse it when
openclaw acpACP server/bridgeAn editor or ACP client wants to talk to an OpenClaw Gateway session
ACP agentsHarness orchestratorOpenClaw should launch Codex, Claude Code, Gemini CLI, OpenCode, or another backend
MCPTool/context integrationAn MCP client/server needs access to OpenClaw conversations or capabilities

The key question is: who is the client, who owns the session, and who runs the tools?

ACP Bridge

openclaw acp speaks Agent Client Protocol over stdio and forwards prompts to a Gateway over WebSocket.

bash
openclaw acp
openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token
openclaw acp --session agent:main:main

Use this when an ACP-compatible editor or client wants an OpenClaw-backed agent session.

The bridge focuses on:

  • session creation and resumption
  • prompt forwarding
  • basic streaming updates
  • cancellation
  • session listing
  • best-effort usage updates
  • permission relay for active prompt turns

It is not a full ACP-native editor runtime.

ACP Agents

ACP agents are different. In this mode, OpenClaw launches an external coding harness through an ACP backend.

Use this when you want OpenClaw to coordinate:

  • Codex
  • Claude Code
  • Gemini CLI
  • OpenCode
  • another compatible ACP harness

This is useful for delegating coding work while keeping Gateway routing, sessions, channels, and delivery around the run.

MCP

MCP paths let external tools or clients interact with OpenClaw conversations or capability surfaces.

Common use cases:

  • expose channel conversations to an MCP client
  • connect OpenClaw-adjacent tools into another agent environment
  • route coding or ops context without writing a custom integration

If an external MCP client should talk directly to OpenClaw channel conversations, start from:

bash
openclaw mcp serve

Permission Model

Protocol bridges are not magic security boundaries. Check:

  • Gateway auth
  • device/session identity
  • tool policy
  • exec approvals
  • sandbox settings
  • provider limitations
  • whether tools run in OpenClaw, in the external harness, or in the client environment

ACP and MCP flows can make authority feel indirect. Document which side owns filesystem access and command execution.

Debugging

For ACP bridge issues:

bash
openclaw gateway status
openclaw acp client
openclaw sessions list
openclaw logs --follow

For ACP agents, inspect the backend/harness config and task/session state:

bash
openclaw tasks list
openclaw sessions list

For MCP, verify the server definition, transport, and auth path.

Choosing the Right Path

  • Editor wants OpenClaw: use openclaw acp.
  • OpenClaw wants an external coding harness: use ACP agents.
  • Another tool wants structured context/capabilities: use MCP.
  • User just wants chat: use Control UI, WebChat, CLI, or a channel.

Protocol clarity

ACP and MCP are useful only when the ownership boundary is clear. Before integrating, name the session owner, tool executor, filesystem boundary, auth source, and cancellation path.

Continue with practice

You have finished the core ideas of ACP & MCP.

If you want to turn the idea into something reusable, continue practicing on AgentWay.

Go to practice