Gateway-Protokoll

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

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 geben zu große eingehende Frames und langsame ausgehende Puffer payload.large-Events aus, bevor der Gateway den betroffenen Frame schließt oder verwirft. Diese Events behalten Größen, Limits, Oberflächen und sichere Reason-Codes. Sie behalten nicht den Nachrichtentext, Anhangsinhalte, den rohen Frame-Body, Tokens, Cookies oder geheime Werte.

​

Handshake (connect)

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

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

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

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

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

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

​

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}
• Event: {type:"event", event, payload, seq?, stateVersion?}

​

Rollen + Scopes

​

Rollen

• operator = Control-Plane-Client (CLI/UI/Automatisierung).
• node = Capability-Host (camera/screen/canvas/system.run).

​

Scopes (Operator)

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

• Anfragen ohne Befehle: 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/commands/permissions (Node)

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

​

Präsenz

• system-presence gibt Einträge zurück, die nach Device-Identity geschlüsselt sind.
• Präsenz-Einträge enthalten deviceId, roles und scopes, damit UIs eine einzelne Zeile pro Gerät 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 dem Grund connect; gepaarte Nodes können außerdem dauerhafte Hintergrundpräsenz melden, wenn ein vertrauenswürdiges Node-Event ihre Pairing-Metadaten aktualisiert.

​

Node-Hintergrund-alive-Event

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

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

​

Scope-Eingrenzung für Broadcast-Events

• Chat-, Agent- und Tool-Result-Frames (einschließlich gestreamter agent-Events und Tool-Call-Ergebnisse) erfordern mindestens operator.read. Sessions ohne operator.read überspringen diese Frames vollständig.
• Plugin-definierte plugin.*-Broadcasts werden je nachdem, wie das Plugin sie registriert hat, auf operator.write oder operator.admin begrenzt.
• Status- und Transport-Events (heartbeat, presence, tick, Connect-/Disconnect-Lebenszyklus usw.) bleiben uneingeschränkt, damit die Transportintegrität für jede authentifizierte Session beobachtbar bleibt.
• Unbekannte Broadcast-Event-Familien sind standardmäßig durch Scopes geschützt (fail-closed), sofern ein registrierter Handler sie nicht ausdrücklich lockert.

​

Häufige RPC-Methodenfamilien

​

Häufige Ereignisfamilien

• chat: UI-Chat-Aktualisierungen wie chat.inject und andere rein transkriptbezogene Chat- Ereignisse.
• session.message und session.tool: Transkript-/Ereignisstrom-Aktualisierungen für eine abonnierte Sitzung.
• sessions.changed: Sitzungsindex oder Metadaten geändert.
• presence: Aktualisierungen des Systempräsenz-Snapshots.
• tick: periodisches Keepalive-/Liveness-Ereignis.
• health: Aktualisierung des Gateway-Zustands-Snapshots.
• heartbeat: Aktualisierung des Heartbeat-Ereignisstroms.
• cron: Ereignis zur Änderung eines Cron-Laufs/-Jobs.
• shutdown: Benachrichtigung zum Herunterfahren des Gateways.
• node.pair.requested / node.pair.resolved: Node-Pairing-Lebenszyklus.
• 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 ausführbaren Skill-Dateien für Auto-Allow-Prüfungen abzurufen.

​

Task-Ledger-RPCs

• 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 Task-IDs geben die Not-Found-Fehlerform des Gateways 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 Ledger eine passende Aufgabe enthielt. cancelled meldet, ob die Laufzeit den Abbruch akzeptiert oder aufgezeichnet hat.

​

Operator-Hilfsmethoden

• Operatoren können commands.list (operator.read) aufrufen, um den Laufzeit- Befehlsbestand für einen Agent abzurufen.
  • agentId ist optional; lassen Sie es weg, um den Standard-Agent-Workspace zu lesen.
  • scope steuert, auf welche Oberfläche das primäre name zielt:
    • text gibt das primäre Textbefehlstoken ohne führendes / zurück
    • native und der standardmäßige both-Pfad geben Provider-bewusste native Namen zurück, wenn verfügbar
  • textAliases enthält exakte Slash-Aliase 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-Toolkatalog für einen Agent abzurufen. Die Antwort enthält gruppierte Tools und Provenienzmetadaten:
  • source: core oder plugin
  • pluginId: Plugin-Besitzer, wenn source="plugin"
  • optional: ob ein Plugin-Tool optional ist
