Protocollo del Gateway

Il protocollo WS del Gateway è l'unico piano di controllo e trasporto dei nodi per OpenClaw. I client operatore e nodo (CLI, interfaccia web, app macOS, nodi iOS/Android, nodi headless) si connettono tramite WebSocket e dichiarano un ruolo e un ambito al momento dell'handshake.

Trasporto e framing

• WebSocket, frame di testo, payload JSON.
• Il primo frame deve essere una richiesta connect.
• I frame precedenti alla connessione sono limitati a 64 KiB (MAX_PREAUTH_PAYLOAD_BYTES). Dopo l'handshake, vengono applicati hello-ok.policy.maxPayload e hello-ok.policy.maxBufferedBytes. Con la diagnostica abilitata, i frame in ingresso sovradimensionati e i buffer in uscita lenti emettono eventi payload.large prima che il Gateway chiuda la connessione o scarti il frame. Questi eventi includono surface, dimensioni in byte, limiti e un codice motivo sicuro, mai corpi dei messaggi, contenuti degli allegati, byte grezzi dei frame, token, cookie o segreti.

Formati dei frame:

• 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 (vedere lo schema).

Handshake

Il Gateway invia una richiesta di verifica precedente alla connessione:

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

Il client risponde con 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": "…"    }  }}

Il Gateway risponde con 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 e auth sono tutti richiesti da HelloOkSchema (packages/gateway-protocol/src/schema/frames.ts). auth riporta il ruolo e gli ambiti negoziati anche quando non viene emesso alcun token del dispositivo (formato illustrato sopra). pluginSurfaceUrls è facoltativo e associa i nomi delle superfici dei Plugin (ad esempio canvas) a URL ospitati con ambito; può scadere, quindi i nodi chiamano node.pluginSurface.refresh con { "surface": "canvas" } per ottenere una nuova voce. Il percorso deprecato canvasHostUrl / canvasCapability / node.canvas.capability.refresh non è supportato; utilizzare le superfici dei Plugin. Il campo facoltativo appliedConfigHash dello snapshot è la revisione risolta della configurazione sorgente accettata dal runtime Gateway attivo. I client possono confrontarla con config.get.configRevisionHash per determinare se una configurazione salvata più recente richieda ancora un riavvio. config.get.hash rimane la revisione non elaborata del file radice utilizzata dalle protezioni contro i conflitti di scrittura della configurazione.

Mentre il Gateway sta ancora completando l'avvio dei processi ausiliari, connect può restituire un errore ripetibile UNAVAILABLE con details.reason: "startup-sidecars" e retryAfterMs. Riprovare entro il budget temporale della connessione anziché considerarlo un errore terminale dell'handshake.

Quando viene emesso un token del dispositivo, hello-ok.auth lo aggiunge:

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

Il bootstrap integrato tramite codice QR/codice di configurazione è un percorso di passaggio ai dispositivi mobili. Una connessione di base riuscita mediante codice di configurazione restituisce un token del nodo principale e un token operatore con ambito limitato:

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

Questo passaggio all'operatore è intenzionalmente limitato: è sufficiente per avviare il ciclo dell'operatore mobile e la configurazione nativa, incluso operator.talk.secrets per le letture della configurazione Talk, ma non include ambiti per modificare l'associazione né operator.admin. Un accesso più ampio all'associazione/amministrazione richiede un flusso separato di associazione approvata o di token. Rendere persistente hello-ok.auth.deviceTokens solo quando l'autenticazione bootstrap è stata eseguita tramite un trasporto attendibile (wss:// o associazione loopback/locale).

I client backend attendibili nello stesso processo (client.id: "gateway-client", client.mode: "backend") possono omettere device nelle connessioni loopback dirette quando si autenticano con il token/la password condivisi del Gateway. Questo percorso è riservato alle RPC interne del piano di controllo (ad esempio gli aggiornamenti delle sessioni dei sottoagenti) ed evita che le baseline obsolete di associazione CLI/dispositivo blocchino il lavoro del backend locale. I client remoti, con origine nel browser, nodo e quelli che usano esplicitamente token del dispositivo/identità del dispositivo continuano a essere sottoposti ai normali controlli di associazione e aggiornamento degli ambiti.

Ruolo worker e protocollo chiuso

I worker cloud utilizzano un ingresso loopback dedicato tramite il tunnel SSH di proprietà del Gateway con chiave host fissata. Accetta solo l'identità del worker e non inoltra mai autenticazione generale, eventi dei nodi, RPC degli operatori o metodi dei Plugin. Un rigoroso connect verifica una credenziale di breve durata, memorizzata sotto forma di hash e vincolata all'ambiente, all'hash del bundle, all'epoca del proprietario, alla versione dell'insieme RPC, alla scadenza e a un'unica sessione nullable; inoltre verifica separatamente la versione corrente e l'insieme di funzionalità. In caso di successo restituisce un worker-hello-ok minimo; la negoziazione delle funzionalità è indipendente dalla versione generale del protocollo. I frame rimangono al di sotto di 64 KiB, tranne un frame worker.inference.start negoziato che può raggiungere 25 MiB. L'elenco consentito chiuso contiene worker.heartbeat, worker.transcript.commit, worker.live-event, worker.inference.start e worker.inference.cancel.

