OpenClaw Gateway - Mission Control

Overview

OpenClaw Gateway is a production-ready gateway server designed for orchestrating multiple AI agents at scale. Mission Control connects to OpenClaw Gateway via WebSocket for real-time session management, log streaming, and agent coordination.

For simpler deployments, see CLI Integration for direct REST/SSE connections without a gateway.

Architecture

Key Features:

WebSocket Protocol v3: Binary-efficient, fully-typed messaging
Device Identity Auth: Ed25519 signature-based authentication
Session Management: Multi-session tracking with token accounting
Real-time Logs: Structured log streaming from agents to UI
Agent Spawning: On-demand process lifecycle management
Heartbeat Protocol: 30s ping/pong with RTT tracking

Connection Protocol

1. WebSocket Handshake

Mission Control initiates a WebSocket connection with protocol negotiation:

Connect to Gateway

const ws = new WebSocket('wss://gateway.example.com:8080');

No query parameters needed — authentication happens post-connect.

Receive Challenge

Gateway sends a connect.challenge event with a nonce:

{
  "type": "event",
  "event": "connect.challenge",
  "payload": {
    "nonce": "a1b2c3d4e5f6...",
    "protocols": [3],
    "deviceAuthRequired": true
  }
}

Send Connect Request with Device Auth

Mission Control signs the nonce with Ed25519 device identity:

{
  "type": "req",
  "method": "connect",
  "id": "mc-1",
  "params": {
    "minProtocol": 3,
    "maxProtocol": 3,
    "client": {
      "id": "gateway-client",
      "displayName": "Mission Control",
      "version": "2026.03.04",
      "platform": "web",
      "mode": "ui",
      "instanceId": "mc-1709582400"
    },
    "role": "operator",
    "scopes": ["operator.admin"],
    "device": {
      "id": "device-550e8400-e29b-41d4",
      "publicKey": "base64_ed25519_public_key",
      "signature": "base64_ed25519_signature",
      "signedAt": 1709582400000,
      "nonce": "a1b2c3d4e5f6..."
    },
    "deviceToken": "cached_token_if_available"
  }
}

Signature Payload (v2 format):

v2|device-id|client-id|client-mode|role|scopes|signed-at|device-token|nonce

Signed using Ed25519 private key stored in browser IndexedDB.

Receive Connection Confirmation

Gateway validates signature and responds:

{
  "type": "res",
  "id": "mc-1",
  "ok": true,
  "result": {
    "protocol": 3,
    "sessionId": "gateway-session-123",
    "deviceToken": "new_token_for_future_reconnects",
    "features": ["spawn", "cron", "logs"]
  }
}

Connection is now authenticated. Mission Control caches deviceToken for faster reconnects.

2. Heartbeat Protocol

Mission Control sends ping requests every 30 seconds:

{
  "type": "req",
  "method": "ping",
  "id": "ping-1"
}

Gateway responds:

{
  "type": "res",
  "id": "ping-1",
  "ok": true
}

Timeout Behavior:

If 3 consecutive pongs are missed → force reconnect
RTT (round-trip time) is calculated: Date.now() - sentTimestamp
Displayed in Mission Control UI as connection latency

3. Event Stream

Gateway broadcasts real-time events:

Session Update

{
  "type": "event",
  "event": "tick",
  "payload": {
    "snapshot": {
      "sessions": [
        {
          "key": "agent1:chat",
          "kind": "chat",
          "model": "claude-sonnet-4",
          "totalTokens": 5432,
          "contextTokens": 35000,
          "messageCount": 12,
          "cost": 0.42,
          "updatedAt": 1709582400000,
          "active": true
        }
      ]
    }
  }
}

Log Entry

{
  "type": "event",
  "event": "log",
  "payload": {
    "id": "log-123",
    "timestamp": 1709582400000,
    "level": "info",
    "source": "agent1",
    "session": "agent1:chat",
    "message": "Task completed successfully",
    "extra": {
      "task_id": 456
    }
  }
}

Agent Status

