Gateway-protocol

Het Gateway-WS-protocol is het centrale besturingsvlak en Node-transport voor OpenClaw. Operator- en Node-clients (CLI, web-UI, macOS-app, iOS-/Android-nodes, headless nodes) maken verbinding via WebSocket en declareren tijdens de handshake een rol en scope.

npm-pakketten

Deze pakketten worden meegeleverd met OpenClaw-releasereeksen. Tijdens de eerste uitrol kan npm E404 retourneren totdat de eerste release met pakketten is gepubliceerd.

• @openclaw/gateway-protocol publiceert de schema's, validators, TypeScript-typen, lichtgewicht helpers voor frames en fouten, en versieconstanten. De tarball bevat het gegenereerde protocol.schema.json machineleesbare contract.
• @openclaw/gateway-client publiceert de referentieclient voor Node en een browserveilige ingang op @openclaw/gateway-client/browser.

Zie voor richtlijnen over de levenscyclus van toepassingen Een Gateway-client bouwen. Zie voor apps die de Gateway als onderliggend proces beheren OpenClaw insluiten.

Transport en framing

• WebSocket, tekstframes, JSON-payloads.
• Het eerste frame moet een connect-verzoek zijn.
• Frames vóór de verbinding zijn beperkt tot 64 KiB (MAX_PREAUTH_PAYLOAD_BYTES). Volg na de handshake hello-ok.policy.maxPayload en hello-ok.policy.maxBufferedBytes. Als diagnostiek is ingeschakeld, genereren te grote binnenkomende frames en trage uitgaande buffers payload.large-gebeurtenissen voordat de Gateway het frame sluit of laat vallen. Deze gebeurtenissen bevatten surface, bytegroottes, limieten en een veilige redencode, maar nooit berichtteksten, inhoud van bijlagen, onbewerkte framebytes, tokens, cookies of geheimen.

Framevormen:

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

Antwoordfouten gebruiken { code, message, details?, retryable?, retryAfterMs? }. Clients moeten vertakken op code en details.code; message blijft voor mensen leesbaar en kan veranderen, behalve waar een compatibiliteitsopmerking anders aangeeft. Autorisatiefouten op methodeniveau gebruiken code: "FORBIDDEN" op het hoogste niveau met gestructureerde details over ontbrekende scopes:

• Ontbrekende scope: { code: "MISSING_SCOPE", missingScope, requiredScopes }. requiredScopes is de volledige bekende scopeset voor de aangevraagde bewerking. Het verouderde missing scope: <scope>-bericht blijft behouden voor oudere clients.

Clients moeten eerst details lezen en het verouderde bericht alleen als compatibiliteits- fallback gebruiken. readMissingScopeError en readMissingScopeErrorDetails worden geëxporteerd vanuit @openclaw/gateway-protocol/gateway-error-details; de browserveilige Gateway-client exporteert ze opnieuw vanuit @openclaw/gateway-client/browser.

De schema's worden geëxporteerd als GatewayErrorDetailsSchema, MissingScopeErrorDetailsSchema vanuit @openclaw/gateway-protocol/schema. HTTP-scopefouten weerspiegelen het MISSING_SCOPE-object onder error.details en gebruiken HTTP-status 403.

Methoden met neveneffecten vereisen idempotentiesleutels (zie schema).

Handshake

De Gateway stuurt vóór de verbinding een challenge:

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

De client antwoordt met connect:

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

De Gateway antwoordt met hello-ok:

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

server, features, snapshot, policy en auth zijn allemaal vereist door HelloOkSchema (packages/gateway-protocol/src/schema/frames.ts). auth rapporteert de overeengekomen rol/scopes, zelfs wanneer geen apparaattoken wordt uitgegeven (vorm hierboven). pluginSurfaceUrls is optioneel en koppelt namen van Plugin-oppervlakken (bijv. canvas) aan gehoste URL's met scopes; deze kunnen verlopen, dus nodes roepen node.pluginSurface.refresh aan met { "surface": "canvas" } voor een nieuwe ingang. Het verouderde pad canvasHostUrl / canvasCapability / node.canvas.capability.refresh wordt niet ondersteund; gebruik Plugin-oppervlakken. De optionele appliedConfigHash van de snapshot is de opgeloste bronconfiguratierevisie die door de actieve Gateway-runtime is geaccepteerd. Clients kunnen deze vergelijken met config.get.configRevisionHash om te bepalen of voor een nieuwere opgeslagen configuratie nog steeds een herstart nodig is. config.get.hash blijft de onbewerkte revisie van het hoofdbestand die wordt gebruikt door conflictbeveiligingen bij het schrijven van configuraties.

Terwijl de Gateway de opstart-sidecars nog voltooit, kan connect een opnieuw te proberen UNAVAILABLE-fout retourneren met details.reason: "startup-sidecars" en retryAfterMs. Probeer het binnen het verbindingsbudget opnieuw in plaats van dit als een definitieve handshakefout te behandelen.

Wanneer een apparaattoken wordt uitgegeven, voegt hello-ok.auth dit toe:

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

De ingebouwde bootstrap via QR-/installatiecode is een overdrachtspad voor mobiele apparaten. Een geslaagde basisverbinding met een installatiecode retourneert een primair Node-token plus één begrensd operatortoken:

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

