Mastering OpenClaw ACP: A Complete Guide to Installing and Managing Autonomous Agents via CLI

Key Takeaways: OpenClaw’s Agent Control Protocol (ACP) standardizes how AI agents interact with their execution environment, providing a secure, IDE-agnostic bridge between agents and local/remote hosts.

Why Agent Control Protocol (ACP) Matters

Modern AI development goes beyond prompting a Large Language Model (LLM) in isolation. A raw LLM can generate text or code but lacks the context, memory and connectivity to perform real‑world tasks. An agent combines an LLM with structured memory, tool plugins and a control loop (think → plan → act → observe) to perform multi‑step workflows.

The Agent Control Protocol was created to solve this interoperability problem. ACP standardizes communication between code editors/IDEs and coding agents so they can operate locally or remotely. Without a protocol, each editor must write custom integrations for every agent, leading to:

• Significant integration overhead.
• Limited compatibility.
• Developer lock‑in.

ACP provides a unified bridge, much like how the Language Server Protocol (LSP) standardized language server integration.

From LLMs to ACP‑Enabled Agents

A raw LLM is a stateless function that returns text. It cannot maintain session state or safely call external tools. In contrast, an ACP‑enabled agent operates within a session, maintains memory and uses JSON‑RPC messages to request permission before executing tools.

The OpenClaw CLI uses ACP to map agent sessions to a Gateway – a process that hosts agents, coordinates tool calls and controls execution. When you run openclaw acp, you start a bridge that speaks ACP over stdio for IDEs and forwards prompts to the Gateway over WebSocket. The CLI keeps ACP sessions mapped to Gateway session keys so each session has its own state and tool permissions.

OpenClaw ACP Architecture

Provisioning: Starting the Bridge and Agents

The provisioning phase focuses on starting the ACP bridge and ensuring that an agent can connect to the Gateway.

• Start a bridge: openclaw acp runs the bridge that talks to the OpenClaw Gateway.
• Connect to a remote Gateway: Use openclaw acp --url wss://gateway-host:18789 --token <token>.
• Secure Auth: Read the token from a file with --token-file ~/.openclaw/gateway.token.
• Bind to an existing session: Pass --session agent:main:main or --session-label "support inbox".
• Reset session: Use --reset-session to start a fresh transcript.

Configuration Persistence:

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

Execution: Managing Sessions and Running Commands

Once provisioned, the CLI manages execution by forwarding prompts and tool calls.

• Interactive Client: Run openclaw acp client to spawn a bridge and type prompts interactively.
• Remote Client: openclaw acp client --server-args --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token.
• Custom Node Build: openclaw acp client --server "node" --server-args openclaw.mjs acp --url ws://127.0.0.1:19001.

Observability: Status and Logs

Operational insight is critical for long‑running agents:

• Status diagnostics: openclaw status prints channel and session diagnostics. Use --all for a complete report or --deep to probe remote messaging channels (WhatsApp, Telegram, Slack, etc.).
• Tail logs: openclaw logs tails Gateway file logs over RPC. Options include --follow (real-time), --json (machine-readable), and --limit <n>.

Step‑by‑Step Installation

Prerequisites

• Node.js: Node 24 is recommended (Node 22 LTS 22.16+ is also supported).
• Supported OS: macOS, Linux, or Windows (WSL2 recommended).
• pnpm (optional): Needed when building from source.

Install via Official Script

• macOS, Linux, or WSL2:Bashcurl -fsSL https://openclaw.ai/install.sh | bash
• Windows (PowerShell):PowerShelliwr -useb https://openclaw.ai/install.ps1 | iex

Install via npm or pnpm

# npm
npm install -g openclaw@latest
openclaw onboard --install-daemon

# pnpm
pnpm add -g openclaw@latest
pnpm approve-builds -g
openclaw onboard --install-daemon

Build from Source

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build
pnpm build
pnpm link --global
openclaw onboard --install-daemon

Using OpenClaw CLI for Agent Control

Initialize and Connect

1. Start Gateway: openclaw gateway run or openclaw gateway install.
2. Set Remote: Configure gateway.remote.url and gateway.remote.token.
3. Run Bridge: Start with openclaw acp.
4. Test: Use an IDE or openclaw acp client.

Passing Complex Parameters

ACP sessions can carry metadata through JSON fields:

{
  "_meta": {
    "sessionKey": "agent:main:main",
    "sessionLabel": "support inbox",
    "resetSession": true
  },
  "prompt": "Update the weekly report and summarise key metrics."
}

Integrating ACP into CI/CD

Integrating ACP into CI/CD gives teams reproducible, auditable agent workflows:

1. Store secrets: Use environment variables OPENCLAW_GATEWAY_TOKEN and OPENCLAW_GATEWAY_PASSWORD.
2. Spin up Gateway: Start openclaw gateway run in the pipeline.
3. Execute tasks: Use the ACP client to submit prompts for code generation or reviews.
4. Observability hooks: Use openclaw status --json and openclaw logs --json --limit 200 to collect diagnostics.
5. Fail fast: Use exit status and JSON output to stop pipelines if errors occur.

Conclusion

OpenClaw’s Agent Control Protocol provides the missing control plane for AI agents. It standardizes communication, reduces integration overhead, and expands compatibility across editors. By leveraging the CLI’s provisioning, execution, and observability commands, you can deploy agents securely, monitor their behavior, and integrate them into modern AgentOps automation pipelines.