{
  "type": "event",
  "event": "agent.status",
  "payload": {
    "id": 42,
    "name": "agent1",
    "status": "busy",
    "last_seen": 1709582400,
    "last_activity": "Processing task #456"
  }
}

Device Identity Authentication

What is Device Identity?

OpenClaw Gateway supports device-based authentication using Ed25519 cryptographic signatures. Each browser generates a unique device identity stored locally, preventing credential sharing and enabling per-device authorization.

Security Benefits

No password transmission over network
Device-bound sessions cannot be hijacked
Revocable per-device access
Cryptographic proof of identity

User Experience

Automatic authentication after first setup
No password re-entry on reconnect
Multi-device support (each device has unique identity)
Transparent to user (happens in background)

Key Generation

On first connection, Mission Control generates an Ed25519 keypair:

import { getOrCreateDeviceIdentity } from '@/lib/device-identity';

const identity = await getOrCreateDeviceIdentity();
// {
//   deviceId: 'device-550e8400-e29b-41d4',
//   publicKeyBase64: 'base64_public_key',
//   privateKey: CryptoKey (non-exportable),
// }

Storage:

Private key: IndexedDB (non-extractable, browser-bound)
Public key: Sent to gateway during connect
Device ID: UUID stored in localStorage

Device identity requires HTTPS or localhost (WebCrypto API restriction). Self-signed certificates are supported.

Signature Process

Gateway sends nonce in connect.challenge

Mission Control builds signature payload:

v2|device-id|client-id|mode|role|scopes|timestamp|token|nonce

Sign payload using Ed25519 private key
Send signature + publicKey + nonce in connect request
Gateway verifies signature using public key
Returns deviceToken for faster future reconnects

Device Token Caching

After successful authentication, gateway issues a device token:

Short-lived token (e.g., 24 hours)
Can be used instead of full signature on reconnect
Stored in localStorage as mc_device_token
Automatically included in connect params

Reconnect flow:

// First connect: full device signature
connect({ device: { signature, publicKey, ... } })

// Reconnect within 24h: use cached token
connect({ deviceToken: 'cached_token' })

Gateway Configuration

Control UI Settings

Gateway must explicitly allow Mission Control origin:

# openclaw-gateway.yml
gateway:
  controlUi:
    enabled: true
    allowedOrigins:
      - https://mc.example.com  # Production
      - http://localhost:3000   # Development
    requireDeviceAuth: true

If your origin is not in allowedOrigins, you’ll receive:

Gateway error: Origin not allowed

Add your Mission Control URL to the gateway config and restart.

Device Auth Settings

gateway:
  auth:
    deviceAuth:
      enabled: true
      requireSignature: true  # Reject unsigned connects
      tokenTTL: 86400         # Device token lifetime (seconds)
      maxDevicesPerUser: 10   # Limit devices per identity

If requireSignature: true, Mission Control must provide device signature. HTTP-only deployments (without WebCrypto) will fail.

TLS Configuration

gateway:
  tls:
    enabled: true
    certFile: /etc/certs/gateway.crt
    keyFile: /etc/certs/gateway.key
    port: 8080

Mission Control connects via wss:// (WebSocket Secure).

Spawn Agents

Gateway can spawn agent processes on-demand:

// Send spawn request
ws.send(JSON.stringify({
  type: 'req',
  method: 'spawn',
  id: 'spawn-1',
  params: {
    command: 'python',
    args: ['agent.py', '--role', 'developer'],
    env: { AGENT_NAME: 'agent1' },
    cwd: '/opt/agents',
  }
}));

Response:

{
  "type": "event",
  "event": "spawn_result",
  "payload": {
    "id": "spawn-1",
    "status": "running",
    "pid": 12345,
    "completedAt": null,
    "result": null,
    "error": null
  }
}

When process exits:

{
  "type": "event",
  "event": "spawn_result",
  "payload": {
    "id": "spawn-1",
    "status": "completed",
    "pid": 12345,
    "completedAt": 1709582400000,
    "result": { "exitCode": 0 },
    "error": null
  }
}

