OpenClaw ACP Bridge: IDE Integration via Agent Client Protocol

Run the Agent Client Protocol (ACP) bridge that communicates with an OpenClaw Gateway.

openclaw acp implements ACP over stdio for IDEs, forwarding prompts to the Gateway via WebSocket while mapping ACP sessions to Gateway session keys. This is a Gateway-backed ACP bridge, not a complete ACP-native editor runtime; its scope covers session routing, prompt delivery, and streaming updates.

For an external MCP client to connect directly to OpenClaw channel conversations rather than hosting an ACP harness session, use openclaw mcp serve instead.

What this is not

With openclaw acp, OpenClaw functions as an ACP server: an IDE or ACP client connects to OpenClaw, which then routes that work into a Gateway session.

This contrasts with ACP Agents, where OpenClaw runs an external harness like Codex or Claude Code through acpx.

Quick guideline:

• editor/client wants to speak ACP to OpenClaw: choose openclaw acp
• OpenClaw should start Codex/Claude/Gemini as an ACP harness: pick /acp spawn and ACP Agents

Compatibility matrix

Known limitations

• loadSession replays complete ACP event-ledger history only for bridge-created sessions. Older/no-ledger sessions use transcript fallback and do not reconstruct historic tool calls or system notices.
• 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-bridge:<uuid> sessions when you need clean editor-local turns.
• Gateway stop states translate into ACP stop reasons, but that mapping is less expressive than a fully ACP-native runtime.
• Session controls 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 exposed as ACP config options.
• session_info_update and usage_update derive 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 surfaces file paths that appear in known tool args/results, but does not emit ACP terminals or structured file diffs.
• Exec approval relay is scoped to the active ACP prompt turn; approvals from other Gateway sessions are ignored.

Usage

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

ACP client (debug)

Sanity-check the bridge with the built-in ACP client, no IDE required. It launches the ACP bridge and accepts interactive prompt input.

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

Permission model (client debug mode):

• Auto-approval is allowlist-based and applies only to trusted core tool IDs.
• read auto-approval is scoped to the current working directory (--cwd when set).
• ACP only auto-approves narrow readonly classes: scoped read calls under the active cwd, plus readonly search tools (search, web_search, memory_search). Unknown/non-core tools, out-of-scope reads, exec-capable tools, control-plane tools, mutating tools, and interactive flows always require explicit prompt approval.
• Server-provided toolCall.kind is treated as untrusted metadata, not an authorization source.
• This ACP bridge policy is separate from ACPX harness permissions. If you run OpenClaw through the acpx backend, plugins.entries.acpx.config.permissionMode=approve-all is the break-glass "yolo" switch for that harness session.

Protocol smoke testing

For low-level protocol inspection, launch a Gateway with clean state and send openclaw acp through stdio using an ACP JSON-RPC client. Test initialize, session/new, session/list with a full cwd, session/resume, session/close, a second close, and an absent resume.

The demonstration must show the advertised lifecycle capabilities, a Gateway-backed session record, update events, and the Gateway sessions.list log entry:

{
  "initialize": {
    "protocolVersion": 1,
    "agentCapabilities": {
      "sessionCapabilities": {
        "list": {},
        "resume": {},
        "close": {}
      }
    }
  },
  "listSessions": {
    "sessions": [
      {
        "sessionId": "agent:main:acp-smoke",
        "cwd": "/path/to/workspace",
        "_meta": {
          "sessionKey": "agent:main:acp-smoke",
          "kind": "direct"
        }
      }
    ],
    "nextCursor": null
  },
  "notifications": ["session_info_update", "available_commands_update", "usage_update"],
  "gatewayLogTail": ["[gateway] ready", "[ws] ⇄ res ✓ sessions.list 305ms"]
}

Do not rely solely on openclaw gateway call sessions.list to verify ACP. That CLI route can trigger a fresh-token operator scope upgrade; proper ACP bridge verification comes from ACP stdio frames plus the Gateway sessions.list log.

How to use this

Choose ACP when an IDE or other client implements Agent Client Protocol and needs to control an OpenClaw Gateway session.

1. Confirm the Gateway is up, whether local or remote.
2. Set the Gateway target through config or flags.
3. Have your IDE launch openclaw acp via stdio.

