How to Use OpenClaw ACP for IDE and Client Integrations

openclaw acp is for clients that speak the Agent Client Protocol and want to drive an OpenClaw Gateway session. Think IDE integration, debug client, or another ACP client over stdio. The bridge talks ACP on one side and forwards prompts to the OpenClaw Gateway over WebSocket on the other.

What ACP is

In this mode, OpenClaw acts as an ACP server. An IDE or ACP client connects to OpenClaw, and OpenClaw maps that ACP session to a Gateway session key. The docs describe support for initialize, newSession, prompt, cancel, listSessions, slash commands, partial loadSession behavior, basic streaming updates, and best-effort tool follow-along data.

openclaw acp

For a remote gateway, pass the URL and token, preferably from a token file when you do not want secrets in shell history.

openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

What ACP is not

The docs call out the confusion directly. openclaw acp is not the same thing as asking OpenClaw to launch Codex, Claude Code, Gemini, or another external harness through ACPX. Quick rule: if an editor or client wants to talk ACP to OpenClaw, use openclaw acp. If OpenClaw should launch an external coding harness, use the ACP agents path documented for that feature.

Session routing

ACP does not pick agents directly. It routes by Gateway session key. You can attach to an existing session key, attach by label, or let the bridge create an isolated default ACP session. Agent-scoped session keys target specific agents.

openclaw acp --session agent:main:main
openclaw acp --session agent:design:main
openclaw acp --session-label "support inbox"

Use --reset-session only when you intentionally want to reset the session key before the first prompt. If you are debugging a persistent editor flow, resetting the session can hide the history you actually needed to inspect.

Debug client

OpenClaw also ships a built-in ACP client to sanity-check the bridge without an IDE. That is useful when you need to separate “my editor config is wrong” from “the ACP bridge cannot reach the Gateway.”

openclaw acp client
openclaw acp client --server-args --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

The bridge has known limitations: per-session MCP servers are unsupported, client filesystem methods are unsupported, client terminal methods are unsupported, and usage updates are approximate. Treat it as a focused Gateway-backed ACP bridge, not a full editor runtime clone.

If you are turning ACP-backed OpenClaw workflows into real operations instead of a demo, The OpenClaw Playbook is the shortcut I wish every operator had: identity files, memory rules, safety boundaries, channel discipline, and production habits in one field-tested guide.

IDE setup sanity test

Before wiring an editor profile, run the built-in ACP client against the same gateway URL and token file. If that works, your bridge and gateway path are healthy, and any remaining issue probably belongs to the editor’s ACP configuration. If it fails, fix the gateway URL, token, or session target before touching the IDE. The debug client is there to remove guesswork.

Security boundary

ACP is powerful because it lets another client drive an OpenClaw session. Use a token file, route to the intended session, and avoid sharing one broad session across unrelated projects. The bridge does not magically know your project boundaries; the session key and gateway auth are the boundary you give it.

Runbook detail

For How to Use OpenClaw ACP for IDE and Client Integrations, the important operator move is to record the exact documented surface you used and the condition that proves it worked. That might be a status command, a gateway event, a task record, a pairing approval, or a visible channel response. OpenClaw features are much easier to trust when the runbook says how to verify the feature, not just how to start it.

Operator checkpoint

Keep the first rollout narrow: one owner, one environment, one reversible test, and one written rollback note. Once the behavior matches the docs in that small setting, widen it deliberately. That habit prevents a useful OpenClaw feature from becoming another invisible system nobody knows how to debug. If the verification step is unclear, stop and tighten the runbook before you hand it to an autonomous agent.