Gateway-protocol

Documentation Index

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

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

​

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 diagnostics ingeschakeld emitten te grote inkomende frames en trage uitgaande buffers payload.large-events voordat de Gateway het betreffende frame sluit of laat vallen. Deze events bewaren groottes, limieten, oppervlakken en veilige reden-codes. Ze bewaren niet de berichttekst, bijlage-inhoud, ruwe frame-body, 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"]
      }
    ]
  }
}

​

Node-voorbeeld

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

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

​

Rollen + scopes

​

Rollen

• operator = control-plane-client (CLI/UI/automation).
• node = capability-host (camera/screen/canvas/system.run).

​

Scopes (operator)

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

• requests zonder command: operator.pairing
• requests met niet-exec-nodecommands: operator.pairing + operator.write
• requests 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: command-allowlist voor invoke.
• permissions: granulaire toggles (bijv. screen.record, camera.capture).

​

Presence

• system-presence retourneert entries met device identity als key.
• Presence entries bevatten deviceId, roles en scopes zodat UI’s één rij per device kunnen tonen, zelfs wanneer het zowel als operator als node verbindt.
• node.list bevat optionele velden lastSeenAtMs en lastSeenReason. Verbonden nodes rapporteren hun huidige verbindingstijd als lastSeenAtMs met reden connect; paired nodes kunnen ook duurzame background presence rapporteren wanneer een vertrouwd node-event hun pairingmetadata bijwerkt.

​

Node background alive event

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

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

​

Scoping van broadcast-events

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

​

Veelvoorkomende RPC-methodfamilies

​

Algemene gebeurtenisfamilies

• chat: UI-chatupdates zoals chat.inject en andere uitsluitend transcript-chatgebeurtenissen.
• session.message en session.tool: transcript-/eventstream-updates voor een geabonneerde sessie.
• sessions.changed: sessie-index of metadata gewijzigd.
• presence: updates van momentopnamen van systeempresentie.
• tick: periodieke keepalive- / liveness-gebeurtenis.
• health: update van Gateway-gezondheidsmomentopname.
• heartbeat: update van Heartbeat-eventstream.
• cron: wijzigingsgebeurtenis voor Cron-run/-taak.
• shutdown: melding van Gateway-afsluiting.
• node.pair.requested / node.pair.resolved: levenscyclus van node-koppeling.
• node.invoke.request: broadcast van node-aanroepverzoek.
• device.pair.requested / device.pair.resolved: levenscyclus van gekoppeld apparaat.
• voicewake.changed: configuratie van wake-wordtrigger gewijzigd.
• exec.approval.requested / exec.approval.resolved: exec-goedkeuringslevenscyclus.
• plugin.approval.requested / plugin.approval.resolved: Plugin-goedkeuringslevenscyclus.

​

Node-helpermethoden

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

​

Taakregister-RPC’s

• tasks.list vereist operator.read.
  • Parameters: 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 optioneel string cursor.
  • Resultaat: { "tasks": TaskSummary[], "nextCursor"?: string }.
• tasks.get vereist operator.read.
  • Parameters: { "taskId": string }.
  • Resultaat: { "task": TaskSummary }.
  • Ontbrekende taak-id’s retourneren de Gateway not-found-foutvorm.
• tasks.cancel vereist operator.write.
  • Parameters: { "taskId": string, "reason"?: string }.
  • Resultaat: { "found": boolean, "cancelled": boolean, "reason"?: string, "task"?: TaskSummary }.
  • found meldt of het register een overeenkomende taak had. cancelled meldt of de runtime annulering heeft geaccepteerd of vastgelegd.

​

Operator-helpermethoden

• Operators mogen commands.list (operator.read) aanroepen om de runtime commando-inventaris voor een agent op te halen.
  • agentId is optioneel; laat het weg om de standaard agent-werkruimte te lezen.
  • scope bepaalt welk oppervlak de primaire name target:
    • text retourneert het primaire tekstcommandotoken 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 commandonaam wanneer die bestaat.
  • provider is optioneel en beïnvloedt alleen native naamgeving plus native beschikbaarheid van Plugin-commando’s.
  • includeArgs=false laat geserialiseerde argumentmetadata weg uit de respons.
• Operators mogen 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 mogen tools.effective (operator.read) aanroepen om de runtime-effectieve tool- inventaris voor een sessie op te halen.
  • sessionKey is vereist.
  • De Gateway leidt vertrouwde runtime-context af uit de sessie aan serverzijde in plaats van door de aanroeper geleverde auth- of leveringscontext te accepteren.
  • De respons is sessiegebonden en weerspiegelt wat het actieve gesprek nu kan gebruiken, inclusief core-, Plugin- en kanaaltools.
