--- summary: "Run the ACP bridge for IDE integrations" read_when: - Setting up ACP-based IDE integrations - Debugging ACP session routing to the Gateway title: "acp" --- # acp Run the [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) bridge that talks to a 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. ## Compatibility Matrix | 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 - `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:` 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 ```bash openclaw acp # Remote Gateway openclaw acp --url wss://gateway-host:18789 --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 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. - `read` auto-approval is scoped to the current working directory (`--cwd` when set). - Unknown/non-core tool names, out-of-scope reads, and dangerous tools always require explicit prompt approval. - Server-provided `toolCall.kind` is treated as untrusted metadata (not an authorization source). ## How to use this Use ACP when an IDE (or other client) speaks Agent Client Protocol and you want it to drive a 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 `openclaw acp` over stdio. Example config (persisted): ```bash openclaw config set gateway.remote.url wss://gateway-host:18789 openclaw config set gateway.remote.token ``` Example direct run (no config write): ```bash openclaw acp --url wss://gateway-host:18789 --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 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 `acp:` session unless you override the key or label. 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 silently ignoring them. ## Use from `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 `acpx` with its built-in `openclaw` target. Typical flow: 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. Examples: ```bash # 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, override the `openclaw` agent command in `~/.acpx/config.json`: ```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, use the direct CLI entrypoint instead of the dev runner so the ACP stream stays clean. For example: ```bash 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 `~/.config/zed/settings.json` (or use Zed’s Settings UI): ```json { "agent_servers": { "OpenClaw ACP": { "type": "custom", "command": "openclaw", "args": ["acp"], "env": {} } } } ``` To target a specific Gateway or agent: ```json { "agent_servers": { "OpenClaw ACP": { "type": "custom", "command": "openclaw", "args": [ "acp", "--url", "wss://gateway-host:18789", "--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 `acp:` prefix. To reuse a known session, pass a session key or label: - `--session `: use a specific Gateway session key. - `--session-label