Protocollo Gateway

Il protocollo WS del Gateway è il singolo piano di controllo + trasporto dei nodi per OpenClaw. Tutti i client (CLI, UI web, app macOS, nodi iOS/Android, nodi headless) si connettono tramite WebSocket e dichiarano il proprio ruolo + ambito al momento dell'handshake.

Trasporto

• WebSocket, frame di testo con payload JSON.
• Il primo frame deve essere una richiesta connect.
• I frame pre-connect sono limitati a 64 KiB. Dopo un handshake riuscito, i client devono rispettare i limiti hello-ok.policy.maxPayload e hello-ok.policy.maxBufferedBytes. Con la diagnostica abilitata, frame in ingresso troppo grandi e buffer in uscita lenti emettono eventi payload.large prima che il gateway chiuda o scarti il frame interessato. Questi eventi conservano dimensioni, limiti, superfici e codici motivo sicuri. Non conservano il corpo del messaggio, contenuti degli allegati, corpo grezzo del frame, token, cookie o valori segreti.

Handshake (connect)

Gateway → Client (challenge pre-connect):

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

Client → Gateway:

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

Gateway → Client:

{  "type": "res",  "id": "…",  "ok": true,  "payload": {    "type": "hello-ok",    "protocol": 4,    "server": { "version": "…", "connId": "…" },    "features": { "methods": ["…"], "events": ["…"] },    "snapshot": { "…": "…" },    "auth": {      "role": "operator",      "scopes": ["operator.read", "operator.write"]    },    "policy": {      "maxPayload": 26214400,      "maxBufferedBytes": 52428800,      "tickIntervalMs": 15000    }  }}

Mentre il Gateway sta ancora completando i sidecar di avvio, la richiesta connect può restituire un errore UNAVAILABLE ritentabile con details.reason impostato su "startup-sidecars" e retryAfterMs. I client devono ritentare quella risposta entro il proprio budget complessivo di connessione invece di presentarla come un errore terminale di handshake.

server, features, snapshot e policy sono tutti richiesti dallo schema (packages/gateway-protocol/src/schema/frames.ts). Anche auth è richiesto e indica il ruolo/gli ambiti negoziati. pluginSurfaceUrls è facoltativo e mappa i nomi delle superfici dei plugin, come canvas, a URL ospitati con ambito.

Gli URL delle superfici dei plugin con ambito possono scadere. I nodi possono chiamare node.pluginSurface.refresh con { "surface": "canvas" } per ricevere una nuova voce in pluginSurfaceUrls. Il refactor sperimentale del Plugin Canvas non supporta il percorso di compatibilità deprecato canvasHostUrl, canvasCapability o node.canvas.capability.refresh; i client nativi e i gateway attuali devono usare le superfici dei plugin.

Quando non viene emesso alcun token dispositivo, hello-ok.auth riporta le autorizzazioni negoziate senza campi token:

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

I client backend attendibili nello stesso processo (client.id: "gateway-client", client.mode: "backend") possono omettere device sulle connessioni loopback dirette quando si autenticano con il token/password gateway condiviso. Questo percorso è riservato agli RPC interni del piano di controllo e impedisce che baseline di associazione CLI/dispositivo obsolete blocchino il lavoro del backend locale, come gli aggiornamenti delle sessioni dei subagent. I client remoti, i client con origine browser, i client nodo e i client espliciti con token dispositivo/identità dispositivo usano ancora i normali controlli di associazione e upgrade degli ambiti.

Quando viene emesso un token dispositivo, hello-ok include anche:

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

Il bootstrap integrato con QR/codice di configurazione è un nuovo percorso di passaggio a mobile. Una connessione baseline con codice di configurazione riuscita restituisce un token nodo primario più un token operatore limitato:

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

Il passaggio operatore è intenzionalmente limitato affinché l'onboarding QR possa avviare il ciclo operatore mobile e completare la configurazione nativa senza concedere ambiti di mutazione dell'associazione o operator.admin. Include operator.talk.secrets affinché il client nativo possa leggere la configurazione Talk di cui ha bisogno dopo il bootstrap. Un accesso più ampio ad associazione e amministrazione richiede un flusso separato di associazione operatore approvata o di token. I client devono rendere persistente hello-ok.auth.deviceTokens solo quando la connessione ha usato l'autenticazione bootstrap su trasporto attendibile come wss:// o associazione loopback/locale.

