OpenClaw ACP Bridge Guide: Connecting Zed to Your Gateway, and When mcp serve Fits Better

openclaw acp lets an editor that speaks the Agent Client Protocol, Zed being the common one, drive a session on your running OpenClaw Gateway. Use it when you want your own agent, with its memory and skills, inside the editor. If the client is Claude Code or Codex and you want it to read and send channel messages, use openclaw mcp serve instead.

The pages that rank for this are the official CLI reference, the docs.claw.so fork, openclawlab, and a pile of jsDelivr copies of old npm tarballs. They list the flags well. None of them tells you which directory the agent works in, or which machine the files get edited on when the Gateway is remote. The official Zed example also leaks a token. Each of those gets its own section below.

What the bridge actually is

The editor launches openclaw acp as a child process and talks ACP to it over stdio. The bridge then forwards each prompt to the Gateway over WebSocket and keeps a map from ACP session IDs to Gateway session keys. Nothing runs in the bridge itself. Everything from the model call down to the exec approval rules lives on the Gateway, so if openclaw gateway status is red, Zed will just sit there.

# local Gateway, fresh isolated session
openclaw acp

# talk to it yourself before wiring an editor
openclaw acp client

openclaw acp client is the step people skip. It is a small interactive ACP client that spawns the bridge for you, and when Zed shows a blank panel it tells you in ten seconds whether the problem is the bridge or the editor config.

Three commands that sound alike

OpenClaw ships three integrations with overlapping names, and the docs cross-reference them without a single place that lines them up. Here they are side by side, with the TUI as a baseline:

The second row is where I disagree with how most people set this up. If what you want is Claude Code answering a support thread, mcp serve gives it conversations_list, messages_read, messages_send, events_wait and the permission tools directly. Routing Claude Code through ACP to get there is the long way around, and Claude Code isn't an ACP client anyway.

Zed setup that doesn't leak your token

The local version is the docs example and it is fine as written. It goes in ~/.config/zed/settings.json:

{
  "agent_servers": {
    "OpenClaw ACP": {
      "type": "custom",
      "command": "openclaw",
      "args": ["acp"],
      "env": {}
    }
  }
}

The remote version is where I'd deviate. The official reference warns you to prefer --token-file or an environment variable because a token on the command line shows up in process listings. Then its own remote Zed example puts "--token", "<token>" straight into args. That is worse than a shell flag. It lands in a settings file that plenty of people commit to a public dotfiles repo, and every time Zed spawns the bridge the token is visible to anyone who can run ps on your laptop. Use the file:

{
  "agent_servers": {
    "OpenClaw ACP": {
      "type": "custom",
      "command": "openclaw",
      "args": [
        "acp",
        "--url", "wss://gateway-host:18789",
        "--token-file", "/Users/you/.openclaw/gateway.token"
      ],
      "env": {}
    }
  }
}

Write the full path. Whether Zed expands ~ inside args is not something I would bet a broken panel on. You can also skip the flags and set gateway.remote.url plus gateway.remote.token in config, or OPENCLAW_GATEWAY_TOKEN in the env block, which at least keeps it out of the process list. For the network path itself I'd put the Gateway on a tailnet before I'd expose 18789 to the internet, and the Tailscale guide covers that.

Session keys decide which agent answers

ACP has no flag for picking an agent. You pick a Gateway session key, and the agent is part of the key. With no flag at all, the bridge mints an isolated session named acp-bridge:<uuid>.

openclaw acp --session agent:main:main          # your main agent's main session
openclaw acp --session agent:design:main        # a different agent
openclaw acp --session agent:qa:bug-123         # a per-ticket session
openclaw acp --session-label release --require-existing
openclaw acp --session agent:qa:bug-123 --reset-session

Use --require-existing with labels. Without it, a typo'd label quietly gives you a session you didn't mean to start, and you only notice when the agent has no idea what you were working on.

A note on stale mirrors, because they still rank. The 2026.2.x copies on jsDelivr describe the default key with an acp: prefix and list no --token-file at all. Current builds use acp-bridge:. If you wrote a cleanup script or a log filter against the old prefix, it now matches nothing, and nobody tells you. The sessions CLI already treats ACP sessions as disposable during cleanup, which is the right call for these throwaway keys and the wrong one if you parked real work there.

