Run OpenClaw ACP Bridge: Connect IDEs to Gateway

The acp command runs the Agent Client Protocol (ACP) bridge that talks to an OpenClaw Gateway. This command speaks ACP over stdio for IDEs and forwards prompts to the Gateway over WebSocket. It keeps ACP sessions mapped to Gateway session keys.

openclaw acp is a Gateway-backed ACP bridge, not a full ACP-native editor runtime. It focuses on session routing, prompt delivery, and basic streaming updates.

If you want an external MCP client to talk directly to OpenClaw channel conversations instead of hosting an ACP harness session, use openclaw mcp serve instead.

Compatibility Matrix

You can use this table to see which parts of the protocol are ready and which ones have specific notes you should be aware of.

ACP area	Status	Notes
initialize, newSession, prompt, cancel	Implemented	Core bridge flow over stdio to Gateway chat/send + abort.
listSessions, slash commands	Implemented	Session list works against Gateway session state; commands are advertised via available_commands_update.
loadSession	Partial	Rebinds the ACP session to a Gateway session key and replays stored user/assistant text history. Tool/system history is not reconstructed yet.
Prompt content (text, embedded resource, images)	Partial	Text/resources are flattened into chat input; images become Gateway attachments.
Session modes	Partial	session/set_mode is supported and the bridge exposes initial Gateway-backed session controls for thought level, tool verbosity, reasoning, usage detail, and elevated actions. Broader ACP-native mode/config surfaces are still out of scope.
Session info and usage updates	Partial	The bridge emits session_info_update and best-effort usage_update notifications from cached Gateway session snapshots. Usage is approximate and only sent when Gateway token totals are marked fresh.
Tool streaming	Partial	tool_call / tool_call_update events include raw I/O, text content, and best-effort file locations when Gateway tool args/results expose them. Embedded terminals and richer diff-native output are still not exposed.
Per-session MCP servers (mcpServers)	Unsupported	Bridge mode rejects per-session MCP server requests. Configure MCP on the OpenClaw gateway or agent instead.
Client filesystem methods (fs/read_text_file, fs/write_text_file)	Unsupported	The bridge does not call ACP client filesystem methods.
Client terminal methods (terminal/*)	Unsupported	The bridge does not create ACP client terminals or stream terminal ids through tool calls.
Session plans / thought streaming	Unsupported	The bridge currently emits output text and tool status, not ACP plan or thought updates.

Known Limitations

Every tool has its boundaries. Here are the current limitations you should keep in mind while using the bridge:

• loadSession replays stored user and assistant text history, but it does not reconstruct historic tool calls, system notices, or richer ACP-native event types.
• If multiple ACP clients share the same Gateway session key, event and cancel routing are best-effort rather than strictly isolated per client. Prefer the default isolated acp:<uuid> sessions when you need clean editor-local turns.
• Gateway stop states are translated into ACP stop reasons, but that mapping is less expressive than a fully ACP-native runtime.
• Initial session controls currently surface a focused subset of Gateway knobs: thought level, tool verbosity, reasoning, usage detail, and elevated actions. Model selection and exec-host controls are not yet exposed as ACP config options.
• session_info_update and usage_update are derived from Gateway session snapshots, not live ACP-native runtime accounting. Usage is approximate, carries no cost data, and is only emitted when the Gateway marks total token data as fresh.
• Tool follow-along data is best-effort. The bridge can surface file paths that appear in known tool args/results, but it does not yet emit ACP terminals or structured file diffs.

Usage

You can get started with openclaw acp quickly. If you’re working locally, just run the base command. For remote setups, you can pass your Gateway URL and token directly or point to a token file to keep things clean.

openclaw acp

# Remote Gateway
openclaw acp --url wss://gateway-host:18789 --token <token>

# Remote Gateway (token from file)
openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

# Attach to an existing session key
openclaw acp --session agent:main:main

# Attach by label (must already exist)
openclaw acp --session-label "support inbox"

# Reset the session key before the first prompt
openclaw acp --session agent:main:main --reset-session

If you need to return to a specific task, you can attach to an existing session key or use a label you’ve already created. You also have the option to reset the session key before you send your first prompt.

ACP client (debug)

You can use the built-in ACP client to check that your bridge is working correctly without needing an IDE. It starts the bridge and lets you type prompts to see how it responds.

openclaw acp client

If you need to point the bridge at a remote Gateway or use a different server command—like running a specific node script—you can use these flags to adjust the setup.

openclaw acp client

# Point the spawned bridge at a remote Gateway
openclaw acp client --server-args --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

# Override the server command (default: openclaw)
openclaw acp client --server "node" --server-args openclaw.mjs acp --url ws://127.0.0.1:19001

The permission model in debug mode keeps things secure by using an allowlist for trusted core tools. For example, read auto-approval is restricted to your current working directory when you set the --cwd flag.

ACP only approves specific readonly tools automatically, such as search, web_search, memory_search, and scoped read calls. Other actions—including unknown tools, out-of-scope reads, exec-capable tools, control-plane tools, mutating tools, and interactive flows—will always ask for your approval. The system treats toolCall.kind as untrusted metadata, so it isn’t used for authorization.

This bridge policy is separate from the ACPX harness. If you’re using the acpx backend and need to bypass these restrictions, you can set plugins.entries.acpx.config.permissionMode=approve-all. This is the “yolo” switch for that session, so use it only when you really need to.

How to use this

You can use ACP when your IDE or another client speaks the Agent Client Protocol and you want it to drive an OpenClaw Gateway session.

First, make sure the Gateway is running, whether it is local or remote. Then, configure the Gateway target using either your config settings or flags. Finally, point your IDE to run openclaw acp over stdio.

If you want to save your configuration, use these commands:

openclaw config set gateway.remote.url wss://gateway-host:18789
openclaw config set gateway.remote.token <token>

If you prefer a direct run without writing to your config file, you can use these flags instead. This is often better for local process safety:

openclaw acp --url wss://gateway-host:18789 --token <token>
# preferred for local process safety
openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

Selecting agents

ACP does not pick agents directly. Instead, it routes everything by the Gateway session key.

You should use agent-scoped session keys to target a specific agent:

openclaw acp --session agent:main:main
openclaw acp --session agent:design:main
openclaw acp --session agent:qa:bug-123

Each ACP session maps to a single Gateway session key. While one agent can have many sessions, ACP defaults to an isolated acp:<uuid> session unless you choose to override the key or label.

Keep in mind that per-session mcpServers are not supported in bridge mode. If an ACP client sends them during newSession or loadSession, the bridge returns a clear error instead of ignoring them.

If you want ACPX-backed sessions to see OpenClaw plugin tools, you should enable the gateway-side ACPX plugin bridge. Do not try to pass per-session mcpServers. You can find the details in the documentation for ACP Agents.

Use from acpx (Codex, Claude, other ACP clients)

If you want a coding agent like Codex or Claude Code to talk to your OpenClaw bot over ACP, you should use acpx with its built-in openclaw target.

The typical flow looks like this:

1. Run the Gateway and make sure the ACP bridge can reach it.
2. Point acpx openclaw at openclaw acp.
3. Target the OpenClaw session key you want the coding agent to use.

Here are some examples of how that looks in practice:

# One-shot request into your default OpenClaw ACP session
acpx openclaw exec "Summarize the active OpenClaw session state."

# Persistent named session for follow-up turns
acpx openclaw sessions ensure --name codex-bridge
acpx openclaw -s codex-bridge --cwd /path/to/repo \
  "Ask my OpenClaw work agent for recent context relevant to this repo."

If you want acpx openclaw to target a specific Gateway and session key every time, you can override the openclaw agent command in your ~/.acpx/config.json file:

{
  "agents": {
    "openclaw": {
      "command": "env OPENCLAW_HIDE_BANNER=1 OPENCLAW_SUPPRESS_NOTES=1 openclaw acp --url ws://127.0.0.1:18789 --token-file ~/.openclaw/gateway.token --session agent:main:main"
    }
  }
}

For a repo-local OpenClaw checkout, use the direct CLI entrypoint instead of the dev runner. This ensures the ACP stream stays clean:

env OPENCLAW_HIDE_BANNER=1 OPENCLAW_SUPPRESS_NOTES=1 node openclaw.mjs acp ...

This is the easiest way to let Codex, Claude Code, or other ACP-aware clients pull context from an OpenClaw agent without needing to scrape a terminal.

Zed editor setup

You can also set up a custom ACP agent in Zed. Just add this to your ~/.config/zed/settings.json or use the Zed Settings UI:

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

If you need to target a specific Gateway or a particular agent, use this configuration instead:

{
  "agent_servers": {
    "OpenClaw ACP": {
      "type": "custom",
      "command": "openclaw",
      "args": [
        "acp",
        "--url",
        "wss://gateway-host:18789",
        "--token",
        "<token>",
        "--session",
        "agent:design:main"
      ],
      "env": {}
    }
  }
}

Once you’ve saved your settings, open the Agent panel in Zed and select “OpenClaw ACP” to start a new thread.

Session mapping

By default, ACP sessions get an isolated Gateway session key with an acp: prefix. If you want to reuse a known session, you can pass a specific session key or a label.

You have a few flags to manage this:

• --session <key>: Use a specific Gateway session key.
• --session-label <label>: Resolve an existing session by its label.
• --reset-session: Mint a fresh session ID for that key, which gives you a new transcript while keeping the same key.

If your ACP client supports metadata, you can override these settings per session with this JSON:

{
  "_meta": {
    "sessionKey": "agent:main:main",
    "sessionLabel": "support inbox",
    "resetSession": true
  }
}

You can find more details about session keys at /concepts/session.

Options

Here are the flags you can use to configure your setup:

• --url <url>: Gateway WebSocket URL (defaults to gateway.remote.url when configured).
• --token <token>: Gateway auth token.
• --token-file <path>: Read Gateway auth token from a file.
• --password <password>: Gateway auth password.
• --password-file <path>: Read Gateway auth password from a file.
• --session <key>: Default session key.
• --session-label <label>: Default session label to resolve.
• --require-existing: Fail if the session key/label does not exist.
• --reset-session: Reset the session key before first use.
• --no-prefix-cwd: Do not prefix prompts with the working directory.
• --verbose, -v: Verbose logging to stderr.

Keep security in mind when choosing your flags. On some systems, --token and --password can be visible in local process listings. I recommend using --token-file and --password-file or environment variables (OPENCLAW_GATEWAY_TOKEN, OPENCLAW_GATEWAY_PASSWORD) to keep your credentials safe.

Gateway auth resolution follows a specific contract:

• In local mode: It checks env variables (OPENCLAW_GATEWAY_*), then gateway.auth.*, and finally gateway.remote.* as a fallback only when gateway.auth.* is unset.
• In remote mode: It uses gateway.remote.* with env/config fallback based on remote precedence rules.
• The --url flag is override-safe and does not reuse implicit config or env credentials. You should pass explicit --token or --password (or their file variants) when using it.

For shell or profile rules that need to know the context, ACP runtime backend child processes receive OPENCLAW_SHELL=acp. When you run openclaw acp client, it sets OPENCLAW_SHELL=acp-client on the spawned bridge process.

acp client options

When working with the client specifically, you have these extra options:

• --cwd <dir>: Working directory for the ACP session.
• --server <command>: ACP server command (default: openclaw).
• --server-args <args...>: Extra arguments passed to the ACP server.
• --server-verbose: Enable verbose logging on the ACP server.
• --verbose, -v: Verbose client logging.