​

Gateway-protocol (WebSocket)

​

Transport

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

​

Handshake (verbinden)

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

{
  "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": "…"
    }
  }
}

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

{
  "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?}

​

Rollen + scopes

​

Rollen

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

​

Reikwijdten (operator)

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

​

Caps/commando’s/machtigingen (node)

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

​

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