ACP

Run 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.

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

instead.

What this is not

This page is often confused with ACP harness sessions.

means:

• OpenClaw acts as an ACP server
• an IDE or ACP client connects to OpenClaw
• OpenClaw forwards that work into a Gateway session

This is different from ACP Agents, where OpenClaw runs an external harness such as Codex or Claude Code through

.

Quick rule:

• editor/client wants to talk ACP to OpenClaw: use
  text

  Copy

  openclaw acp
• OpenClaw should launch Codex/Claude/Gemini as an ACP harness: use
  text

  Copy

  /acp spawn
  and ACP Agents

Compatibility Matrix

Known Limitations

• text

  Copy

  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
  text

  Copy

  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.
• text

  Copy

  session_info_update
  and
  text

  Copy

  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

bash
Copy
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)

Use the built-in ACP client to sanity-check the bridge without an IDE. It spawns the ACP bridge and lets you type prompts interactively.

bash
Copy
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 only applies to trusted core tool IDs.
• text

  Copy

  read
  auto-approval is scoped to the current working directory (
  text

  Copy

  --cwd
  when set).
• ACP only auto-approves narrow readonly classes: scoped
  text

  Copy

  read
  calls under the active cwd plus readonly search tools (
  text

  Copy

  search
  ,
  text

  Copy

  web_search
  ,
  text

  Copy

  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
  text

  Copy

  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
  text

  Copy

  acpx
  backend,
  text

  Copy

  plugins.entries.acpx.config.permissionMode=approve-all
  is the break-glass “yolo” switch for that harness session.

How to use this

Use ACP when an IDE (or other client) speaks Agent Client Protocol and you want it to drive an OpenClaw Gateway session.

1. Ensure the Gateway is running (local or remote).
2. Configure the Gateway target (config or flags).
3. Point your IDE to run
   text

   Copy

   openclaw acp
   over stdio.

Example config (persisted):

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

Example direct run (no config write):

bash
Copy
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. It routes by the Gateway session key.

Use agent-scoped session keys to target a specific agent:

bash
Copy
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. One agent can have many sessions; ACP defaults to an isolated

session unless you override the key or label.

Per-session

are not supported in bridge mode. If an ACP client sends them during or , the bridge returns a clear error instead of silently ignoring them.

If you want ACPX-backed sessions to see OpenClaw plugin tools or selected built-in tools such as

, enable the gateway-side ACPX MCP bridges instead of trying to pass per-session . See ACP Agents and OpenClaw tools MCP bridge.

Use from

text

Copy

acpx

(Codex, Claude, other ACP clients)

If you want a coding agent such as Codex or Claude Code to talk to your OpenClaw bot over ACP, use

with its built-in target.

Typical flow:

1. Run the Gateway and make sure the ACP bridge can reach it.
2. Point
   text

   Copy

   acpx openclaw
   at
   text

   Copy

   openclaw acp
   .
3. Target the OpenClaw session key you want the coding agent to use.

Examples:

bash
Copy
# 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

to target a specific Gateway and session key every time, override the agent command in :

json
Copy
{
  "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 so the ACP stream stays clean. For example:

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

This is the easiest way to let Codex, Claude Code, or another ACP-aware client pull contextual information from an OpenClaw agent without scraping a terminal.

Zed editor setup

Add a custom ACP agent in

(or use Zed’s Settings UI):

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

To target a specific Gateway or agent:

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

In Zed, open the Agent panel and select “OpenClaw ACP” to start a thread.

Session mapping

By default, ACP sessions get an isolated Gateway session key with an

prefix. To reuse a known session, pass a session key or label:

• text

  Copy

  --session <key>
  : use a specific Gateway session key.
• text

  Copy

  --session-label <label>
  : resolve an existing session by label.
• text

  Copy

  --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:

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

Learn more about session keys at /concepts/session.

Options

• text

  Copy

  --url <url>
  : Gateway WebSocket URL (defaults to gateway.remote.url when configured).
• text

  Copy

  --token <token>
  : Gateway auth token.
• text

  Copy

  --token-file <path>
  : read Gateway auth token from file.
• text

  Copy

  --password <password>
  : Gateway auth password.
• text

  Copy

  --password-file <path>
  : read Gateway auth password from file.
• text

  Copy

  --session <key>
  : default session key.
• text

  Copy

  --session-label <label>
  : default session label to resolve.
• text

  Copy

  --require-existing
  : fail if the session key/label does not exist.
• text

  Copy

  --reset-session
  : reset the session key before first use.
• text

  Copy

  --no-prefix-cwd
  : do not prefix prompts with the working directory.
• text

  Copy

  --provenance <off|meta|meta+receipt>
  : include ACP provenance metadata or receipts.
• text

  Copy

  --verbose, -v
  : verbose logging to stderr.

Security note:

• text

  Copy

  --token
  and
  text

  Copy

  --password
  can be visible in local process listings on some systems.
• Prefer
  text

  Copy

  --token-file
  /
  text

  Copy

  --password-file
  or environment variables (
  text

  Copy

  OPENCLAW_GATEWAY_TOKEN
  ,
  text

  Copy

  OPENCLAW_GATEWAY_PASSWORD
  ).
• Gateway auth resolution follows the shared contract used by other Gateway clients:
  • local mode: env (
    text

    Copy

    OPENCLAW_GATEWAY_*
    ) ->
    text

    Copy

    gateway.auth.*
    ->
    text

    Copy

    gateway.remote.*
    fallback only when
    text

    Copy

    gateway.auth.*
    is unset (configured-but-unresolved local SecretRefs fail closed)
  • remote mode:
    text

    Copy

    gateway.remote.*
    with env/config fallback per remote precedence rules
  • text

    Copy

    --url
    is override-safe and does not reuse implicit config/env credentials; pass explicit
    text

    Copy

    --token
    /
    text

    Copy

    --password
    (or file variants)
• ACP runtime backend child processes receive
  text

  Copy

  OPENCLAW_SHELL=acp
  , which can be used for context-specific shell/profile rules.
• text

  Copy

  openclaw acp client
  sets
  text

  Copy

  OPENCLAW_SHELL=acp-client
  on the spawned bridge process.

text

Copy

acp client

options

• text

  Copy

  --cwd <dir>
  : working directory for the ACP session.
• text

  Copy

  --server <command>
  : ACP server command (default:
  text

  Copy

  openclaw
  ).
• text

  Copy

  --server-args <args...>
  : extra arguments passed to the ACP server.
• text

  Copy

  --server-verbose
  : enable verbose logging on the ACP server.
• text

  Copy

  --verbose, -v
  : verbose client logging.

Related

• CLI reference
• ACP agents