Error Handling

Non-Retryable Errors

Mission Control stops reconnecting for these errors:

Error	Cause	Solution
`origin not allowed`	Origin not in `allowedOrigins`	Add your URL to gateway config
`device identity required`	Gateway requires device auth, but browser doesn’t support WebCrypto	Use HTTPS or localhost
`device_auth_signature_invalid`	Invalid Ed25519 signature	Clear device identity in browser DevTools → Application → IndexedDB
`auth rate limit`	Too many auth attempts	Wait 1 minute, then reconnect

User Experience:

Error displayed in Mission Control logs panel
Notification: “Gateway Handshake Blocked” with actionable help text
Reconnect button disabled until error is resolved

Retryable Errors

Auto-reconnect with exponential backoff for:

Network errors (DNS, connection refused)
WebSocket close codes (except 4001 non-retryable)
Heartbeat timeout (3 missed pongs)

Backoff schedule:

Attempt 1: 1s
Attempt 2: 2s
Attempt 3: 4s
Attempt 4: 8s
Attempt 5: 16s
Attempt 6+: 30s (max)

Deployment

Docker Compose

version: '3.8'
services:
  gateway:
    image: openclaw/gateway:latest
    ports:
      - "8080:8080"
    volumes:
      - ./gateway.yml:/etc/openclaw/gateway.yml
      - ./sessions:/var/lib/openclaw/sessions
    environment:
      - OPENCLAW_CONFIG=/etc/openclaw/gateway.yml
      - LOG_LEVEL=info
    restart: unless-stopped

  mission-control:
    image: missioncontrol/web:latest
    ports:
      - "3000:3000"
    environment:
      - GATEWAY_URL=wss://localhost:8080
    depends_on:
      - gateway

Systemd Service

# /etc/systemd/system/openclaw-gateway.service
[Unit]
Description=OpenClaw Gateway
After=network.target

[Service]
Type=simple
User=openclaw
WorkingDirectory=/opt/openclaw
ExecStart=/opt/openclaw/bin/gateway --config /etc/openclaw/gateway.yml
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

sudo systemctl enable openclaw-gateway
sudo systemctl start openclaw-gateway
sudo systemctl status openclaw-gateway

Nginx Reverse Proxy

Proxy WebSocket connections through Nginx:

upstream gateway {
    server localhost:8080;
}

server {
    listen 443 ssl http2;
    server_name gateway.example.com;

    ssl_certificate /etc/letsencrypt/live/gateway.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/gateway.example.com/privkey.pem;

    location / {
        proxy_pass http://gateway;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # WebSocket timeout (30s pings prevent timeout)
        proxy_read_timeout 300s;
        proxy_send_timeout 300s;
    }
}

Monitoring

Connection Health

Mission Control UI displays:

Connection Status: Connected / Disconnected / Reconnecting
Latency: Real-time RTT from ping/pong (ms)
Reconnect Attempts: Counter during reconnection
Protocol Version: Negotiated protocol (should be 3)

Gateway Metrics

OpenClaw Gateway exposes Prometheus metrics:

curl http://localhost:9090/metrics

Key metrics:

openclaw_gateway_connections_total - Active WebSocket connections
openclaw_gateway_messages_sent_total - Messages sent to clients
openclaw_gateway_messages_received_total - Messages from clients
openclaw_gateway_spawn_requests_total - Agent spawn requests
openclaw_gateway_auth_failures_total - Failed authentications

Logs

Gateway structured logs:

sudo journalctl -u openclaw-gateway -f

Example log entries:

{"level":"info","msg":"WebSocket connection established","client_id":"gateway-client","device_id":"device-550e8400","role":"operator"}
{"level":"info","msg":"Device signature verified","device_id":"device-550e8400","valid":true}
{"level":"warn","msg":"Heartbeat timeout","client_id":"gateway-client","missed_pongs":3}

Troubleshooting

Connection stuck on 'Waiting for connect challenge...'

