Gateway-protocol

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

# Transport

• WebSocket, tekstframes met JSON-payloads.
• Het eerste frame moet een connect-request zijn.
• Pre-connect-frames zijn beperkt tot 64 KiB. Na een geslaagde handshake moeten clients de limieten hello-ok.policy.maxPayload en hello-ok.policy.maxBufferedBytes volgen. Met diagnostiek ingeschakeld genereren te grote inkomende frames en trage uitgaande buffers payload.large-events voordat de Gateway sluit of het betreffende frame laat vallen. Deze events bewaren groottes, limieten, oppervlakken en veilige redencodes. Ze bewaren niet de berichttekst, bijlage-inhoud, ruwe frame-inhoud, tokens, cookies of geheime waarden.

# Handshake (connect)

Gateway → Client (pre-connect-uitdaging):

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

Client → Gateway:

{
  "type": "req",
  "id": "…",
  "method": "connect",
  "params": {
    "minProtocol": 4,
    "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
    }
  }
}

Terwijl de Gateway nog bezig is met het afronden van opstart-sidecars, kan het connect-request een opnieuw te proberen UNAVAILABLE-fout retourneren met details.reason ingesteld op "startup-sidecars" en retryAfterMs. Clients moeten die response opnieuw proberen binnen hun totale verbindingsbudget in plaats van deze als een terminale handshakefout te tonen.

server, features, snapshot en policy zijn allemaal vereist door het schema (src/gateway/protocol/schema/frames.ts). auth is ook vereist en rapporteert de onderhandelde rol/scopes. pluginSurfaceUrls is optioneel en koppelt Plugin- oppervlaknamen, zoals canvas, aan scoped gehoste URL's.

Scoped Plugin-oppervlak-URL's kunnen verlopen. Nodes kunnen node.pluginSurface.refresh aanroepen met { "surface": "canvas" } om een nieuwe entry in pluginSurfaceUrls te ontvangen. De experimentele Canvas Plugin-refactor ondersteunt niet het verouderde compatibiliteitspad canvasHostUrl, canvasCapability of node.canvas.capability.refresh; huidige native clients en gateways moeten Plugin-oppervlakken gebruiken.

Wanneer er geen device-token wordt uitgegeven, rapporteert hello-ok.auth de onderhandelde machtigingen zonder tokenvelden:

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

Vertrouwde backend-clients binnen hetzelfde proces (client.id: "gateway-client", client.mode: "backend") mogen device weglaten bij directe local loopback-verbindingen wanneer ze authenticeren met het gedeelde Gateway-token/wachtwoord. Dit pad is gereserveerd voor interne RPC's van het besturingsvlak en voorkomt dat verouderde CLI/device-koppelingsbaselines lokaal backend-werk blokkeren, zoals subagent-sessie-updates. Externe clients, browser-origin-clients, node-clients en expliciete device-token/device-identiteit- clients gebruiken nog steeds de normale koppelings- en scope-upgradecontroles.

Wanneer een device-token wordt uitgegeven, bevat hello-ok ook:

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

Tijdens vertrouwde bootstrap-overdracht kan hello-ok.auth ook aanvullende begrensde rolentries in deviceTokens bevatten:

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

Voor de ingebouwde node/operator-bootstrapflow blijft het primaire node-token scopes: [] en blijft elk overgedragen operator-token begrensd tot de bootstrap- operator-allowlist (operator.approvals, operator.read, operator.talk.secrets, operator.write). Bootstrap-scopecontroles blijven rolgeprefixd: operatorentries voldoen alleen aan operator-requests, en niet-operator- rollen hebben nog steeds scopes nodig onder hun eigen rolprefix.

# Node-voorbeeld

