Protocollo del Gateway

Documentation Index

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

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

​

Trasporto

• WebSocket, frame di testo con payload JSON.
• Il primo frame deve essere una richiesta connect.
• I frame pre-connessione 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, i frame in ingresso sovradimensionati e i 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, i contenuti degli allegati, il corpo grezzo del frame, token, cookie o valori segreti.

​

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

​

Esempio di nodo

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

​

Ruoli + ambiti

​

Ruoli

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

​

Ambiti (operatore)

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

• richieste senza comandi: 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)

• 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).

​

Presenza

• system-presence restituisce voci indicizzate per identità dispositivo.
• Le voci di presenza includono deviceId, roles e scopes così le UI possono mostrare una singola riga per dispositivo anche quando si connette sia come operatore sia come nodo.
• node.list include i campi facoltativi lastSeenAtMs e lastSeenReason. I nodi connessi riportano l’ora della connessione corrente come lastSeenAtMs con motivo connect; i nodi associati possono anche riportare una presenza in background persistente quando un evento nodo attendibile aggiorna i metadati di pairing.

​

Evento alive in background del nodo

{
  "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 degli eventi broadcast

• I frame chat, agente e risultato strumento (inclusi gli eventi agent in streaming e i risultati delle chiamate agli strumenti) richiedono almeno operator.read. Le sessioni senza operator.read saltano completamente questi frame.
• I broadcast plugin.* definiti dai plugin sono vincolati a 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 così la salute del trasporto rimane osservabile da ogni sessione autenticata.
• Le famiglie di eventi broadcast sconosciute sono vincolate agli ambiti per impostazione predefinita (fail-closed) a meno che un handler registrato non le renda esplicitamente meno restrittive.

​

Famiglie comuni di metodi RPC

​

Famiglie di eventi comuni

• chat: aggiornamenti della chat della UI, come chat.inject e altri eventi di chat solo di trascrizione.
• session.message e session.tool: aggiornamenti di trascrizione/flusso di eventi per una sessione sottoscritta.
• sessions.changed: indice della sessione o metadati modificati.
• presence: aggiornamenti degli snapshot della presenza di sistema.
• tick: evento periodico keepalive / liveness.
• health: aggiornamento dello snapshot di stato del gateway.
• heartbeat: aggiornamento del flusso di eventi Heartbeat.
• cron: evento di modifica di esecuzione/job Cron.
• shutdown: notifica di arresto del gateway.
• node.pair.requested / node.pair.resolved: ciclo di vita dell’abbinamento del nodo.
• node.invoke.request: broadcast della richiesta di invocazione del nodo.
• device.pair.requested / device.pair.resolved: ciclo di vita del dispositivo abbinato.
• voicewake.changed: configurazione del trigger della parola di attivazione modificata.
• exec.approval.requested / exec.approval.resolved: ciclo di vita dell’approvazione exec.
• plugin.approval.requested / plugin.approval.resolved: ciclo di vita dell’approvazione del Plugin.

​

Metodi helper del nodo

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

​

RPC del registro delle attività

• 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.

​

Metodi helper dell’operatore

• Gli operatori possono chiamare commands.list (operator.read) per recuperare l’inventario dei comandi runtime per un agente.
  • agentId è opzionale; omettilo per leggere l’area di lavoro dell’agente predefinito.
  • scope controlla quale superficie viene indirizzata 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 è opzionale e influisce solo sulla denominazione nativa più sulla disponibilità dei comandi Plugin nativi.
  • includeArgs=false omette dalla risposta i metadati serializzati degli argomenti.
• 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: se uno strumento Plugin è opzionale
• 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 consegna fornito dal chiamante.
  • La risposta ha ambito di sessione e riflette ciò che la conversazione attiva può usare in questo momento, inclusi strumenti core, Plugin e di canale.
• Gli operatori possono chiamare tools.invoke (operator.write) per invocare uno strumento disponibile tramite lo stesso percorso dei criteri del gateway di /tools/invoke.
  • name è obbligatorio. args, sessionKey, agentId, confirm e idempotencyKey sono opzionali.
  • Se sono presenti sia sessionKey sia agentId, l’agente della sessione risolta deve corrispondere a agentId.
  • La risposta è un envelope orientato all’SDK con ok, toolName, output opzionale e campi error tipizzati. Rifiuti di approvazione o di policy restituiscono ok:false nel payload invece di aggirare la pipeline dei criteri degli strumenti del gateway.
• Gli operatori possono chiamare skills.status (operator.read) per recuperare l’inventario visibile delle skill per un agente.
  • agentId è opzionale; omettilo per leggere l’area di lavoro dell’agente predefinito.
  • La risposta include idoneità, requisiti mancanti, controlli di configurazione e opzioni di installazione sanitizzate senza esporre valori segreti grezzi.
• Gli operatori possono chiamare skills.search e skills.detail (operator.read) per i metadati di scoperta di ClawHub.
• Gli operatori possono chiamare skills.upload.begin, skills.upload.chunk e skills.upload.commit (operator.admin) per preparare un archivio skill privato prima di installarlo. Questo è un percorso di upload amministrativo separato per client attendibili, non il normale flusso di installazione delle skill ClawHub, ed è disabilitato per impostazione predefinita salvo che skills.install.allowUploadedArchives sia abilitato.
  • skills.upload.begin({ kind: "skill-archive", slug, sizeBytes, sha256?, force?, idempotencyKey? }) crea un upload associato a quel valore slug e 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 l’upload; non installa la skill.
  • Gli archivi skill caricati sono archivi zip contenenti una root 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/ dell’area di lavoro dell’agente predefinito.
  • Modalità upload: { source: "upload", uploadId, slug, force?, sha256?, timeoutMs? } installa un upload sottoposto a commit nella directory skills/<slug> dell’area di lavoro dell’agente predefinito. Lo slug e il valore force devono corrispondere alla richiesta skills.upload.begin originale. Questa modalità viene rifiutata salvo che skills.install.allowUploadedArchives sia abilitato. L’impostazione non influisce sulle installazioni ClawHub.
  • Modalità installer Gateway: { name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? } esegue un’azione metadata.openclaw.install dichiarata sull’host del gateway.
• Gli operatori possono chiamare skills.update (operator.admin) in due modalità:
  • La modalità ClawHub aggiorna uno slug tracciato o tutte le installazioni ClawHub tracciate nell’area di lavoro dell’agente predefinito.
  • La modalità configurazione applica patch ai valori skills.entries.<skillKey> come enabled, apiKey ed env.

​

Viste di models.list

• Omesso o "default": comportamento runtime corrente. Se agents.defaults.models è configurato, la risposta è il catalogo consentito, inclusi i modelli scoperti dinamicamente per le voci provider/*. Altrimenti la risposta è il catalogo completo del Gateway.
• "configured": comportamento dimensionato per picker. Se agents.defaults.models è configurato, prevale comunque, inclusa la scoperta con ambito provider per le voci provider/*. Senza una allowlist, la risposta usa le voci esplicite models.providers.*.models, ripiegando sul catalogo completo solo quando non esistono righe di modello configurate.
• "all": catalogo completo del Gateway, bypassando agents.defaults.models. Usalo per diagnostica e UI di scoperta, non per i normali picker di modelli.

​

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 node.invoke system.run inoltrate 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 della consegna dell’agente

• Le richieste agent possono includere deliver=true per richiedere la consegna in uscita.
• bestEffortDeliver=false mantiene un comportamento rigoroso: destinazioni di consegna irrisolte o solo interne restituiscono INVALID_REQUEST.
• bestEffortDeliver=true consente il fallback all’esecuzione solo su sessione quando non può essere risolta alcuna rotta consegnabile esterna (per esempio sessioni interne/webchat o configurazioni multi-canale ambigue).
• I risultati finali di agent possono includere result.deliveryStatus quando la consegna è stata richiesta, usando gli stessi stati sent, suppressed, partial_failed e failed documentati per openclaw agent --json --deliver.

​

Versionamento

• PROTOCOL_VERSION risiede in src/gateway/protocol/version.ts.
• I client inviano minProtocol + maxProtocol; il server rifiuta gli intervalli che non includono il suo protocollo corrente. I client nativi usano un limite inferiore v3 così i client v4 additivi possono ancora raggiungere i gateway v3.
• Schemi + modelli sono generati dalle definizioni TypeBox:
  • pnpm protocol:gen
  • pnpm protocol:gen:swift
  • pnpm protocol:check

​

Costanti del client

​

Auth

• L’autenticazione Gateway con segreto condiviso usa connect.params.auth.token oppure connect.params.auth.password, a seconda della modalità di autenticazione configurata.
• Le modalità con identità, come Tailscale Serve (gateway.auth.allowTailscale: true) o gateway.auth.mode: "trusted-proxy" non-local loopback, soddisfano il controllo di autenticazione della connessione dai header della richiesta invece che da connect.params.auth.*.
• gateway.auth.mode: "none" per private-ingress salta completamente l’autenticazione di connessione con segreto condiviso; non esporre questa modalità su ingress pubblici/non attendibili.
• Dopo il pairing, il Gateway emette un device token con ambito limitato al ruolo + scopes della connessione. Viene restituito in hello-ok.auth.deviceToken e dovrebbe essere persistito dal client per connessioni future.
• I client dovrebbero persistere il hello-ok.auth.deviceToken primario dopo ogni connessione riuscita.
• La riconnessione con quel device token memorizzato dovrebbe riutilizzare anche il set di scope approvati memorizzato per quel token. Questo preserva l’accesso di lettura/probe/status già concesso ed evita di ridurre silenziosamente le riconnessioni a uno scope implicito più ristretto solo admin.
• 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 token condiviso esplicito, poi un deviceToken esplicito, poi un token per dispositivo memorizzato (indicizzato per deviceId + role).
  • auth.bootstrapToken viene inviato solo quando nessuno dei valori precedenti ha risolto un auth.token. Un token condiviso o qualunque device token risolto lo sopprime.
  • La promozione automatica di un device token memorizzato nel retry una tantum AUTH_TOKEN_MISMATCH è consentita solo per endpoint attendibili: loopback, oppure wss:// con un tlsFingerprint fissato. wss:// pubblico senza pinning non è idoneo.
• Le voci aggiuntive hello-ok.auth.deviceTokens sono token di handoff bootstrap. Persistile solo quando la connessione ha usato autenticazione bootstrap su un trasporto attendibile come wss:// o pairing loopback/locale.
• Se un client fornisce un deviceToken esplicito o scopes espliciti, quel set di scope richiesto dal chiamante rimane autoritativo; gli scope in cache vengono riutilizzati solo quando il client riutilizza il token per dispositivo memorizzato.
• I device token possono essere ruotati/revocati tramite device.token.rotate e device.token.revoke (richiede scope operator.pairing).
• device.token.rotate restituisce metadati di rotazione. Ripete il bearer token sostitutivo solo per chiamate dello stesso dispositivo già autenticate con quel device token, così i client solo token possono persistere il sostituto prima della riconnessione. Le rotazioni shared/admin non ripetono il bearer token.
• Emissione, rotazione e revoca dei token restano limitate al set di ruoli approvato registrato nella voce di pairing di quel dispositivo; la mutazione dei token non può espandere né indirizzare un ruolo dispositivo che l’approvazione del pairing non ha mai concesso.
• Per le sessioni con token di dispositivo accoppiato, la gestione dei dispositivi è auto-limitata salvo che il chiamante abbia anche operator.admin: i chiamanti non admin possono rimuovere/revocare/ruotare solo la voce del proprio dispositivo.
• device.token.rotate e device.token.revoke controllano anche il set di scope del token operatore di destinazione rispetto agli scope 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 (boolean)
  • 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 in cache.
  • Se il retry fallisce, i client dovrebbero interrompere i loop automatici di riconnessione e mostrare indicazioni di azione per l’operatore.
• AUTH_SCOPE_MISMATCH significa che il device token è stato riconosciuto ma non copre il ruolo/gli scope richiesti. I client non dovrebbero presentarlo come token errato; chiedi all’operatore di rifare il pairing o approvare il contratto di scope più stretto/più ampio.

​

Identità dispositivo + pairing

• I nodi dovrebbero includere un’identità dispositivo stabile (device.id) derivata da un fingerprint della keypair.
• I Gateway emettono token per dispositivo + ruolo.
• Le approvazioni di pairing sono richieste per nuovi ID dispositivo a meno che l’auto-approvazione locale sia abilitata.
• L’auto-approvazione del pairing è centrata sulle connessioni dirette local loopback.
• OpenClaw ha anche uno stretto percorso di self-connect backend/container-locale per flussi helper attendibili con segreto condiviso.
• Le connessioni stessa-host tailnet o LAN sono comunque trattate come remote per il pairing 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 downgrade di sicurezza).
  • RPC backend gateway-client direct-loopback autenticate con token/password Gateway condivisi.
• Tutte le connessioni devono firmare il nonce connect.challenge fornito dal server.

​

Diagnostica della migrazione dell’autenticazione dispositivo

• 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 del dispositivo accoppiato controlla comunque la policy dei comandi alla riconnessione.

​

TLS + pinning

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

​

Scope

​

Correlati

• Protocollo bridge
• Runbook Gateway