I commit delle trascrizioni utilizzano il fencing dell'epoca del proprietario, un'associazione della sessione di proprietà del Gateway, un compare-and-swap della foglia di base e la riproduzione durevole della sequenza; il Gateway genera gli ID delle voci e dei genitori della trascrizione tramite il normale writer di sessione. La proprietà e la scadenza vengono verificate nuovamente a ogni RPC.

Funzionalità dei client

I client operatore possono dichiarare funzionalità facoltative in connect.params.caps:

• tool-events: accetta eventi strutturati del ciclo di vita degli strumenti.
• inline-widgets: può visualizzare i risultati degli strumenti dei widget inline ospitati.

Le funzionalità del client descrivono il client connesso, non l'autorizzazione. Gli strumenti degli agenti possono dichiarare le funzionalità richieste; il Gateway omette tali strumenti a meno che ogni requisito non sia presente in caps del client di origine. Le esecuzioni originate dai canali non hanno funzionalità del client Gateway, quindi gli strumenti vincolati alle funzionalità non sono disponibili anche quando la policy degli strumenti li consente esplicitamente.

Esempio di connessione di un nodo

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

I nodi dichiarano le attestazioni delle funzionalità al momento della connessione:

• caps: categorie di alto livello come camera, canvas, screen, location, voice, talk.
• commands: elenco consentito dei comandi per l'invocazione.
• permissions: opzioni granulari (ad esempio screen.record, camera.capture).

Il Gateway le considera attestazioni e applica elenchi consentiti lato server.

Ruoli e ambiti

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

Ruoli:

• operator: client del piano di controllo (CLI/interfaccia utente/automazione).
• node: host delle funzionalità (camera/schermo/canvas/system.run).
• worker: host di esecuzione cloud sul protocollo worker dedicato e chiuso.

Ambiti dell'operatore (src/gateway/operator-scopes.ts), l'insieme chiuso completo:

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

talk.config con includeSecrets: true richiede operator.talk.secrets (oppure operator.admin). Quando sono inclusi i segreti, leggere la credenziale attiva del provider Talk da talk.resolved.config.apiKey; talk.providers.<id>.apiKey mantiene il formato della sorgente e può essere un oggetto SecretRef oppure una stringa oscurata.

I metodi RPC del Gateway registrati dai Plugin possono richiedere un proprio ambito operatore, ma questi prefissi riservati del core vengono sempre risolti in operator.admin (src/shared/gateway-method-policy.ts): config.*, exec.approvals.*, wizard.*, update.*.

L'ambito del metodo è solo il primo controllo. Alcuni comandi slash raggiunti tramite chat.send applicano controlli più rigorosi a livello di comando: le scritture persistenti /config set e /config unset richiedono operator.admin anche per i client del Gateway che dispongono già di un ambito operatore inferiore.

node.pair.approve prevede un ulteriore controllo dell'ambito al momento dell'approvazione, oltre all'ambito di base del metodo (operator.pairing), in funzione del valore commands dichiarato dalla richiesta in sospeso (src/infra/node-pairing-authz.ts):

Funzionalità/comandi/autorizzazioni (nodo)

I nodi dichiarano le attestazioni delle funzionalità al momento della connessione:

• caps: categorie di funzionalità di alto livello come camera, canvas, screen, location, voice e talk.
• commands: elenco consentito dei comandi per l'invocazione.
• permissions: opzioni granulari (ad esempio screen.record, camera.capture).

Il Gateway tratta questi elementi come dichiarazioni e applica allowlist lato server. I nodi connessi possono pubblicare descrittori facoltativi, visibili all'agente, di Plugin o strumenti MCP con node.pluginTools.update dopo una connessione o riconnessione riuscita. Gli host dei nodi headless vengono riavviati per applicare le modifiche dichiarative all'inventario MCP. Questo metodo di aggiornamento è l'unico percorso di pubblicazione; i descrittori degli strumenti dei Plugin non sono accettati nei parametri connect. Ogni descrittore deve usare un name dello strumento sicuro per il provider e indicare un command presente nell'allowlist dei comandi corrente del nodo. Il Gateway considera attendibili i metadati dei descrittori provenienti dal nodo associato, filtra i descrittori esterni alla superficie dei comandi approvata, li rimuove quando il nodo si disconnette e rifiuta i tentativi dell'operatore di modificare il catalogo di un altro nodo. Impostare gateway.nodes.pluginTools.enabled: false per ignorare i descrittori pubblicati dai nodi.

Gli host dei nodi connessi pubblicano il proprio catalogo completo di sostituzione delle skill con node.skills.update. Questo metodo del ruolo nodo è l'unico percorso di pubblicazione delle skill del nodo; le skill non sono accettate nei parametri connect. Ogni descrittore contiene un nome sicuro, una descrizione e contenuto SKILL.md limitato. Il Gateway analizza tale contenuto con il normale caricatore delle skill, lo include nelle istantanee delle skill dell'agente mentre il nodo è connesso e lo rimuove alla disconnessione. Impostare gateway.nodes.skills.enabled: false per ignorare le skill pubblicate dai nodi.

Presenza

• system-presence restituisce voci indicizzate per identità del dispositivo, inclusi deviceId, roles e scopes, affinché le UI possano mostrare una riga per dispositivo anche quando si connette sia come operatore sia come nodo.
• node.list include lastSeenAtMs e lastSeenReason facoltativi. I nodi connessi segnalano l'ora della connessione corrente con il motivo connect; i nodi associati possono inoltre segnalare una presenza persistente in background tramite un evento attendibile del nodo.