Cause: Gateway not sending connect.challenge event.Debug:

Check gateway logs for connection attempt
Verify gateway is running: systemctl status openclaw-gateway
Test WebSocket manually:
```
wscat -c ws://localhost:8080
```
Check firewall rules allow port 8080

Device signature invalid

Error: device_auth_signature_invalidSolutions:

Clear device identity:
- Chrome DevTools → Application → IndexedDB → Delete device-identity
Reconnect (triggers new key generation)
Check browser console for WebCrypto errors
Ensure HTTPS (or localhost) for WebCrypto access

Origin not allowed

Error: origin not allowedSolution: Add Mission Control origin to gateway config:

gateway:
  controlUi:
    allowedOrigins:
      - https://your-mc-domain.com  # Add this

Restart gateway:

sudo systemctl restart openclaw-gateway

Frequent disconnections

Cause: Network instability or proxy timeout.Solutions:

Check Mission Control logs for error patterns
Verify 30s heartbeats are being sent
Increase proxy timeout (nginx: proxy_read_timeout 300s)
Check for firewall/NAT issues
Monitor RTT — high latency may indicate network issues

Agent spawn fails

Error: spawn_result with status: 'failed'Debug:

Check gateway has permissions to execute command
Verify cwd path exists
Check agent script has execute permission: chmod +x agent.py
Review gateway logs for spawn errors

Test command manually:

cd /opt/agents && python agent.py --role developer

Security Considerations

TLS Required

Always use WSS (WebSocket Secure) in production:

// Production
wss://gateway.example.com:8080

// Development only
ws://localhost:8080

Device auth requires HTTPS for WebCrypto API access.

Origin Whitelist

Limit allowedOrigins to trusted domains:

allowedOrigins:
  - https://mc.example.com  # Production only
  # - https://mc-staging.example.com  # Add staging

Never use * (wildcard) in production.

Device Limits

Prevent device proliferation:

deviceAuth:
  maxDevicesPerUser: 10  # Limit per identity
  tokenTTL: 86400        # 24h token lifetime

Users must re-authenticate after token expiry.

Audit Logs

Enable gateway audit logging:

audit:
  enabled: true
  logFile: /var/log/openclaw/audit.log
  events:
    - auth.success
    - auth.failure
    - device.registered
    - device.revoked

CLI Integration

Simpler REST/SSE alternative

WebSocket Client

Client implementation details

Authentication

API key and role-based auth

Get Started

Core Features

Integrations

Deployment

Advanced

​Overview

​Architecture

​Connection Protocol

​1. WebSocket Handshake

​2. Heartbeat Protocol

​3. Event Stream

​Session Update

​Log Entry

​Agent Status

​Device Identity Authentication

​What is Device Identity?

Security Benefits

User Experience

​Key Generation

​Signature Process

​Device Token Caching

​Gateway Configuration

​Control UI Settings

​Device Auth Settings

​TLS Configuration

​Spawn Agents

​Error Handling

​Non-Retryable Errors

​Retryable Errors

​Deployment

​Docker Compose

​Systemd Service

​Nginx Reverse Proxy

​Monitoring

​Connection Health

​Gateway Metrics

​Logs

​Troubleshooting

​Security Considerations

TLS Required

Origin Whitelist

Device Limits

Audit Logs

​Related Docs

CLI Integration

WebSocket Client

Authentication

Overview

Architecture

Connection Protocol

1. WebSocket Handshake

2. Heartbeat Protocol

3. Event Stream

Session Update

Log Entry

Agent Status

Device Identity Authentication

What is Device Identity?

Key Generation

Signature Process

Device Token Caching

Gateway Configuration

Control UI Settings

Device Auth Settings

TLS Configuration

Spawn Agents

Error Handling

Non-Retryable Errors

Retryable Errors

Deployment

Docker Compose

Systemd Service

Nginx Reverse Proxy

Monitoring

Connection Health

Gateway Metrics

Logs

Troubleshooting

Security Considerations

Related Docs