Esempio Node

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

• Richiesta: {type:"req", id, method, params}
• Risposta: {type:"res", id, ok, payload|error}
• Evento: {type:"event", event, payload, seq?, stateVersion?}

I metodi con effetti collaterali richiedono chiavi di idempotenza (vedi schema).

Ruoli + ambiti

Per il modello completo degli ambiti operatore, i controlli al momento dell'approvazione e la semantica dei segreti condivisi, consulta Ambiti operatore.

Ruoli

• operator = client del piano di controllo (CLI/UI/automazione).
• node = host di capacità (camera/screen/canvas/system.run).

Ambiti (operatore)

Ambiti comuni:

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

talk.config con includeSecrets: true richiede operator.talk.secrets (o operator.admin). Quando i segreti sono inclusi, i client devono leggere la credenziale del provider Talk attivo da talk.resolved.config.apiKey; talk.providers.<id>.apiKey mantiene la forma sorgente e può essere un oggetto SecretRef o una stringa redatta.

I metodi RPC del gateway registrati dai plugin possono richiedere il proprio ambito operatore, ma i prefissi admin core riservati (config.*, exec.approvals.*, wizard.*, update.*) si risolvono sempre in operator.admin.

L'ambito del metodo è solo il primo gate. Alcuni comandi slash raggiunti tramite chat.send applicano controlli più severi a livello di comando in aggiunta. Per esempio, le scritture persistenti /config set e /config unset richiedono operator.admin.

node.pair.approve ha anche un controllo aggiuntivo dell'ambito al momento dell'approvazione oltre all'ambito base del metodo:

• richieste senza comando: operator.pairing
• richieste con comandi nodo non-exec: operator.pairing + operator.write
• richieste che includono system.run, system.run.prepare o system.which: operator.pairing + operator.admin

Capacità/comandi/autorizzazioni (nodo)

I nodi dichiarano le attestazioni di capacità al momento della connessione:

• caps: categorie di capacità di alto livello come camera, canvas, screen, location, voice e talk.
• commands: allowlist dei comandi per invoke.
• permissions: toggle granulari (ad esempio screen.record, camera.capture).

Il Gateway tratta queste come attestazioni e applica allowlist lato server.

Presenza

• system-presence restituisce voci indicizzate per identità dispositivo.
• Le voci di presenza includono deviceId, roles e scopes affinché le UI possano mostrare una singola riga per dispositivo anche quando si connette sia come operator sia come node.
• node.list include i campi facoltativi lastSeenAtMs e lastSeenReason. I nodi connessi indicano l'ora della connessione corrente come lastSeenAtMs con motivo connect; i nodi associati possono anche indicare una presenza in background durevole quando un evento nodo attendibile aggiorna i loro metadati di associazione.

Evento alive in background del nodo

I nodi possono chiamare node.event con event: "node.presence.alive" per registrare che un nodo associato era attivo durante un risveglio in background senza contrassegnarlo come connesso.

