An analysis of where OpenClaw’s ACP bridge works, where it diverges from the protocol, and when it is not suitable for your coding agent workflow. OpenClaw ACP Is a Bridge, Not a Full ACP Agent. 

There is a quiet standardisation effort happening in how code editors talk to AI agents. It is called the Agent Client Protocol, or ACP, and if you have been paying attention to the AI tooling space in 2026, you have probably seen it mentioned alongside editors like Zed, agents like Claude Code and Codex, and a growing ecosystem of integrations on both sides. The idea behind ACP is the same one that made the Language Server Protocol successful: define a shared contract so that any agent can work with any editor. One protocol. No custom integrations for every combination of agent and IDE.

OpenClaw, a platform for running AI agents across channels like Discord, Telegram, and the web, recently shipped ACP support. Their openclaw acp command launches a stdio server that IDEs can connect to. It uses the official @agentclientprotocol/sdk TypeScript package. The documentation describes it as an ACP bridge for IDE integration.

We read the source code. All of it. The implementation is real and production-worthy and it is not slop. The engineering is competent, the TypeScript is well-typed, and there are tests. But it is also not what the ACP label implies if you are expecting the full protocol experience inside your editor. The gap between what OpenClaw implements and what ACP specifies is significant enough to affect your decision if you are evaluating ACP agents for IDE workflows. This post lays out exactly where that gap is.

What ACP Promises

Before we evaluate any implementation, it helps to understand what ACP was designed to do. ACP is a JSON-RPC 2.0 protocol over stdio. The spec is public, the schema is machine-readable, and there are official SDKs in TypeScript, Rust, Python, and Kotlin. It emerged from the Zed editor team and has since been adopted by a growing number of agents and clients across the ecosystem.

The protocol defines a structured lifecycle. First, the client and agent initialize by exchanging version numbers and capabilities. Then the client creates or loads a session, providing a working directory and optional MCP (Model Context Protocol) server configurations for tooling. After that, prompt turns begin: the user sends a message, the agent processes it, and results stream back through notifications carrying text chunks, tool calls, execution plans, and file diffs. There are two things make ACP more than a chat API.

The first is two-way communication. The client calls the agent with prompts and cancellations. The agent can call the client back to read and write files, execute terminal commands, and request permission before taking sensitive actions. Both directions are part of the protocol contract.

The second is structured output. Tool calls carry status updates, content blocks, diff payloads, and file locations. The agent can share its execution plan. Session configuration options are negotiable. When a session is loaded, the agent replays conversation history so the IDE can reconstruct its UI. This is the experience ACP is designed to enable. Now let us look at what happens when OpenClaw implements it.

The Architecture: A Bridge, Not an Agent

Everything we found traces back to one architectural decision. OpenClaw does not implement a native ACP agent. It implements a translator between the ACP protocol and its proprietary Gateway, which communicates over WebSocket. The flow looks like this:

IDE/Client --> ACP over stdio ──>  OpenClaw Bridge ──> WebSocket ──>  Gateway  ──>  Agent

The bridge is a class called AcpGatewayAgent that implements the SDK’s Agent interface. When your IDE sends a prompt, the bridge converts it into a Gateway chat.send call. When the Gateway emits events, the bridge translates them back into ACP session/update notifications.

This is a legitimate architecture for a platform that already has a Gateway managing agent execution. The problem is that ACP features only work if someone explicitly mapped them through this translation layer. Features that were not mapped are silently dropped. And several features that were mapped behave differently from what the spec describes. The docs for the OpenClaw ACP is here, some of the user on the X who worked on the OpenClaw implementation claimed that they would not use it as it only works on the yolo-mode. This sounds like aligned with what OpenClaw is but might not follow the ACP protocol strictly.

Where OpenClaw Diverges from ACP

We organized our findings into three categories: protocol divergences where behavior contradicts the spec, capability gaps where optional but practically important features are missing, and behavioral risks where implemented features have correctness issues.

Protocol Divergences

These are cases where the ACP specification defines a behavior and OpenClaw does something different.

• Session resume does not replay history.

This is the most consequential divergence. When a user reopens a previous session, the ACP spec expects the agent to replay prior conversation messages through session/update notifications before completing the load response. This is how the IDE reconstructs the conversation thread, restores tool call state, and shows the user what happened before. OpenClaw’s loadSession creates a fresh internal session mapping and returns an empty response immediately. The conversation history exists on the Gateway, but the IDE/Client never receives it. Reopen a session in your editor and you get a blank thread.

• MCP server configurations are discarded.

