Okki Claw

Node.js sidecar that bridges local OpenClaw gateway to the agent-relay cloud relay.

Architecture

Local OpenClaw Gateway (WebSocket)
    ^
    | Gateway WebSocket bridge + auto-auth
    |
agent-relay Sidecar (this)
    |
    | persistent WebSocket tunnel
    v
agent-relay Cloud Relay (WebSocket)

Gateway Authentication

Sidecar supports two authentication methods for connecting to the local OpenClaw Gateway:

Method 1: Gateway Shared Token (Recommended for Docker/OrbStack)

When running OpenClaw Gateway in Docker or OrbStack, the Gateway exposes a shared token via the OPENCLAW_GATEWAY_TOKEN environment variable. Sidecar can use this token to authenticate without device pairing.

# Set the Gateway shared token (replace the placeholder with your value)
export OPENCLAW_GATEWAY_TOKEN

# Run sidecar
npm run dev

The Gateway shared token can be found:

• In Gateway container environment: docker exec <container> env | grep OPENCLAW_GATEWAY_TOKEN
• In OrbStack Gateway logs at startup
• Set via OPENCLAW_GATEWAY_TOKEN environment variable when starting Gateway

Method 2: Device Credentials

For direct local Gateway connections, Sidecar can use device credentials from ~/.openclaw/identity/:

1. Device identity: ~/.openclaw/identity/device.json (Ed25519 keypair)
2. Device auth: ~/.openclaw/identity/device-auth.json (operator token)

Note: Device authentication requires the device to be paired in Gateway Control UI. For Docker/OrbStack deployments, use Method 1 (Gateway Shared Token) instead.

Phase 3: Device Pairing

Pair a device

First, get a pairing token from the agent-relay web app or API:

curl -X POST http://localhost:8080/devices/pair \
  -H "Cookie: access_token=your-jwt" \
  | jq .pairing_token

Then pair your local sidecar:

npm run pair -- --pairing-token <token> --device-name "my-openclaw"

This saves credentials under device.identity in ~/.agent-relay/config.json. Set AGENT_RELAY_CONFIG_PATH=/path/to/config.json (or pass --config-path to pair) to use a different sidecar config file.

Run the sidecar

npm run dev
# or after build
npm run start

The sidecar will use stored credentials from pairing.

Config Discovery

1. Reads ~/.openclaw/openclaw.json for gateway URL and auth token
2. Falls back to OPENCLAW_GATEWAY_URL and OPENCLAW_GATEWAY_TOKEN env vars
3. Periodic health checks detect gateway restart or token mismatch

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | AGENT_RELAY_CONFIG_PATH | Sidecar persistent config path for pairing credentials, relay config, and adapters | ~/.agent-relay/config.json | | RELAY_URL | WebSocket URL of the agent-relay relay | ws://localhost:8080/tunnel | | OPENCLAW_GATEWAY_TOKEN | Gateway shared token for authentication | (from Gateway) | | OPENCLAW_GATEWAY_URL | Local Gateway URL | (auto-discovered) | | DEVICE_TOKEN | Device credential token | (from pairing) | | HEALTH_CHECK_INTERVAL_SEC | Health check interval | 60 | | HEARTBEAT_INTERVAL_SEC | Heartbeat interval | 30 | | SIDECAR_AUTO_UPDATE | Enable daemon auto-update from npm (off/false/0 disables) | 1 | | SIDECAR_AUTO_UPDATE_INTERVAL_MS | Auto-update check interval for daemon mode | 21600000 | | SIDECAR_AUTO_UPDATE_INITIAL_DELAY_MS | Initial delay before daemon's first update check | 300000 |

See .env.example for all configuration options.

Updates

okki-claw check-update
okki-claw update

Daemon mode checks npm for @okki-global/okki-claw updates automatically. When an update installs successfully, sidecar starts a replacement daemon and exits the old process cleanly.

Setup

cp .env.example .env
# Edit .env with your relay URL and gateway token
npm install
npm run dev

Docker/OrbStack Deployment

For Gateway running in Docker or OrbStack:

1. Find the Gateway shared token:

   docker exec openclaw-gateway env | grep OPENCLAW_GATEWAY_TOKEN

2. Configure Sidecar:

   export OPENCLAW_GATEWAY_TOKEN
   export RELAY_URL="wss://relay.agent-relay.io/tunnel"
   npm run dev

3. If Gateway is behind a proxy, configure trustedProxies in Gateway's openclaw.json:

   {
     "gateway": {
       "trustedProxies": ["192.168.97.1", "192.168.97.0/24"]
     }
   }

Plugin Packages

See plugins/README.md for per-agent installation guides and the compatibility matrix.