Gateway-protocol

​

Transport

• WebSocket, tekstframes met JSON-payloads.
• Het eerste frame moet een connect-verzoek 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 zenden te grote inkomende frames en trage uitgaande buffers payload.large-events uit voordat de Gateway het betrokken frame sluit of laat vallen. Deze events bewaren groottes, limieten, oppervlakken en veilige redencodes. Ze bewaren niet de berichttekst, inhoud van bijlagen, ruwe framebody, tokens, cookies of geheime waarden.

​

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

​

Nodevoorbeeld

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

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

​

Rollen + scopes

​

Rollen

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

​

Scopes (operator)

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

• verzoeken zonder commando: operator.pairing
• verzoeken met niet-exec-nodecommando’s: operator.pairing + operator.write
• verzoeken die system.run, system.run.prepare of system.which bevatten: operator.pairing + operator.admin

​

Caps/commands/permissions (node)

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

​

Aanwezigheid

• system-presence retourneert vermeldingen met device-identiteit als sleutel.
• Aanwezigheidsvermeldingen 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 voor nodes

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

​

Scoping van broadcastevents

• Chat-, agent- en tool-result-frames (inclusief gestreamde agent-events en resultaten van toolcalls) vereisen minimaal operator.read. Sessies zonder operator.read slaan deze frames volledig over.
• Door Plugins gedefinieerde plugin.*-broadcasts zijn beperkt tot 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 transportstatus zichtbaar blijft voor elke geauthenticeerde sessie.
• Onbekende broadcasteventfamilies zijn standaard scope-gated (fail-closed), tenzij een geregistreerde handler ze expliciet versoepelt.

​

Veelgebruikte RPC-methodefamilies

​

Veelvoorkomende gebeurtenisfamilies

• chat: UI-chatupdates zoals chat.inject en andere uitsluitend-transcriptiechat- gebeurtenissen. In protocol v4 dragen deltapayloads deltaText; message blijft de cumulatieve assistentsnapshot. Niet-prefixvervangingen zetten replace=true en gebruiken deltaText als vervangende tekst.
• session.message, session.operation en session.tool: transcriptie, lopende sessiebewerking en event-streamupdates voor een geabonneerde sessie.
• sessions.changed: sessie-index of metadata gewijzigd.
• presence: updates van systeempresentiesnapshots.
• tick: periodieke keepalive-/livenessgebeurtenis.
• health: update van gateway-gezondheidssnapshot.
• heartbeat: update van Heartbeat-gebeurtenisstroom.
• cron: wijzigingsgebeurtenis voor Cron-run/taak.
• shutdown: gateway-afsluitmelding.
• node.pair.requested / node.pair.resolved: levenscyclus van Node-koppeling.
• node.invoke.request: broadcast van Node-aanroepaanvraag.
• device.pair.requested / device.pair.resolved: levenscyclus van gekoppeld apparaat.
• voicewake.changed: wake-word-triggerconfiguratie gewijzigd.
• exec.approval.requested / exec.approval.resolved: levenscyclus van exec-goedkeuring.
• plugin.approval.requested / plugin.approval.resolved: levenscyclus van plugin-goedkeuring.

​

Node-helpermethoden

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

​

RPC’s voor taakregister

• tasks.list vereist operator.read.
  • Params: optioneel status ("queued", "running", "completed", "failed", "cancelled" of "timed_out") of een array van die statussen, optioneel agentId, optioneel sessionKey, optioneel limit van 1 tot 500, en optionele string cursor.
  • Resultaat: { "tasks": TaskSummary[], "nextCursor"?: string }.
• tasks.get vereist operator.read.
  • Params: { "taskId": string }.
  • Resultaat: { "task": TaskSummary }.
  • Ontbrekende taak-id’s retourneren de Gateway-foutvorm voor niet gevonden.
• tasks.cancel vereist operator.write.
  • Params: { "taskId": string, "reason"?: string }.
  • Resultaat: { "found": boolean, "cancelled": boolean, "reason"?: string, "task"?: TaskSummary }.
  • found rapporteert of het register een overeenkomende taak had. cancelled rapporteert of de runtime annulering heeft geaccepteerd of vastgelegd.

​

Operator-helpermethoden