ACP session setup includes an mcpServers field so clients can provide tool and context integrations to the agent. These might be database connectors, API wrappers, or custom development tools that the IDE user has configured.OpenClaw drops them in both newSession and loadSession:

if (params.mcpServers.length > 0) {
  this.log(`ignoring ${params.mcpServers.length} MCP servers`);
}

The spec treats stdio MCP transport as a baseline capability that agents should handle or at least acknowledge. OpenClaw treats it as irrelevant. Your IDE-configured tools do not reach the agent. It could be because OpenClaw architecture compltely omitted MCP from the implementation and reluctant to support the MCP part but you might already have some sort of MCP config in your coding setup.

• Stop-reason semantics are lossy.

ACP defines five stop reasons, each with distinct meaning: end_turn, max_tokens, max_turn_requests, refusal, and cancelled. OpenClaw maps max_tokens correctly and handles cancelled through its abort flow. But Gateway errors are mapped to refusal, and everything else collapses to end_turn. The max_turn_requests reason is never returned.

This matters for IDE/Client behaviour. A refusal means the agent deliberately chose not to respond. An error means something went wrong. When both arrive with the same label, IDE/Client cannot offer appropriate recovery options or accurate status messages to the user.

• Mode changes can silently fail.

When setSessionMode forwards a mode change to the Gateway and the Gateway rejects it, the bridge catches the error, logs it to stderr, and returns a success response. The IDE believes the mode changed when it did not.

Capability Gaps

These are not strict protocol violations. The features below are optional capabilities in the ACP spec. But they are the capabilities that differentiate ACP from a basic chat API, and they represent what IDE/Client users typically expect when they hear “ACP support.”

• No filesystem method usage.

ACP defines fs/read_text_file and fs/write_text_file so the agent can access files through the editor. This is how agents see unsaved changes in your buffer and how they write modifications the editor can track and display as inline diffs. OpenClaw’s bridge never calls either method. All file operations happen on the Gateway side, invisible to the IDE/Client .

• No terminal method usage.

ACP defines a full terminal lifecycle with five methods: create, output, wait for exit, kill, and release. These let the agent run commands in your local environment with real-time output streaming visible in the IDE. OpenClaw implements none of them. All execution is remote.

• No permission request flow.

ACP’s session/request_permission method lets the agent ask the user before taking sensitive actions. The spec says agents MAY request permission before proceeding with tool execution. It is not required in every case, but it is the mechanism that gives users control over destructive operations. OpenClaw’s bridge never sends these requests. The Gateway executes tools without surfacing approval prompts to the IDE.

There is an irony worth noting here. OpenClaw’s own ACP client code, used in debug mode, has a sophisticated permission resolver with auto-approve allowlists, path scoping, dangerous-tool detection, and a 30-second interactive prompt. It is well-engineered. It just only runs when OpenClaw itself is the client, not when an IDE connects to the bridge.

• No plan updates, limited tool output richness.

The bridge does send session/update notifications for text chunks and basic tool call status. This works and is a meaningful part of the protocol. But it does not send plan entries, thought messages, or configuration option updates. Tool call updates carry status and raw output but not the richer content blocks, diff payloads, or file location annotations that the spec supports as optional fields. The result is a thinner IDE experience than what ACP was designed to enable.

Behavioral Risks

• Cancellation and event routing can cross-wire on shared session keys.

This is a correctness issue in the current implementation. When multiple ACP sessions share one Gateway session key (which is possible through the --session flag), cancelling one session sends an abort for the shared key, affecting all runs on that key rather than just the intended one.

Event routing compounds the problem. Incoming Gateway events are matched to pending prompts by session key, and the bridge returns the first match it finds. If two sessions share a key, responses can route to the wrong one. This is unlikely in typical single-session usage but becomes a real risk in multi-session setups.

The Numbers

Here is how the implementation breaks down across the stable ACP spec surface. We are not counting unstable or draft features like session/stop, message IDs, or $/cancel_request, since scoring those as failures would be unfair to any implementation.

Category	Correct	Partial	Missing
Agent methods (Client to Agent)	4	3	1
Agent-to-Client methods (optional)	0	0	5
Session notification types	2	2	4

The prompt turn flow and basic session management work. The gaps are concentrated in the agent-to-client direction (filesystem, terminals, permissions) and in the richness of session update notifications (plans, config, thought messages).

The session/update mechanism itself is implemented and functional. Text streaming works correctly with proper incremental delta tracking. Tool call notifications emit start and result phases. The gap is not that the agent-to-client channel is silent. It is that the channel carries only a subset of what the protocol defines.