• Operators mogen 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.
  • De respons is een SDK-gerichte envelop met ok, toolName, optionele output en getypeerde error-velden. Goedkeurings- of beleidsweigeringen retourneren ok:false in de payload in plaats van de Gateway-toolbeleidspijplijn te omzeilen.
• Operators mogen skills.status (operator.read) aanroepen om de zichtbare skill-inventaris voor een agent op te halen.
  • agentId is optioneel; laat het weg om de standaard agent-werkruimte te lezen.
  • De respons bevat geschiktheid, ontbrekende vereisten, configuratiecontroles en opgeschoonde installatieopties zonder ruwe geheime waarden bloot te leggen.
• Operators mogen skills.search en skills.detail (operator.read) aanroepen voor ClawHub-ontdekkingsmetadata.
• Operators mogen skills.upload.begin, skills.upload.chunk en skills.upload.commit (operator.admin) aanroepen om een privé-skillarchief klaar te zetten voordat het wordt geïnstalleerd. Dit is een apart admin-uploadpad voor vertrouwde clients, niet de normale ClawHub-skillinstallatiestroom, 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 is gekoppeld aan die slug en force-waarde.
  • 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; het installeert de skill niet.
  • Geüploade skillarchieven zijn zip-archieven met een SKILL.md-root. De interne directorynaam van het archief selecteert nooit het installatiedoel.
• Operators mogen skills.install (operator.admin) aanroepen in drie modi:
  • ClawHub-modus: { source: "clawhub", slug, version?, force? } installeert een skillmap in de skills/-directory van de standaard agent-werkruimte.
  • Uploadmodus: { source: "upload", uploadId, slug, force?, sha256?, timeoutMs? } installeert een gecommitte upload in de directory skills/<slug> van de standaard agent-werkruimte. De slug en force-waarde moeten overeenkomen met het oorspronkelijke skills.upload.begin-verzoek. Deze modus wordt geweigerd tenzij skills.install.allowUploadedArchives is ingeschakeld. De instelling heeft geen invloed op ClawHub-installaties.
  • Gateway-installermodus: { name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? } voert een gedeclareerde metadata.openclaw.install-actie uit op de Gateway-host.
• Operators mogen skills.update (operator.admin) aanroepen in twee modi:
  • ClawHub-modus werkt één bijgehouden slug of alle bijgehouden ClawHub-installaties bij in de standaard agent-werkruimte.
  • Configuratiemodus patcht skills.entries.<skillKey>-waarden zoals enabled, apiKey en env.

​

models.list-weergaven

