OpenClaw

​

Prerequisites

• An OpenClaw Gateway, reachable over WebSocket (default ws://localhost:18789). The Clawboo server connects to the URL stored in settings (gatewayUrl).
• The Gateway’s auth token. Clawboo’s onboarding writes one into OpenClaw’s ~/.openclaw/.env as GATEWAY_AUTH_TOKEN and mirrors it into Clawboo’s settings.json (gatewayToken).
• Node.js (Clawboo’s prerequisite). The install step runs npm install -g openclaw@~2026.9, so npm must be on PATH.
• For OpenClaw 2026.5.x and later: a one-time device pairing approval, see Device pairing.

​

How OpenClaw connects

​

The browser connection (same-origin proxy)

​

The server connection (OpenClawAgentSource)

• The server connects with client.id = cli (the Gateway validates client.id against a fixed allowlist; a custom id like clawboo-server is rejected and the socket closes with code 1008).
• The server presents an Origin of the gateway host (http(s)://<gateway-host>). A headless Node WebSocket sends no Origin by default, which the Gateway rejects with CONTROL_UI_ORIGIN_NOT_ALLOWED; Clawboo injects the ws package’s WebSocket (which honours a custom origin) to satisfy the check.

​

Channels

​

Steps

​

1. Detect

{
  "node": { "version": "v22.x.x", "major": 22, "sufficient": true, "path": "…" },
  "openclaw": {
    "installed": true,
    "version": "2026.5.x",
    "path": "…",
    "stateDir": "~/.openclaw",
    "configExists": true,
    "envExists": true
  },
  "gateway": {
    "running": true,
    "port": 18789,
    "pid": 12345,
    "managedByClawboo": true,
    "uptimeMs": 9000
  }
}

​

2. Install (optional)

​

3. Configure

{ "ok": true, "gatewayUrl": "ws://localhost:18789" }

​

Or: use your ChatGPT subscription

openclaw models auth login --provider openai-codex

​

4. Start the Gateway

​

5. Connect (and pair the device)

​

Device pairing (NOT_PAIRED)

GatewayResponseError { code: 'NOT_PAIRED', message: 'pairing required: device is not approved yet' }

1. openclaw devices approve --latest runs in preview mode: it prints Approve this exact request with: openclaw devices approve <UUID> and exits non-zero. Clawboo regex-extracts the UUID from the captured stdout/stderr.
2. openclaw devices approve <UUID> performs the actual approval.

​

What a new Boo is allowed to run

​

Seeing what a Boo has already been allowed

​

Why OpenClaw can’t be run by the per-task executor

• The OpenClaw adapter’s capabilities() declare runtimeClass: 'connected-substrate' (and worktrees: false).
• resolveRuntimeIntegration(caps) maps that class to home.kind === 'connected'.
• The executor runner checks this before the atomic claim and returns { ok: false, reason: 'connected_substrate' }, which the REST layer maps to 422. The refusal landing pre-claim is the point: a misrouted run never touches the board.

​

Global memory scope

• Memory is registered at GLOBAL scope for OpenClaw. The other four runtimes get a per-run team scope baked into their attach URL; a single static Gateway-config URL can’t carry a per-run team binding, so an OpenClaw agent’s memory facts are team-unscoped. This is an organizational boundary for the local-first single-user model, not a security one. Global scope here is enforced, not assumed. Because the Gateway’s URLs carry no signed scope, an OpenClaw agent’s MCP session is treated as an unidentified HTTP caller: the scopeTeamId / scopeAgentId arguments it passes are ignored, saves land on the global tier and reads see the global tier only. Without that, “global” would have meant “whatever the model asked for”, and any agent could have written a fact tagged as another team and read every team’s facts back.
• Tasks refuses the tools that name an agent. For the same reason, an OpenClaw session is not served claim_task or assign_task (both require an assigneeAgentId the caller cannot prove), and add_comment drops a caller-supplied authorAgentId and authorType. The anonymous board writes are unaffected, so an OpenClaw agent can still create, re-status, block, unblock and link tasks. Server-orchestrated board runs are unaffected either way: Clawboo claims those directly, without going through the MCP tool.
• TeamChat is deliberately NOT registered for OpenClaw. A process-wide static URL can’t carry a per-run author binding, and registering the team_chat tool unbound would let an OpenClaw agent post as any author (identity from tool args), breaking the anti-spoof property that the peer-chat room depends on. Instead, an OpenClaw agent’s room participation is fully server-mediated through the team exchange, which posts the agent’s drained turn under the authoritative bound identity.

​

Verify it worked

• GET /api/agents/registry/health (always 200) reports the source connection; it should read connected with a recent lastSyncedAt.
• GET /api/agents should return your OpenClaw agents with stale: false.
• GET /api/system/status should show gateway.running: true.
• Send a message in group chat; the send is an HTTP POST /api/teams/:id/chat and the reply streams back over SSE (/api/teams/:id/chat/stream), because team orchestration runs server-side. The same-origin WS proxy carries the 1:1 chat, not the team run. Exec approvals ride both Gateway connections: the browser’s proxied socket and the server’s own connection, so a command waiting on you is still there after you close the tab.

​

Troubleshooting

​

Related

• Connecting runtimes, the CLI runtimes (different connection model)
• Runtimes overview, the capability matrix
• Gateway and events, the Gateway flow and the Bridge→Policy→Handler pipeline
• AgentSource, the registry-of-record sync internals
• Memory, the shared Memory-MCP tier
• Peer chat, why TeamChat is server-mediated for OpenClaw
• System API · Agents API, full request/response shapes
• Glossary, canonical term definitions