Gateway-Protokoll

Das Gateway-WS-Protokoll ist die einzige Steuerungsebene + Node-Transport für OpenClaw. Alle Clients (CLI, Web-UI, macOS-App, iOS/Android-Nodes, headless Nodes) verbinden sich per WebSocket und deklarieren ihre Rolle + ihren Geltungsbereich beim Handshake.

Transport

• WebSocket, Text-Frames mit JSON-Payloads.
• Der erste Frame muss eine connect-Anfrage sein.
• Pre-Connect-Frames sind auf 64 KiB begrenzt. Nach einem erfolgreichen Handshake sollten Clients die Limits hello-ok.policy.maxPayload und hello-ok.policy.maxBufferedBytes einhalten. Bei aktivierter Diagnose erzeugen zu große eingehende Frames und langsame ausgehende Puffer payload.large-Ereignisse, bevor der Gateway den betroffenen Frame schließt oder verwirft. Diese Ereignisse speichern Größen, Limits, Oberflächen und sichere Reason-Codes. Sie speichern nicht den Nachrichteninhalt, Attachment-Inhalte, den rohen Frame-Body, Tokens, Cookies oder Secret-Werte.

Handshake (connect)

Gateway → Client (Pre-Connect-Challenge):

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

Client → Gateway:

{  "type": "req",  "id": "…",  "method": "connect",  "params": {    "minProtocol": 3,    "maxProtocol": 4,    "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": 4,    "server": { "version": "…", "connId": "…" },    "features": { "methods": ["…"], "events": ["…"] },    "snapshot": { "…": "…" },    "auth": {      "role": "operator",      "scopes": ["operator.read", "operator.write"]    },    "policy": {      "maxPayload": 26214400,      "maxBufferedBytes": 52428800,      "tickIntervalMs": 15000    }  }}

Während der Gateway noch Start-Sidecars abschließt, kann die connect-Anfrage einen erneut versuchbaren UNAVAILABLE-Fehler mit details.reason auf "startup-sidecars" und retryAfterMs zurückgeben. Clients sollten diese Antwort innerhalb ihres gesamten Verbindungsbudgets erneut versuchen, statt sie als terminalen Handshake-Fehler anzuzeigen.

server, features, snapshot und policy sind alle vom Schema (packages/gateway-protocol/src/schema/frames.ts) vorgeschrieben. auth ist ebenfalls erforderlich und meldet die ausgehandelte Rolle bzw. die ausgehandelten Geltungsbereiche. pluginSurfaceUrls ist optional und ordnet Plugin- Oberflächennamen wie canvas bereichsgebundenen gehosteten URLs zu.

Bereichsgebundene Plugin-Oberflächen-URLs können ablaufen. Nodes können node.pluginSurface.refresh mit { "surface": "canvas" } aufrufen, um einen frischen Eintrag in pluginSurfaceUrls zu erhalten. Das experimentelle Canvas-Plugin-Refactoring unterstützt nicht den veralteten Kompatibilitätspfad canvasHostUrl, canvasCapability oder node.canvas.capability.refresh; aktuelle native Clients und Gateways müssen Plugin-Oberflächen verwenden.

Wenn kein Device-Token ausgestellt wird, meldet hello-ok.auth die ausgehandelten Berechtigungen ohne Token-Felder:

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

Vertrauenswürdige Same-Process-Backend-Clients (client.id: "gateway-client", client.mode: "backend") dürfen device bei direkten Loopback-Verbindungen weglassen, wenn sie sich mit dem gemeinsamen Gateway-Token/Passwort authentifizieren. Dieser Pfad ist für interne Steuerungsebenen-RPCs reserviert und verhindert, dass veraltete CLI-/Device-Pairing-Baselines lokale Backend-Arbeit wie Subagent-Sitzungsaktualisierungen blockieren. Remote-Clients, Browser-Origin-Clients, Node-Clients und explizite Device-Token-/Device-Identity- Clients verwenden weiterhin die normalen Pairing- und Scope-Upgrade-Prüfungen.

Wenn ein Device-Token ausgestellt wird, enthält hello-ok außerdem:

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

Der integrierte QR-/Setup-Code-Bootstrap ist ein frischer mobiler Übergabepfad. Eine erfolgreiche Baseline-Setup-Code-Verbindung gibt ein primäres Node-Token plus ein begrenztes Operator-Token zurück:

{  "auth": {    "deviceToken": "…",    "role": "node",    "scopes": [],    "deviceTokens": [      {        "deviceToken": "…",        "role": "operator",        "scopes": ["operator.approvals", "operator.read", "operator.talk.secrets", "operator.write"]      }    ]  }}