• Operators kunnen commands.list (operator.read) aanroepen om de runtime opdrachteninventaris voor een agent op te halen.
  • agentId is optioneel; laat dit weg om de standaard agentwerkruimte te lezen.
  • scope bepaalt welk oppervlak de primaire name aanstuurt:
    • text retourneert het primaire tekstopdrachttoken zonder de voorafgaande /
    • 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 opdrachtnaam wanneer die bestaat.
  • provider is optioneel en beïnvloedt alleen native naamgeving plus beschikbaarheid van native Plugin-opdrachten.
  • includeArgs=false laat geserialiseerde argumentmetadata weg uit de respons.
• Operators kunnen tools.catalog (operator.read) aanroepen om de runtime-toolcatalogus voor een agent op te halen. De respons 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 toolinventaris voor een sessie op te halen.
  • sessionKey is verplicht.
  • De Gateway leidt vertrouwde runtimecontext server-side af uit de sessie in plaats van door de aanroeper aangeleverde auth- of aflevercontext te accepteren.
  • De respons is een sessiegebonden, server-afgeleide projectie van de actieve inventaris, inclusief core-, Plugin-, kanaal- en al ontdekte MCP-servertools.
  • tools.effective is alleen-lezen voor MCP: het kan een warme MCP-catalogus van een sessie projecteren via het uiteindelijke toolbeleid, maar het maakt geen MCP-runtimes aan, verbindt geen transporten en geeft geen tools/list uit. Als er geen overeenkomende warme catalogus bestaat, kan de respons een melding bevatten zoals mcp-not-yet-connected, mcp-not-yet-listed of mcp-stale-catalog.
  • Effectieve toolvermeldingen gebruiken source="core", source="plugin", source="channel" of source="mcp".
• Operators kunnen tools.invoke (operator.write) aanroepen om één beschikbare tool uit te voeren via hetzelfde Gateway-beleidspad als /tools/invoke.
  • name is verplicht. args, sessionKey, agentId, confirm en idempotencyKey zijn optioneel.
  • Als zowel sessionKey als agentId aanwezig zijn, moet de opgeloste sessieagent overeenkomen met agentId.
  • Core-wrappers die alleen voor eigenaren zijn, zoals cron, gateway en nodes, vereisen eigenaar-/adminidentiteit (operator.admin), ook al is de methode tools.invoke zelf operator.write.
  • De respons is een SDK-gerichte envelope 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 Skills-inventaris voor een agent op te halen.
  • agentId is optioneel; laat dit weg om de standaard agentwerkruimte te lezen.
  • De respons bevat geschiktheid, ontbrekende vereisten, configcontroles 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.upload.begin, skills.upload.chunk en skills.upload.commit (operator.admin) aanroepen om een privé-Skill-archief te stagen voordat het wordt geïnstalleerd. Dit is een afzonderlijk admin-uploadpad voor vertrouwde clients, niet de normale ClawHub-Skill-installatiestroom, en is standaard uitgeschakeld tenzij skills.install.allowUploadedArchives is ingeschakeld.
  • skills.upload.begin({ kind: "skill-archive", slug, sizeBytes, sha256?, force?, idempotencyKey? }) maakt een upload aan die aan die slug en force-waarde is gekoppeld.
  • skills.upload.chunk({ uploadId, offset, dataBase64 }) voegt bytes toe op de exacte gedecodeerde offset.
  • skills.upload.commit({ uploadId, sha256? }) verifieert de uiteindelijke grootte en SHA-256. Commit rondt alleen de upload af; het installeert de Skill niet.
  • Geüploade Skill-archieven zijn ziparchieven met een SKILL.md-root. De interne mapnaam van het archief selecteert nooit het installatiedoel.
• Operators kunnen skills.install (operator.admin) in drie modi aanroepen:
  • ClawHub-modus: { source: "clawhub", slug, version?, force? } installeert een Skill-map in de standaard skills/-directory van de agentwerkruimte.
  • Uploadmodus: { source: "upload", uploadId, slug, force?, sha256?, timeoutMs? } installeert een gecommitte upload in de directory skills/<slug> van de standaard agentwerkruimte. De slug en force-waarde moeten overeenkomen met de oorspronkelijke skills.upload.begin-aanvraag. Deze modus wordt geweigerd tenzij skills.install.allowUploadedArchives is ingeschakeld. De instelling heeft geen invloed op ClawHub-installaties.
  • Gateway-installatiemodus: { name, installId, timeoutMs? } voert een gedeclareerde metadata.openclaw.install-actie uit op de Gateway-host. Oudere clients kunnen nog steeds dangerouslyForceUnsafeInstall sturen; dit veld is verouderd, wordt alleen geaccepteerd voor protocolcompatibiliteit en wordt genegeerd. Gebruik security.installPolicy voor installatiebeslissingen die door de operator worden beheerd.