I nodi macOS nativi possono inoltre inviare eventi node.presence.activity autenticati con un tempo di inattività dell'input limitato. Il Gateway ricava i timestamp dell'attività usando il proprio orologio, espone il Mac connesso più recente tramite node.list e node.describe e trasmette gli aggiornamenti node.presence ai client con ambito di lettura. Consultare Presenza del computer attivo per il comportamento relativo a selezione, privacy, contesto del modello e instradamento delle notifiche.

Evento di attività in background del nodo

I nodi chiamano node.event con event: "node.presence.alive" per registrare che un nodo associato era attivo durante una riattivazione 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'enumerazione chiusa: background, silent_push, bg_app_refresh, significant_location, manual, connect. I valori sconosciuti vengono normalizzati in background (src/shared/node-presence.ts). L'evento viene reso persistente solo per sessioni autenticate di dispositivi nodo; le sessioni senza dispositivo o non associate restituiscono handled: false.

I Gateway che completano correttamente l'operazione restituiscono un risultato strutturato:

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

I Gateway meno recenti possono restituire solo { "ok": true } per node.event; considerarlo un RPC confermato, non una persistenza durevole della presenza.

Definizione dell'ambito degli eventi broadcast

Gli eventi broadcast inviati dal server sono vincolati all'ambito, affinché le sessioni limitate all'associazione o riservate ai nodi non ricevano passivamente il contenuto delle sessioni (src/gateway/server-broadcast.ts):

• I frame di chat, agente e risultati degli strumenti (eventi agent trasmessi in streaming, eventi dei risultati degli strumenti) richiedono almeno operator.read. Le sessioni che ne sono prive ignorano completamente questi frame.
• I broadcast plugin.* definiti dai Plugin sono limitati per impostazione predefinita a operator.write o operator.admin; le voci esplicite come plugin.approval.requested / plugin.approval.resolved usano invece operator.approvals.
• Gli eventi di stato/trasporto (heartbeat, presence, tick, ciclo di vita di connessione/disconnessione) rimangono senza restrizioni, affinché l'integrità del trasporto sia osservabile da ogni sessione autenticata.
• Le famiglie sconosciute di eventi broadcast sono vincolate all'ambito per impostazione predefinita (chiusura in caso di errore), salvo che un gestore registrato non le renda esplicitamente meno restrittive.

Ogni connessione client mantiene il proprio numero di sequenza per client, quindi i broadcast rimangono ordinati in modo monotono su quel socket anche quando client diversi vedono sottoinsiemi differenti del flusso di eventi filtrati per ambito.

Famiglie di metodi RPC