Deze operatoroverdracht is bewust begrensd: voldoende om de mobiele operatorlus en systeemeigen installatie te starten, inclusief operator.talk.secrets voor het lezen van de Talk- configuratie, maar zonder scopes voor koppelingsmutaties en zonder operator.admin. Ruimere toegang voor koppeling/beheer vereist een afzonderlijk goedgekeurd koppelings- of tokenproces. Sla hello-ok.auth.deviceTokens alleen permanent op wanneer de bootstrapauthenticatie via een vertrouwd transport is uitgevoerd (wss:// of loopback/lokale koppeling).

Vertrouwde backendclients binnen hetzelfde proces (client.id: "gateway-client", client.mode: "backend") mogen device weglaten bij directe loopbackverbindingen wanneer ze authenticeren met het gedeelde Gateway-token/wachtwoord. Dit pad is voorbehouden aan interne RPC's van het besturingsvlak (bijv. sessie-updates van subagents) en voorkomt dat verouderde basisinstellingen voor CLI-/apparaatkoppeling lokaal backendwerk blokkeren. Externe clients, clients met browseroorsprong, nodes en expliciete clients met apparaattokens/apparaatidentiteit doorlopen nog steeds de normale controles voor koppeling en scope-upgrades.

Workerrol en gesloten protocol

Cloudworkers gebruiken een speciale loopback-ingang via de door de Gateway beheerde, met een hostsleutel vastgezette SSH-tunnel. Deze accepteert alleen een workeridentiteit en stuurt nooit algemene authenticatie, Node-gebeurtenissen, operator-RPC's of Plugin-methoden door. Een strikte connect verifieert een gehashte, permanent opgeslagen, kortstondige credential die is gebonden aan de omgeving, de bundle- hash, de ownerepoch, de RPC-setversie, de vervaldatum en één nullable sessie; afzonderlijk worden de huidige versie en functieset gecontroleerd. Bij succes wordt een minimale worker-hello-ok geretourneerd; functieonderhandeling staat los van de algemene protocolversie. Frames blijven kleiner dan 64 KiB, behalve dat een overeengekomen worker.inference.start- frame maximaal 25 MiB mag zijn. De gesloten allowlist bevat worker.heartbeat, worker.transcript.commit, worker.live-event, worker.inference.start en worker.inference.cancel.

Transcriptcommits gebruiken fencing op basis van de ownerepoch, een door de Gateway beheerde sessiekoppeling, compare-and-swap van het basisblad en duurzame herhaling van sequenties; de Gateway genereert transcriptitem- en bovenliggende ID's via de normale sessieschrijver. Eigendom en verval worden bij elke RPC opnieuw gecontroleerd.

Clientmogelijkheden

Operatorclients kunnen optionele mogelijkheden adverteren in connect.params.caps:

• tool-events: accepteert gestructureerde gebeurtenissen uit de levenscyclus van tools.
• inline-widgets: kan gehoste inline widgetresultaten van tools weergeven.

Clientmogelijkheden beschrijven de verbonden client, niet de autorisatie. Agenttools kunnen vereiste mogelijkheden declareren; de Gateway laat die tools weg tenzij elke vereiste voorkomt in caps van de oorspronkelijke client. Runs die vanuit een kanaal afkomstig zijn, hebben geen Gateway-clientmogelijkheden, waardoor tools waarvoor mogelijkheden vereist zijn niet beschikbaar zijn, zelfs wanneer het toolbeleid ze expliciet toestaat.

Voorbeeld van een Node-verbinding

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

Nodes declareren claims voor mogelijkheden wanneer ze verbinding maken:

• caps: categorieën op hoog niveau, zoals camera, canvas, screen, location, voice, talk.
• commands: allowlist met opdrachten voor aanroepen.
• permissions: fijnmazige schakelaars (bijv. screen.record, camera.capture).

De Gateway behandelt deze als claims en dwingt allowlists aan de serverzijde af.

Rollen en scopes

Zie Operatorscopes voor het volledige model voor operatorscopes, controles tijdens goedkeuring en de semantiek van gedeelde geheimen.

Rollen:

• operator: client van het besturingsvlak (CLI/UI/automatisering).
• node: host voor mogelijkheden (camera/scherm/canvas/system.run).
• worker: cloudhost voor uitvoering via het speciale, gesloten workerprotocol.

Operatorscopes (src/gateway/operator-scopes.ts), de volledige gesloten set:

• 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). Wanneer geheimen zijn opgenomen, lees je de credential van de actieve Talk-provider uit talk.resolved.config.apiKey; talk.providers.<id>.apiKey behoudt de bronvorm en kan een SecretRef-object of een geredigeerde tekenreeks zijn.

Door Plugins geregistreerde Gateway-RPC-methoden kunnen hun eigen operatorscope vereisen, maar deze gereserveerde kernprefixen worden altijd omgezet naar operator.admin (src/shared/gateway-method-policy.ts): config.*, exec.approvals.*, wizard.*, update.*.

De methodescope is slechts de eerste controle. Sommige slash-opdrachten die via chat.send worden bereikt, passen strengere controles op opdrachtniveau toe: permanente schrijfbewerkingen naar /config set en /config unset vereisen operator.admin, zelfs voor Gateway-clients die al een lagere operatorscope hebben.

node.pair.approve heeft naast de basismethodescope (operator.pairing) een extra scopecontrole tijdens de goedkeuring, gebaseerd op de gedeclareerde commands (src/infra/node-pairing-authz.ts) van het openstaande verzoek:

Capaciteiten/opdrachten/machtigingen (node)

Nodes declareren claims over capaciteiten wanneer ze verbinding maken:

• caps: categorieën van capaciteiten op hoog niveau, zoals camera, canvas, screen, location, voice en talk.
• commands: lijst met toegestane opdrachten voor aanroepen.
• permissions: gedetailleerde schakelaars (bijv. screen.record, camera.capture).

De Gateway behandelt deze als claims en dwingt aan de serverzijde lijsten met toegestane waarden af. Verbonden nodes kunnen na een geslaagde verbinding of herverbinding optionele, voor agents zichtbare Plugin- of MCP-tooldescriptors publiceren met node.pluginTools.update. Headless nodehosts worden opnieuw gestart om wijzigingen in de declaratieve MCP-inventaris toe te passen. Deze updatemethode is het enige publicatiepad; descriptors van Plugin-tools worden niet geaccepteerd in de parameters van connect. Elke descriptor moet een providerveilige tool-name gebruiken en een command opgeven uit de huidige lijst met toegestane opdrachten van de node. De Gateway vertrouwt de metagegevens van descriptors van de gekoppelde node, filtert descriptors buiten het goedgekeurde opdrachtoppervlak, verwijdert ze wanneer de verbinding met de node wordt verbroken en weigert pogingen van operators om de catalogus van een andere node te wijzigen. Stel gateway.nodes.pluginTools.enabled: false in om door nodes gepubliceerde descriptors te negeren.

