mirror of
https://github.com/openclaw/openclaw.git
synced 2026-03-13 11:00:50 +00:00
0125ce1f44
* Gateway: fail closed unresolved local auth SecretRefs * Docs: align node-host gateway auth precedence * CI: resolve rebase breakages in checks lanes * Tests: isolate LOCAL_REMOTE_FALLBACK_TOKEN env state * Gateway: remove stale remote.enabled auth-surface semantics * Changelog: note gateway SecretRef fail-closed fix
289 lines
13 KiB
Markdown
289 lines
13 KiB
Markdown
---
|
||
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:<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
|
||
|
||
```bash
|
||
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
|
||
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 <token>
|
||
```
|
||
|
||
Example direct run (no config write):
|
||
|
||
```bash
|
||
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
|
||
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:<uuid>` 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",
|
||
"<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 <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:
|
||
|
||
```json
|
||
{
|
||
"_meta": {
|
||
"sessionKey": "agent:main:main",
|
||
"sessionLabel": "support inbox",
|
||
"resetSession": true
|
||
}
|
||
}
|
||
```
|
||
|
||
Learn more about session keys at [/concepts/session](/concepts/session).
|
||
|
||
## Options
|
||
|
||
- `--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 file.
|
||
- `--password <password>`: Gateway auth password.
|
||
- `--password-file <path>`: read Gateway auth password from 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.
|
||
|
||
Security note:
|
||
|
||
- `--token` and `--password` can be visible in local process listings on some systems.
|
||
- Prefer `--token-file`/`--password-file` or environment variables (`OPENCLAW_GATEWAY_TOKEN`, `OPENCLAW_GATEWAY_PASSWORD`).
|
||
- Gateway auth resolution follows the shared contract used by other Gateway clients:
|
||
- local mode: env (`OPENCLAW_GATEWAY_*`) -> `gateway.auth.*` -> `gateway.remote.*` fallback only when `gateway.auth.*` is unset (configured-but-unresolved local SecretRefs fail closed)
|
||
- remote mode: `gateway.remote.*` with env/config fallback per remote precedence rules
|
||
- `--url` is override-safe and does not reuse implicit config/env credentials; pass explicit `--token`/`--password` (or file variants)
|
||
- ACP runtime backend child processes receive `OPENCLAW_SHELL=acp`, which can be used for context-specific shell/profile rules.
|
||
- `openclaw acp client` sets `OPENCLAW_SHELL=acp-client` on the spawned bridge process.
|
||
|
||
### `acp client` 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.
|