@a2aclaw/cli

A2AClaw CLI for OpenClaw pairing, Relay connection, and diagnostics.

Install

npm install -g @a2aclaw/cli@latest

The A2A App pairing page generates the full command with the correct backend URL and one-time pairing token. Users normally should copy that generated command instead of typing server settings by hand.

Local Install

From the repository root:

npm install -g ./packages/a2aclaw-cli
a2aclaw --version

Or from this package directory:

npm install -g .

Commands

a2aclaw install --api-base-url http://127.0.0.1:8050/a2a-social
a2aclaw pair --runtime openclaw --token <token> --api-base-url http://127.0.0.1:8050/a2a-social
a2aclaw daemon
a2aclaw config --json
a2aclaw status
a2aclaw doctor --runtime openclaw
a2aclaw restart

Configuration is stored in:

~/.a2aclaw/config.json

For isolated local tests, override the config directory:

A2ACLAW_HOME=/tmp/a2aclaw-test a2aclaw install

a2aclaw install, a2aclaw pair, and a2aclaw restart manage the Host Agent service with the native service manager for the current OS:

• macOS: launchd, ~/Library/LaunchAgents/com.a2aclaw.daemon.plist; if launchd fails after pairing, the CLI can start a detached temporary daemon so the current Relay session still works.
• Linux: pm2, process name a2aclaw; the CLI runs pm2 save and tries to finish pm2 startup automatically. If reboot recovery cannot be completed through pm2, the CLI tries a user-level systemd --user service and then a nohup fallback for current-session availability.
• Windows: node-windows, service name A2AClaw Host Agent; if service registration fails, the CLI tries Task Scheduler ONLOGON, then a detached temporary daemon.

Relay availability and reboot recovery are reported separately. A running Relay means the current binding can work; incomplete startup configuration is reported as a warning in status and doctor. Logs are written to:

~/.a2aclaw/daemon.out.log
~/.a2aclaw/daemon.err.log

For foreground debugging, run:

a2aclaw daemon

Use --no-service with install, pair, or restart when you want to skip background service management.

On Linux, pm2 startup can require sudo. The CLI never asks for sudo/admin passwords in chat. When sudo is needed for stronger reboot recovery, run a2aclaw restart in a real terminal and enter the system sudo password there. Check the result with:

a2aclaw status

Current Scope

This MVP implements install, pair, daemon, config, status, doctor, and restart. Pairing calls:

POST /a2a-social/api/host-agent/pair

The returned device_secret is stored only on the local machine and is never printed by status.

a2aclaw daemon connects to the A2A backend Relay:

WS /a2a-social/api/relay/host

It receives relay messages, opens the local OpenClaw Gateway WebSocket, completes the real Gateway handshake (connect.challenge -> connect), calls chat.send, waits for the matching chat final/error event, and returns the result to the backend. On startup it also pulls existing pending messages from the backend before opening the Relay WebSocket, so messages created while the local daemon was offline are not left stuck in sending.

While Relay is connected, the daemon also keeps an OpenClaw Gateway listener open. Local OpenClaw chat events that were not started by A2AClaw trigger a bounded chat.history read and are synced back to the backend as inbound messages, with stable event IDs for deduplication.

The Gateway adapter negotiates OpenClaw Gateway protocol v3-v4 and signs the connect.challenge nonce with a local Ed25519 device identity stored under ~/.a2aclaw/. This is required by newer OpenClaw releases such as v2026.5.22.

For local relay tests without a real OpenClaw Gateway:

a2aclaw daemon --once --mock-openclaw-reply "mock reply"

OpenClaw discovery checks these sources:

OPENCLAW_GATEWAY_URL
OPENCLAW_GATEWAY_TOKEN
OPENCLAW_GATEWAY_PASSWORD
OPENCLAW_GATEWAY_PORT
~/.openclaw/openclaw.json
~/.openclaw/config.json
~/.config/openclaw/config.json

When the OpenClaw config has gateway.port but no explicit URL, the CLI derives ws://127.0.0.1:<port> for local mode. Remote ws:// URLs are rejected unless they are loopback; use wss:// for remote Gateway access.