Persisted configuration example:

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

Direct invocation example, no config file needed:

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 on its own. Routing happens through the Gateway session key. To reach a particular agent, use agent-scoped session keys:

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

Every ACP session corresponds to exactly one Gateway session key. A single agent may hold many sessions; unless you specify a key or label, ACP uses an isolated acp-bridge:<uuid> session.

Per-session mcpServers do not work in bridge mode. When an ACP client includes them during newSession or loadSession, the bridge responds with a clear error rather than quietly dropping them.

For ACPX-backed sessions to access OpenClaw plugin tools or selected built-ins like cron, turn on the gateway-side ACPX MCP bridges. Do not attempt to pass per-session mcpServers. See ACP Agents and OpenClaw tools MCP bridge.

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

To let a coding agent such as Codex or Claude Code reach your OpenClaw bot through ACP, run acpx with its bundled openclaw target.

Standard workflow:

1. Start the Gateway and verify the ACP bridge can connect to it.
2. Point acpx openclaw at openclaw acp.
3. Select the OpenClaw session key you want the coding agent to use.

Examples:

# 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."

To have acpx openclaw consistently hit a specific Gateway and session key, override the openclaw agent command inside ~/.acpx/config.json:

{
  "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, invoke the direct CLI entrypoint rather than the dev runner so the ACP stream stays uncluttered:

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

This approach gives Codex, Claude Code, or any other ACP-aware client the simplest path to pull context from an OpenClaw agent without terminal scraping.

Zed editor setup

Register a custom ACP agent in ~/.config/zed/settings.json, or use Zed's Settings UI:

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

To point at a particular Gateway or agent:

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

Inside Zed, open the Agent panel and pick "OpenClaw ACP" to begin a thread.

Session mapping

ACP bridge sessions default to an isolated Gateway session key prefixed with acp-bridge:. These normal-model bridge sessions are synthetic and disposable: they can be removed by stale-entry pruning and are not protected human conversation surfaces. To reuse a known session, supply a session key or label:

• --session <key>: use a specific Gateway session key.
• --session-label <label>: resolve an existing session by label.
• --reset-session: mint a fresh session id for that key (same key, new transcript).

If your ACP client supports metadata, you can override per session:

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

Session key details are covered at /concepts/session.

Options

• --url <url>: WebSocket address for the Gateway, which falls back to gateway.remote.url when it has been set up.
• --token <token>: authentication token for the Gateway.
• --token-file <path>: load the Gateway auth token from a file.
• --password <password>: password used for Gateway authentication.
• --password-file <path>: retrieve the Gateway auth password from a file.
• --session <key>: session key applied by default.
• --session-label <label>: session label that gets resolved by default.
• --require-existing: stop with an error if the session key or label is missing.
• --reset-session: clear the session key before its initial use.
• --no-prefix-cwd: skip adding the working directory as a prefix to prompts.
• --provenance <off|meta|meta+receipt>: attach ACP provenance metadata or receipts.
• --verbose, -v: send detailed logging to stderr.

Security considerations:

• On certain systems, --token and --password might show up in local process listings. Favor --token-file/--password-file or environment variables (OPENCLAW_GATEWAY_TOKEN, OPENCLAW_GATEWAY_PASSWORD) instead.
• Gateway auth resolution follows the same contract shared across other Gateway clients:
  • local mode: gateway.auth.* comes first, then env (OPENCLAW_GATEWAY_*), with gateway.remote.* used only when gateway.auth.* is not set (a local SecretRef that is configured but unresolved fails closed rather than quietly falling back)
  • remote mode: gateway.remote.* applies, with env/config fallback following remote precedence rules
  • --url avoids overrides and does not pull in implicit config/env credentials; supply explicit --token/--password (or their file counterparts)

acp client options

• --cwd <dir>: directory where the ACP session runs.
• --server <command>: command that starts the ACP server, defaulting to openclaw.
• --server-args <args...>: additional arguments handed to the ACP server.
• --server-verbose: turn on verbose logging for the ACP server.
• --verbose, -v: verbose logging on the client side.
• openclaw acp client applies OPENCLAW_SHELL=acp-client to the spawned bridge process, which supports shell or profile rules tied to specific contexts.

Related

• Command line reference
• ACP agents