• Weggelaten of "default": huidig runtime-gedrag. Als agents.defaults.models is geconfigureerd, is de respons de toegestane catalogus, inclusief dynamisch ontdekte modellen voor provider/*-items. Anders is de respons de volledige Gateway-catalogus.
• "configured": picker-formaat gedrag. Als agents.defaults.models is geconfigureerd, heeft dit nog steeds voorrang, inclusief providergebonden ontdekking voor provider/*-items. Zonder allowlist gebruikt de respons expliciete models.providers.*.models-items, 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-verzoek goedkeuring nodig heeft, broadcast de Gateway exec.approval.requested.
• Operatorclients lossen dit op door exec.approval.resolve aan te roepen (vereist operator.approvals-scope).
• 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 dat canonieke systemRunPlan als de gezaghebbende opdracht-/cwd-/sessiecontext.
• Als een aanroeper command, rawCommand, cwd, agentId of sessionKey muteert tussen voorbereiding en de definitieve goedgekeurde system.run-forward, weigert de Gateway de run in plaats van de gemuteerde payload te vertrouwen.

​

Terugval voor agentlevering

• agent-verzoeken kunnen deliver=true bevatten om uitgaande levering aan te vragen.
• bestEffortDeliver=false behoudt strikt gedrag: onopgeloste of alleen interne leveringsdoelen retourneren INVALID_REQUEST.
• bestEffortDeliver=true staat terugval naar sessie-only uitvoering toe wanneer geen externe leverbare route kan worden opgelost (bijvoorbeeld interne/webchat-sessies of dubbelzinnige multikanaalconfiguraties).
• Definitieve agent-resultaten kunnen result.deliveryStatus bevatten wanneer levering is aangevraagd, met dezelfde statussen sent, suppressed, partial_failed en failed die zijn gedocumenteerd voor openclaw agent --json --deliver.

​

Versiebeheer

• PROTOCOL_VERSION staat in src/gateway/protocol/version.ts.
• Clients sturen minProtocol + maxProtocol; de server weigert bereiken die het huidige protocol niet bevatten. Native clients gebruiken een v3-ondergrens zodat additieve v4-clients nog steeds v3-Gateways kunnen bereiken.
• Schema’s + modellen worden gegenereerd uit TypeBox-definities:
  • pnpm protocol:gen
  • pnpm protocol:gen:swift
  • pnpm protocol:check

​

Clientconstanten

​

Authenticatie

• Shared-secret Gateway-authenticatie gebruikt connect.params.auth.token of connect.params.auth.password, afhankelijk van de geconfigureerde authenticatiemodus.
• Modi die identiteit dragen, zoals Tailscale Serve (gateway.auth.allowTailscale: true) of niet-loopback gateway.auth.mode: "trusted-proxy" voldoen aan de connect-authenticatiecontrole via aanvraagheaders in plaats van connect.params.auth.*.
• Private-ingress gateway.auth.mode: "none" slaat shared-secret connect-authenticatie volledig over; stel die modus niet bloot op publieke/niet-vertrouwde ingress.
• Na pairing geeft de Gateway een apparaat-token uit dat is beperkt tot de verbindingsrol
  • scopes. Het wordt teruggegeven in hello-ok.auth.deviceToken en moet door de client worden bewaard voor toekomstige verbindingen.
• Clients moeten het 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-/statustoegang die al was verleend en voorkomt dat reconnects stilzwijgend worden teruggebracht tot een beperktere 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 expliciet gedeeld token, daarna een expliciete deviceToken, daarna een opgeslagen per-device token (gesleuteld op deviceId + role).
  • auth.bootstrapToken wordt alleen verzonden wanneer geen van bovenstaande een auth.token heeft opgelost. 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 eindpunten — loopback, of wss:// met een gepinde tlsFingerprint. Publieke wss:// zonder pinning kwalificeert niet.
• Aanvullende vermeldingen in hello-ok.auth.deviceTokens zijn bootstrap-handofftokens. Bewaar ze alleen wanneer de verbinding bootstrap-authenticatie gebruikte op een vertrouwd transport zoals wss:// of loopback/lokale pairing.
• Als een client een expliciete deviceToken of expliciete scopes levert, blijft die door de caller aangevraagde scopeset leidend; gecachte scopes worden alleen hergebruikt wanneer de client het opgeslagen per-device token hergebruikt.
• Apparaat-tokens kunnen worden geroteerd/ingetrokken via device.token.rotate en device.token.revoke (vereist scope operator.pairing).
• 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. Shared/admin-rotaties echoën het bearer-token niet.
• Tokenuitgifte, rotatie en intrekking blijven begrensd tot de goedgekeurde rollenset die is vastgelegd in de pairing-vermelding van dat apparaat; tokenmutatie kan geen apparaatrol uitbreiden of targeten die nooit door pairing-goedkeuring is verleend.
• Voor paired-device tokensessies is apparaatbeheer self-scoped, tenzij de caller ook operator.admin heeft: niet-admin-callers kunnen alleen hun eigen apparaatvermelding verwijderen/intrekken/roteren.
• device.token.rotate en device.token.revoke controleren ook de scopeset van het target operator-token tegen de huidige sessiescopes van de caller. Niet-admin-callers kunnen geen breder operator-token roteren of intrekken dan ze 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-device token.
  • Als die retry faalt, moeten clients automatische reconnect-loops stoppen en operator-actieadvies tonen.
• AUTH_SCOPE_MISMATCH betekent dat het apparaat-token werd herkend maar de gevraagde rol/scopes niet dekt. Clients moeten dit niet presenteren als een ongeldig token; vraag de operator om opnieuw te pairen of het smallere/bredere scopecontract goed te keuren.

​

Apparaatidentiteit + pairing

• Nodes moeten een stabiele apparaatidentiteit (device.id) opnemen die is afgeleid van een keypair-fingerprint.
• Gateways geven tokens uit per apparaat + rol.
• Pairing-goedkeuringen zijn vereist voor nieuwe apparaat-ID’s, tenzij lokale auto-goedkeuring is ingeschakeld.
• Pairing-auto-goedkeuring is gericht op directe local loopback-verbindingen.
• OpenClaw heeft ook een smal backend-/container-lokaal self-connect-pad voor vertrouwde shared-secret helperflows.
• Same-host tailnet- of LAN-verbindingen worden nog steeds als remote behandeld voor pairing en vereisen goedkeuring.
• WS-clients nemen normaal gesproken device-identiteit op tijdens connect (operator + node). De enige operator-uitzonderingen 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 beveiligingsdowngrade).
  • direct-loopback gateway-client backend-RPC’s geauthenticeerd met het gedeelde gatewaytoken/wachtwoord.
• Alle verbindingen moeten de door de server geleverde nonce connect.challenge ondertekenen.

​

Diagnostiek voor migratie van apparaatauthenticatie

• 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 naast device/client/role/scopes/token/nonce-velden ook platform en deviceFamily bindt.
• Legacy v2-handtekeningen blijven geaccepteerd voor compatibiliteit, maar paired-device metadata-pinning blijft commandobeleid bij reconnect bepalen.

​

TLS + pinning

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

​

Scope

​

Gerelateerd

• Bridge-protocol
• Gateway-runbook