openclaw-agent

Connect your OpenClaw instance to the OpenClaw GUI dashboard via a secure outbound WSS tunnel.

Features

• Zero configuration — auto-detects your OpenClaw API address, config directory, Docker containers, and token database
• Outbound-only WSS — no ports to open, no IP exposure; the agent connects out to the GUI server
• Cross-platform — Linux (amd64/arm64), macOS (Intel/Apple Silicon), and Windows
• Docker-transparent — works whether OpenClaw runs bare-metal or inside Docker (auto-discovers containers)
• Secure by design — write commands restricted to a strict whitelist (cron-run, cron-enable, cron-disable); all execution uses execFile with parameterized arguments, never shell interpolation
• Resilient connection — exponential back-off reconnect (1 s to 60 s cap), 30 s heartbeat, offline event buffer (up to 1 000 events)

Quick Start

npx openclaw-agent --token oca_your_token_here

The agent will auto-detect the local OpenClaw instance and establish a tunnel to the GUI dashboard.

CLI Options

| Option | Description | Default | |--------|-------------|---------| | --token <token> | Agent token (required, must start with oca_) | — | | --api <url> | OpenClaw API address | Auto-detected | | --server <url> | WSS tunnel server | wss://gui.openclaw.io/ws | | --version, -v | Print version and exit | — | | --help, -h | Show help | — |

How It Works

┌──────────────────┐         WSS (outbound)        ┌──────────────────┐
│  Your Server     │  ──────────────────────────▶   │  GUI Dashboard   │
│                  │                                │                  │
│  OpenClaw        │  ◀── commands (whitelist) ───  │  gui.openclaw.io │
│  openclaw-agent  │  ──▶ status / cron / tokens ▶  │                  │
└──────────────────┘                                └──────────────────┘

1. Environment detection — the agent scans localhost ports (18791, 18789, 18790), Docker containers, and known config paths to find your OpenClaw instance automatically.
2. WSS handshake — connects to the tunnel server with a protocol-versioned handshake (protocol: 1), reporting OS, architecture, Node version, and available capabilities.
3. Data collection — reads instance status via HTTP API, cron job lists via the OpenClaw CLI, cron run history from log files, and token usage from the local SQLite database.
4. Command execution — the GUI can send write commands back through the tunnel; only whitelisted operations (cron-run, cron-enable, cron-disable) are accepted, with strict ID validation.
5. Offline buffer — if the connection drops, events are buffered in memory (up to 1 000 entries, alerts prioritized) and flushed on reconnect.

Requirements

• Node.js >= 18
• OpenClaw instance running on the same machine (or reachable via --api)
• An agent token (prefix oca_) obtained from the GUI dashboard settings page

Security

• Write command whitelist — only cron-run, cron-enable, and cron-disable are permitted; all other commands are rejected.
• No shell execution — all commands use execFile with parameterized arguments; no string concatenation, no shell injection surface.
• ID validation — job IDs are validated against /^[a-zA-Z0-9_-]{1,64}$/ before execution.
• Token privacy — only a hashed token is sent during handshake; the raw token never leaves the machine.
• Read-only collection — status, cron, and token data are collected via read-only HTTP calls and CLI commands; no files are written (except the agent's own state).
• Log filtering — readLog strips sensitive fields (conversation, prompt, response content) before transmission.

License

MIT