Verbonden nodehosts publiceren hun volledige vervangingscatalogus voor Skills met node.skills.update. Deze methode voor de noderol is het enige publicatiepad voor Skills van nodes; Skills worden niet geaccepteerd in de parameters van connect. Elke descriptor bevat een veilige naam, beschrijving en begrensde SKILL.md-inhoud. De Gateway parseert die inhoud met de normale Skills-loader, neemt deze op in snapshots van Skills voor agents zolang de node verbonden is en verwijdert deze wanneer de verbinding wordt verbroken. Stel gateway.nodes.allowSkills: false in om door nodes gepubliceerde Skills te negeren.

Aanwezigheid

• system-presence retourneert vermeldingen met de apparaatidentiteit als sleutel, waaronder deviceId, roles en scopes, zodat UI's één rij per apparaat kunnen tonen, zelfs wanneer het zowel als operator als node verbinding maakt.
• node.list bevat optioneel lastSeenAtMs en lastSeenReason. Verbonden nodes rapporteren de huidige verbindingstijd met reden connect; gekoppelde nodes kunnen ook duurzame achtergrondaanwezigheid rapporteren via een vertrouwde nodegebeurtenis.

Native macOS-nodes kunnen ook geverifieerde node.presence.activity-gebeurtenissen verzenden met een begrensde inactieve invoertijd. De Gateway leidt activiteitstijdstempels af met zijn eigen klok, maakt de meest recent actieve verbonden Mac beschikbaar via node.list en node.describe en zendt node.presence-updates uit naar clients met leesscope. De app verzendt { "action": "clear" } wanneer de gebruiker het delen van activiteit uitschakelt; de Gateway wist tijdstempels alleen voor precies die geverifieerde nodeverbinding. Gateways van vóór deze bevestigde actie retourneren deze als niet-afgehandeld, waarna de Mac- node eenmaal opnieuw verbinding maakt en de opschoning bij het verbreken van de verbinding de oude verbindingsstatus laat verwijderen. Zie Aanwezigheid van actieve computer voor selectie, privacy, modelcontext en gedrag voor het routeren van meldingen.

Gebeurtenis dat een node op de achtergrond actief was

Nodes roepen node.event aan met event: "node.presence.alive" om vast te leggen dat een gekoppelde node tijdens een achtergrondactivatie actief was, 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 enumeratie: background, silent_push, bg_app_refresh, significant_location, manual, connect. Onbekende waarden worden genormaliseerd naar background (src/shared/node-presence.ts). De gebeurtenis wordt alleen opgeslagen voor geverifieerde apparaatsessies van nodes; sessies zonder apparaat of niet-gekoppelde sessies retourneren handled: false.

Geslaagde Gateways retourneren een gestructureerd resultaat:

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

Oudere Gateways retourneren mogelijk alleen { "ok": true } voor node.event; behandel dit als een bevestigde RPC, niet als duurzame opslag van aanwezigheid.

Scoping van broadcastgebeurtenissen

Door de server gepushte broadcastgebeurtenissen worden op basis van scope afgeschermd, zodat sessies met alleen een koppelingsscope of alleen een noderol niet passief sessie-inhoud ontvangen (src/gateway/server-broadcast.ts):

• Frames voor chats, agents en toolresultaten (gestreamde agent-gebeurtenissen, toolresultaatgebeurtenissen) vereisen ten minste operator.read. Sessies zonder deze scope slaan deze frames volledig over.
• Door Plugins gedefinieerde plugin.*-broadcasts worden standaard beperkt tot operator.write of operator.admin; expliciete vermeldingen zoals plugin.approval.requested / plugin.approval.resolved gebruiken in plaats daarvan operator.approvals.
• Status-/transportgebeurtenissen (heartbeat, presence, tick, de levenscyclus van verbinden/verbreken) blijven onbeperkt, zodat de transportstatus voor elke geverifieerde sessie waarneembaar is.
• Onbekende families van broadcastgebeurtenissen worden standaard op basis van scope afgeschermd (fail-closed), tenzij een geregistreerde handler deze beperking expliciet versoepelt.

Elke clientverbinding behoudt een eigen volgnummer per client, zodat broadcasts op die socket monotoon geordend blijven, zelfs wanneer verschillende clients verschillende, op scope gefilterde subsets van de gebeurtenisstroom zien.

Families van RPC-methoden