• Operators kunnen skills.update (operator.admin) in twee modi aanroepen:
  • ClawHub-modus werkt één gevolgde slug bij of alle gevolgde ClawHub-installaties in de standaard agentwerkruimte.
  • Configmodus patcht waarden van skills.entries.<skillKey>, zoals enabled, apiKey en env.

​

models.list-weergaven

• Weggelaten of "default": huidig runtimegedrag. Als agents.defaults.models is geconfigureerd, is de respons de toegestane catalogus, inclusief dynamisch ontdekte modellen voor provider/*-vermeldingen. Anders is de respons de volledige Gateway-catalogus.
• "configured": gedrag met picker-grootte. Als agents.defaults.models is geconfigureerd, heeft dat nog steeds voorrang, inclusief providergebonden ontdekking voor provider/*-vermeldingen. Zonder allowlist gebruikt de respons expliciete models.providers.*.models-vermeldingen, 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 nodig heeft, 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 gebruiken doorgestuurde node.invoke system.run-aanroepen dat canonieke systemRunPlan opnieuw als de gezaghebbende opdracht-/cwd-/sessiecontext.
• Als een aanroeper command, rawCommand, cwd, agentId of sessionKey wijzigt tussen voorbereiding en de uiteindelijke 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: onopgeloste of alleen-interne afleverdoelen retourneren INVALID_REQUEST.
• bestEffortDeliver=true staat fallback naar uitvoering alleen binnen de sessie toe wanneer geen extern afleverbare route kan worden opgelost (bijvoorbeeld interne/webchat-sessies of dubbelzinnige multi-channel-configuraties).
• Uiteindelijke agent-resultaten kunnen result.deliveryStatus bevatten wanneer aflevering is aangevraagd, met dezelfde statussen sent, suppressed, partial_failed en failed die zijn gedocumenteerd voor openclaw agent --json --deliver.

​

Versiebeheer

• PROTOCOL_VERSION staat in packages/gateway-protocol/src/version.ts.
• Clients sturen minProtocol + maxProtocol; de server weigert bereiken die het huidige protocol niet bevatten. Huidige clients en servers vereisen protocol v4.
• Schema’s + modellen worden gegenereerd uit TypeBox-definities:
  • pnpm protocol:gen
  • pnpm protocol:gen:swift
  • pnpm protocol:check

​

Clientconstanten

​

Auth

• Gedeelde-geheim Gateway-authenticatie 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 gedeelde-geheim connect-authenticatie volledig over; stel die modus niet bloot via publieke/niet-vertrouwde ingress.
• Na het koppelen geeft de Gateway een apparaat-token uit dat is beperkt tot de verbindingsrol
  • scopes. 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 geslaagde verbinding.
• Opnieuw verbinden met dat opgeslagen apparaat-token moet ook de opgeslagen goedgekeurde scopeset voor dat token hergebruiken. Dit behoudt lees-/probe-/status-toegang die al was verleend en voorkomt dat reconnects stilzwijgend worden teruggebracht tot een smallere impliciete admin-only scope.
• Client-side samenstelling van connect-authenticatie (selectConnectAuth in src/gateway/client.ts):
  • auth.password is orthogonaal en wordt altijd doorgestuurd wanneer ingesteld.
  • auth.token wordt gevuld in prioriteitsvolgorde: eerst een expliciet gedeeld token, daarna een expliciete deviceToken, daarna een opgeslagen per-apparaat-token (gesleuteld op deviceId + role).
  • auth.bootstrapToken wordt alleen verzonden wanneer geen van bovenstaande een auth.token heeft opgeleverd. Een gedeeld token of een opgelost apparaat-token onderdrukt dit.
  • Automatische promotie van een opgeslagen apparaat-token bij de eenmalige AUTH_TOKEN_MISMATCH-retry is beperkt tot vertrouwde endpoints: loopback, of wss:// met een vastgezette tlsFingerprint. Publieke wss:// zonder pinning komt niet in aanmerking.
• Ingebouwde bootstrap met installatiecode retourneert het primaire node hello-ok.auth.deviceToken plus een begrensd operator-token in hello-ok.auth.deviceTokens voor vertrouwde mobiele overdracht. Het operator-token bevat operator.talk.secrets voor native leesacties van Talk-configuratie, maar sluit scopes voor koppelingsmutaties en operator.admin uit.
• Terwijl een niet-baseline bootstrap met installatiecode wacht op goedkeuring, bevatten PAIRING_REQUIRED-details recommendedNextStep: "wait_then_retry", retryable: true, en pauseReconnect: false. Clients moeten met hetzelfde bootstrap-token blijven reconnecten totdat het verzoek is goedgekeurd of het token ongeldig wordt.
• Bewaar hello-ok.auth.deviceTokens alleen wanneer de verbinding bootstrap-authenticatie gebruikte via 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 scopeset gezaghebbend; gecachte scopes worden alleen hergebruikt wanneer de client het opgeslagen per-apparaat-token hergebruikt.
• Apparaat-tokens kunnen worden geroteerd/ingetrokken via device.token.rotate en device.token.revoke (vereist de scope operator.pairing). Het roteren of intrekken van een node- of andere niet-operatorrol vereist ook operator.admin.
• device.token.rotate retourneert rotatiemetadata. Het echoot het vervangende bearer-token alleen voor same-device calls die al met dat apparaat-token zijn geauthenticeerd, zodat token-only clients hun vervanging kunnen bewaren voordat ze opnieuw verbinden. Gedeelde/admin-rotaties echoën het bearer-token niet.
• Tokenuitgifte, rotatie en intrekking blijven begrensd tot de goedgekeurde rollenset die in de koppelingsvermelding van dat apparaat is vastgelegd; tokenmutatie kan geen apparaatrol uitbreiden of targeten die nooit door koppelingsgoedkeuring is verleend.
• Voor token-sessies van gekoppelde apparaten is apparaatbeheer self-scoped tenzij de aanroeper ook operator.admin heeft: niet-admin aanroepers kunnen alleen het operator-token voor hun eigen apparaatvermelding beheren. Node- en ander niet-operator-tokenbeheer is admin-only, zelfs voor het eigen apparaat van de aanroeper.
• device.token.rotate en device.token.revoke controleren ook de doel-operator token-scopeset tegen de huidige sessiescopes 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 retry proberen met een gecacht per-apparaat-token.
  • Als die retry mislukt, moeten clients automatische reconnect-lussen stoppen en guidance voor operatoractie tonen.
• AUTH_SCOPE_MISMATCH betekent dat het apparaat-token is herkend maar niet dekt wat voor de gevraagde rol/scopes nodig is. Clients moeten dit niet presenteren als een verkeerd token; vraag de operator om opnieuw te koppelen of het smallere/bredere scopecontract goed te keuren.

​

Apparaatidentiteit + koppeling

• Nodes moeten een stabiele apparaatidentiteit (device.id) opnemen die is afgeleid van een keypair-vingerafdruk.
• 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-local self-connect-pad voor vertrouwde helperflows met gedeeld geheim.
• Same-host tailnet- of LAN-verbindingen worden nog steeds als remote behandeld voor koppeling en vereisen goedkeuring.
• WS-clients nemen normaal gesproken device-identiteit op tijdens connect (operator + node). De enige operatoruitzonderingen zonder apparaat zijn expliciete vertrouwenspaden:
  • gateway.controlUi.allowInsecureAuth=true voor localhost-only onveilige HTTP-compatibiliteit.
  • geslaagde gateway.auth.mode: "trusted-proxy" operator Control UI-authenticatie.
  • gateway.controlUi.dangerouslyDisableDeviceAuth=true (break-glass, ernstige beveiligingsverlaging).
  • direct-loopback gateway-client backend-RPC’s op het gereserveerde interne helperpad.
• Het weglaten van apparaatidentiteit heeft scopegevolgen. Wanneer een apparaatloze operatorverbinding via een expliciet vertrouwenspad wordt toegestaan, wist OpenClaw nog steeds zelfverklaarde scopes naar een lege set, tenzij dat pad een benoemde uitzondering voor scopebehoud heeft. Scope-gated methoden falen dan met missing scope.
• gateway.controlUi.dangerouslyDisableDeviceAuth=true is een Control UI break-glass-pad voor scopebehoud. Het kent geen scopes toe aan willekeurige aangepaste backend- of CLI-vormige WebSocket-clients.
• Het gereserveerde direct-loopback gateway-client backend-helperpad behoudt scopes alleen voor interne lokale control-plane RPC’s; aangepaste backend-ID’s krijgen deze uitzondering niet.
• Alle verbindingen moeten de door de server verstrekte connect.challenge-nonce ondertekenen.

​

Diagnostiek voor apparaat-authenticatiemigratie

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

​

TLS + pinning

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

​

Scope

​

Gerelateerd

• Bridge-protocol
• Gateway-runbook