{  "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 è un enum chiuso: background, silent_push, bg_app_refresh, significant_location, manual o connect. Le stringhe trigger sconosciute vengono normalizzate a background dal gateway prima della persistenza. L'evento è durevole solo per sessioni dispositivo nodo autenticate; le sessioni senza dispositivo o non associate restituiscono handled: false.

I gateway riusciti restituiscono un risultato strutturato:

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

I gateway più vecchi possono ancora restituire { "ok": true } per node.event; i client devono trattarlo come un RPC confermato, non come persistenza durevole della presenza.

Definizione degli ambiti degli eventi broadcast

Gli eventi broadcast WebSocket inviati dal server sono soggetti a gate di ambito, così le sessioni con ambito di associazione o solo nodo non ricevono passivamente contenuti di sessione.

• I frame di chat, agente e risultato tool (inclusi gli eventi agent in streaming e i risultati delle chiamate tool) richiedono almeno operator.read. Le sessioni senza operator.read saltano interamente questi frame.
• I broadcast plugin.* definiti dai plugin sono soggetti a gate su operator.write o operator.admin, a seconda di come il plugin li ha registrati.
• Gli eventi di stato e trasporto (heartbeat, presence, tick, ciclo di vita connect/disconnect, ecc.) restano senza restrizioni affinché lo stato del trasporto rimanga osservabile da ogni sessione autenticata.
• Le famiglie di eventi broadcast sconosciute sono soggette a gate di ambito per impostazione predefinita (fail-closed), a meno che un handler registrato non le rilassi esplicitamente.

Ogni connessione client mantiene il proprio numero di sequenza per-client, così i broadcast preservano un ordinamento monotono su quel socket anche quando client diversi vedono sottoinsiemi diversi, filtrati per ambito, del flusso di eventi.

Famiglie comuni di metodi RPC

La superficie WS pubblica è più ampia degli esempi di handshake/auth sopra. Questo non è un dump generato: hello-ok.features.methods è una lista di discovery conservativa costruita da src/gateway/server-methods-list.ts più gli export dei metodi plugin/canale caricati. Trattala come discovery delle funzionalità, non come enumerazione completa di src/gateway/server-methods/*.ts.

Famiglie di eventi comuni

• chat: aggiornamenti chat della UI come chat.inject e altri eventi chat solo di trascrizione. Nel protocollo v4, i payload delta contengono deltaText; message rimane lo snapshot cumulativo dell'assistente. Le sostituzioni non prefisso impostano replace=true e usano deltaText come testo sostitutivo.
• session.message, session.operation e session.tool: aggiornamenti di trascrizione, operazione di sessione in corso e stream di eventi per una sessione sottoscritta.
• sessions.changed: indice sessioni o metadati modificati.
• presence: aggiornamenti dello snapshot di presenza del sistema.
• tick: evento periodico keepalive / liveness.
• health: aggiornamento dello snapshot di salute del gateway.
• heartbeat: aggiornamento dello stream di eventi heartbeat.
• cron: evento di modifica esecuzione/job cron.
• shutdown: notifica di arresto del gateway.
• node.pair.requested / node.pair.resolved: ciclo di vita dell'abbinamento Node.
• node.invoke.request: broadcast di richiesta invoke Node.
• device.pair.requested / device.pair.resolved: ciclo di vita del dispositivo abbinato.
• voicewake.changed: configurazione del trigger wake-word modificata.
• exec.approval.requested / exec.approval.resolved: ciclo di vita dell'approvazione exec.
• plugin.approval.requested / plugin.approval.resolved: ciclo di vita dell'approvazione plugin.

Metodi helper Node

• I Node possono chiamare skills.bins per recuperare l'elenco corrente degli eseguibili delle skill per i controlli di auto-consenso.

RPC del registro attività

I client operatore possono ispezionare e annullare i record delle attività in background del Gateway tramite gli RPC del registro attività. Questi metodi restituiscono riepiloghi attività sanificati, non lo stato runtime grezzo.

• tasks.list richiede operator.read.
  • Parametri: status opzionale ("queued", "running", "completed", "failed", "cancelled" o "timed_out") o un array di tali stati, agentId opzionale, sessionKey opzionale, limit opzionale da 1 a 500 e stringa cursor opzionale.
  • Risultato: { "tasks": TaskSummary[], "nextCursor"?: string }.
• tasks.get richiede operator.read.
  • Parametri: { "taskId": string }.
  • Risultato: { "task": TaskSummary }.
  • Gli id attività mancanti restituiscono la forma di errore not-found del Gateway.
• tasks.cancel richiede operator.write.
  • Parametri: { "taskId": string, "reason"?: string }.
  • Risultato: { "found": boolean, "cancelled": boolean, "reason"?: string, "task"?: TaskSummary }.
  • found indica se il registro conteneva un'attività corrispondente. cancelled indica se il runtime ha accettato o registrato l'annullamento.

TaskSummary include id, status e metadati opzionali come kind, runtime, title, agentId, sessionKey, childSessionKey, ownerKey, runId, taskId, flowId, parentTaskId, sourceId, timestamp, avanzamento, riepilogo terminale e testo di errore sanificato. agentId identifica l'agente che esegue l'attività; sessionKey e ownerKey preservano il contesto di richiedente e controllo.

Metodi helper operatore

• Gli operatori possono chiamare commands.list (operator.read) per recuperare l'inventario dei comandi runtime per un agente.
  • agentId è facoltativo; omettilo per leggere il workspace agente predefinito.
  • scope controlla quale superficie è destinata dal name primario:
    • text restituisce il token del comando di testo primario senza il / iniziale
    • native e il percorso predefinito both restituiscono nomi nativi consapevoli del provider quando disponibili
  • textAliases contiene alias slash esatti come /model e /m.
  • nativeName contiene il nome del comando nativo consapevole del provider quando esiste.
  • provider è facoltativo e influisce solo sulla denominazione nativa e sulla disponibilità dei comandi Plugin nativi.
  • includeArgs=false omette dalla risposta i metadati degli argomenti serializzati.
• Gli operatori possono chiamare tools.catalog (operator.read) per recuperare il catalogo degli strumenti runtime per un agente. La risposta include strumenti raggruppati e metadati di provenienza:
  • source: core o plugin
  • pluginId: proprietario del plugin quando source="plugin"
  • optional: indica se uno strumento Plugin è facoltativo
• Gli operatori possono chiamare tools.effective (operator.read) per recuperare l'inventario degli strumenti effettivo a runtime per una sessione.
  • sessionKey è obbligatorio.
  • Il Gateway deriva il contesto runtime attendibile dalla sessione lato server invece di accettare contesto di autenticazione o recapito fornito dal chiamante.
  • La risposta è una proiezione con ambito sessione e derivata dal server dell'inventario attivo, inclusi strumenti core, Plugin, canale e strumenti di server MCP già rilevati.
  • tools.effective è di sola lettura per MCP: può proiettare un catalogo MCP di sessione già caldo attraverso la policy finale degli strumenti, ma non crea runtime MCP, non connette trasporti né invia tools/list. Se non esiste un catalogo caldo corrispondente, la risposta può includere un avviso come mcp-not-yet-connected, mcp-not-yet-listed o mcp-stale-catalog.
  • Le voci degli strumenti effettivi usano source="core", source="plugin", source="channel" o source="mcp".
• Gli operatori possono chiamare tools.invoke (operator.write) per invocare uno strumento disponibile attraverso lo stesso percorso di policy del gateway di /tools/invoke.
  • name è obbligatorio. args, sessionKey, agentId, confirm e idempotencyKey sono facoltativi.
  • Se sono presenti sia sessionKey sia agentId, l'agente della sessione risolta deve corrispondere a agentId.
  • Wrapper core riservati al proprietario come cron, gateway e nodes richiedono identità proprietario/admin (operator.admin) anche se il metodo tools.invoke stesso è operator.write.
  • La risposta è un envelope rivolto all'SDK con ok, toolName, output facoltativo e campi error tipizzati. Approvazioni o rifiuti di policy restituiscono ok:false nel payload invece di aggirare la pipeline di policy degli strumenti del gateway.
• Gli operatori possono chiamare skills.status (operator.read) per recuperare l'inventario visibile delle skill per un agente.
  • agentId è facoltativo; omettilo per leggere il workspace agente predefinito.
  • La risposta include idoneità, requisiti mancanti, controlli di configurazione e opzioni di installazione sanificate senza esporre valori segreti grezzi.
• Gli operatori possono chiamare skills.search e skills.detail (operator.read) per i metadati di discovery di ClawHub.
• Gli operatori possono chiamare skills.upload.begin, skills.upload.chunk e skills.upload.commit (operator.admin) per preparare un archivio di skill privata prima di installarlo. Questo è un percorso di caricamento admin separato per client attendibili, non il normale flusso di installazione skill di ClawHub, ed è disabilitato per impostazione predefinita a meno che skills.install.allowUploadedArchives non sia abilitato.
  • skills.upload.begin({ kind: "skill-archive", slug, sizeBytes, sha256?, force?, idempotencyKey? }) crea un caricamento associato a quello slug e a quel valore force.
  • skills.upload.chunk({ uploadId, offset, dataBase64 }) aggiunge byte all'offset decodificato esatto.
  • skills.upload.commit({ uploadId, sha256? }) verifica la dimensione finale e SHA-256. Il commit finalizza solo il caricamento; non installa la skill.
  • Gli archivi di skill caricati sono archivi zip contenenti una radice SKILL.md. Il nome della directory interna dell'archivio non seleziona mai la destinazione di installazione.
• Gli operatori possono chiamare skills.install (operator.admin) in tre modalità:
  • Modalità ClawHub: { source: "clawhub", slug, version?, force? } installa una cartella skill nella directory skills/ del workspace agente predefinito.
  • Modalità upload: { source: "upload", uploadId, slug, force?, sha256?, timeoutMs? } installa un caricamento confermato nella directory skills/<slug> del workspace agente predefinito. Lo slug e il valore force devono corrispondere alla richiesta originale skills.upload.begin. Questa modalità viene rifiutata a meno che skills.install.allowUploadedArchives non sia abilitato. L'impostazione non influisce sulle installazioni ClawHub.
  • Modalità installer Gateway: { name, installId, timeoutMs? } esegue un'azione metadata.openclaw.install dichiarata sull'host gateway. I client meno recenti possono ancora inviare dangerouslyForceUnsafeInstall; questo campo è deprecato, accettato solo per compatibilità di protocollo e ignorato. Usa security.installPolicy per decisioni di installazione gestite dall'operatore.
• Gli operatori possono chiamare skills.update (operator.admin) in due modalità:
  • La modalità ClawHub aggiorna uno slug tracciato o tutte le installazioni ClawHub tracciate nel workspace agente predefinito.
  • La modalità config corregge valori skills.entries.<skillKey> come enabled, apiKey ed env.

Viste di models.list

models.list accetta un parametro view facoltativo:

• Omesso o "default": comportamento runtime corrente. Se agents.defaults.models è configurato, la risposta è il catalogo consentito, inclusi i modelli rilevati dinamicamente per le voci provider/*. Altrimenti la risposta è il catalogo Gateway completo.
• "configured": comportamento di dimensione adatta a un selettore. Se agents.defaults.models è configurato, ha comunque la precedenza, inclusa la discovery con ambito provider per le voci provider/*. Senza una allowlist, la risposta usa voci esplicite models.providers.*.models, ripiegando sul catalogo completo solo quando non esistono righe di modello configurate.
• "all": catalogo Gateway completo, bypassando agents.defaults.models. Usalo per diagnostica e UI di discovery, non per i normali selettori di modello.

Approvazioni exec

• Quando una richiesta exec richiede approvazione, il gateway trasmette exec.approval.requested.
• I client operatore risolvono chiamando exec.approval.resolve (richiede l'ambito operator.approvals).
• Per host=node, exec.approval.request deve includere systemRunPlan (argv/cwd/rawCommand/metadati sessione canonici). Le richieste prive di systemRunPlan vengono rifiutate.
• Dopo l'approvazione, le chiamate inoltrate node.invoke system.run riutilizzano quel systemRunPlan canonico come contesto autorevole di comando/cwd/sessione.
• Se un chiamante modifica command, rawCommand, cwd, agentId o sessionKey tra la preparazione e l'inoltro finale approvato di system.run, il gateway rifiuta l'esecuzione invece di fidarsi del payload modificato.

Fallback di recapito agente

• Le richieste agent possono includere deliver=true per richiedere il recapito in uscita.
• bestEffortDeliver=false mantiene il comportamento rigoroso: destinazioni di recapito non risolte o solo interne restituiscono INVALID_REQUEST.
• bestEffortDeliver=true consente il fallback all'esecuzione solo sessione quando non è possibile risolvere una rotta recapitabile esterna (per esempio sessioni interne/webchat o configurazioni multi-canale ambigue).
• I risultati finali agent possono includere result.deliveryStatus quando è stato richiesto il recapito, usando gli stessi stati sent, suppressed, partial_failed e failed documentati per openclaw agent --json --deliver.

Versioning

• PROTOCOL_VERSION si trova in packages/gateway-protocol/src/version.ts.
• I client inviano minProtocol + maxProtocol; il server rifiuta intervalli che non includono il suo protocollo corrente. Client e server correnti richiedono il protocollo v4.
• Schemi e modelli vengono generati dalle definizioni TypeBox:
  • pnpm protocol:gen
  • pnpm protocol:gen:swift
  • pnpm protocol:check

Costanti client

Il client di riferimento in src/gateway/client.ts usa questi valori predefiniti. I valori sono stabili nel protocollo v4 e sono la baseline prevista per client di terze parti.

Il server pubblicizza i valori effettivi policy.tickIntervalMs, policy.maxPayload e policy.maxBufferedBytes in hello-ok; i client dovrebbero rispettare tali valori invece dei predefiniti pre-handshake.

Auth

• L'autenticazione del Gateway con segreto condiviso usa connect.params.auth.token o connect.params.auth.password, a seconda della modalità di autenticazione configurata.
• Le modalità che trasportano identità, come Tailscale Serve (gateway.auth.allowTailscale: true) o non-local loopback gateway.auth.mode: "trusted-proxy" soddisfano il controllo di autenticazione della connessione dagli header della richiesta invece che da connect.params.auth.*.
• La modalità gateway.auth.mode: "none" con ingresso privato salta interamente l'autenticazione della connessione con segreto condiviso; non esporre tale modalità su ingressi pubblici/non attendibili.
• Dopo l'associazione, il Gateway emette un token dispositivo limitato al ruolo della connessione + ambiti. Viene restituito in hello-ok.auth.deviceToken e deve essere conservato dal client per connessioni future.
• I client devono conservare il hello-ok.auth.deviceToken primario dopo ogni connessione riuscita.
• La riconnessione con quel token dispositivo memorizzato deve anche riutilizzare l'insieme degli ambiti approvati memorizzato per quel token. Questo preserva l'accesso in lettura/probe/stato già concesso ed evita di restringere silenziosamente le riconnessioni a un ambito implicito più stretto di sola amministrazione.
• Assemblaggio dell'autenticazione di connessione lato client (selectConnectAuth in src/gateway/client.ts):
  • auth.password è ortogonale e viene sempre inoltrato quando impostato.
  • auth.token viene popolato in ordine di priorità: prima il token condiviso esplicito, poi un deviceToken esplicito, quindi un token per dispositivo memorizzato (indicizzato da deviceId + role).
  • auth.bootstrapToken viene inviato solo quando nessuno dei precedenti ha risolto un auth.token. Un token condiviso o qualsiasi token dispositivo risolto lo sopprime.
  • La promozione automatica di un token dispositivo memorizzato nel retry una tantum AUTH_TOKEN_MISMATCH è limitata ai soli endpoint attendibili: loopback, oppure wss:// con tlsFingerprint fissato. wss:// pubblico senza pinning non è idoneo.
• Il bootstrap con codice di configurazione integrato restituisce il hello-ok.auth.deviceToken del nodo primario più un token operatore limitato in hello-ok.auth.deviceTokens per il passaggio mobile attendibile. Il token operatore include operator.talk.secrets per le letture della configurazione Talk nativa, ma esclude gli ambiti di mutazione dell'associazione e operator.admin.
• Mentre un bootstrap con codice di configurazione non baseline attende l'approvazione, i dettagli di PAIRING_REQUIRED includono recommendedNextStep: "wait_then_retry", retryable: true, e pauseReconnect: false. I client devono continuare a riconnettersi con lo stesso token di bootstrap finché la richiesta non viene approvata o il token diventa non valido.
• Conserva hello-ok.auth.deviceTokens solo quando la connessione ha usato l'autenticazione bootstrap su un trasporto attendibile come wss:// o associazione loopback/locale.
• Se un client fornisce un deviceToken esplicito o scopes espliciti, quell'insieme di ambiti richiesto dal chiamante resta autorevole; gli ambiti nella cache vengono riutilizzati solo quando il client riusa il token per dispositivo memorizzato.
• I token dispositivo possono essere ruotati/revocati tramite device.token.rotate e device.token.revoke (richiede l'ambito operator.pairing). Ruotare o revocare un nodo o un altro ruolo non operatore richiede anche operator.admin.
• device.token.rotate restituisce metadati di rotazione. Restituisce in eco il token bearer sostitutivo solo per chiamate dallo stesso dispositivo già autenticate con quel token dispositivo, così i client solo-token possono conservarne il sostituto prima di riconnettersi. Le rotazioni condivise/admin non restituiscono in eco il token bearer.
• Emissione, rotazione e revoca dei token restano limitate all'insieme di ruoli approvati registrato nella voce di associazione di quel dispositivo; la mutazione dei token non può espandere o prendere di mira un ruolo dispositivo che l'approvazione dell'associazione non ha mai concesso.
• Per le sessioni con token di dispositivo associato, la gestione del dispositivo è auto-limitata salvo che il chiamante abbia anche operator.admin: i chiamanti non admin possono gestire solo il token operatore per la voce del proprio dispositivo. La gestione dei token di nodi e altri non operatori è solo admin, anche per il dispositivo del chiamante.
• device.token.rotate e device.token.revoke controllano anche l'insieme degli ambiti del token operatore di destinazione rispetto agli ambiti della sessione corrente del chiamante. I chiamanti non admin non possono ruotare o revocare un token operatore più ampio di quello che già possiedono.
• Gli errori di autenticazione includono error.details.code più suggerimenti di recupero:
  • error.details.canRetryWithDeviceToken (booleano)
  • error.details.recommendedNextStep (retry_with_device_token, update_auth_configuration, update_auth_credentials, wait_then_retry, review_auth_configuration)
• Comportamento del client per AUTH_TOKEN_MISMATCH:
  • I client attendibili possono tentare un retry limitato con un token per dispositivo nella cache.
  • Se quel retry fallisce, i client devono interrompere i cicli di riconnessione automatica e mostrare indicazioni per l'intervento dell'operatore.
• AUTH_SCOPE_MISMATCH significa che il token dispositivo è stato riconosciuto ma non copre il ruolo/gli ambiti richiesti. I client non devono presentarlo come token errato; chiedi all'operatore di associare di nuovo o approvare il contratto di ambito più stretto/più ampio.

Identità dispositivo + associazione

• I nodi devono includere un'identità dispositivo stabile (device.id) derivata da una fingerprint della coppia di chiavi.
• I Gateway emettono token per dispositivo + ruolo.
• Le approvazioni di associazione sono richieste per nuovi ID dispositivo salvo che l'approvazione automatica locale sia abilitata.
• L'approvazione automatica dell'associazione è centrata sulle connessioni dirette local loopback.
• OpenClaw ha anche un percorso stretto di autoconnessione backend/container-locale per flussi helper attendibili con segreto condiviso.
• Le connessioni tailnet o LAN sullo stesso host sono comunque trattate come remote per l'associazione e richiedono approvazione.
• I client WS normalmente includono l'identità device durante connect (operatore + nodo). Le uniche eccezioni operatore senza dispositivo sono percorsi di fiducia espliciti:
  • gateway.controlUi.allowInsecureAuth=true per compatibilità HTTP non sicura solo localhost.
  • autenticazione Control UI operatore riuscita con gateway.auth.mode: "trusted-proxy".
  • gateway.controlUi.dangerouslyDisableDeviceAuth=true (break-glass, grave riduzione della sicurezza).
  • RPC backend gateway-client su direct-loopback nel percorso helper interno riservato.
• Omettere l'identità dispositivo ha conseguenze sugli ambiti. Quando una connessione operatore senza dispositivo è consentita tramite un percorso di fiducia esplicito, OpenClaw cancella comunque gli ambiti autodichiarati impostandoli a un insieme vuoto, salvo che quel percorso abbia un'eccezione denominata di preservazione degli ambiti. I metodi protetti da ambito falliscono quindi con missing scope.
• gateway.controlUi.dangerouslyDisableDeviceAuth=true è un percorso di preservazione degli ambiti break-glass della Control UI. Non concede ambiti a client WebSocket backend personalizzati arbitrari o con forma CLI.
• Il percorso helper backend gateway-client direct-loopback riservato preserva gli ambiti solo per RPC interne del piano di controllo locale; gli ID backend personalizzati non ricevono questa eccezione.
• Tutte le connessioni devono firmare il nonce connect.challenge fornito dal server.

Diagnostica della migrazione dell'autenticazione dispositivo

Per i client legacy che usano ancora il comportamento di firma pre-challenge, connect ora restituisce codici di dettaglio DEVICE_AUTH_* sotto error.details.code con un error.details.reason stabile.

Errori di migrazione comuni:

Obiettivo della migrazione:

• Attendi sempre connect.challenge.
• Firma il payload v2 che include il nonce del server.
• Invia lo stesso nonce in connect.params.device.nonce.
• Il payload di firma preferito è v3, che vincola platform e deviceFamily oltre ai campi device/client/role/scopes/token/nonce.
• Le firme legacy v2 restano accettate per compatibilità, ma il pinning dei metadati dei dispositivi associati controlla comunque la policy dei comandi alla riconnessione.

TLS + pinning

• TLS è supportato per le connessioni WS.
• I client possono facoltativamente fissare la fingerprint del certificato del gateway (vedi configurazione gateway.tls più gateway.remote.tlsFingerprint o CLI --tls-fingerprint).

Ambito

Questo protocollo espone la API gateway completa (stato, canali, modelli, chat, agente, sessioni, nodi, approvazioni, ecc.). La superficie esatta è definita dagli schemi TypeBox in packages/gateway-protocol/src/schema.ts.

Correlati

• Protocollo bridge
• Runbook Gateway