{
  "type": "req",
  "id": "…",
  "method": "connect",
  "params": {
    "minProtocol": 4,
    "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

• Request: {type:"req", id, method, params}
• Response: {type:"res", id, ok, payload|error}
• Event: {type:"event", event, payload, seq?, stateVersion?}

Methoden met bijwerkingen vereisen idempotentiesleutels (zie schema).

# Rollen + scopes

Voor het volledige operator-scope-model, controles tijdens goedkeuring en semantiek van gedeelde geheimen, zie Operator-scopes.

# Rollen

• operator = client van het besturingsvlak (CLI/UI/automatisering).
• node = capability-host (camera/screen/canvas/system.run).

# Scopes (operator)

Veelvoorkomende scopes:

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

talk.config met includeSecrets: true vereist operator.talk.secrets (of operator.admin).

Door Plugins geregistreerde Gateway RPC-methoden kunnen hun eigen operator-scope aanvragen, maar gereserveerde core-adminprefixen (config.*, exec.approvals.*, wizard.*, update.*) worden altijd herleid tot operator.admin.

Methodscope is alleen de eerste poort. Sommige slash-commando's die via chat.send worden bereikt, passen daarbovenop strengere controles op commandoniveau toe. Bijvoorbeeld: persistente /config set- en /config unset-schrijfacties vereisen operator.admin.

node.pair.approve heeft ook een extra scopecontrole tijdens goedkeuring bovenop de basismethodscope:

• requests zonder commando: operator.pairing
• requests met non-exec-nodecommando's: operator.pairing + operator.write
• requests die system.run, system.run.prepare of system.which bevatten: operator.pairing + operator.admin

# Caps/commando's/machtigingen (node)

Nodes declareren capability-claims tijdens het verbinden:

• caps: capability-categorieën op hoog niveau, zoals camera, canvas, screen, location, voice en talk.
• commands: commando-allowlist voor invoke.
• permissions: granulaire schakelaars (bijv. screen.record, camera.capture).

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

# Aanwezigheid

• system-presence retourneert entries gesleuteld op device-identiteit.
• Aanwezigheidsentries bevatten deviceId, roles en scopes, zodat UI's één rij per device kunnen tonen zelfs wanneer het verbindt als zowel operator als node.
• node.list bevat optionele velden lastSeenAtMs en lastSeenReason. Verbonden nodes rapporteren hun huidige verbindingstijd als lastSeenAtMs met reden connect; gekoppelde nodes kunnen ook duurzame achtergrondaanwezigheid rapporteren wanneer een vertrouwd node-event hun koppelingsmetadata bijwerkt.

# Achtergrond-alive-event van node

Nodes kunnen node.event aanroepen met event: "node.presence.alive" om vast te leggen dat een gekoppelde node alive was tijdens een background wake zonder deze als verbonden te markeren.

{
  "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 is een gesloten enum: background, silent_push, bg_app_refresh, significant_location, manual of connect. Onbekende triggerstrings worden door de gateway genormaliseerd naar background vóór persistentie. Het event is alleen duurzaam voor geauthenticeerde node- devicesessies; device-loze of ongekoppelde sessies retourneren handled: false.

Geslaagde gateways retourneren een gestructureerd resultaat:

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

Oudere gateways kunnen nog steeds { "ok": true } retourneren voor node.event; clients moeten dat behandelen als een bevestigde RPC, niet als duurzame aanwezigheidspersistentie.

# Scoping van broadcast-events

Door de server gepushte WebSocket-broadcast-events zijn scope-gated, zodat sessies met pairing-scope of alleen node-sessies niet passief sessie-inhoud ontvangen.

• Chat-, agent- en tool-result-frames (inclusief gestreamde agent-events en tool call-resultaten) vereisen ten minste operator.read. Sessies zonder operator.read slaan deze frames volledig over.
• Door Plugins gedefinieerde plugin.*-broadcasts zijn gated op operator.write of operator.admin, afhankelijk van hoe de Plugin ze heeft geregistreerd.
• Status- en transportevents (heartbeat, presence, tick, connect/disconnect-levenscyclus, enz.) blijven onbeperkt, zodat transportgezondheid voor elke geauthenticeerde sessie observeerbaar blijft.
• Onbekende broadcast-eventfamilies zijn standaard scope-gated (fail-closed), tenzij een geregistreerde handler ze expliciet versoepelt.

Elke clientverbinding behoudt zijn eigen sequence number per client, zodat broadcasts monotone ordening op die socket behouden, zelfs wanneer verschillende clients verschillende scope-gefilterde subsets van de eventstream zien.

# Veelvoorkomende RPC-methodfamilies

Het publieke WS-oppervlak is breder dan de handshake-/auth-voorbeelden hierboven. Dit is geen gegenereerde dump — hello-ok.features.methods is een conservatieve discoverylijst opgebouwd uit src/gateway/server-methods-list.ts plus geladen Plugin-/channel-methodexports. Behandel het als featurediscovery, niet als een volledige opsomming van src/gateway/server-methods/*.ts.

# Veelvoorkomende eventfamilies

• chat: UI-chatupdates zoals chat.inject en andere chatgebeurtenissen die alleen voor transcripten zijn.
• session.message en session.tool: transcript-/eventstreamupdates voor een geabonneerde sessie.
• sessions.changed: sessie-index of metadata gewijzigd.
• presence: updates van systeemaanwezigheidssnapshots.
• tick: periodieke keepalive-/liveness-gebeurtenis.
• health: update van Gateway-gezondheidssnapshot.
• heartbeat: update van Heartbeat-eventstream.
• cron: Cron-run-/taakwijzigingsgebeurtenis.
• shutdown: melding voor afsluiten van de Gateway.
• node.pair.requested / node.pair.resolved: koppelingslevenscyclus van Node.
• node.invoke.request: broadcast van Node-aanroepverzoek.
• device.pair.requested / device.pair.resolved: levenscyclus van gekoppeld apparaat.
• voicewake.changed: configuratie voor wake-wordtrigger gewijzigd.
• exec.approval.requested / exec.approval.resolved: exec-goedkeuringslevenscyclus.
• plugin.approval.requested / plugin.approval.resolved: Plugin-goedkeuringslevenscyclus.

# Node-helpermethoden

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

# Operator-helpermethoden

• Operators kunnen commands.list (operator.read) aanroepen om de runtime- commando-inventaris voor een agent op te halen.
  • agentId is optioneel; laat dit weg om de standaardagentwerkruimte te lezen.
  • scope bepaalt op welk oppervlak de primaire name is gericht:
    • text retourneert het primaire tekstcommandotoken zonder de voorloop-/
    • native en het standaardpad both retourneren providerbewuste native namen wanneer beschikbaar
  • textAliases bevat exacte slash-aliassen zoals /model en /m.
  • nativeName bevat de providerbewuste native commandonaam wanneer die bestaat.
  • provider is optioneel en beïnvloedt alleen native naamgeving plus beschikbaarheid van native Plugin- commando's.
  • includeArgs=false laat geserialiseerde argumentmetadata weg uit het antwoord.
• Operators kunnen tools.catalog (operator.read) aanroepen om de runtime-toolcatalogus voor een agent op te halen. Het antwoord bevat gegroepeerde tools en herkomstmetadata:
  • source: core of plugin
  • pluginId: Plugin-eigenaar wanneer source="plugin"
  • optional: of een Plugin-tool optioneel is
• Operators kunnen tools.effective (operator.read) aanroepen om de runtime-effectieve tool- inventaris voor een sessie op te halen.
  • sessionKey is vereist.
  • De Gateway leidt vertrouwde runtimecontext server-side af uit de sessie in plaats van door de aanroeper geleverde auth- of afleveringscontext te accepteren.
  • Het antwoord is sessiegebonden en weerspiegelt wat het actieve gesprek nu kan gebruiken, inclusief core-, Plugin- en kanaaltools.
• Operators kunnen tools.invoke (operator.write) aanroepen om één beschikbare tool aan te roepen via hetzelfde Gateway-beleidspad als /tools/invoke.
  • name is vereist. args, sessionKey, agentId, confirm en idempotencyKey zijn optioneel.
  • Als zowel sessionKey als agentId aanwezig zijn, moet de opgeloste sessieagent overeenkomen met agentId.
  • Het antwoord is een SDK-gerichte envelop met ok, toolName, optioneel output en getypeerde error-velden. Goedkeurings- of beleidsweigeringen retourneren ok:false in de payload in plaats van de Gateway-toolbeleidspijplijn te omzeilen.
• Operators kunnen skills.status (operator.read) aanroepen om de zichtbare skill-inventaris voor een agent op te halen.
  • agentId is optioneel; laat dit weg om de standaardagentwerkruimte te lezen.
  • Het antwoord bevat geschiktheid, ontbrekende vereisten, configuratiecontroles en opgeschoonde installatieopties zonder ruwe geheime waarden bloot te leggen.
• Operators kunnen skills.search en skills.detail (operator.read) aanroepen voor ClawHub-ontdekkingsmetadata.
• Operators kunnen skills.install (operator.admin) in twee modi aanroepen:
  • ClawHub-modus: { source: "clawhub", slug, version?, force? } installeert een skill-map in de skills/-directory van de standaardagentwerkruimte.
  • Gateway-installatiemodus: { name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? } voert een gedeclareerde metadata.openclaw.install-actie uit op de Gateway-host.
• Operators kunnen skills.update (operator.admin) in twee modi aanroepen:
  • ClawHub-modus werkt één gevolgde slug of alle gevolgde ClawHub-installaties bij in de standaardagentwerkruimte.
  • Configuratiemodus patcht waarden van skills.entries.<skillKey> zoals enabled, apiKey en env.

# models.list-weergaven

models.list accepteert een optionele parameter view:

• Weggelaten of "default": huidig runtimegedrag. Als agents.defaults.models is geconfigureerd, is het antwoord de toegestane catalogus; anders is het antwoord de volledige Gateway-catalogus.
• "configured": gedrag op picker-formaat. Als agents.defaults.models is geconfigureerd, heeft dat nog steeds voorrang. Anders gebruikt het antwoord expliciete vermeldingen in models.providers.*.models, met terugval naar de volledige catalogus alleen wanneer er geen geconfigureerde modelrijen bestaan.
• "all": volledige Gateway-catalogus, waarbij agents.defaults.models wordt omzeild. Gebruik dit voor diagnostiek en ontdekkings-UI's, niet voor normale modelpickers.

# Exec-goedkeuringen

• Wanneer een exec-aanvraag goedkeuring vereist, broadcast de Gateway exec.approval.requested.
• Operatorclients lossen dit op door exec.approval.resolve aan te roepen (vereist scope operator.approvals).
• Voor host=node moet exec.approval.request systemRunPlan bevatten (canonieke argv/cwd/rawCommand/sessiemetadata). Aanvragen zonder systemRunPlan worden geweigerd.
• Na goedkeuring hergebruiken doorgestuurde node.invoke system.run-aanroepen dat canonieke systemRunPlan als de gezaghebbende command-/cwd-/sessiecontext.
• Als een aanroeper command, rawCommand, cwd, agentId of sessionKey wijzigt tussen voorbereiding en de definitieve goedgekeurde system.run-doorsturing, weigert de Gateway de run in plaats van de gewijzigde payload te vertrouwen.

# Fallback voor agentaflevering

• agent-aanvragen kunnen deliver=true bevatten om uitgaande aflevering aan te vragen.
• bestEffortDeliver=false behoudt strikt gedrag: niet-opgeloste of alleen-interne afleverdoelen retourneren INVALID_REQUEST.
• bestEffortDeliver=true staat fallback naar alleen-sessie-uitvoering toe wanneer geen externe afleverbare route kan worden opgelost (bijvoorbeeld interne/webchatsessies of dubbelzinnige multikanaalconfiguraties).

# Versionering

• PROTOCOL_VERSION staat in src/gateway/protocol/version.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

# Clientconstanten

De referentieclient in src/gateway/client.ts gebruikt deze standaardwaarden. Waarden zijn stabiel binnen protocol v4 en vormen de verwachte baseline voor clients van derden.

Constante	Standaard	Bron
PROTOCOL_VERSION	4	src/gateway/protocol/version.ts
Aanvraagtime-out (per RPC)	30_000 ms	src/gateway/client.ts (requestTimeoutMs)
Preauth-/connect-challenge-time-out	15_000 ms	src/gateway/handshake-timeouts.ts (config/env kan het gekoppelde server-/clientbudget verhogen)
Initiële reconnect-backoff	1_000 ms	src/gateway/client.ts (backoffMs)
Maximale reconnect-backoff	30_000 ms	src/gateway/client.ts (scheduleReconnect)
Fast-retry-klem na sluiten door device-token	250 ms	src/gateway/client.ts
Force-stop-respijt vóór terminate()	250 ms	FORCE_STOP_TERMINATE_GRACE_MS
Standaardtime-out van stopAndWait()	1_000 ms	STOP_AND_WAIT_TIMEOUT_MS
Standaard tick-interval (vóór hello-ok)	30_000 ms	src/gateway/client.ts
Sluiten bij tick-time-out	code 4000 wanneer stilte langer duurt dan tickIntervalMs * 2	src/gateway/client.ts
MAX_PAYLOAD_BYTES	25 * 1024 * 1024 (25 MB)	src/gateway/server-constants.ts

De server adverteert de effectieve policy.tickIntervalMs, policy.maxPayload en policy.maxBufferedBytes in hello-ok; clients moeten die waarden respecteren in plaats van de standaardwaarden van vóór de handshake.

# Auth

• Gateway-authenticatie met gedeeld geheim gebruikt connect.params.auth.token of connect.params.auth.password, afhankelijk van de geconfigureerde authenticatiemodus.
• Modi met identiteit, zoals Tailscale Serve (gateway.auth.allowTailscale: true) of niet-loopback gateway.auth.mode: "trusted-proxy" voldoen aan de connect-authenticatiecontrole via requestheaders in plaats van connect.params.auth.*.
• Private-ingress gateway.auth.mode: "none" slaat connect-authenticatie met gedeeld geheim volledig over; stel die modus niet bloot op publieke/niet-vertrouwde ingress.
• Na koppeling geeft de Gateway een apparaat-token uit dat is beperkt tot de verbindingsrol
  • bereiken. Het wordt geretourneerd in hello-ok.auth.deviceToken en moet door de client worden bewaard voor toekomstige verbindingen.
• Clients moeten de primaire hello-ok.auth.deviceToken bewaren na elke succesvolle verbinding.
• Opnieuw verbinden met dat opgeslagen apparaat-token moet ook de opgeslagen goedgekeurde bereikenset voor dat token hergebruiken. Dit behoudt lees-/probe-/statustoegang die al was verleend en voorkomt dat herverbindingen stilzwijgend terugvallen naar een smaller impliciet alleen-admin-bereik.
• Samenstelling van connect-authenticatie aan clientzijde (selectConnectAuth in src/gateway/client.ts):
  • auth.password staat los hiervan en wordt altijd doorgestuurd wanneer ingesteld.
  • auth.token wordt gevuld in prioriteitsvolgorde: eerst een expliciet gedeeld token, daarna een expliciete deviceToken, daarna een opgeslagen token per apparaat (gesleuteld op deviceId + role).
  • auth.bootstrapToken wordt alleen verzonden wanneer geen van bovenstaande een auth.token opleverde. Een gedeeld token of elk opgelost apparaat-token onderdrukt dit.
  • Automatische promotie van een opgeslagen apparaat-token bij de eenmalige AUTH_TOKEN_MISMATCH-herpoging is beperkt tot alleen vertrouwde endpoints — loopback, of wss:// met een vastgepinde tlsFingerprint. Publieke wss:// zonder pinning komt niet in aanmerking.
• Aanvullende hello-ok.auth.deviceTokens-vermeldingen zijn bootstrap-overdrachtstokens. Bewaar ze alleen wanneer de verbinding bootstrap-authenticatie gebruikte op een vertrouwd transport zoals wss:// of loopback/lokale koppeling.
• Als een client een expliciete deviceToken of expliciete scopes opgeeft, blijft die door de aanroeper gevraagde bereikenset gezaghebbend; gecachete bereiken worden alleen hergebruikt wanneer de client het opgeslagen token per apparaat hergebruikt.
• Apparaat-tokens kunnen worden geroteerd/ingetrokken via device.token.rotate en device.token.revoke (vereist bereik operator.pairing).
• device.token.rotate retourneert rotatiemetadata. Het echoot het vervangende bearer-token alleen voor oproepen vanaf hetzelfde apparaat die al met dat apparaat-token zijn geauthenticeerd, zodat clients met alleen tokens hun vervanging kunnen bewaren voordat ze opnieuw verbinden. Rotaties via gedeelde/admin-authenticatie echoën het bearer-token niet.
• Tokenuitgifte, -rotatie en -intrekking blijven beperkt tot de goedgekeurde rollenset die is vastgelegd in de koppelingsvermelding van dat apparaat; tokenmutatie kan geen apparaatrol uitbreiden of targeten waarvoor koppeling nooit goedkeuring heeft verleend.
• Voor token-sessies van gekoppelde apparaten is apparaatbeheer zelf-beperkt tenzij de aanroeper ook operator.admin heeft: niet-admin-aanroepers kunnen alleen hun eigen apparaatvermelding verwijderen/intrekken/roteren.
• device.token.rotate en device.token.revoke controleren ook de bereikenset van het doeloperator-token tegen de huidige sessiebereiken van de aanroeper. Niet-admin-aanroepers kunnen geen breder operator-token roteren of intrekken dan ze zelf al hebben.
• Authenticatiefouten bevatten error.details.code plus herstelhints:
  • error.details.canRetryWithDeviceToken (boolean)
  • error.details.recommendedNextStep (retry_with_device_token, update_auth_configuration, update_auth_credentials, wait_then_retry, review_auth_configuration)
• Clientgedrag voor AUTH_TOKEN_MISMATCH:
  • Vertrouwde clients mogen één begrensde herpoging proberen met een gecachet token per apparaat.
  • Als die herpoging mislukt, moeten clients automatische herverbindingslussen stoppen en begeleiding voor operatoractie tonen.

# Apparaatidentiteit + koppeling

• Nodes moeten een stabiele apparaatidentiteit (device.id) bevatten, afgeleid van een keypair-fingerprint.
• Gateways geven tokens uit per apparaat + rol.
• Koppelingsgoedkeuringen zijn vereist voor nieuwe apparaat-ID's tenzij lokale automatische goedkeuring is ingeschakeld.
• Automatische koppelingsgoedkeuring is gericht op directe local loopback-verbindingen.
• OpenClaw heeft ook een smal backend-/container-lokaal zelfverbindingspad voor vertrouwde helperflows met gedeeld geheim.
• Tailnet- of LAN-verbindingen op dezelfde host worden nog steeds behandeld als extern voor koppeling en vereisen goedkeuring.
• WS-clients bevatten normaal gesproken device-identiteit tijdens connect (operator + node). De enige operator-uitzonderingen zonder apparaat zijn expliciete vertrouwenspaden:
  • gateway.controlUi.allowInsecureAuth=true voor localhost-only compatibiliteit met onveilige HTTP.
  • succesvolle gateway.auth.mode: "trusted-proxy" operator-Control UI-authenticatie.
  • gateway.controlUi.dangerouslyDisableDeviceAuth=true (noodmaatregel, ernstige beveiligingsverlaging).
  • direct-loopback gateway-client backend-RPC's die zijn geauthenticeerd met het gedeelde gateway-token/wachtwoord.
• Alle verbindingen moeten de door de server geleverde connect.challenge-nonce ondertekenen.

# Migratiediagnostiek voor apparaatauthenticatie

Voor legacy clients die nog pre-challenge ondertekeningsgedrag gebruiken, retourneert connect nu DEVICE_AUTH_*-detailcodes onder error.details.code met een stabiele error.details.reason.

Veelvoorkomende migratiefouten:

Bericht	details.code	details.reason	Betekenis
device nonce required	DEVICE_AUTH_NONCE_REQUIRED	device-nonce-missing	Client liet device.nonce weg (of stuurde leeg).
device nonce mismatch	DEVICE_AUTH_NONCE_MISMATCH	device-nonce-mismatch	Client ondertekende met een verouderde/verkeerde nonce.
device signature invalid	DEVICE_AUTH_SIGNATURE_INVALID	device-signature	Signature-payload komt niet overeen met v2-payload.
device signature expired	DEVICE_AUTH_SIGNATURE_EXPIRED	device-signature-stale	Ondertekende timestamp valt buiten de toegestane skew.
device identity mismatch	DEVICE_AUTH_DEVICE_ID_MISMATCH	device-id-mismatch	device.id komt niet overeen met de publieke-sleutel-fingerprint.
device public key invalid	DEVICE_AUTH_PUBLIC_KEY_INVALID	device-public-key	Publieke-sleutelindeling/canonicalisatie is mislukt.

Migratiedoel:

• Wacht altijd op connect.challenge.
• Onderteken de v2-payload die de servernonce bevat.
• Stuur dezelfde nonce in connect.params.device.nonce.
• De voorkeurs-signature-payload is v3, die platform en deviceFamily bindt naast de velden voor apparaat/client/rol/bereiken/token/nonce.
• Legacy v2-handtekeningen blijven geaccepteerd voor compatibiliteit, maar metadata-pinning van gekoppelde apparaten blijft het opdrachtbeleid bij herverbinding bepalen.

# TLS + pinning

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

# Bereik

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.

# Gerelateerd

• Bridge-protocol
• Gateway-runbook