Gateway-protocol (WebSocket)¶

Het Gateway WS-protocol is het enige control plane + node-transport voor OpenClaw. Alle clients (CLI, web-UI, macOS-app, iOS/Android-nodes, headless nodes) verbinden via WebSocket en verklaren hun rol + scope tijdens de handshake.

Transport¶

• WebSocket, tekstframes met JSON-payloads.
• Het eerste frame moet een connect-request zijn.

Handshake (verbinden)¶

Gateway → Cliënt (pre-connect-uitdaging):

{
  "type": "event",
  "event": "connect.challenge",
  "payload": { "nonce": "…", "ts": 1737264000000 }
}

Cliënt → Gateway:

{
  "type": "req",
  "id": "…",
  "method": "connect",
  "params": {
    "minProtocol": 3,
    "maxProtocol": 3,
    "client": {
      "id": "cli",
      "version": "1.2.3",
      "platform": "macos",
      "mode": "operator"
    },
    "role": "operator",
    "scopes": ["operator.read", "operator.write"],
    "caps": [],
    "commands": [],
    "permissions": {},
    "auth": { "token": "…" },
    "locale": "en-US",
    "userAgent": "openclaw-cli/1.2.3",
    "device": {
      "id": "device_fingerprint",
      "publicKey": "…",
      "signature": "…",
      "signedAt": 1737264000000,
      "nonce": "…"
    }
  }
}

Gateway → Cliënt:

{
  "type": "res",
  "id": "…",
  "ok": true,
  "payload": { "type": "hello-ok", "protocol": 3, "policy": { "tickIntervalMs": 15000 } }
}

Wanneer een apparaattoken wordt uitgegeven, bevat hello-ok ook:

{
  "auth": {
    "deviceToken": "…",
    "role": "operator",
    "scopes": ["operator.read", "operator.write"]
  }
}

Node-voorbeeld¶

{
  "type": "req",
  "id": "…",
  "method": "connect",
  "params": {
    "minProtocol": 3,
    "maxProtocol": 3,
    "client": {
      "id": "ios-node",
      "version": "1.2.3",
      "platform": "ios",
      "mode": "node"
    },
    "role": "node",
    "scopes": [],
    "caps": ["camera", "canvas", "screen", "location", "voice"],
    "commands": ["camera.snap", "canvas.navigate", "screen.record", "location.get"],
    "permissions": { "camera.capture": true, "screen.record": false },
    "auth": { "token": "…" },
    "locale": "en-US",
    "userAgent": "openclaw-ios/1.2.3",
    "device": {
      "id": "device_fingerprint",
      "publicKey": "…",
      "signature": "…",
      "signedAt": 1737264000000,
      "nonce": "…"
    }
  }
}

Framing¶

• Verzoek: {type:"req", id, method, params}
• Antwoord: {type:"res", id, ok, payload|error}
• Gebeurtenis: {type:"event", event, payload, seq?, stateVersion?}

Methoden met bijwerkingen vereisen idempotency keys (zie schema).

Rollen + scopes¶

Rollen¶

• operator = control plane-client (CLI/UI/automatisering).
• node = capability-host (camera/scherm/canvas/system.run).

Reikwijdten (operator)¶

Veelvoorkomende scopes:

• operator.read
• operator.write
• operator.admin
• operator.approvals
• operator.pairing

Caps/commando's/machtigingen (node)¶

Nodes verklaren capability-claims tijdens het verbinden:

• caps: hoog-niveau capability-categorieën.
• commands: command-allowlist voor invoke.
• permissions: fijnmazige toggles (bijv. screen.record, camera.capture).

De Gateway behandelt deze als claims en handhaaft server-side allowlists.

Presence¶

• system-presence retourneert items die zijn gesleuteld op apparaatidentiteit.
• Presence-items bevatten deviceId, roles en scopes, zodat UI’s één rij per apparaat kunnen tonen, zelfs wanneer het zowel als operator als node verbindt.

Node-hulpmethoden¶

• Nodes kunnen skills.bins aanroepen om de huidige lijst met skill-executables op te halen voor auto-allow-controles.

Exec approvals¶

• Wanneer een exec-aanvraag goedkeuring vereist, broadcast de gateway exec.approval.requested.
• Operator-clients lossen dit op door exec.approval.resolve aan te roepen (vereist operator.approvals-scope).

Versionering¶

• PROTOCOL_VERSION leeft in src/gateway/protocol/schema.ts.
• Clients sturen minProtocol + maxProtocol; de server weigert mismatches.
• Schema’s + modellen worden gegenereerd uit TypeBox-definities:
• pnpm protocol:gen
• pnpm protocol:gen:swift
• pnpm protocol:check

Auth¶

• Als OPENCLAW_GATEWAY_TOKEN (of --token) is ingesteld, moet connect.params.auth.token overeenkomen, anders wordt de socket gesloten.
• Na pairing geeft de Gateway een apparaattoken uit, gescopeerd op de verbindingsrol + scopes. Deze wordt teruggegeven in hello-ok.auth.deviceToken en moet door de client worden opgeslagen voor toekomstige verbindingen.
• Apparaattokens kunnen worden geroteerd/ingetrokken via device.token.rotate en device.token.revoke (vereist operator.pairing-scope).

Apparaatidentiteit + pairing¶

• Nodes moeten een stabiele apparaatidentiteit (device.id) opnemen die is afgeleid van een keypair-fingerprint.
• Gateways geven tokens uit per apparaat + rol.
• Pairing-goedkeuringen zijn vereist voor nieuwe apparaat-ID’s, tenzij lokale auto-goedkeuring is ingeschakeld.
• Lokale verbindingen omvatten loopback en het eigen tailnet-adres van de Gateway-host (zodat tailnet-binds op dezelfde host nog steeds automatisch kunnen worden goedgekeurd).
• Alle WS-clients moeten device-identiteit opnemen tijdens connect (operator + node). Control UI mag dit alleen weglaten wanneer gateway.controlUi.allowInsecureAuth is ingeschakeld (of gateway.controlUi.dangerouslyDisableDeviceAuth voor break-glass-gebruik).
• Niet-lokale verbindingen moeten de door de server geleverde connect.challenge-nonce ondertekenen.

TLS + pinning¶

• TLS wordt ondersteund voor WS-verbindingen.
• Clients kunnen optioneel de gateway-certificaatvingerafdruk pinnen (zie gateway.tls- config plus gateway.remote.tlsFingerprint of CLI --tls-fingerprint).

Scope¶

Dit protocol stelt de volledige gateway-API bloot (status, kanalen, modellen, chat, agent, sessies, nodes, goedkeuringen, enz.). Het exacte oppervlak wordt gedefinieerd door de TypeBox-schema’s in src/gateway/protocol/schema.ts.