• Operatoren können tools.effective (operator.read) aufrufen, um den zur Laufzeit wirksamen Tool- Bestand für eine Sitzung abzurufen.
  • sessionKey ist erforderlich.
  • Das Gateway leitet vertrauenswürdigen Laufzeitkontext serverseitig aus der Sitzung ab, statt vom Aufrufer bereitgestellten Auth- oder Zustellungskontext zu akzeptieren.
  • Die Antwort ist sitzungsbezogen und spiegelt wider, was die aktive Unterhaltung jetzt verwenden kann, einschließlich Core-, Plugin- und Kanal-Tools.
• 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 Sitzungs-Agent agentId entsprechen.
  • Die Antwort ist ein SDK-seitiges Envelope 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 den sichtbaren Skill-Bestand für einen Agent abzurufen.
  • agentId ist optional; lassen Sie es weg, um den Standard-Agent-Workspace zu lesen.
  • Die Antwort enthält Eignung, 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-Discovery-Metadaten 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-Upload-Pfad für vertrauenswürdige Clients, nicht der normale ClawHub-Skill-Installationsablauf, 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 decodierten Offset an.
  • skills.upload.commit({ uploadId, sha256? }) prüft die endgültige Größe und SHA-256. Commit schließt nur den Upload ab; es installiert den Skill nicht.
  • Hochgeladene Skill-Archive sind ZIP-Archive, die eine 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-Workspaces.
  • Upload-Modus: { source: "upload", uploadId, slug, force?, sha256?, timeoutMs? } installiert einen abgeschlossenen Upload in das Verzeichnis skills/<slug> des Standard-Agent-Workspaces. Slug und Force-Wert müssen der ursprünglichen skills.upload.begin-Anfrage entsprechen. Dieser Modus wird abgelehnt, sofern skills.install.allowUploadedArchives nicht aktiviert ist. Die Einstellung wirkt sich nicht auf ClawHub-Installationen aus.
  • Gateway-Installer-Modus: { name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? } führt eine deklarierte metadata.openclaw.install-Aktion auf dem Gateway-Host aus.
• Operatoren können skills.update (operator.admin) in zwei Modi aufrufen:
  • Der ClawHub-Modus aktualisiert einen nachverfolgten Slug oder alle nachverfolgten ClawHub-Installationen im Standard-Agent-Workspace.
  • Der Konfigurationsmodus patcht Werte unter skills.entries.<skillKey> wie enabled, apiKey und env.

​

models.list-Ansichten

• 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": Picker-großes Verhalten. Wenn agents.defaults.models konfiguriert ist, hat es weiterhin Vorrang, einschließlich Provider-bezogener Discovery 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 Discovery-UIs, nicht für normale Modell-Picker.

​

Exec-Genehmigungen

• Wenn eine Exec-Anfrage Genehmigung benötigt, sendet 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.
• Wenn ein Aufrufer command, rawCommand, cwd, agentId oder sessionKey zwischen Vorbereitung und der abschließenden genehmigten system.run-Weiterleitung verändert, lehnt das Gateway den Lauf ab, statt der veränderten 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 Zustellziele geben INVALID_REQUEST zurück.
• bestEffortDeliver=true erlaubt einen Fallback auf sitzungsgebundene Ausfü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, und verwenden dabei dieselben Statuswerte sent, suppressed, partial_failed und failed, die für openclaw agent --json --deliver dokumentiert sind.

​

Versionierung

• PROTOCOL_VERSION befindet sich in src/gateway/protocol/version.ts.
• Clients senden minProtocol + maxProtocol; der Server lehnt Bereiche ab, die sein aktuelles Protokoll nicht einschließen. Native Clients verwenden eine v3-Untergrenze, sodass additive v4-Clients weiterhin v3-Gateways erreichen können.
• Schemas + Modelle werden aus TypeBox-Definitionen generiert:
  • pnpm protocol:gen
  • pnpm protocol:gen:swift
  • pnpm protocol:check

​

Client-Konstanten

​

Authentifizierung