The working directory trap

For a session the bridge creates, ACP session/new sends the editor's absolute working directory, the Gateway stores it, and later prompts run there. By default the bridge also prefixes each prompt with that path (--no-prefix-cwd turns it off). So far, so sensible.

Attach to an existing key with --session and that stops being true. The docs say sessions selected by key or label keep their existing Gateway-owned directory. Open Zed on project B, point it at agent:main:main, and the agent keeps working in whatever directory that session had last week. Ask it which version of a dependency you're on and it can answer from the wrong repo's package.json, with total confidence.

My rule is simple. For code, let the bridge create the session. Use --session for conversations that aren't tied to a checkout.

The files get edited on the Gateway host

The bridge does not implement the ACP client filesystem methods (fs/read_text_file, fs/write_text_file) or the client terminal methods. Zed never hands the agent its open buffers. The agent reads and writes with its own tools, on the machine where the Gateway runs.

Local Gateway, no problem, same disk. Remote Gateway, real problem: your laptop path gets sent as the working directory, and either it doesn't exist on the server or, worse, it does because you cloned the repo there too, and the agent edits the server copy while you stare at an unchanged buffer. If you want the agent touching your laptop's files, the Gateway has to be on your laptop, or the work has to go through a node host on it.

Per-session MCP servers are unsupported too, so the MCP servers Zed has configured for its built-in agent don't follow you into the OpenClaw panel. The agent gets what the Gateway has.

Approvals only reach Zed mid-turn

When the agent hits an exec approval during an active prompt turn, the bridge relays it to the editor as session/request_permission and you click allow or deny in Zed. Outside an active turn there is no relay. An approval triggered by something else on that session (a cron job, a message from another channel) waits wherever your approvals normally go. That is one more reason to keep editor work on its own isolated key: one surface, one approver.

The permission model in acp client debug mode is stricter than people expect, which I count in its favor. Reads scoped to the current directory and readonly search tools are auto-approved. Exec-capable or mutating tools ask first, and so does any tool outside the trusted core list.

What will look broken but isn't

• Streamed text never gets corrected. ACP v1 can't retract or replace text already displayed, so if the Gateway revises a reply, the editor keeps the first draft.
• Token usage in the panel is approximate, it carries no cost data, and it only updates when the Gateway marks the counts fresh. Read real spend from /usage cost in the TUI.
• Reopening an old session replays its full event history only if the bridge created it. Older sessions come back as plain user and assistant text, without the tool calls.
• Two editors on one session key get best-effort routing. That means replies can land in the wrong window.
• Images in a prompt become attachments, and text resources get flattened into the prompt.

Run with -v and the bridge logs to stderr, which Zed captures in its log. That is the first place to look. If you need an audit trail of which prompts came from the editor, --provenance meta (or meta+receipt) attaches ACP provenance metadata to each turn.

Where each option fits (and where it does not)

openclaw acp fits a local Gateway and an ACP editor, when the point is your agent with its memory and skills in the sidebar. It is a poor fit for pairing with a remote Gateway on a codebase that lives on your laptop. Zed's built-in agent or a direct coding agent wins there, because it edits the buffers you are looking at.

openclaw mcp serve fits Claude Code or Codex needing your channels. It does not bring your OpenClaw agent along.

ACP Agents fit the reverse job, your agent handing work to Codex, and nothing on this page applies to them.

If you are exposing the Gateway to an editor on another machine at all, most of the security story is the token and where your approvals go. The Security Hardening Kit walks through tool permission boundaries and secret handling for exactly that kind of always-on Gateway, and I would read it before pointing a remote --url at production.

Final verdict

Worth setting up if your Gateway runs on the machine you code on. Let the bridge mint its own acp-bridge: sessions for code, keep --session for chats, and test with openclaw acp client before blaming Zed. Put the token in a file. For anything remote, I still think the bridge is the wrong tool until it implements the client filesystem methods, because an agent editing a copy of your repo on another box is a quiet way to lose an afternoon.