Gateway-Protokoll (WebSocket)¶

Das Gateway-WS-Protokoll ist die einzige Kontroll­ebene + Node-Transport für OpenClaw. Alle Clients (CLI, Web-UI, macOS-App, iOS/Android-Nodes, headless Nodes) verbinden sich über WebSocket und deklarieren ihre Rolle + Geltungsbereiche (Scopes) zum Zeitpunkt des Handshakes.

Transport¶

• WebSocket, Text-Frames mit JSON-Payloads.
• Das erste Frame muss eine connect-Anfrage sein.

Handshake (Verbindung)¶

Gateway → Client (Vorab‑Challenge vor der Verbindung):

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

Client → 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 → Client:

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

Wenn ein Gerätetoken ausgegeben wird, enthält hello-ok außerdem:

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

Knoten-Beispiel¶

{
  "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¶

• Anfrage: {type:"req", id, method, params}
• Antwort: {type:"res", id, ok, payload|error}
• Ereignis: {type:"event", event, payload, seq?, stateVersion?}

Methoden mit Nebenwirkungen erfordern Idempotenzschlüssel (siehe Schema).

Rollen + Scopes¶

Rollen¶

• operator = Kontroll­ebenen‑Client (CLI/UI/Automatisierung).
• node = Fähigkeits‑Host (Kamera/Bildschirm/Canvas/system.run).

Scopes (Operator)¶

Häufige Scopes:

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

Caps/Commands/Berechtigungen (Node)¶

Nodes deklarieren beim Verbinden Fähigkeitsansprüche:

• caps: übergeordnete Fähigkeitskategorien.
• commands: Befehls‑Allowlist für Aufrufe.
• permissions: granulare Schalter (z. B. screen.record, camera.capture).

Das Gateway behandelt diese als Claims und erzwingt serverseitige Allowlists.

Präsenz¶

• system-presence liefert Einträge, die nach Geräteidentität geschlüsselt sind.
• Presence‑Einträge enthalten deviceId, roles und scopes, sodass UIs eine einzelne Zeile pro Gerät anzeigen können, selbst wenn es sich sowohl als Operator als auch als Node verbindet.

Node‑Hilfsmethoden¶

• Nodes können skills.bins aufrufen, um die aktuelle Liste der Skill‑Executables für Auto‑Allow‑Prüfungen abzurufen.

Exec-Genehmigungen¶

• Wenn eine Exec‑Anfrage eine Freigabe benötigt, sendet das Gateway exec.approval.requested als Broadcast.
• Operator‑Clients lösen dies durch Aufruf von exec.approval.resolve (erfordert den Scope operator.approvals).

Versionierung¶

• PROTOCOL_VERSION befindet sich in src/gateway/protocol/schema.ts.
• Clients senden minProtocol + maxProtocol; der Server lehnt Abweichungen ab.
• Schemas + Modelle werden aus TypeBox‑Definitionen generiert:
• pnpm protocol:gen
• pnpm protocol:gen:swift
• pnpm protocol:check

Authentifizierung¶

• Wenn OPENCLAW_GATEWAY_TOKEN (oder --token) gesetzt ist, muss connect.params.auth.token übereinstimmen, andernfalls wird der Socket geschlossen.
• Nach der Paarung stellt das Gateway einen Geräte-Token dar, der auf die Verbindung Rolle + Skala reicht. Es wird in hello-ok.auth.deviceToken zurückgegeben und sollte vom Client für zukünftige Verbindungen persistiert werden.
• Gerätetoken können über device.token.rotate und device.token.revoke rotiert/widerrufen werden (erfordert den Scope operator.pairing).

Geräteidentität + Pairing¶

• Nodes sollten eine stabile Geräteidentität (device.id) angeben, die aus einem Schlüsselpaar‑Fingerprint abgeleitet ist.
• Gateways geben Tokens pro Gerät + Rolle aus.
• Pairing‑Freigaben sind für neue Geräte‑IDs erforderlich, sofern lokale Auto‑Freigabe nicht aktiviert ist.
• Lokale Verbindungen umfassen Loopback und die eigene Tailnet‑Adresse des Gateway‑Hosts (sodass Tailnet‑Bindings auf demselben Host weiterhin auto‑freigegeben werden können).
• Alle WS‑Clients müssen während connect (Operator + Node) eine device‑Identität angeben. Die Kontroll‑UI darf sie nur weglassen, wenn gateway.controlUi.allowInsecureAuth aktiviert ist (oder gateway.controlUi.dangerouslyDisableDeviceAuth für Break‑Glass‑Nutzung).
• Nicht‑lokale Verbindungen müssen den vom Server bereitgestellten connect.challenge‑Nonce signieren.

TLS + Pinning¶

• TLS wird für WS‑Verbindungen unterstützt.
• Clients können optional den Zertifikats‑Fingerprint des Gateways pinnen (siehe die gateway.tls‑Konfiguration sowie gateway.remote.tlsFingerprint oder CLI --tls-fingerprint).

Geltungsbereich¶

Dieses Protokoll stellt die vollständige Gateway‑API bereit (Status, Kanäle, Modelle, Chat, Agent, Sitzungen, Nodes, Freigaben usw.). Der exakte Umfang wird durch die TypeBox‑Schemas in src/gateway/protocol/schema.ts definiert.