• Shared-Secret-Gateway-Authentifizierung verwendet connect.params.auth.token oder connect.params.auth.password, abhängig vom konfigurierten Authentifizierungsmodus.
• Identitätstragende Modi wie Tailscale Serve (gateway.auth.allowTailscale: true) oder nicht über Loopback laufendes gateway.auth.mode: "trusted-proxy" erfüllen die Connect-Authentifizierungsprüfung über Anfrage-Header statt über connect.params.auth.*.
• Private-Ingress gateway.auth.mode: "none" überspringt die Shared-Secret-Connect-Authentifizierung vollständig; stellen Sie diesen Modus nicht auf öffentlichem/nicht vertrauenswürdigem Ingress bereit.
• Nach dem Pairing stellt der Gateway ein Device Token aus, das auf die Verbindungsrolle und Scopes begrenzt ist. Es wird in hello-ok.auth.deviceToken zurückgegeben und sollte vom Client für zukünftige Verbindungen persistiert werden.
• Clients sollten das primäre hello-ok.auth.deviceToken nach jeder erfolgreichen Verbindung persistieren.
• Beim erneuten Verbinden mit diesem gespeicherten Device Token sollte auch die gespeicherte genehmigte Scope-Menge für dieses Token wiederverwendet werden. Dadurch bleibt Lese-/Probe-/Statuszugriff erhalten, der bereits gewährt wurde, und es wird vermieden, dass Reconnects stillschweigend auf einen engeren impliziten Nur-Admin-Scope reduziert werden.
• Clientseitige Connect-Auth-Zusammenstellung (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 gerätespezifisches Token (indiziert nach deviceId + role).
  • auth.bootstrapToken wird nur gesendet, wenn keines der oben Genannten ein auth.token ergeben hat. Ein Shared Token oder ein aufgelöstes Device Token unterdrückt es.
  • Die automatische Hochstufung eines gespeicherten Device 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.
• Zusätzliche Einträge in hello-ok.auth.deviceTokens sind Bootstrap-Handoff-Tokens. Persistieren Sie sie nur, wenn die Verbindung Bootstrap-Auth über einen vertrauenswürdigen Transport wie wss:// oder Loopback/lokales Pairing verwendet hat.
• Wenn ein Client ein explizites deviceToken oder explizite scopes angibt, bleibt diese vom Aufrufer angeforderte Scope-Menge maßgeblich; gecachte Scopes werden nur wiederverwendet, wenn der Client das gespeicherte gerätespezifische Token wiederverwendet.
• Device Tokens können über device.token.rotate und device.token.revoke rotiert/widerrufen werden (erfordert den Scope operator.pairing).
• device.token.rotate gibt Rotationsmetadaten zurück. Es gibt das ersetzende Bearer-Token nur bei Aufrufen desselben Geräts aus, die bereits mit diesem Device Token authentifiziert sind, damit tokenbasierte Clients ihren Ersatz persistieren können, bevor sie sich erneut verbinden. Shared-/Admin-Rotationen geben das Bearer-Token nicht aus.
• Token-Ausstellung, -Rotation und -Widerruf bleiben auf die genehmigte Rollenmenge begrenzt, die im Pairing-Eintrag dieses Geräts erfasst ist; Token-Mutation kann keine Geräterolle erweitern oder ansteuern, die durch die Pairing-Genehmigung nie gewährt wurde.
• Bei Token-Sitzungen gekoppelter Geräte ist die Geräteverwaltung selbstbegrenzt, sofern der Aufrufer nicht auch operator.admin besitzt: Nicht-Admin-Aufrufer können nur ihren eigenen Geräteeintrag entfernen/widerrufen/rotieren.
• device.token.rotate und device.token.revoke prüfen außerdem die Ziel-Operator-Token-Scope-Menge gegen die aktuellen Sitzungsscopes 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)
• Clientverhalten bei AUTH_TOKEN_MISMATCH:
  • Vertrauenswürdige Clients dürfen einen begrenzten Retry mit einem gecachten gerätespezifischen Token versuchen.
  • Wenn dieser Retry fehlschlägt, sollten Clients automatische Reconnect-Schleifen beenden und Handlungsanleitung für den Operator anzeigen.
• AUTH_SCOPE_MISMATCH bedeutet, dass das Device Token erkannt wurde, aber die angeforderte Rolle/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 Keypair-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.
• Automatische Pairing-Genehmigung ist auf direkte local loopback-Verbindungen ausgerichtet.
• OpenClaw hat außerdem einen engen Backend-/Container-lokalen Self-Connect-Pfad für vertrauenswürdige Shared-Secret-Hilfsabläufe.
• Same-Host-Tailnet- oder LAN-Verbindungen werden für Pairing weiterhin als remote behandelt und erfordern 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 nur auf localhost beschränkte unsichere HTTP-Kompatibilität.
  • erfolgreiche Operator-Control-UI-Auth mit gateway.auth.mode: "trusted-proxy".
  • gateway.controlUi.dangerouslyDisableDeviceAuth=true (Break-Glass, schwere Sicherheitsherabstufung).
  • direkte Loopback-gateway-client-Backend-RPCs, die mit dem gemeinsamen Gateway-Token/Passwort authentifiziert sind.
• Alle Verbindungen müssen die vom Server bereitgestellte connect.challenge-Nonce signieren.

​

Diagnose für Geräteauthentifizierungs-Migration

• 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 werden aus Kompatibilitätsgründen weiterhin akzeptiert, aber Metadaten-Pinning für gekoppelte Geräte steuert weiterhin die Befehlsrichtlinie beim Reconnect.

​

TLS + Pinning

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

​

Scope

​

Verwandte Themen

• Bridge-Protokoll
• Gateway-Runbook