openclaw-acp

Agent Client Protocol (ACP) adapter for OpenClaw via Gateway.

OpenClaw includes a native openclaw acp command, but it's a minimal implementation with limited features. This adapter provides a fuller ACP implementation by bridging through OpenClaw's local gateway, offering streaming support, session persistence, and reliable reconnection.

How It Works

┌──────────────┐      stdio      ┌───────────────┐     WebSocket     ┌─────────────────┐
│  ACP Client  │◄───────────────►│  openclaw-acp │◄──────────────────►│ OpenClaw Gateway│
│  (Zed, AFK)  │   ACP JSON-RPC  │               │  Gateway protocol  │  (localhost)    │
└──────────────┘                 └───────────────┘                    └─────────────────┘

Features

• Full ACP protocol support: initialize, session/new, session/load, session/prompt, session/cancel
• Streaming responses: Real-time text and tool call updates
• Session persistence: Sessions are stored in the gateway and can be resumed
• Automatic reconnection: Reconnects to gateway with exponential backoff
• History replay: On session/load, replays full conversation history

Prerequisites

• OpenClaw installed and gateway running (openclaw command available)
• Gateway token configured in ~/.openclaw/openclaw.json
• Device identity initialized (required for operator scopes)

Device Identity Setup

OpenClaw requires device identity authentication to grant operator scopes (operator.write, operator.read). Without device identity, the adapter cannot send prompts to the gateway.

The device identity is automatically created when you run any OpenClaw CLI command that connects to the gateway. To initialize it:

# Start the gateway if not running
openclaw gateway &

# Initialize device identity (this triggers auto-pairing)
openclaw devices list

This creates ~/.openclaw/identity/device.json and ~/.openclaw/identity/device-auth.json.

For containerized deployments, ensure the device identity is initialized after the gateway starts:

# In your entrypoint script, after starting the gateway:
openclaw devices list > /dev/null 2>&1

Usage

With Zed

Add to your Zed settings.json:

{
  "agent_servers": {
    "openclaw": {
      "type": "custom",
      "command": "npx",
      "args": ["-y", "openclaw-acp"],
      "env": {}
    }
  }
}

With AFK

The AFK host can use this adapter by configuring it in AcpAgents:

static const openclawAcp = AcpAgentConfig(
  id: 'openclaw',
  name: 'OpenClaw',
  command: 'npx',
  args: ['-y', 'openclaw-acp'],
  detectCommand: 'openclaw',
);

Development

npm install
npm run dev        # Run from source
npm run build      # Build for distribution
npm run typecheck  # Type check
npm test           # Run tests
npm run test:watch # Run tests in watch mode

Testing

The project includes comprehensive unit tests for:

• SessionManager (test/session.test.ts): Session creation, loading, prompt handling, event translation
• GatewayClient (test/gateway.test.ts): Connection, authentication, reconnection, event handling

Run tests:

npm test

Architecture

src/
├── index.ts              # Entry point
├── acp/
│   ├── server.ts         # ACP server using @agentclientprotocol/sdk
│   └── session.ts        # Session state management
└── gateway/
    ├── client.ts         # WebSocket client with reconnection
    └── types.ts          # Gateway protocol types

Key Components

GatewayClient (src/gateway/client.ts)

• WebSocket connection to OpenClaw gateway
• Automatic reconnection with exponential backoff
• Request/response correlation
• Event dispatching (chat, agent events)

SessionManager (src/acp/session.ts)

• Maps ACP sessions to gateway sessions
• Translates gateway events to ACP SessionUpdate notifications
• Handles history replay for session/load

AcpServer (src/acp/server.ts)

• Implements ACP Agent interface
• Handles stdio communication via ndJsonStream
• Orchestrates gateway client and session manager

Protocol Translation

| ACP Method | Gateway Action | |------------|----------------| | initialize | Connect to gateway (WebSocket auth) | | session/new | Generate UUID, store in memory | | session/load | Fetch history via chat.history, replay to client | | session/prompt | chat.send (streaming via events) | | session/cancel | chat.abort |

| Gateway Event | ACP Notification | |---------------|------------------| | chat (delta) | session/update → agent_message_chunk | | chat (thinking) | session/update → agent_thought_chunk | | agent (lifecycle start) | session/update → tool_call | | agent (lifecycle end) | session/update → tool_call_update |

License

MIT