hello-ok.features.methods è un elenco di rilevamento prudenziale costruito da src/gateway/server-methods-list.ts più le esportazioni dei metodi dei Plugin/canali caricati: non è un dump generato di ogni metodo e alcuni metodi (ad esempio push.test, web.login.start, web.login.wait, sessions.usage) sono intenzionalmente esclusi dal rilevamento, sebbene siano metodi reali e richiamabili. Va considerato come rilevamento delle funzionalità, non come enumerazione completa di src/gateway/server-methods/*.ts.

Famiglie di eventi comuni

• chat: aggiornamenti della chat dell'interfaccia utente, come chat.inject, e altri eventi di chat limitati alla trascrizione. Nel protocollo v4, i payload delta includono deltaText; message rimane l'istantanea cumulativa dell'assistente. Le sostituzioni che non sono prefissi impostano replace=true e utilizzano deltaText come testo sostitutivo.
• session.message, session.operation, session.tool: aggiornamenti della trascrizione, delle operazioni di sessione in corso e del flusso di eventi per una sessione sottoscritta.
• session.approval: stato effettivo sanificato delle approvazioni in sospeso e terminali per un sottoscrittore di sessione esatta che ha aderito esplicitamente. Le approvazioni figlie utilizzano il pubblico dell'antenato persistito; gli eventi non modificano mai le trascrizioni né riattivano gli agenti.
• sessions.changed: indice o metadati della sessione modificati.
• presence: aggiornamenti dell'istantanea della presenza di sistema.
• tick: evento periodico di keepalive/verifica dell'attività.
• health: aggiornamento dell'istantanea dello stato del Gateway.
• heartbeat: aggiornamento del flusso di eventi Heartbeat.
• cron: evento di modifica di un'esecuzione/processo Cron.
• shutdown: notifica di arresto del Gateway.
• node.pair.requested / node.pair.resolved: ciclo di vita dell'associazione dei Node.
• node.invoke.request: trasmissione della richiesta di invocazione del Node.
• device.pair.requested / device.pair.resolved: ciclo di vita dei dispositivi associati.
• voicewake.changed: configurazione dell'attivazione tramite parola chiave modificata.
• exec.approval.requested / exec.approval.resolved: ciclo di vita dell'approvazione dell'esecuzione.
• plugin.approval.requested / plugin.approval.resolved: ciclo di vita dell'approvazione dei Plugin.

Metodi ausiliari dei Node

I Node possono chiamare skills.bins per recuperare l'elenco corrente degli eseguibili delle Skills per i controlli di autorizzazione automatica.

RPC del registro di audit

audit.activity.list offre ai client degli operatori una vista stabile, dal più recente al meno recente, dei metadati del ciclo di vita delle esecuzioni degli agenti, delle azioni degli strumenti e dei messaggi soggetti ad adesione esplicita. Richiede operator.read. Le query escludono i record più vecchi di 30 giorni e il registro SQLite condiviso è limitato a 100,000 record. Le righe scadute vengono eliminate durante l'avvio del Gateway, la manutenzione oraria e le scritture successive. Vedere Cronologia di audit per il modello dati e la semantica della privacy.

• Parametri: valori esatti facoltativi agentId, sessionKey o runId; valore facoltativo kind ("agent_run", "tool_action" o "message"); valore facoltativo status ("started", "succeeded", "failed", "cancelled", "timed_out", "blocked" o "unknown"); valore facoltativo del messaggio direction ("inbound" o "outbound") e valore esatto channel; limiti inclusivi facoltativi after / before in millisecondi Unix; valore facoltativo limit da 1 a 500; e stringa facoltativa cursor della pagina precedente.
• Risultato: { "events": AuditActivityEventV1[], "nextCursor"?: string }.

L'unione dei risultati V1 denominata dispone di schemi distinti per le esecuzioni degli agenti, le azioni degli strumenti, i messaggi in entrata e i messaggi in uscita. Il discriminatore eventType è rispettivamente agent_run, tool_action, inbound_message o outbound_message; kind e il valore direction del messaggio rimangono disponibili per il filtraggio e la visualizzazione. Ogni evento dispone di un valore intero schemaVersion: 1. I riferimenti all'identità del messaggio utilizzano il formato esatto hmac-sha256:v1:<32 hex key id>:<64 hex digest>; l'ID dell'attore mittente del canale utilizza lo stesso formato.

Tutte le varianti richiedono eventType, schemaVersion, eventId, sequence, sourceSequence, occurredAt, kind, action, status, actor e redaction. I campi delle varianti sono:

Le enumerazioni chiuse dei messaggi sono:

• conversationKind: direct, group, channel o unknown.
• outcome in entrata: completed, skipped o failed; valore facoltativo 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 o acp_dispatch_aborted.
• outcome in uscita: sent, suppressed, failed o unknown; valore facoltativo reasonCode: cancelled_by_message_sending_hook, cancelled_by_reply_payload_sending_hook, empty_after_message_sending_hook, empty_after_reply_payload_sending_hook o no_visible_payload. Un adattatore che non restituisce alcuna identità della piattaforma è unknown, poiché l'effetto collaterale esterno non può essere escluso.
• deliveryKind: text, media o other; failureStage: platform_send, queue o unknown.

I campi terminali sono correlati, non facoltativi in modo indipendente:

Ogni evento di attività include un id evento stabile, una sequenza monotona del registro, una sequenza dell'evento di origine, un timestamp, un attore, un'azione, uno stato, un valore intero schemaVersion: 1 e redaction: "metadata_only". I record di esecuzione e degli strumenti richiedono la provenienza dell'agente e dell'esecuzione e possono includere la provenienza della sessione. I record dei messaggi possono includere gli id dell'agente e dell'esecuzione, ma intenzionalmente non includono mai sessionKey o sessionId; il filtro di query sessionKey si applica pertanto solo alle righe delle esecuzioni e degli strumenti. Gli eventi degli strumenti possono includere l'id della chiamata dello strumento e il nome dello strumento.

I record dei messaggi usano message.inbound.processed o message.outbound.finished e aggiungono direzione, canale, tipo di conversazione, esito normalizzato e, facoltativamente, tipo di consegna, fase dell'errore, durata, numero di risultati, codice del motivo e pseudonimi basati su chiave e locali all'installazione per account/conversazione/messaggio/destinazione. Questi pseudonimi agevolano la correlazione, ma non costituiscono anonimizzazione: il database di stato contiene la relativa chiave, mentre le esportazioni RPC e CLI non la contengono. Il registro non memorizza prompt, corpi dei messaggi, argomenti degli strumenti, risultati degli strumenti, output dei comandi o testo grezzo degli errori. I valori sessionKey di esecuzioni/strumenti restano metadati grezzi di correlazione e possono incorporare id di account o peer della piattaforma; i record dei messaggi omettono le chiavi di sessione.

Per le righe in entrata, durationMs misura il dispatch del core fino al relativo stato terminale e resultCount conta i payload finalizzati di strumenti, blocchi e risposte in coda. Per le righe in uscita, durationMs copre la responsabilità della consegna fino alla conferma, alla dead letter o alla riconciliazione (incluso il tempo di attesa in coda), mentre resultCount conta gli invii fisici identificati sulla piattaforma. deliveryKind, quando presente, descrive il payload effettivo dopo gli hook e il rendering; le righe soppresse o ambigue a causa di un arresto anomalo lo omettono.

L'attuale copertura dei messaggi include i messaggi in entrata accettati che raggiungono il dispatch del core, inclusi gli esiti di duplicazione/terminali del core. La copertura in uscita scrive una riga terminale per ogni payload di risposta logico originale che raggiunge la consegna durevole condivisa; la suddivisione in blocchi e il fan-out dell'adattatore sono aggregati in resultCount. Gli invii in coda ritentabili o ambigui vengono registrati solo dopo la conferma, la dead letter o la riconciliazione. I percorsi locali ai Plugin e di invio diretto che eludono tali confini condivisi non sono ancora coperti. La coda limitata del worker opera secondo il principio del massimo sforzo e può perdere record in caso di errore o saturazione, pertanto questa superficie non è un archivio di conformità senza perdite.

La registrazione è attiva per impostazione predefinita ed è controllata da audit.enabled. La registrazione dei messaggi è controllata separatamente da audit.messages e il valore predefinito è "off". Quando la registrazione è disabilitata, audit.activity.list continua a fornire i record scritti in precedenza fino alla loro scadenza.

Gli schemi distribuiti di richiesta, risultato e AuditEvent di audit.list restano invariati e restituiscono solo record delle esecuzioni dell'agente e delle azioni degli strumenti. I nuovi client operatore devono chiamare audit.activity.list quando il Gateway ne segnala la disponibilità. I Gateway meno recenti possono restituire unknown method: audit.activity.list oppure, poiché nelle versioni distribuite l'autorizzazione precedeva la ricerca del metodo, missing scope: operator.admin a una richiesta con ambito di lettura. Quest'ultimo va considerato come assenza del metodo solo quando il metodo non era segnalato. Un client può quindi ritentare audit.list solo quando i suoi filtri non richiedono il supporto per tipo di messaggio, direzione o canale.

Usare openclaw audit per query testuali ed esportazioni JSON limitate.

RPC del registro delle attività

I client operatore esaminano e annullano i record delle attività in background del Gateway tramite gli RPC del registro delle attività (packages/gateway-protocol/src/schema/tasks.ts). Questi restituiscono riepiloghi sanificati delle attività, non lo stato grezzo del runtime.

• tasks.list richiede operator.read.
  • Parametri: status facoltativo ("queued", "running", "completed", "failed", "cancelled" o "timed_out") oppure un array di tali stati, agentId facoltativo, sessionKey facoltativo, limit facoltativo da 1 a 500 e la stringa facoltativa cursor.
  • Risultato: { "tasks": TaskSummary[], "nextCursor"?: string }.
• tasks.get richiede operator.read.
  • Parametri: { "taskId": string }.
  • Risultato: { "task": TaskSummary }.
  • Gli id attività mancanti restituiscono il formato dell'errore «non trovato» 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 facoltativi: kind, runtime, title, agentId, sessionKey, childSessionKey, ownerKey, runId, taskId, flowId, parentTaskId, sourceId, timestamp, avanzamento, riepilogo terminale e testo sanificato dell'errore. agentId identifica l'agente che esegue l'attività; sessionKey e ownerKey conservano il contesto del richiedente e di controllo.

Metodi di supporto per gli operatori

• commands.list (operator.read) recupera l'inventario dei comandi del runtime per un agente.
  • agentId è facoltativo; ometterlo per leggere lo spazio di lavoro dell'agente predefinito.
  • scope controlla a quale superficie è destinato il valore primario name: text restituisce il token primario del comando testuale senza il carattere iniziale /; native e il percorso predefinito both restituiscono nomi nativi che tengono conto del provider, quando disponibili.
  • textAliases contiene alias slash esatti come /model e /m.
  • nativeName contiene il nome del comando nativo che tiene conto del provider, quando esiste.
  • provider è facoltativo e influisce solo sulla denominazione nativa e sulla disponibilità dei comandi nativi dei Plugin.
  • includeArgs=false omette dalla risposta i metadati serializzati degli argomenti.
• tools.catalog (operator.read) recupera il catalogo degli strumenti del runtime per un agente. La risposta include strumenti raggruppati e metadati sulla provenienza:
  • source: core o plugin
  • pluginId: Plugin proprietario quando source="plugin"
  • optional: indica se uno strumento del Plugin è facoltativo
• tools.effective (operator.read) recupera l'inventario degli strumenti effettivo nel runtime per una sessione.
  • sessionKey è obbligatorio.
  • Il Gateway deriva il contesto attendibile del runtime dalla sessione lato server anziché accettare dal chiamante un contesto di autenticazione o consegna.
  • La risposta è una proiezione derivata dal server e circoscritta alla sessione dell'inventario attivo, inclusi gli strumenti del core, dei Plugin, dei canali e dei server MCP già individuati.
  • tools.effective è di sola lettura per MCP: può proiettare un catalogo MCP di una sessione attiva attraverso la policy finale degli strumenti, ma non crea runtime MCP, non connette trasporti e non emette tools/list. Se non esiste un catalogo attivo 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".
• tools.invoke (operator.write) richiama 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 risolto deve corrispondere a agentId.
  • I wrapper del core riservati al proprietario, come cron, gateway e nodes, richiedono un'identità del proprietario/amministratore (operator.admin), anche se tools.invoke è operator.write.
  • La risposta è un envelope destinato all'SDK con ok, toolName, il valore facoltativo output e i campi tipizzati error. I rifiuti dovuti all'approvazione o alla policy restituiscono ok:false nel payload anziché eludere la pipeline delle policy degli strumenti del Gateway.
• skills.status (operator.read) recupera l'inventario delle skill visibili per un agente.
  • agentId è facoltativo; ometterlo per leggere lo spazio di lavoro dell'agente predefinito.
  • La risposta include idoneità, requisiti mancanti, verifiche della configurazione e opzioni di installazione sanificate senza esporre valori segreti grezzi.
• skills.search e skills.detail (operator.read) restituiscono i metadati di individuazione di ClawHub.
• skills.upload.begin, skills.upload.chunk e skills.upload.commit (operator.admin) preparano un archivio privato di skill prima di installarlo. Questo è un percorso di caricamento amministrativo separato per client attendibili, non il normale flusso di installazione delle 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 tale slug e al 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 soltanto 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 dell'installazione.
• skills.install (operator.admin) dispone di tre modalità:
  • Modalità ClawHub: { source: "clawhub", slug, version?, force? } installa una cartella di skill nella directory skills/ dello spazio di lavoro dell'agente predefinito.
  • Modalità di caricamento: { source: "upload", uploadId, slug, force?, sha256?, timeoutMs? } installa un caricamento sottoposto a commit nella directory skills/<slug> dello spazio di lavoro dell'agente predefinito. Lo slug e il valore force devono corrispondere alla richiesta skills.upload.begin originale. La richiesta viene rifiutata a meno che skills.install.allowUploadedArchives non sia abilitato; l'impostazione non influisce sulle installazioni da ClawHub.
  • Modalità programma di installazione del Gateway: { name, installId, timeoutMs? } esegue un'azione metadata.openclaw.install dichiarata sull'host del Gateway. I client meno recenti possono continuare a inviare dangerouslyForceUnsafeInstall; questo campo è deprecato, accettato solo per compatibilità del protocollo e ignorato. Usare security.installPolicy per le decisioni di installazione di competenza dell'operatore.
• skills.update (operator.admin) dispone di due modalità:
  • La modalità ClawHub aggiorna uno slug monitorato o tutte le installazioni ClawHub monitorate nello spazio di lavoro dell'agente predefinito.
  • La modalità di configurazione modifica i valori skills.entries.<skillKey>, come enabled, apiKey e env.

Viste di models.list

models.list accetta un parametro facoltativo view (src/agents/model-catalog-visibility.ts):

• Omesso oppure "default": se agents.defaults.models è configurato, la risposta è il catalogo consentito, inclusi i modelli rilevati dinamicamente per le voci provider/*. Altrimenti, la risposta è il catalogo completo del gateway.
• "configured": comportamento adatto a un selettore. Se agents.defaults.models è configurato, continua ad avere la precedenza, incluso il rilevamento specifico del provider per le voci provider/*. Senza un elenco di elementi consentiti, la risposta usa le voci models.providers.<provider>.models esplicite, ricorrendo al catalogo completo solo quando non esistono righe di modelli configurate.
• "provider-config": inventario models.providers.*.models definito nell'origine, indipendente dagli elenchi consentiti del selettore. Le righe includono le funzionalità pubbliche dei modelli e la disponibilità in base alla route, ma omettono gli endpoint dei provider, il materiale di autenticazione e la configurazione delle richieste di runtime.
• "all": catalogo completo del gateway, ignorando agents.defaults.models. Da usare per le interfacce di diagnostica/rilevamento, non per i normali selettori di modelli.

Approvazioni di esecuzione

• Quando una richiesta di esecuzione necessita di approvazione, il gateway trasmette exec.approval.requested.
• I client dell'operatore risolvono la richiesta chiamando exec.approval.resolve (richiede operator.approvals).
• Per host=node, exec.approval.request deve includere systemRunPlan (metadati canonici di argv/cwd/rawCommand/sessione). Le richieste prive di systemRunPlan vengono rifiutate.
• Dopo l'approvazione, le chiamate node.invoke system.run inoltrate riutilizzano tale 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 anziché considerare attendibile il payload modificato.

Fallback per la consegna dell'agente

• Le richieste agent possono includere deliver=true per richiedere la consegna in uscita.
• bestEffortDeliver=false (valore predefinito) mantiene un comportamento rigoroso: le destinazioni di consegna non risolte o esclusivamente interne restituiscono INVALID_REQUEST.
• bestEffortDeliver=true consente il fallback all'esecuzione limitata alla sessione quando non è possibile risolvere alcuna route esterna utilizzabile per la consegna (ad esempio, sessioni interne/webchat o configurazioni multicanale ambigue).
• I risultati finali di agent possono includere result.deliveryStatus quando è stata richiesta la consegna, usando gli stessi stati sent, suppressed, partial_failed e failed documentati per openclaw agent --json --deliver.

Controllo delle versioni

• PROTOCOL_VERSION, MIN_CLIENT_PROTOCOL_VERSION, MIN_NODE_PROTOCOL_VERSION e MIN_PROBE_PROTOCOL_VERSION si trovano in packages/gateway-protocol/src/version.ts.
• I client inviano minProtocol + maxProtocol. I client operatore e dell'interfaccia utente devono includere il protocollo corrente in tale intervallo; i client e i server correnti usano il protocollo v4.
• I client autenticati con entrambi role: "node" e client.mode: "node" possono usare il protocollo Node N-1 (attualmente v3). Le sonde leggere di riavvio usano la stessa finestra N-1. L'autenticazione del dispositivo, l'associazione, gli ambiti, i criteri dei comandi e le approvazioni di esecuzione non sono modificati da questa finestra di compatibilità. Le funzionalità e i comandi Node di proprietà dei Plugin non sono resi disponibili finché il Node non viene aggiornato al protocollo corrente, perché le superfici che li ospitano non fanno parte del contratto N-1.
• Gli schemi e i modelli vengono generati dalle definizioni TypeBox:
  • pnpm protocol:gen
  • pnpm protocol:gen:swift
  • pnpm protocol:check

Costanti del client

L'implementazione client di riferimento si trova in packages/gateway-client/src/ (OpenClaw la racchiude tramite la sottile facciata src/gateway/client.ts). Questi valori predefiniti sono stabili nel protocollo v4 e costituiscono la base di riferimento prevista per i client di terze parti.

Il server comunica i valori effettivi di policy.tickIntervalMs, policy.maxPayload e policy.maxBufferedBytes in hello-ok; i client devono rispettare tali valori anziché i valori predefiniti precedenti all'handshake.

Il client di riferimento consente alle richieste finite di gestire la propria scadenza configurata quando ogni richiesta in sospeso ne ha una. Una richiesta expectFinal senza un valore finito di timeoutMs, qualsiasi richiesta con timeoutMs: null o una combinazione di richieste finite e senza limite mantiene attivo il watchdog del tick. Se gli eventi e le risposte in ingresso rimangono assenti oltre la soglia di timeout del tick, il client chiude il socket con il codice 4000, rifiuta ogni richiesta in sospeso e si riconnette. Non riesegue le richieste rifiutate dopo la riconnessione.

Autenticazione

• L'autenticazione del Gateway tramite segreto condiviso usa connect.params.auth.token oppure connect.params.auth.password, a seconda del valore configurato per gateway.auth.mode ("none" | "token" | "password" | "trusted-proxy").
• Le modalità che includono l'identità, come Tailscale Serve (gateway.auth.allowTailscale: true) o gateway.auth.mode: "trusted-proxy" non loopback, soddisfano il controllo di autenticazione della connessione tramite le intestazioni della richiesta anziché connect.params.auth.*.
• Il gateway.auth.mode: "none" con ingresso privato ignora completamente l'autenticazione della connessione tramite segreto condiviso; non esporre questa modalità su ingressi pubblici/non attendibili.
• Dopo l'associazione, il Gateway emette un token del dispositivo limitato al ruolo e agli ambiti della connessione, restituito in hello-ok.auth.deviceToken. I client devono conservarlo dopo ogni connessione riuscita.
• Quando ci si riconnette con il token del dispositivo memorizzato, deve essere riutilizzato anche l'insieme di ambiti approvato e memorizzato per tale token. Ciò mantiene l'accesso già concesso a lettura/verifica/stato ed evita che le riconnessioni vengano silenziosamente ridotte a un ambito implicito più ristretto riservato ai soli amministratori.
• Composizione dell'autenticazione della connessione lato client (selectConnectAuth in packages/gateway-client/src/client.ts):
  • auth.password è indipendente e viene sempre inoltrato quando impostato.
  • auth.token viene valorizzato in ordine di priorità: prima il token condiviso esplicito, poi un deviceToken esplicito, quindi un token memorizzato per dispositivo (indicizzato da deviceId + role).
  • auth.bootstrapToken viene inviato solo quando nessuna delle opzioni precedenti ha determinato auth.token. Un token condiviso o qualsiasi token del dispositivo determinato ne impedisce l'invio.
  • La promozione automatica di un token del dispositivo memorizzato nel singolo nuovo tentativo AUTH_TOKEN_MISMATCH è limitata ai soli endpoint attendibili: loopback oppure wss:// con un tlsFingerprint bloccato. Un wss:// pubblico senza pinning non è idoneo.
• Il bootstrap integrato tramite codice di configurazione restituisce il hello-ok.auth.deviceToken del Node primario e un token operatore limitato in hello-ok.auth.deviceTokens per il trasferimento attendibile a dispositivi mobili. Il token operatore include operator.talk.secrets per le letture della configurazione nativa di Talk, ma esclude gli ambiti di modifica dell'associazione e operator.admin.
• Mentre un bootstrap tramite codice di configurazione non di base attende l'approvazione, i dettagli di PAIRING_REQUIRED includono recommendedNextStep: "wait_then_retry", retryable: true e pauseReconnect: false. Continuare a riconnettersi con lo stesso token di bootstrap finché la richiesta non viene approvata o il token non diventa non valido.
• Conservare hello-ok.auth.deviceTokens solo quando la connessione ha usato l'autenticazione bootstrap su un trasporto attendibile, come wss://, oppure tramite associazione loopback/locale.
• Se un client fornisce un deviceToken esplicito o un scopes esplicito, tale insieme di ambiti richiesto dal chiamante rimane autorevole; gli ambiti memorizzati nella cache vengono riutilizzati solo quando il client riutilizza il token memorizzato per dispositivo.
• I token dei dispositivi possono essere ruotati/revocati tramite device.token.rotate e device.token.revoke (richiede operator.pairing). La rotazione o la revoca di un Node o di un altro ruolo non operatore richiede anche operator.admin.
• device.token.rotate restituisce i metadati di rotazione. Ripete il token bearer sostitutivo solo per le chiamate dello stesso dispositivo già autenticate con tale token del dispositivo, affinché i client che usano solo token possano conservarne il sostituto prima di riconnettersi. Le rotazioni condivise/amministrative non ripetono il token bearer.
• L'emissione, la rotazione e la revoca dei token restano limitate all'insieme di ruoli approvato e registrato nella voce di associazione del dispositivo; la modifica dei token non può ampliare né prendere di mira un ruolo del dispositivo mai concesso dall'approvazione dell'associazione.
• Per le sessioni con token di dispositivi associati, la gestione dei dispositivi è limitata al proprio dispositivo, salvo che il chiamante disponga anche di operator.admin: i chiamanti non amministratori possono gestire solo il token operatore della propria voce dispositivo. La gestione dei token di Node e di altri ruoli non operatore è riservata agli amministratori, anche per il dispositivo del chiamante.
• device.token.rotate e device.token.revoke verificano inoltre l'insieme di ambiti del token operatore di destinazione rispetto agli ambiti della sessione corrente del chiamante. I chiamanti non amministratori non possono ruotare o revocare un token operatore con ambiti più ampi di quelli già posseduti.
• Gli errori di autenticazione includono error.details.code e indicazioni per il ripristino:
  • error.details.canRetryWithDeviceToken (booleano)
  • error.details.recommendedNextStep: uno tra retry_with_device_token, update_auth_configuration, update_auth_credentials, wait_then_retry, review_auth_configuration (packages/gateway-protocol/src/connect-error-details.ts).
• Comportamento del client per AUTH_TOKEN_MISMATCH:
  • I client attendibili possono tentare una sola volta con un token memorizzato nella cache per dispositivo.
  • Se tale nuovo tentativo non riesce, interrompere i cicli di riconnessione automatica e mostrare le indicazioni sulle azioni richieste all'operatore.
• AUTH_SCOPE_MISMATCH indica che il token del dispositivo è stato riconosciuto, ma non copre il ruolo o gli ambiti richiesti. Non presentarlo come token errato; richiedere all'operatore di ripetere l'associazione o approvare il contratto di ambiti più ristretto/ampio.

Identità e associazione dei dispositivi

• I Node devono includere un'identità stabile del dispositivo (device.id) derivata dall'impronta digitale di una coppia di chiavi.
• I Gateway emettono token per dispositivo e ruolo.
• Le approvazioni dell'associazione sono necessarie per i nuovi ID dispositivo, salvo che sia abilitata l'approvazione automatica locale.
• L'approvazione automatica dell'associazione è incentrata sulle connessioni loopback locali dirette.
• OpenClaw dispone inoltre di un percorso ristretto di connessione automatica locale al backend/contenitore per flussi helper attendibili tramite segreto condiviso.
• Le connessioni tailnet o LAN dello stesso host sono comunque considerate remote ai fini dell'associazione e richiedono l'approvazione.
• I client WS normalmente includono l'identità device durante connect (operatore + Node). Le uniche eccezioni per operatori senza dispositivo sono percorsi di attendibilità espliciti:
  • gateway.controlUi.allowInsecureAuth=true per la compatibilità HTTP non sicura limitata a localhost.
  • autenticazione riuscita dell'operatore nella Control UI tramite gateway.auth.mode: "trusted-proxy".
  • gateway.controlUi.dangerouslyDisableDeviceAuth=true (misura di emergenza, grave riduzione della sicurezza).
  • RPC del backend gateway-client tramite loopback diretto nel percorso helper interno riservato.
• L'omissione dell'identità del dispositivo ha conseguenze sugli ambiti. Quando una connessione operatore senza dispositivo è consentita tramite un percorso di attendibilità esplicito, OpenClaw azzera comunque gli ambiti autodichiarati impostandoli su un insieme vuoto, salvo che tale percorso disponga di un'eccezione denominata per la conservazione degli ambiti. I metodi vincolati agli ambiti hanno quindi esito negativo con missing scope.
• gateway.controlUi.dangerouslyDisableDeviceAuth=true è un percorso di emergenza della Control UI che conserva gli ambiti. Non concede ambiti a client WebSocket arbitrari con backend personalizzati o strutturati come CLI.
• Il percorso helper riservato del backend gateway-client tramite loopback diretto conserva gli ambiti solo per le 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 dei dispositivi

Per i client legacy che usano ancora il comportamento di firma precedente alla challenge, connect restituisce codici di dettaglio DEVICE_AUTH_* in error.details.code con un error.details.reason stabile.

Errori di migrazione comuni:

Obiettivo della migrazione:

• Attendere sempre connect.challenge.
• Firmare il payload v2 che include il nonce del server.
• Inviare lo stesso nonce in connect.params.device.nonce.
• Il payload di firma preferito è v3 (buildDeviceAuthPayloadV3 in packages/gateway-client/src/device-auth.ts), che vincola platform e deviceFamily, oltre ai campi dispositivo/client/ruolo/ambiti/token/nonce.
• Le firme legacy v2 restano accettate per compatibilità, ma il pinning dei metadati dei dispositivi associati continua a controllare i criteri dei comandi alla riconnessione.

TLS e pinning

• TLS è supportato per le connessioni WS (configurazione gateway.tls).
• I client possono facoltativamente applicare il pinning dell'impronta digitale del certificato del Gateway tramite gateway.remote.tlsFingerprint o l'opzione CLI --tls-fingerprint.

Ambito

Questo protocollo espone l'intera API del Gateway: stato, canali, modelli, chat, agente, sessioni, Node, approvazioni e altro ancora. La superficie esatta è definita dagli schemi TypeBox riesportati da packages/gateway-protocol/src/schema.ts.

Correlati

• Protocollo bridge
• Runbook del Gateway