ACP

Run the ACP (Agent Client Protocol) bridge to talk to the OpenClaw gateway.

This command speaks ACP over the IDE's stdio and forwards prompts to the gateway

over WebSocket. It maps ACP sessions to gateway session keys.

Use the built-in ACP client to sanity-check the bridge without an IDE.

It spawns an ACP bridge and lets you type prompts interactively.

openclaw acp client


openclaw acp client --server-args --url wss://gateway-host:18789 --token <token>


openclaw acp client --server "node" --server-args openclaw.mjs acp --url ws://127.0.0.1:19001

Use ACP when your IDE (or other client) speaks the 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. Set your IDE to run ''openclaw acp'' over stdio.

Config example (persistent):

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

Direct run example (no config write):

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

ACP does not directly pick an agent. It routes via the gateway session key.

Use an agent-scoped session key 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 gateway session key. An agent can have multiple agent

sessions; ACP defaults to an isolated ''acp:<uuid>'' session unless you override

the key or label.

Add 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 target a specific 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": {}
    }
  }
}

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

By default, ACP sessions get isolated gateway session keys with the ''acp:'' prefix.

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

- ''--session <key>'': Use a specific gateway session key.

- ''--session-label <label>'': Resolve an existing session by label.

- ''--reset-session'': Create a new session ID for that key (same key, new record).

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

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

To learn more about session keys, visit ''/concepts/session''.

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

- ''--token <token>'': Gateway authentication token.

- ''--password <password>'': Gateway verification password.

- ''--session <key>'': Default session key.

- ''--session-label <label>'': Default session label to resolve.

- ''--require-existing'': Fail if session key/label does not exist.

- ''--reset-session'': Reset session key before first use.

- ''--no-prefix-cwd'': Do not prefix prompts with working directory.

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

#

- ''--cwd <dir>'': Working directory for ACP session.

- ''--server <command>'': ACP server command (default: ''openclaw'').

- ''--server-args <args...>'': Extra arguments to pass to ACP server.

- ''--server-verbose'': Enable verbose logging on ACP server.

- ''--verbose, -v'': Verbose client logging.