What OpenClaw ACP Does Well

A fair analysis should acknowledge the strengths, and there are real from OpenClaw ACP.

• The basic prompt-to-response flow is solid. Text streams back as proper agent_message_chunk notifications with correct offset tracking. Image attachments are forwarded as base64 payloads. Slash commands are advertised to the IDE through available_commands_update. The session key architecture, mapping ACP session IDs to Gateway keys with support for labels and explicit overrides, is clean and well-designed.
• The defensive engineering is notable. Session creation is rate-limited at 120 per 10 seconds. Prompt payloads are validated at 2MB with block-by-block byte counting before full string assembly, a deliberate mitigation against memory exhaustion. Token and password handling warns about process listing visibility and supports file-based secrets.
• The authenticate method returns an empty response with no auth methods listed, which is valid behavior under the spec when the agent handles authentication through other means. In this case, that means Gateway-level WebSocket auth.

This is why the right conclusion is not “OpenClaw ACP is broken.” The right conclusion is that it is a fit-for-purpose bridge with clear limits that the ACP label does not communicate on its own.

Suitability Guide

OpenClaw ACP is likely not suitable for you if you need:

• Session restore with conversation replay in the IDE/Client
• IDE/Client-visible local file and terminal operations
• Permission-gated tool execution through the editor
• Rich, structured tool output with diffs, plans, and file locations
• Strict per-run cancellation and event correlation in multi-session setups
• MCP tool integration flowing from the IDE to the agent

OpenClaw ACP may be suitable if you need:

• A remote, gateway-managed coding agent accessible from an ACP-compatible editor
• Basic prompt and streaming text response over ACP framing
• Centralized agent management with the IDE as one of several access channels

How to Verify This Yourself

These checks work for evaluating any ACP implementation, not just OpenClaw.

• Check session replay. Connect your ACP client and load an existing session ID. Watch for session/update notifications before the load response completes. If the session loads with an empty conversation, replay is not implemented.
• Check MCP handling. Configure MCP servers in your IDE session setup. If the bridge has a verbose mode, check its logs for how servers are handled. With OpenClaw, --verbose will show “ignoring N MCP servers” on stderr.
• Check tool call permissions. Trigger an action that modifies files. Watch for a session/request_permission request from the agent. If edits happen without any permission prompt surfacing in the IDE, the mechanism is not wired up.
• Check stop-reason accuracy. Force an error condition by disconnecting the backend mid-turn or triggering a timeout. Examine the stop reason in the prompt response. If it says refusal rather than indicating an error, stop reasons are being misrepresented.
• Check cancellation scoping. If the implementation allows multiple sessions on the same backend key, open two and cancel one. If both stop, cancellation is not scoped to individual runs.

What Would Close the Gap

A concrete path toward fuller ACP coverage for OpenClaw would include if they want to:

• Implementing session/load history replay through session/update notifications
• Handling MCP server configurations instead of dropping them
• Scoping cancellation and event routing by run ID rather than session key alone
• Mapping stop reasons accurately to all five ACP-defined values
• Propagating mode and config mutation failures as errors rather than swallowing them
• Wiring up filesystem, terminal, and permission-request methods from agent to client
• Enriching tool call updates with content blocks, diffs, and locations
• Updating documentation to clearly distinguish “bridge scope” from “full ACP behavior”

None of these are architecturally impossible. The bridge pattern does not inherently prevent fuller ACP coverage. It just means every capability needs explicit mapping work, and that work has not been done yet for the deeper parts of the protocol.

Bottom Line

OpenClaw’s ACP implementation is a working bridge between IDE clients and the OpenClaw Gateway. It handles the basic prompt turn flow reliably, and the engineering around it is solid. But “supports ACP” creates an expectation that the protocol contract is broadly met. Today, OpenClaw’s bridge implements the surface of ACP while leaving much of the depth untouched: the two-way file access, the terminal integration, the permission model, the session continuity, the structured output.

If your bar is “remote prompt and response over ACP framing,” it can deliver. If your bar is the deeper IDE agent experience that ACP was designed to enable, you should evaluate accordingly. The protocol spec has the answers. Check whether the implementation meets them.

---

This analysis was conducted independently by reading the OpenClaw source code, the official ACP specification (v0.11.0), and the ACP TypeScript SDK (v0.15.0). All findings are verifiable against publicly available code and documentation. if any questions reach out to us. 

The ACP specification is maintained at agentclientprotocol.com.