Die Operator-Übergabe ist bewusst begrenzt, damit das QR-Onboarding die mobile Operator-Schleife starten und die native Einrichtung abschließen kann, ohne Pairing- Mutations-Scopes oder operator.admin zu gewähren. Sie enthält operator.talk.secrets, damit der native Client die nach dem Bootstrap benötigte Talk-Konfiguration lesen kann. Umfassenderer Pairing- und Admin-Zugriff erfordert einen separaten genehmigten Operator-Pairing- oder Token- Flow. Clients sollten hello-ok.auth.deviceTokens nur dann persistieren, wenn die Verbindung Bootstrap-Authentifizierung über vertrauenswürdigen Transport wie wss:// oder Loopback-/lokales Pairing verwendet hat.

Node-Beispiel

{  "type": "req",  "id": "…",  "method": "connect",  "params": {    "minProtocol": 3,    "maxProtocol": 4,    "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 Seiteneffekten erfordern Idempotenzschlüssel (siehe Schema).

Rollen + Geltungsbereiche

Das vollständige Operator-Scope-Modell, Prüfungen zum Genehmigungszeitpunkt und die Semantik gemeinsamer Secrets finden Sie unter Operator-Scopes.

Rollen

• operator = Client der Steuerungsebene (CLI/UI/Automatisierung).
• node = Capability-Host (Kamera/Bildschirm/Canvas/system.run).

Geltungsbereiche (Operator)

Gängige Geltungsbereiche:

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

talk.config mit includeSecrets: true erfordert operator.talk.secrets (oder operator.admin). Wenn Secrets enthalten sind, sollten Clients die aktive Zugangsdatenkonfiguration des Talk-Providers aus talk.resolved.config.apiKey lesen; talk.providers.<id>.apiKey bleibt quellförmig und kann ein SecretRef-Objekt oder ein redigierter String sein.

Von Plugins registrierte Gateway-RPC-Methoden können ihren eigenen Operator-Scope anfordern, aber reservierte Core-Admin-Präfixe (config.*, exec.approvals.*, wizard.*, update.*) werden immer zu operator.admin aufgelöst.

Der Methoden-Scope ist nur die erste Schranke. Einige über chat.send erreichte Slash-Befehle wenden zusätzlich strengere Prüfungen auf Befehlsebene an. Beispielsweise erfordern persistente /config set- und /config unset-Schreibvorgänge operator.admin.

node.pair.approve hat zusätzlich zum Basis-Methoden-Scope eine weitere Scope-Prüfung zum Genehmigungszeitpunkt:

• Anfragen ohne Befehl: operator.pairing
• Anfragen mit Nicht-Exec-Node-Befehlen: operator.pairing + operator.write
• Anfragen, die system.run, system.run.prepare oder system.which enthalten: operator.pairing + operator.admin

Caps/Befehle/Berechtigungen (Node)

Nodes deklarieren Capability-Ansprüche zum Verbindungszeitpunkt:

• caps: übergeordnete Capability-Kategorien wie camera, canvas, screen, location, voice und talk.
• commands: Befehls-Allowlist für Invoke.
• permissions: granulare Umschalter (z. B. screen.record, camera.capture).

Der Gateway behandelt diese als Ansprüche und erzwingt serverseitige Allowlists.

Präsenz

• system-presence gibt Einträge zurück, die nach Device-Identität geschlüsselt sind.
• Präsenzeinträge enthalten deviceId, roles und scopes, damit UIs eine einzelne Zeile pro Device anzeigen können, auch wenn es sowohl als operator als auch als node verbunden ist.
• node.list enthält optionale Felder lastSeenAtMs und lastSeenReason. Verbundene Nodes melden ihre aktuelle Verbindungszeit als lastSeenAtMs mit Reason connect; gekoppelte Nodes können außerdem dauerhafte Hintergrundpräsenz melden, wenn ein vertrauenswürdiges Node-Ereignis ihre Pairing-Metadaten aktualisiert.

Hintergrund-Alive-Ereignis für Nodes

Nodes können node.event mit event: "node.presence.alive" aufrufen, um aufzuzeichnen, dass ein gekoppelte Node während eines Hintergrund-Weckvorgangs aktiv war, ohne ihn als verbunden zu markieren.

{  "event": "node.presence.alive",  "payloadJSON": "{\"trigger\":\"silent_push\",\"sentAtMs\":1737264000000,\"displayName\":\"Peter's iPhone\",\"version\":\"2026.4.28\",\"platform\":\"iOS 18.4.0\",\"deviceFamily\":\"iPhone\",\"modelIdentifier\":\"iPhone17,1\",\"pushTransport\":\"relay\"}"}

trigger ist ein geschlossenes Enum: background, silent_push, bg_app_refresh, significant_location, manual oder connect. Unbekannte Trigger-Strings werden vom Gateway vor der Persistierung zu background normalisiert. Das Ereignis ist nur für authentifizierte Node- Device-Sitzungen dauerhaft; Device-lose oder nicht gekoppelte Sitzungen geben handled: false zurück.

Erfolgreiche Gateways geben ein strukturiertes Ergebnis zurück:

{  "ok": true,  "event": "node.presence.alive",  "handled": true,  "reason": "persisted"}

Ältere Gateways können für node.event weiterhin { "ok": true } zurückgeben; Clients sollten dies als bestätigten RPC behandeln, nicht als dauerhafte Präsenzpersistierung.

Geltungsbereich für Broadcast-Ereignisse

Vom Server gepushte WebSocket-Broadcast-Ereignisse sind scope-gesteuert, damit Pairing-begrenzte oder Node-only-Sitzungen keine Sitzungsinhalte passiv empfangen.

• Chat-, Agent- und Tool-Ergebnis-Frames (einschließlich gestreamter agent-Ereignisse und Tool-Aufrufergebnisse) erfordern mindestens operator.read. Sitzungen ohne operator.read überspringen diese Frames vollständig.
• Plugin-definierte plugin.*-Broadcasts sind je nach Registrierung durch das Plugin auf operator.write oder operator.admin beschränkt.
• Status- und Transportereignisse (heartbeat, presence, tick, Connect-/Disconnect-Lebenszyklus usw.) bleiben uneingeschränkt, damit die Transportgesundheit für jede authentifizierte Sitzung beobachtbar bleibt.
• Unbekannte Broadcast-Ereignisfamilien sind standardmäßig scope-gesteuert (fail-closed), sofern ein registrierter Handler sie nicht ausdrücklich lockert.

Jede Client-Verbindung behält ihre eigene Sequenznummer pro Client, sodass Broadcasts auf diesem Socket eine monotone Reihenfolge bewahren, auch wenn verschiedene Clients unterschiedliche scope-gefilterte Teilmengen des Ereignisstreams sehen.

Häufige RPC-Methodenfamilien

Die öffentliche WS-Oberfläche ist breiter als die obigen Handshake-/Auth-Beispiele. Dies ist kein generierter Dump — hello-ok.features.methods ist eine konservative Discovery-Liste, die aus src/gateway/server-methods-list.ts plus geladenen Plugin-/Channel-Methodenexporten erstellt wird. Behandeln Sie sie als Feature Discovery, nicht als vollständige Aufzählung von src/gateway/server-methods/*.ts.

Häufige Ereignisfamilien

• chat: UI-Chat-Updates wie chat.inject und andere reine Transkript-Chat- Ereignisse. In Protokoll v4 tragen Delta-Nutzdaten deltaText; message bleibt der kumulative Assistant-Snapshot. Nicht-Präfix-Ersetzungen setzen replace=true und verwenden deltaText als Ersetzungstext.
• session.message, session.operation und session.tool: Transkript-, laufende Sitzungsoperation- und Ereignisstrom-Updates für eine abonnierte Sitzung.
• sessions.changed: Sitzungsindex oder Metadaten wurden geändert.
• presence: Aktualisierungen des System-Präsenz-Snapshots.
• tick: periodisches Keepalive-/Liveness-Ereignis.
• health: Aktualisierung des Gateway-Health-Snapshots.
• heartbeat: Aktualisierung des Heartbeat-Ereignisstroms.
• cron: Cron-Run-/Job-Änderungsereignis.
• shutdown: Gateway-Herunterfahrbenachrichtigung.
• node.pair.requested / node.pair.resolved: Node-Kopplungslebenszyklus.
• node.invoke.request: Broadcast einer Node-Aufrufanfrage.
• device.pair.requested / device.pair.resolved: Lebenszyklus gekoppelter Geräte.
• voicewake.changed: Wake-Word-Trigger-Konfiguration geändert.
• exec.approval.requested / exec.approval.resolved: Exec-Genehmigungs- lebenszyklus.
• plugin.approval.requested / plugin.approval.resolved: Plugin-Genehmigungs- lebenszyklus.

Node-Hilfsmethoden

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

Aufgabenbuch-RPCs

Operator-Clients können Gateway-Hintergrundaufgabendatensätze über die Aufgabenbuch-RPCs prüfen und abbrechen. Diese Methoden geben bereinigte Aufgabenzusammenfassungen zurück, keinen rohen Laufzeitzustand.

• tasks.list erfordert operator.read.
  • Parameter: optional status ("queued", "running", "completed", "failed", "cancelled" oder "timed_out") oder ein Array dieser Statuswerte, optional agentId, optional sessionKey, optional limit von 1 bis 500 und optionaler String cursor.
  • Ergebnis: { "tasks": TaskSummary[], "nextCursor"?: string }.
• tasks.get erfordert operator.read.
  • Parameter: { "taskId": string }.
  • Ergebnis: { "task": TaskSummary }.
  • Fehlende Aufgaben-IDs geben die Gateway-Not-found-Fehlerform zurück.
• tasks.cancel erfordert operator.write.
  • Parameter: { "taskId": string, "reason"?: string }.
  • Ergebnis: { "found": boolean, "cancelled": boolean, "reason"?: string, "task"?: TaskSummary }.
  • found meldet, ob das Aufgabenbuch eine passende Aufgabe enthielt. cancelled meldet, ob die Laufzeit den Abbruch akzeptiert oder aufgezeichnet hat.

TaskSummary enthält id, status und optionale Metadaten wie kind, runtime, title, agentId, sessionKey, childSessionKey, ownerKey, runId, taskId, flowId, parentTaskId, sourceId, Zeitstempel, Fortschritt, terminale Zusammenfassung und bereinigten Fehlertext. agentId identifiziert den Agenten, der die Aufgabe ausführt; sessionKey und ownerKey bewahren Anfragesteller- und Steuerungs- kontext.

Operator-Hilfsmethoden

• Operatoren können commands.list (operator.read) aufrufen, um das Laufzeit- Befehlsinventar für einen Agenten abzurufen.
  • agentId ist optional; lassen Sie es weg, um den Standard-Agent-Arbeitsbereich zu lesen.
  • scope steuert, welche Oberfläche das primäre name adressiert:
    • text gibt das primäre Textbefehlstoken ohne führendes / zurück
    • native und der Standardpfad both geben Provider-bewusste native Namen zurück, wenn verfügbar
  • textAliases enthält exakte Slash-Aliasse wie /model und /m.
  • nativeName enthält den Provider-bewussten nativen Befehlsnamen, wenn einer existiert.
  • provider ist optional und wirkt sich nur auf native Benennung sowie native Plugin- Befehlsverfügbarkeit aus.
  • includeArgs=false lässt serialisierte Argumentmetadaten in der Antwort weg.
• Operatoren können tools.catalog (operator.read) aufrufen, um den Laufzeit-Tool-Katalog für einen Agenten abzurufen. Die Antwort enthält gruppierte Tools und Herkunftsmetadaten:
  • source: core oder plugin
  • pluginId: Plugin-Eigentümer, wenn source="plugin"
  • optional: ob ein Plugin-Tool optional ist
• Operatoren können tools.effective (operator.read) aufrufen, um das zur Laufzeit wirksame Tool- Inventar für eine Sitzung abzurufen.
  • sessionKey ist erforderlich.
  • Das Gateway leitet vertrauenswürdigen Laufzeitkontext serverseitig aus der Sitzung ab, statt vom Aufrufer bereitgestellten Authentifizierungs- oder Zustellungskontext zu akzeptieren.
  • Die Antwort ist eine sitzungsbezogene, serverseitig abgeleitete Projektion des aktiven Inventars, einschließlich Core-, Plugin-, Channel- und bereits entdeckter MCP-Server-Tools.
  • tools.effective ist für MCP schreibgeschützt: Es kann einen warmen Sitzungs-MCP-Katalog durch die finale Tool-Richtlinie projizieren, erstellt aber keine MCP-Laufzeiten, verbindet keine Transports und gibt kein tools/list aus. Wenn kein passender warmer Katalog existiert, kann die Antwort einen Hinweis wie mcp-not-yet-connected, mcp-not-yet-listed oder mcp-stale-catalog enthalten.
  • Wirksame Tool-Einträge verwenden source="core", source="plugin", source="channel" oder source="mcp".
• Operatoren können tools.invoke (operator.write) aufrufen, um ein verfügbares Tool über denselben Gateway-Richtlinienpfad wie /tools/invoke aufzurufen.
  • name ist erforderlich. args, sessionKey, agentId, confirm und idempotencyKey sind optional.
  • Wenn sowohl sessionKey als auch agentId vorhanden sind, muss der aufgelöste Sitzungsagent mit agentId übereinstimmen.
  • Nur Eigentümern vorbehaltene Core-Wrapper wie cron, gateway und nodes erfordern Eigentümer-/Admin-Identität (operator.admin), obwohl die Methode tools.invoke selbst operator.write ist.
  • Die Antwort ist ein SDK-seitiger Umschlag mit ok, toolName, optionalem output und typisierten error-Feldern. Genehmigungs- oder Richtlinienablehnungen geben ok:false in der Nutzlast zurück, statt die Gateway-Tool-Richtlinienpipeline zu umgehen.
• Operatoren können skills.status (operator.read) aufrufen, um das sichtbare Skill-Inventar für einen Agenten abzurufen.
  • agentId ist optional; lassen Sie es weg, um den Standard-Agent-Arbeitsbereich zu lesen.
  • Die Antwort enthält Berechtigung, fehlende Anforderungen, Konfigurationsprüfungen und bereinigte Installationsoptionen, ohne rohe Secret-Werte offenzulegen.
• Operatoren können skills.search und skills.detail (operator.read) für ClawHub-Entdeckungsmetadaten aufrufen.
• Operatoren können skills.upload.begin, skills.upload.chunk und skills.upload.commit (operator.admin) aufrufen, um ein privates Skill-Archiv vor der Installation bereitzustellen. Dies ist ein separater Admin-Uploadpfad für vertrauenswürdige Clients, nicht der normale ClawHub-Skill-Installationsfluss, und standardmäßig deaktiviert, sofern skills.install.allowUploadedArchives nicht aktiviert ist.
  • skills.upload.begin({ kind: "skill-archive", slug, sizeBytes, sha256?, force?, idempotencyKey? }) erstellt einen Upload, der an diesen Slug und Force-Wert gebunden ist.
  • skills.upload.chunk({ uploadId, offset, dataBase64 }) hängt Bytes am exakt dekodierten Offset an.
  • skills.upload.commit({ uploadId, sha256? }) verifiziert die endgültige Größe und SHA-256. Commit finalisiert nur den Upload; es installiert den Skill nicht.
  • Hochgeladene Skill-Archive sind Zip-Archive, die ein SKILL.md-Root enthalten. Der interne Verzeichnisname des Archivs wählt niemals das Installationsziel aus.
• Operatoren können skills.install (operator.admin) in drei Modi aufrufen:
  • ClawHub-Modus: { source: "clawhub", slug, version?, force? } installiert einen Skill-Ordner in das skills/-Verzeichnis des Standard-Agent-Arbeitsbereichs.
  • Upload-Modus: { source: "upload", uploadId, slug, force?, sha256?, timeoutMs? } installiert einen committeten Upload in das Verzeichnis skills/<slug> des Standard-Agent-Arbeitsbereichs. Der Slug und der Force-Wert müssen mit der ursprünglichen skills.upload.begin-Anfrage übereinstimmen. Dieser Modus wird abgelehnt, sofern skills.install.allowUploadedArchives nicht aktiviert ist. Die Einstellung wirkt sich nicht auf ClawHub-Installationen aus.
  • Gateway-Installationsmodus: { name, installId, timeoutMs? } führt eine deklarierte metadata.openclaw.install-Aktion auf dem Gateway-Host aus. Ältere Clients können weiterhin dangerouslyForceUnsafeInstall senden; dieses Feld ist veraltet, wird nur aus Protokollkompatibilität akzeptiert und ignoriert. Verwenden Sie security.installPolicy für operatorgesteuerte Installationsentscheidungen.
• Operatoren können skills.update (operator.admin) in zwei Modi aufrufen:
  • Der ClawHub-Modus aktualisiert einen verfolgten Slug oder alle verfolgten ClawHub-Installationen im Standard-Agent-Arbeitsbereich.
  • Der Konfigurationsmodus patcht skills.entries.<skillKey>-Werte wie enabled, apiKey und env.

models.list-Ansichten

models.list akzeptiert einen optionalen Parameter view:

• Weggelassen oder "default": aktuelles Laufzeitverhalten. Wenn agents.defaults.models konfiguriert ist, ist die Antwort der erlaubte Katalog, einschließlich dynamisch entdeckter Modelle für provider/*-Einträge. Andernfalls ist die Antwort der vollständige Gateway-Katalog.
• "configured": Verhalten in Picker-Größe. Wenn agents.defaults.models konfiguriert ist, hat es weiterhin Vorrang, einschließlich providerbezogener Entdeckung für provider/*-Einträge. Ohne Allowlist verwendet die Antwort explizite models.providers.*.models-Einträge und fällt nur dann auf den vollständigen Katalog zurück, wenn keine konfigurierten Modellzeilen existieren.
• "all": vollständiger Gateway-Katalog, unter Umgehung von agents.defaults.models. Verwenden Sie dies für Diagnose- und Entdeckungs-UIs, nicht für normale Modell-Picker.

Exec-Genehmigungen

• Wenn eine Exec-Anfrage Genehmigung benötigt, broadcastet das Gateway exec.approval.requested.
• Operator-Clients lösen dies durch Aufruf von exec.approval.resolve auf (erfordert den Scope operator.approvals).
• Für host=node muss exec.approval.request systemRunPlan enthalten (kanonische argv/cwd/rawCommand/Sitzungsmetadaten). Anfragen ohne systemRunPlan werden abgelehnt.
• Nach der Genehmigung verwenden weitergeleitete node.invoke system.run-Aufrufe diesen kanonischen systemRunPlan als autoritativen Befehls-/cwd-/Sitzungskontext wieder.
• Wenn ein Aufrufer command, rawCommand, cwd, agentId oder sessionKey zwischen Vorbereitung und der final genehmigten system.run-Weiterleitung mutiert, lehnt das Gateway den Lauf ab, statt der mutierten Nutzlast zu vertrauen.

Fallback für Agent-Zustellung

• agent-Anfragen können deliver=true enthalten, um ausgehende Zustellung anzufordern.
• bestEffortDeliver=false behält striktes Verhalten bei: nicht auflösbare oder nur interne Zustellungsziele geben INVALID_REQUEST zurück.
• bestEffortDeliver=true erlaubt Fallback auf reine Sitzungsausführung, wenn keine extern zustellbare Route aufgelöst werden kann (zum Beispiel interne/Webchat-Sitzungen oder mehrdeutige Mehrkanal-Konfigurationen).
• Finale agent-Ergebnisse können result.deliveryStatus enthalten, wenn Zustellung angefordert wurde, mit denselben Statuswerten sent, suppressed, partial_failed und failed, die für openclaw agent --json --deliver dokumentiert sind.

Versionierung

• PROTOCOL_VERSION befindet sich in packages/gateway-protocol/src/version.ts.
• Clients senden minProtocol + maxProtocol; der Server lehnt Bereiche ab, die sein aktuelles Protokoll nicht enthalten. Aktuelle Clients und Server erfordern Protokoll v4.
• Schemas + Modelle werden aus TypeBox-Definitionen generiert:
  • pnpm protocol:gen
  • pnpm protocol:gen:swift
  • pnpm protocol:check

Client-Konstanten

Der Referenzclient in src/gateway/client.ts verwendet diese Standardwerte. Werte sind über Protokoll v4 hinweg stabil und bilden die erwartete Baseline für Drittanbieter-Clients.

Der Server kündigt das effektive policy.tickIntervalMs, policy.maxPayload und policy.maxBufferedBytes in hello-ok an; Clients sollten diese Werte statt der Standardwerte vor dem Handshake beachten.

Auth

• Die Shared-Secret-Gateway-Authentifizierung verwendet je nach konfiguriertem Authentifizierungsmodus connect.params.auth.token oder connect.params.auth.password.
• Modi mit Identitätsinformationen wie Tailscale Serve (gateway.auth.allowTailscale: true) oder nicht-loopback gateway.auth.mode: "trusted-proxy" erfüllen die Authentifizierungsprüfung beim Verbindungsaufbau anhand von Request-Headern statt connect.params.auth.*.
• Private-Ingress gateway.auth.mode: "none" überspringt die Shared-Secret-Authentifizierung beim Verbindungsaufbau vollständig; setzen Sie diesen Modus nicht auf öffentlichem/nicht vertrauenswürdigem Ingress ein.
• Nach dem Pairing stellt der Gateway ein Geräte-Token aus, das auf die Verbindungsrolle
  • Scopes beschränkt ist. Es wird in hello-ok.auth.deviceToken zurückgegeben und sollte vom Client für zukünftige Verbindungen dauerhaft gespeichert werden.
• Clients sollten das primäre hello-ok.auth.deviceToken nach jeder erfolgreichen Verbindung dauerhaft speichern.
• Eine erneute Verbindung mit diesem gespeicherten Geräte-Token sollte auch den gespeicherten genehmigten Scope-Satz für dieses Token wiederverwenden. Dadurch bleiben bereits gewährte Lese-/Probe-/Statuszugriffe erhalten, und erneute Verbindungen werden nicht stillschweigend auf einen engeren impliziten Nur-Admin-Scope reduziert.
• Clientseitige Zusammensetzung der Verbindungs-Authentifizierung (selectConnectAuth in src/gateway/client.ts):
  • auth.password ist orthogonal und wird immer weitergeleitet, wenn gesetzt.
  • auth.token wird in Prioritätsreihenfolge befüllt: zuerst explizites Shared Token, dann ein explizites deviceToken, dann ein gespeichertes Token pro Gerät (geschlüsselt nach deviceId + role).
  • auth.bootstrapToken wird nur gesendet, wenn keines der oben genannten ein auth.token aufgelöst hat. Ein Shared Token oder ein beliebiges aufgelöstes Geräte-Token unterdrückt es.
  • Die automatische Hochstufung eines gespeicherten Geräte-Tokens beim einmaligen AUTH_TOKEN_MISMATCH-Retry ist auf vertrauenswürdige Endpunkte beschränkt — loopback oder wss:// mit angepinntem tlsFingerprint. Öffentliches wss:// ohne Pinning qualifiziert sich nicht.
• Der integrierte Setup-Code-Bootstrap gibt das primäre Node- hello-ok.auth.deviceToken sowie ein begrenztes Operator-Token in hello-ok.auth.deviceTokens für die vertrauenswürdige mobile Übergabe zurück. Das Operator-Token enthält operator.talk.secrets für native Talk-Konfigurationslesevorgänge, schließt aber Pairing-Mutations-Scopes und operator.admin aus.
• Während ein nicht-baseline Setup-Code-Bootstrap auf Genehmigung wartet, enthalten PAIRING_REQUIRED- Details recommendedNextStep: "wait_then_retry", retryable: true und pauseReconnect: false. Clients sollten weiterhin mit demselben Bootstrap-Token neu verbinden, bis die Anfrage genehmigt wurde oder das Token ungültig wird.
• Speichern Sie hello-ok.auth.deviceTokens nur dauerhaft, wenn die Verbindung Bootstrap-Authentifizierung über einen vertrauenswürdigen Transport wie wss:// oder loopback/lokales Pairing verwendet hat.
• Wenn ein Client ein explizites deviceToken oder explizite scopes bereitstellt, bleibt dieser vom Aufrufer angeforderte Scope-Satz maßgeblich; gecachte Scopes werden nur wiederverwendet, wenn der Client das gespeicherte Token pro Gerät wiederverwendet.
• Geräte-Token können über device.token.rotate und device.token.revoke rotiert/widerrufen werden (erfordert Scope operator.pairing). Das Rotieren oder Widerrufen eines Node- oder anderen Nicht-Operator-Rollen-Tokens erfordert zusätzlich operator.admin.
• device.token.rotate gibt Rotationsmetadaten zurück. Es gibt das Ersatz- Bearer-Token nur bei Aufrufen desselben Geräts zurück, die bereits mit diesem Geräte-Token authentifiziert sind, sodass reine Token-Clients ihren Ersatz vor dem erneuten Verbinden dauerhaft speichern können. Shared-/Admin-Rotationen geben das Bearer-Token nicht zurück.
• Token-Ausstellung, -Rotation und -Widerruf bleiben auf den genehmigten Rollensatz beschränkt, der im Pairing-Eintrag dieses Geräts aufgezeichnet ist; Token-Mutation kann keine Geräterolle erweitern oder anvisieren, die die Pairing-Genehmigung nie gewährt hat.
• Bei gekoppelten Geräte-Token-Sitzungen ist die Geräteverwaltung selbstbezogen, es sei denn, der Aufrufer hat zusätzlich operator.admin: Nicht-Admin-Aufrufer können nur das Operator-Token für ihren eigenen Geräteeintrag verwalten. Node- und andere Nicht-Operator- Token-Verwaltung ist nur Admins vorbehalten, auch für das eigene Gerät des Aufrufers.
• device.token.rotate und device.token.revoke prüfen außerdem den Scope-Satz des Ziel-Operator- Tokens gegen die aktuellen Sitzungs-Scopes des Aufrufers. Nicht-Admin-Aufrufer können kein breiteres Operator-Token rotieren oder widerrufen, als sie bereits besitzen.
• Authentifizierungsfehler enthalten error.details.code plus Wiederherstellungshinweise:
  • error.details.canRetryWithDeviceToken (boolesch)
  • error.details.recommendedNextStep (retry_with_device_token, update_auth_configuration, update_auth_credentials, wait_then_retry, review_auth_configuration)
• Client-Verhalten bei AUTH_TOKEN_MISMATCH:
  • Vertrauenswürdige Clients dürfen einen begrenzten Retry mit einem gecachten Token pro Gerät versuchen.
  • Wenn dieser Retry fehlschlägt, sollten Clients automatische Wiederverbindungs-Schleifen stoppen und Hinweise für Operator-Aktionen anzeigen.
• AUTH_SCOPE_MISMATCH bedeutet, dass das Geräte-Token erkannt wurde, aber die angeforderten Rollen/Scopes nicht abdeckt. Clients sollten dies nicht als fehlerhaftes Token darstellen; fordern Sie den Operator auf, erneut zu pairen oder den engeren/breiteren Scope-Vertrag zu genehmigen.

Geräteidentität + Pairing

• Nodes sollten eine stabile Geräteidentität (device.id) enthalten, die aus einem Schlüsselpaar-Fingerprint abgeleitet ist.
• Gateways stellen Tokens pro Gerät + Rolle aus.
• Pairing-Genehmigungen sind für neue Geräte-IDs erforderlich, sofern lokale automatische Genehmigung nicht aktiviert ist.
• Die automatische Pairing-Genehmigung konzentriert sich auf direkte lokale loopback-Verbindungen.
• OpenClaw hat außerdem einen schmalen backend-/container-lokalen Selbstverbindungspfad für vertrauenswürdige Shared-Secret-Hilfsabläufe.
• Same-Host-tailnet- oder LAN-Verbindungen werden für Pairing weiterhin als remote behandelt und erfordern eine Genehmigung.
• WS-Clients enthalten normalerweise während connect eine device-Identität (Operator + Node). Die einzigen gerätelosen Operator-Ausnahmen sind explizite Vertrauenspfade:
  • gateway.controlUi.allowInsecureAuth=true für localhost-only unsichere HTTP-Kompatibilität.
  • erfolgreiche Operator-Control-UI-Authentifizierung mit gateway.auth.mode: "trusted-proxy".
  • gateway.controlUi.dangerouslyDisableDeviceAuth=true (Break-Glass, erhebliche Sicherheitsherabstufung).
  • direkte-loopback gateway-client Backend-RPCs auf dem reservierten internen Hilfspfad.
• Das Weglassen der Geräteidentität hat Auswirkungen auf Scopes. Wenn eine gerätelose Operator- Verbindung über einen expliziten Vertrauenspfad zugelassen wird, löscht OpenClaw dennoch selbst deklarierte Scopes auf eine leere Menge, sofern dieser Pfad keine benannte Ausnahme zur Scope-Beibehaltung hat. Scope-gesteuerte Methoden schlagen dann mit missing scope fehl.
• gateway.controlUi.dangerouslyDisableDeviceAuth=true ist ein Control-UI- Break-Glass-Pfad zur Scope-Beibehaltung. Er gewährt keinen beliebigen benutzerdefinierten Backend- oder CLI-förmigen WebSocket-Clients Scopes.
• Der reservierte direkte-loopback gateway-client Backend-Hilfspfad behält Scopes nur für interne lokale Control-Plane-RPCs bei; benutzerdefinierte Backend-IDs erhalten diese Ausnahme nicht.
• Alle Verbindungen müssen die vom Server bereitgestellte connect.challenge-Nonce signieren.

Diagnose der Geräteauthentifizierungs-Migration

Für Legacy-Clients, die noch das Signaturverhalten vor Challenge verwenden, gibt connect nun DEVICE_AUTH_*-Detailcodes unter error.details.code mit einem stabilen error.details.reason zurück.

Häufige Migrationsfehler:

Migrationsziel:

• Warten Sie immer auf connect.challenge.
• Signieren Sie den v2-Payload, der die Server-Nonce enthält.
• Senden Sie dieselbe Nonce in connect.params.device.nonce.
• Bevorzugter Signatur-Payload ist v3, der zusätzlich zu Geräte-/Client-/Rollen-/Scope-/Token-/Nonce-Feldern platform und deviceFamily bindet.
• Legacy-v2-Signaturen bleiben aus Kompatibilitätsgründen akzeptiert, aber Metadaten-Pinning für gekoppelte Geräte steuert weiterhin die Befehlsrichtlinie bei erneuter Verbindung.

TLS + Pinning

• TLS wird für WS-Verbindungen unterstützt.
• Clients können optional den Gateway-Zertifikats-Fingerprint anpinnen (siehe gateway.tls- Konfiguration plus gateway.remote.tlsFingerprint oder CLI --tls-fingerprint).

Scope

Dieses Protokoll stellt die vollständige Gateway-API bereit (Status, Kanäle, Modelle, Chat, Agent, Sitzungen, Nodes, Genehmigungen usw.). Die genaue Oberfläche wird durch die TypeBox-Schemas in packages/gateway-protocol/src/schema.ts definiert.

Verwandt

• Bridge-Protokoll
• Gateway-Runbook