hello-ok.features.methods is een conservatieve ontdekkingslijst die is opgebouwd uit src/gateway/server-methods-list.ts plus geëxporteerde methoden van geladen Plugins/kanalen — het is geen gegenereerde dump van elke methode, en sommige methoden (bijvoorbeeld push.test, web.login.start, web.login.wait, sessions.usage) zijn bewust uitgesloten van ontdekking, hoewel het echte, aanroepbare methoden zijn. Behandel dit als functieontdekking, niet als een volledige opsomming van src/gateway/server-methods/*.ts.

Algemene gebeurteniscategorieën

• chat: UI-chatupdates zoals chat.inject en andere chatgebeurtenissen die alleen in het transcript voorkomen. In protocol v4 bevatten delta-payloads deltaText; message blijft de cumulatieve momentopname van de assistent. Vervangingen die geen prefix zijn, stellen replace=true in en gebruiken deltaText als vervangende tekst.
• session.message, session.operation, session.tool: updates voor het transcript, een lopende sessiebewerking en de gebeurtenisstroom van een gevolgde sessie.
• session.approval: opgeschoonde waarheid over openstaande en definitieve goedkeuringen voor een expliciet aangemelde abonnee van exact die sessie. Onderliggende goedkeuringen gebruiken het opgeslagen publiek van de bovenliggende goedkeuring; gebeurtenissen wijzigen nooit transcripten en activeren geen agents.
• sessions.changed: sessie-index of metagegevens gewijzigd.
• presence: updates van de momentopname van systeemaanwezigheid.
• tick: periodieke keepalive-/levendigheidsgebeurtenis.
• health: update van de momentopname van de Gateway-status.
• heartbeat: update van de Heartbeat-gebeurtenisstroom.
• cron: gebeurtenis bij een wijziging van een Cron-uitvoering of -taak.
• shutdown: melding dat de Gateway wordt afgesloten.
• node.pair.requested / node.pair.resolved: levenscyclus van nodekoppeling.
• node.invoke.request: uitzending van een node-aanroepaanvraag.
• device.pair.requested / device.pair.resolved: levenscyclus van gekoppelde apparaten.
• voicewake.changed: configuratie voor activering via een trefwoord gewijzigd.
• config.changed: een configuratieschrijfactie is opgeslagen (de payload bevat het configuratiepad, de hash van de nieuwe momentopname en een tijdstempel — nooit configuratie-inhoud). Beperkt tot operators met leesbereik; clients vernieuwen via config.get.
• exec.approval.requested / exec.approval.resolved: levenscyclus van uitvoeringsgoedkeuringen.
• plugin.approval.requested / plugin.approval.resolved: levenscyclus van plugingoedkeuringen.

Hulpmethoden voor nodes

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

RPC voor het auditlogboek

audit.activity.list biedt operatorclients een stabiele weergave, met de nieuwste eerst, van metagegevens over de levenscyclus van agentuitvoeringen, hulpmiddelacties en vrijwillig opgenomen berichten. Hiervoor is operator.read vereist. Query's sluiten records ouder dan 30 dagen uit en het gedeelde SQLite-logboek is beperkt tot 100.000 records. Verlopen rijen worden verwijderd tijdens het opstarten van de Gateway, bij elk uuronderhoud en bij latere schrijfacties. Zie Auditgeschiedenis voor het gegevensmodel en de privacysemantiek.

• Parameters: optioneel exact agentId, sessionKey of runId; optioneel kind ("agent_run", "tool_action" of "message"); optioneel status ("started", "succeeded", "failed", "cancelled", "timed_out", "blocked" of "unknown"); optioneel bericht-direction ("inbound" of "outbound") en exact channel; optionele inclusieve Unix-millisecondegrenzen after / before; optioneel limit van 1 tot 500; en optionele tekenreeks cursor van de voorgaande pagina.
• Resultaat: { "events": AuditActivityEventV1[], "nextCursor"?: string }.

De benoemde V1-resultaatunie heeft afzonderlijke schema's voor agentuitvoeringen, hulpmiddelacties, inkomende berichten en uitgaande berichten. De discriminator eventType is respectievelijk agent_run, tool_action, inbound_message of outbound_message; kind en bericht-direction blijven beschikbaar voor filtering en weergave. Elke gebeurtenis heeft een gehele schemaVersion: 1. Verwijzingen naar berichtidentiteiten gebruiken de exacte hmac-sha256:v1:<32 hex key id>:<64 hex digest>-indeling; een actor-id van een kanaalafzender gebruikt dezelfde indeling.

Alle varianten vereisen eventType, schemaVersion, eventId, sequence, sourceSequence, occurredAt, kind, action, status, actor en redaction. De variantvelden zijn:

De gesloten berichten-enums zijn:

• conversationKind: direct, group, channel of unknown.
• Inkomend outcome: completed, skipped of failed; optioneel reasonCode: duplicate, reply_operation_active, reply_operation_aborted, fast_abort, plugin_bound_handled, plugin_bound_unavailable, plugin_bound_declined, plugin_bound_error, before_dispatch_handled, acp_dispatch_completed, acp_dispatch_failed, acp_dispatch_empty of acp_dispatch_aborted.
• Uitgaand outcome: sent, suppressed, failed of unknown; optioneel reasonCode: cancelled_by_message_sending_hook, cancelled_by_reply_payload_sending_hook, empty_after_message_sending_hook, empty_after_reply_payload_sending_hook of no_visible_payload. Een adapter die geen platformidentiteit retourneert, is unknown, omdat de externe bijwerking niet kan worden weerlegd.
• deliveryKind: text, media of other; failureStage: platform_send, queue of unknown.

Definitieve velden zijn gecorreleerd en niet onafhankelijk optioneel:

Elke activiteitsgebeurtenis bevat een stabiele gebeurtenis-id, monotoon oplopend logboekvolgnummer, brongebeurtenisvolgnummer, tijdstempel, actor, actie, status, gehele schemaVersion: 1 en redaction: "metadata_only". Uitvoerings- en hulpmiddelrecords vereisen de herkomst van de agent en uitvoering en kunnen sessieherkomst bevatten. Berichtrecords kunnen agent- en uitvoerings-id's bevatten, maar bevatten bewust nooit sessionKey of sessionId; het queryfilter sessionKey is daarom alleen van toepassing op uitvoerings- en hulpmiddelrijen. Hulpmiddelgebeurtenissen kunnen de id van de hulpmiddelaanroep en de hulpmiddelnaam bevatten.

Berichtrecords gebruiken message.inbound.processed of message.outbound.finished en voegen richting, kanaal, gesprekstype, genormaliseerd resultaat en optioneel afleveringstype, foutfase, duur, aantal resultaten, redencode en met een installatiegebonden sleutel aangemaakte pseudoniemen voor account/gesprek/bericht/doel toe. Deze pseudoniemen helpen bij correlatie, maar zijn geen anonimisering: de statusdatabase bevat hun sleutel, terwijl RPC- en CLI-exports die niet bevatten. Het logboek slaat geen prompts, berichtinhoud, toolargumenten, toolresultaten, opdrachtuitvoer of onbewerkte fouttekst op. Run/tool-waarden van sessionKey blijven onbewerkte correlatiemetadata en kunnen platformaccount- of peer-id's bevatten; berichtrecords bevatten geen sessiesleutels.

Voor inkomende rijen meet durationMs de kerndispatch tot en met de eindstatus en telt resultCount de definitief verwerkte tool-, blok- en antwoordpayloads in de wachtrij. Voor uitgaande rijen omvat durationMs het eigenaarschap van de aflevering tot en met bevestiging, dead letter of reconciliatie (inclusief wachttijd in de wachtrij), en telt resultCount de geïdentificeerde fysieke verzendingen naar het platform. deliveryKind beschrijft, indien aanwezig, de effectieve payload na hooks en rendering; onderdrukte rijen of rijen waarvan de status door een crash onduidelijk is, bevatten deze waarde niet.

De huidige berichtdekking omvat geaccepteerde inkomende berichten die de kerndispatch bereiken, inclusief dubbele/eindresultaten van de kern. Voor uitgaande berichten wordt één eindrij geschreven per oorspronkelijke logische antwoordpayload die de gedeelde duurzame aflevering bereikt; segmentering en adapter-fan-out worden samengevoegd in resultCount. Opnieuw te proberen verzendingen in de wachtrij of verzendingen met een onduidelijke status worden pas vastgelegd na bevestiging, een dead letter of reconciliatie. Plugin-lokale en directe verzendpaden die deze gedeelde grenzen omzeilen, worden nog niet gedekt. De begrensde workerwachtrij werkt volgens het best-effortprincipe en kan records laten vallen bij fouten of verzadiging. Dit oppervlak is daarom geen verliesvrij nalevingsarchief.

Registratie is standaard ingeschakeld en wordt beheerd via audit.enabled. Berichtregistratie wordt afzonderlijk beheerd via audit.messages en is standaard ingesteld op "off". Wanneer registratie is uitgeschakeld, blijft audit.activity.list eerder geschreven records aanbieden totdat ze verlopen.

De meegeleverde schema's voor het audit.list-verzoek, het resultaat en AuditEvent blijven ongewijzigd en retourneren alleen records van agentruns en toolacties. Nieuwe operatorclients moeten audit.activity.list aanroepen wanneer de Gateway deze methode adverteert. Oudere Gateways kunnen unknown method: audit.activity.list rapporteren of, omdat autorisatie in meegeleverde versies voorafging aan het opzoeken van de methode, missing scope: operator.admin voor een verzoek met leesbereik. Behandel dat laatste alleen als afwezigheid van de methode wanneer de methode niet was geadverteerd. Een client kan vervolgens alleen audit.list opnieuw proberen wanneer de filters geen ondersteuning voor berichtstype, richting of kanaal vereisen.

Gebruik openclaw audit voor tekstquery's en begrensde JSON-exports.

RPC's voor het taaklogboek

Operatorclients inspecteren en annuleren records van achtergrondtaken van de Gateway via de RPC's van het taaklogboek (packages/gateway-protocol/src/schema/tasks.ts). Deze retourneren opgeschoonde taaksamenvattingen, geen onbewerkte runtimestatus.

• tasks.list vereist operator.read.
  • Parameters: optioneel status ("queued", "running", "completed", "failed", "cancelled" of "timed_out") of een array met deze statussen, optioneel agentId, optioneel sessionKey, optioneel limit van 1 tot 500 en optionele tekenreeks cursor.
  • Resultaat: { "tasks": TaskSummary[], "nextCursor"?: string }.
• tasks.get vereist operator.read.
  • Parameters: { "taskId": string }.
  • Resultaat: { "task": TaskSummary }.
  • Ontbrekende taak-id's retourneren de vorm van de niet-gevonden-fout van de Gateway.
• tasks.cancel vereist operator.write.
  • Parameters: { "taskId": string, "reason"?: string }.
  • Resultaat: { "found": boolean, "cancelled": boolean, "reason"?: string, "task"?: TaskSummary }.
  • found geeft aan of het logboek een overeenkomende taak bevatte. cancelled geeft aan of de runtime de annulering heeft geaccepteerd of vastgelegd.

TaskSummary bevat id, status en optionele metadata: kind, runtime, title, agentId, sessionKey, childSessionKey, ownerKey, runId, taskId, flowId, parentTaskId, sourceId, tijdstempels, voortgang, eindsamenvatting en opgeschoonde fouttekst. agentId identificeert de agent die de taak uitvoert; sessionKey en ownerKey behouden de context van de aanvrager en de besturing.

Hulpmethoden voor operators

• commands.list (operator.read) haalt de runtimeopdrachtinventaris voor een agent op.
  • agentId is optioneel; laat dit weg om de standaardwerkruimte van de agent te lezen.
  • scope bepaalt op welk oppervlak de primaire name is gericht: text retourneert het primaire token van de tekstopdracht zonder de voorafgaande /; native en het standaardpad both retourneren providerbewuste systeemeigen namen wanneer die beschikbaar zijn.
  • textAliases bevat exacte slash-aliassen zoals /model en /m.
  • nativeName bevat de providerbewuste systeemeigen opdrachtnaam wanneer die bestaat.
  • provider is optioneel en beïnvloedt alleen systeemeigen naamgeving en de beschikbaarheid van systeemeigen Plugin- opdrachten.
  • includeArgs=false laat geserialiseerde argumentmetadata weg uit het antwoord.
• tools.catalog (operator.read) haalt de runtimetoolcatalogus voor een agent op. Het antwoord bevat gegroepeerde tools en herkomstmetadata:
  • source: core of plugin
  • pluginId: eigenaar van de Plugin wanneer source="plugin"
  • optional: of een Plugin-tool optioneel is
• tools.effective (operator.read) haalt de runtime-effectieve toolinventaris voor een sessie op.
  • sessionKey is vereist.
  • De Gateway leidt vertrouwde runtimecontext server-side af uit de sessie in plaats van door de aanroeper verstrekte authenticatie- of afleveringscontext te accepteren.
  • Het antwoord is een sessiegebonden, door de server afgeleide projectie van de actieve inventaris, inclusief tools van de kern, Plugins, kanalen en reeds ontdekte MCP- servers.
  • tools.effective is alleen-lezen voor MCP: deze methode kan een MCP- catalogus van een warme sessie via het definitieve toolbeleid projecteren, maar maakt geen MCP-runtimes, verbindt geen transports en geeft geen tools/list uit. Als er geen overeenkomende warme catalogus bestaat, kan het antwoord 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".
• tools.invoke (operator.write) roept één beschikbare tool aan 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.
  • Kernwrappers die alleen voor de eigenaar zijn bedoeld, zoals cron, gateway en nodes, vereisen een eigenaars-/beheerdersidentiteit (operator.admin), hoewel tools.invoke zelf operator.write is.
  • Het antwoord is een op de SDK gerichte envelop met ok, toolName, optioneel output en getypeerde error-velden. Weigeringen wegens goedkeuring of beleid retourneren ok:false in de payload in plaats van de Gateway-pijplijn voor toolbeleid te omzeilen.
• skills.status (operator.read) haalt de zichtbare Skills-inventaris voor een agent op.
  • agentId is optioneel; laat dit weg om de standaardwerkruimte van de agent te lezen.
  • Het antwoord bevat geschiktheid, ontbrekende vereisten, configuratiecontroles en opgeschoonde installatieopties zonder onbewerkte geheime waarden bloot te stellen.
• skills.search en skills.detail (operator.read) retourneren ClawHub- detectiemetadata.
• skills.upload.begin, skills.upload.chunk en skills.upload.commit (operator.admin) bereiden een privé-Skills-archief voor voordat het wordt geïnstalleerd. Dit is een afzonderlijk uploadpad voor beheerders voor vertrouwde clients, niet de normale ClawHub- installatiestroom voor Skills, en is standaard uitgeschakeld tenzij skills.install.allowUploadedArchives is ingeschakeld.
  • skills.upload.begin({ kind: "skill-archive", slug, sizeBytes, sha256?, force?, idempotencyKey? }) maakt een upload 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 voltooit alleen de upload; de Skill wordt niet geïnstalleerd.
  • Geüploade Skills-archieven zijn ziparchieven met een SKILL.md-hoofdmap. De interne mapnaam van het archief bepaalt nooit het installatiedoel.
• skills.install (operator.admin) heeft drie modi:
  • ClawHub-modus: { source: "clawhub", slug, version?, force? } installeert een Skills-map in de map skills/ van de standaardwerkruimte van de agent.
  • Uploadmodus: { source: "upload", uploadId, slug, force?, sha256?, timeoutMs? } installeert een vastgelegde upload in de map skills/<slug> van de standaardwerkruimte van de agent. De slug en force-waarde moeten overeenkomen met het oorspronkelijke skills.upload.begin-verzoek. 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 verzenden; dit veld is verouderd, wordt alleen geaccepteerd voor protocolcompatibiliteit en wordt genegeerd. Gebruik security.installPolicy voor installatiebeslissingen van operators.
• skills.update (operator.admin) heeft twee modi:
  • De ClawHub-modus werkt één bijgehouden slug of alle bijgehouden ClawHub-installaties in de standaardwerkruimte van de agent bij.
  • De configuratiemodus past skills.entries.<skillKey>-waarden aan, zoals enabled, apiKey en env.

models.list-weergaven

models.list accepteert een optionele parameter view (src/agents/model-catalog-visibility.ts):

• Weggelaten of "default": als agents.defaults.modelPolicy.allow is geconfigureerd, is het antwoord de toegestane catalogus, inclusief dynamisch ontdekte modellen voor provider/*-vermeldingen. Anders is het antwoord de volledige Gateway- catalogus.
• "configured": gedrag met de omvang van een keuzelijst. Als agents.defaults.modelPolicy.allow is geconfigureerd, krijgt deze nog steeds voorrang, inclusief providergebonden detectie voor provider/*-vermeldingen. Zonder een toelatingslijst gebruikt het antwoord expliciete models.providers.<provider>.models-vermeldingen, met een terugval op de volledige catalogus alleen wanneer er geen geconfigureerde modelrijen bestaan.
• "provider-config": door de bron opgestelde models.providers.*.models-inventaris, onafhankelijk van toelatingslijsten voor keuzelijsten. Rijen bevatten openbare modelmogelijkheden en routebewuste beschikbaarheid, maar laten providereindpunten, authenticatiemateriaal en runtimeverzoekconfiguratie weg.
• "all": volledige Gateway-catalogus, waarbij agents.defaults.modelPolicy.allow wordt omzeild. Gebruik dit voor diagnostische/detectie-UI's, niet voor normale modelkeuzelijsten.

Uitvoeringsgoedkeuringen

• Wanneer een exec-verzoek goedkeuring vereist, zendt de Gateway exec.approval.requested uit.
• Operatorclients handelen dit af door exec.approval.resolve aan te roepen (vereist operator.approvals).
• Voor host=node moet exec.approval.request systemRunPlan bevatten (canonieke argv/cwd/rawCommand/sessiemetadata). Verzoeken zonder systemRunPlan worden geweigerd.
• Na goedkeuring hergebruiken doorgestuurde node.invoke system.run-aanroepen die canonieke systemRunPlan als de gezaghebbende opdracht-/cwd-/sessiecontext.
• Als een aanroeper command, rawCommand, cwd, agentId of sessionKey wijzigt tussen de voorbereiding en het uiteindelijk goedgekeurde doorsturen van system.run, weigert de Gateway de uitvoering in plaats van de gewijzigde payload te vertrouwen.

Terugvaloptie voor agentbezorging

• agent-verzoeken kunnen deliver=true bevatten om uitgaande bezorging aan te vragen.
• bestEffortDeliver=false (de standaardwaarde) handhaaft strikt gedrag: niet-opgeloste of uitsluitend interne bezorgingsdoelen retourneren INVALID_REQUEST.
• bestEffortDeliver=true staat terugvallen op uitvoering binnen alleen de sessie toe wanneer geen externe bezorgbare route kan worden bepaald (bijvoorbeeld bij interne/webchat- sessies of dubbelzinnige configuraties met meerdere kanalen).
• Uiteindelijke agent-resultaten kunnen result.deliveryStatus bevatten wanneer bezorging is aangevraagd, met dezelfde statussen sent, suppressed, partial_failed en failed die zijn gedocumenteerd voor openclaw agent --json --deliver.

Versiebeheer

• PROTOCOL_VERSION, MIN_CLIENT_PROTOCOL_VERSION, MIN_NODE_PROTOCOL_VERSION en MIN_PROBE_PROTOCOL_VERSION bevinden zich in packages/gateway-protocol/src/version.ts.
• Clients verzenden minProtocol + maxProtocol. Operator- en UI-clients moeten het huidige protocol in dat bereik opnemen; huidige clients en servers gebruiken protocol v4.
• Geverifieerde clients met zowel role: "node" als client.mode: "node" mogen het N-1-nodeprotocol gebruiken (momenteel v3). Lichtgewicht herstartcontroles gebruiken hetzelfde N-1-venster. Apparaatverificatie, koppeling, bereiken, opdrachtbeleid en exec- goedkeuringen blijven door dit compatibiliteitsvenster ongewijzigd. Door Plugins beheerde node- mogelijkheden en opdrachten worden niet beschikbaar gesteld totdat de node naar het huidige protocol is bijgewerkt, omdat de door hen gehoste oppervlakken geen deel uitmaken van het N-1-contract.
• Schema's en modellen worden gegenereerd uit TypeBox-definities:
  • pnpm protocol:gen
  • pnpm protocol:gen:swift
  • pnpm protocol:check

Clientconstanten

De referentie-implementatie van de client bevindt zich in packages/gateway-client/src/ (OpenClaw verpakt deze via de dunne src/gateway/client.ts-facade). Deze standaardwaarden zijn stabiel in protocol v4 en vormen de verwachte basis voor clients van derden.

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

De referentieclient laat eindige verzoeken hun geconfigureerde deadline beheren wanneer elk verzoek in behandeling er een heeft. Een expectFinal-verzoek zonder een eindige timeoutMs, elk verzoek met timeoutMs: null of een combinatie van eindige en onbegrensde verzoeken houdt de tick-watchdog actief. Als inkomende gebeurtenissen en antwoorden langer stil blijven dan de drempel voor de tick-time-out, sluit de client de socket met code 4000, wijst elk verzoek in behandeling af en maakt opnieuw verbinding. De client speelt afgewezen verzoeken na het opnieuw verbinden niet opnieuw af.

Verificatie

• Gateway-authenticatie met een gedeeld geheim gebruikt connect.params.auth.token of connect.params.auth.password, afhankelijk van de geconfigureerde gateway.auth.mode ("none" | "token" | "password" | "trusted-proxy").
• Modi die identiteit bevatten, zoals Tailscale Serve (gateway.auth.allowTailscale: true) of niet-loopback-gateway.auth.mode: "trusted-proxy", voldoen op basis van aanvraagheaders aan de authenticatiecontrole voor de verbinding, in plaats van via connect.params.auth.*.
• gateway.auth.mode: "none" voor privé-ingang slaat authenticatie met een gedeeld geheim bij het verbinden volledig over; stel die modus niet beschikbaar via een openbare/niet-vertrouwde ingang.
• Na het koppelen geeft de Gateway een apparaattoken uit dat beperkt is tot de verbindingsrol en -bereiken en wordt geretourneerd in hello-ok.auth.deviceToken. Clients moeten dit na elke geslaagde verbinding opslaan.
• Bij opnieuw verbinden met dat opgeslagen apparaattoken moet ook de opgeslagen goedgekeurde bereikenset voor dat token opnieuw worden gebruikt. Dit behoudt reeds verleende lees-/controle-/statustoegang en voorkomt dat nieuwe verbindingen ongemerkt worden beperkt tot een smaller impliciet bereik dat alleen voor beheerders bestemd is.
• Samenstelling van verbindingsauthenticatie aan clientzijde (selectConnectAuth in packages/gateway-client/src/client.ts):
  • auth.password staat hier los van en wordt altijd doorgestuurd wanneer het is ingesteld.
  • auth.token wordt in deze prioriteitsvolgorde ingevuld: eerst een expliciet gedeeld token, vervolgens een expliciete deviceToken en daarna een opgeslagen token per apparaat (met deviceId + role als sleutel).
  • auth.bootstrapToken wordt alleen verzonden wanneer geen van de bovenstaande opties auth.token heeft opgeleverd. Een gedeeld token of elk gevonden apparaattoken onderdrukt dit.
  • Automatische promotie van een opgeslagen apparaattoken bij de eenmalige nieuwe poging voor AUTH_TOKEN_MISMATCH is uitsluitend toegestaan voor vertrouwde eindpunten: loopback of wss:// met een vastgezette tlsFingerprint. Openbare wss:// zonder vastzetten komt niet in aanmerking.
• De ingebouwde bootstrap met installatiecode retourneert de hello-ok.auth.deviceToken van de primaire Node plus een begrensd operatortoken in hello-ok.auth.deviceTokens voor vertrouwde overdracht naar mobiele apparaten. Het operatortoken bevat operator.talk.secrets voor het lezen van de native Talk-configuratie, maar sluit bereiken voor koppelingswijzigingen en operator.admin uit.
• Terwijl een bootstrap met een niet-standaardinstallatiecode op goedkeuring wacht, bevatten de details van PAIRING_REQUIRED recommendedNextStep: "wait_then_retry", retryable: true en pauseReconnect: false. Blijf opnieuw verbinden met hetzelfde bootstraptoken totdat de aanvraag is goedgekeurd of het token ongeldig wordt.
• Sla hello-ok.auth.deviceTokens alleen op wanneer voor de verbinding bootstrap- authenticatie via een vertrouwd transport is gebruikt, zoals wss:// of lokale koppeling/loopback.
• Als een client een expliciete deviceToken of expliciete scopes opgeeft, blijft die door de aanroeper aangevraagde bereikenset leidend; gecachte bereiken worden alleen hergebruikt wanneer de client het opgeslagen token per apparaat hergebruikt.
• Apparaattokens kunnen worden geroteerd/ingetrokken via device.token.rotate en device.token.revoke (vereist operator.pairing). Voor het roteren of intrekken van een Node of een andere niet-operatorrol is ook operator.admin vereist.
• device.token.rotate retourneert rotatiemetadata. Het geeft het vervangende bearertoken alleen terug bij aanroepen vanaf hetzelfde apparaat die al met dat apparaattoken zijn geauthenticeerd, zodat clients die uitsluitend tokens gebruiken hun vervanging vóór het opnieuw verbinden kunnen opslaan. Rotaties door middel van gedeelde/beheerderstokens geven het bearertoken niet terug.
• Uitgifte, rotatie en intrekking van tokens blijven beperkt tot de goedgekeurde rollenset die in de koppelingsvermelding van dat apparaat is vastgelegd; tokenwijzigingen kunnen geen apparaatrol uitbreiden of als doel kiezen die nooit via koppelingsgoedkeuring is verleend.
• Voor tokensessies van gekoppelde apparaten is apparaatbeheer beperkt tot het eigen apparaat, tenzij de aanroeper ook operator.admin heeft: niet-beheerders kunnen alleen het operatortoken voor hun eigen apparaatvermelding beheren. Tokenbeheer voor Nodes en andere niet-operatorrollen is uitsluitend voor beheerders, zelfs voor het eigen apparaat van de aanroeper.
• device.token.rotate en device.token.revoke controleren ook de bereikenset van het beoogde operatortoken aan de hand van de huidige sessiebereiken van de aanroeper. Niet-beheerders kunnen geen operatortoken roteren of intrekken dat ruimere bereiken heeft dan het token waarover ze al beschikken.
• Authenticatiefouten bevatten error.details.code plus hersteltips:
  • error.details.canRetryWithDeviceToken (booleaans)
  • error.details.recommendedNextStep: een van retry_with_device_token, update_auth_configuration, update_auth_credentials, wait_then_retry, review_auth_configuration (packages/gateway-protocol/src/connect-error-details.ts).
• Clientgedrag voor AUTH_TOKEN_MISMATCH:
  • Vertrouwde clients mogen één begrensde nieuwe poging doen met een gecacht token per apparaat.
  • Als die nieuwe poging mislukt, stop dan automatische lussen voor opnieuw verbinden en toon aanwijzingen voor actie door de operator.
• AUTH_SCOPE_MISMATCH betekent dat het apparaattoken is herkend, maar niet de aangevraagde rol/bereiken dekt. Presenteer dit niet als een ongeldig token; vraag de operator opnieuw te koppelen of het smallere/ruimere bereikcontract goed te keuren.

Apparaatidentiteit en koppeling

• Nodes moeten een stabiele apparaatidentiteit (device.id) bevatten die is afgeleid van de vingerafdruk van een sleutelpaar.
• Gateways geven tokens uit per apparaat + rol.
• Voor nieuwe apparaat-ID's is koppelingsgoedkeuring vereist, tenzij lokale automatische goedkeuring is ingeschakeld.
• Automatische koppelingsgoedkeuring is gericht op directe lokale loopbackverbindingen.
• OpenClaw heeft ook een beperkt zelfverbindingspad dat lokaal is voor de backend/container, voor vertrouwde helperstromen met een gedeeld geheim.
• Tailnet- of LAN-verbindingen vanaf dezelfde host worden voor koppeling nog steeds als extern behandeld en vereisen goedkeuring.
• WS-clients nemen tijdens connect normaal gesproken de identiteit device op (operator + Node). De enige uitzonderingen voor operators zonder apparaat zijn expliciete vertrouwenspaden:
  • geslaagde gateway.auth.mode: "trusted-proxy"-operatorauthenticatie voor de Control UI.
  • directe loopback-gateway-client-backend-RPC's op het gereserveerde interne helperpad.
• Het weglaten van de apparaatidentiteit heeft gevolgen voor de bereiken. Wanneer een operatorverbinding zonder apparaat via een expliciet vertrouwenspad wordt toegestaan, wist OpenClaw zelf opgegeven bereiken nog steeds tot een lege set, tenzij dat pad een benoemde uitzondering voor bereikbehoud heeft. Methoden waarvoor bereiken vereist zijn, mislukken vervolgens met missing scope.
• Het gereserveerde directe loopback-gateway-client-backendhelperpad behoudt bereiken alleen voor interne lokale RPC's van het besturingsvlak; aangepaste backend-ID's krijgen deze uitzondering niet.
• Alle verbindingen moeten de door de server verstrekte connect.challenge-nonce ondertekenen.

Migratiediagnostiek voor apparaatauthenticatie

Voor verouderde clients die nog ondertekeningsgedrag van vóór de challenge gebruiken, retourneert connect DEVICE_AUTH_*-detailcodes onder error.details.code met een stabiele error.details.reason.

Veelvoorkomende migratiefouten:

Migratiedoel:

• Wacht altijd op connect.challenge.
• Onderteken de v2-payload die de servernonce bevat.
• Verzend dezelfde nonce in connect.params.device.nonce.
• De voorkeurspayload voor ondertekening is v3 (buildDeviceAuthPayloadV3 in packages/gateway-client/src/device-auth.ts), die naast de velden voor apparaat/client/rol/bereiken/token/nonce ook platform en deviceFamily bindt.
• Verouderde v2-handtekeningen blijven voor compatibiliteit geaccepteerd, maar het vastzetten van metadata van gekoppelde apparaten blijft bij opnieuw verbinden het opdrachtenbeleid bepalen.

TLS en vastzetten

• TLS wordt ondersteund voor WS-verbindingen (gateway.tls-configuratie).
• Clients kunnen optioneel de vingerafdruk van het Gateway-certificaat vastzetten via gateway.remote.tlsFingerprint of CLI --tls-fingerprint.

Bereik

Dit protocol ontsluit de volledige Gateway-API: status, kanalen, modellen, chat, agent, sessies, Nodes, goedkeuringen en meer. Het exacte oppervlak wordt bepaald door de TypeBox-schema's die opnieuw worden geëxporteerd vanuit packages/gateway-protocol/src/schema.ts.

Gerelateerd

• Een Gateway-client bouwen
• OpenClaw insluiten
• Bridge-protocol
• Gateway-draaiboek