OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Gateway

Associazione dei Node

L'associazione dei Node prevede due livelli, entrambi memorizzati nel record del dispositivo associato nel database di stato SQLite del Gateway:

  • Associazione del dispositivo (ruolo node) controlla l'handshake connect. Vedere Approvazione automatica dei dispositivi tramite CIDR attendibili di seguito e Associazione dei canali.
  • Approvazione delle funzionalità del Node (node.pair.*) controlla quali funzionalità/comandi dichiarati può esporre un Node connesso. Il Gateway è la fonte autorevole; le interfacce utente (app macOS, Control UI) sono frontend che approvano o rifiutano le richieste in sospeso.

Il precedente archivio autonomo delle associazioni dei Node (nodes/paired.json con un token per Node, ritirato dal percorso di connessione a gennaio 2026) non esiste più: all'avvio, i Gateway integrano una sola volta eventuali righe rimanenti nei record dei dispositivi e archiviano i file legacy con il suffisso .migrated. Il supporto per il bridge TCP legacy è stato rimosso.

Funzionamento dell'approvazione delle funzionalità

  1. Un Node si connette al WS del Gateway (l'associazione del dispositivo controlla questo passaggio).
  2. Il Gateway confronta l'insieme delle funzionalità/dei comandi dichiarati con quello approvato; gli insiemi nuovi o ampliati memorizzano una richiesta in sospeso nel record del dispositivo ed emettono node.pair.requested.
  3. La richiesta viene approvata o rifiutata (tramite CLI o interfaccia utente).
  4. Fino all'approvazione, i comandi del Node restano filtrati; l'approvazione espone l'insieme dichiarato, nel rispetto dei normali criteri dei comandi.

Le richieste in sospeso scadono automaticamente 5 minuti dopo l'ultimo nuovo tentativo del Node: un Node che tenta attivamente di riconnettersi mantiene valida la propria unica richiesta in sospeso invece di generarne una nuova (con la relativa richiesta di approvazione) a ogni tentativo.

Flusso di lavoro CLI (adatto agli ambienti headless)

bash
openclaw nodes pendingopenclaw nodes approve <requestId>openclaw nodes reject <requestId>openclaw nodes statusopenclaw nodes remove --node <id|name|ip>openclaw nodes rename --node <id|name|ip> --name "Living Room iPad"

nodes status mostra i Node associati/connessi e le relative funzionalità.

Superficie API (protocollo del Gateway)

Eventi:

  • node.pair.requested - emesso quando viene creata una nuova richiesta in sospeso.
  • node.pair.resolved - emesso quando una richiesta viene approvata, rifiutata o scade.

Metodi:

  • node.pair.list - elenca i Node in sospeso e associati (operator.pairing).
  • node.pair.approve - approva una richiesta in sospeso.
  • node.pair.reject - rifiuta una richiesta in sospeso.
  • node.pair.remove - rimuove un Node associato. Questa operazione revoca il ruolo node del dispositivo nell'archivio dei dispositivi associati, rimuove insieme a esso la superficie approvata del Node e invalida/disconnette le sessioni con ruolo Node di tale dispositivo. Un dispositivo con più ruoli (ad esempio, che possiede anche operator) mantiene la propria riga e perde soltanto il ruolo node; la riga di un dispositivo con il solo ruolo Node viene eliminata. Autorizzazione: operator.pairing può rimuovere le righe dei Node che non hanno il ruolo operator; un chiamante con token del dispositivo che revoca il proprio ruolo Node su un dispositivo con più ruoli necessita inoltre di operator.admin.
  • node.rename - rinomina il nome visualizzato di un Node associato mostrato agli operatori.

Rimossi nella versione 2026.7: node.pair.request e node.pair.verify. Le richieste in sospeso vengono create dal Gateway stesso durante le connessioni dei Node e il token autonomo per Node a cui erano destinati non esiste più; l'autenticazione del Node usa il token di associazione del dispositivo.

Note:

  • Le riconnessioni con un insieme invariato riutilizzano la richiesta in sospeso; le richieste ripetute aggiornano i metadati memorizzati del Node e l'ultima istantanea dei comandi dichiarati inclusi nell'elenco di autorizzazione, per renderli visibili all'operatore.
  • I livelli di ambito dell'operatore e i controlli effettuati al momento dell'approvazione sono riepilogati in Ambiti dell'operatore.
  • node.pair.approve usa i comandi dichiarati nella richiesta in sospeso per applicare ambiti di approvazione aggiuntivi:
    • richiesta senza comandi: operator.pairing
    • richiesta di comandi non esecutivi: operator.pairing + operator.write
    • richiesta di system.run / system.run.prepare / system.which: operator.pairing + operator.admin

Controllo dei comandi dei Node (2026.3.31+)

Quando un Node si connette per la prima volta, l'associazione viene richiesta automaticamente. Finché la richiesta non viene approvata, tutti i comandi in sospeso provenienti da tale Node vengono filtrati e non vengono eseguiti. Una volta approvata l'associazione, i comandi dichiarati dal Node diventano disponibili, nel rispetto dei normali criteri dei comandi.

Ciò significa che:

  • I Node che in precedenza si affidavano alla sola associazione del dispositivo per esporre i comandi devono ora completare anche l'associazione del Node.
  • I comandi accodati prima dell'approvazione dell'associazione vengono eliminati, non rinviati.

Confini di attendibilità degli eventi dei Node (2026.3.31+)

I riepiloghi originati dai Node e gli eventi di sessione correlati sono limitati alla superficie attendibile prevista. Potrebbe essere necessario modificare i flussi attivati da notifiche o dai Node che in precedenza si affidavano a un accesso più ampio agli strumenti dell'host o della sessione. Questo rafforzamento impedisce agli eventi dei Node di ottenere l'accesso agli strumenti a livello di host oltre quanto consentito dal confine di attendibilità del Node.

Gli aggiornamenti persistenti della presenza dei Node seguono lo stesso confine di identità: l'evento node.presence.alive viene accettato soltanto dalle sessioni autenticate dei dispositivi Node e aggiorna i metadati di associazione soltanto quando l'identità del dispositivo/Node è già associata. Un valore client.id autodichiarato non è sufficiente per scrivere lo stato dell'ultima attività.

Approvazione automatica dei dispositivi verificata tramite SSH (predefinita)

L'associazione iniziale di un dispositivo con role: node da un indirizzo privato/CGNAT viene approvata automaticamente quando il Gateway può dimostrare la proprietà della macchina tramite SSH: si riconnette all'host che richiede l'associazione (BatchMode, StrictHostKeyChecking=yes), esegue lì openclaw node identity --json e approva soltanto quando l'ID del dispositivo remoto e la chiave pubblica corrispondono esattamente alla richiesta in sospeso. È la corrispondenza della chiave a rendere sicuro il processo: la sola raggiungibilità non comporta mai l'approvazione, pertanto gli altri utenti dietro lo stesso NAT, gli altri utenti di un host condiviso e lo spoofing della LAN vengono tutti reindirizzati alla normale richiesta di approvazione.

Abilitata per impostazione predefinita. Requisiti per l'attivazione:

  • L'utente del processo del Gateway (o sshVerify.user) può connettersi tramite SSH all'host del Node in modo non interattivo (chiavi/agent; funziona anche Tailscale SSH) e la chiave dell'host è già considerata attendibile.
  • openclaw viene risolto nel PATH remoto per l'esecuzione non interattiva di sh -lc.
  • L'IP di connessione è un indirizzo diretto (senza proxy e non local loopback) privato, ULA, link-local o CGNAT oppure corrisponde a sshVerify.cidrs, se impostato.
  • Si applica lo stesso requisito minimo di idoneità dell'approvazione tramite CIDR attendibili: soltanto una nuova associazione di Node senza ambiti; aggiornamenti, browser, Control UI e WebChat richiedono sempre l'approvazione.

Mentre è in corso una verifica, al client Node viene indicato di continuare a riprovare (wait_then_retry) invece di restare in attesa dell'approvazione manuale; se la verifica non riesce, il tentativo successivo torna al normale flusso di richiesta. Per le destinazioni non riuscite viene applicato un breve periodo di sospensione (5 minuti dopo una mancata corrispondenza della chiave).

I dispositivi approvati registrano approvedVia: "ssh-verified" e la loro prima superficie di funzionalità dichiarata viene approvata nello stesso passaggio: la corrispondenza della chiave dimostra già che il Node viene eseguito con l'account dell'operatore su una macchina di sua proprietà, che è la stessa attestazione fornita dall'approvazione manuale delle funzionalità. Gli ampliamenti successivi della superficie richiedono comunque l'approvazione.

Per rafforzare la sicurezza o disabilitare:

json5
{  gateway: {    nodes: {      pairing: {        // Disabilita completamente:        sshVerify: false,        // ...oppure limita/regola la verifica:        // sshVerify: { user: "me", identity: "~/.ssh/probe", timeoutMs: 7000, cidrs: ["10.0.0.0/8"] },      },    },  },}

Approvazione automatica (app macOS)

L'app macOS può tentare un'approvazione silenziosa delle richieste di funzionalità dei Node quando:

  • la richiesta è contrassegnata come silent (il Gateway contrassegna come silenziosa la prima superficie di funzionalità quando l'associazione del dispositivo è stata approvata in modo non interattivo), e
  • l'app può verificare una connessione SSH all'host del Gateway utilizzando lo stesso utente.

Se l'approvazione silenziosa non riesce, viene mostrata la normale richiesta Approve/Reject.

Approvazione automatica dei dispositivi tramite CIDR attendibili

L'associazione dei dispositivi WS per role: node resta manuale per impostazione predefinita. Per le reti private dei Node in cui il Gateway considera già attendibile il percorso di rete, gli operatori possono abilitarla specificando CIDR o indirizzi IP esatti:

json5
{  gateway: {    nodes: {      pairing: {        autoApproveCidrs: ["192.168.1.0/24"],      },    },  },}

Confine di sicurezza:

  • Disabilitata quando gateway.nodes.pairing.autoApproveCidrs non è impostato.
  • Non esiste una modalità di approvazione automatica generale per la LAN o le reti private; l'approvazione automatica verificata tramite SSH (descritta sopra) richiede una corrispondenza crittografica della chiave del dispositivo, mai la sola prossimità di rete.
  • È idonea soltanto una nuova richiesta di associazione di un dispositivo con role: node senza ambiti richiesti.
  • I client operator, browser, Control UI e WebChat restano manuali.
  • Gli ampliamenti di ruolo, ambito, metadati e chiave pubblica restano manuali.
  • I percorsi delle intestazioni del proxy attendibile su local loopback dello stesso host non sono idonei, perché tale percorso può essere contraffatto dai chiamanti locali.

Pulizia delle associazioni silenziose sostituite

Le approvazioni non interattive registrano la propria provenienza nella riga del dispositivo associato: le approvazioni tramite criteri locali sullo stesso host come silent, le approvazioni dei Node tramite CIDR attendibili come trusted-cidr, le approvazioni dei Node verificate tramite SSH come ssh-verified. I client la cui directory di stato è effimera (directory home temporanee, container, sandbox per esecuzione) generano una nuova coppia di chiavi del dispositivo a ogni esecuzione e ogni esecuzione effettua silenziosamente una nuova associazione come dispositivo completamente nuovo: senza pulizia, l'elenco dei dispositivi associati aumenta di una riga obsoleta per ogni esecuzione.

Quando il Gateway approva silenziosamente l'associazione di un dispositivo locale, ritira i record approvati come silent meno recenti che appartengono allo stesso gruppo di client (con clientId, clientMode e nome visualizzato corrispondenti) e che non sono attualmente connessi. I client locali vengono eseguiti sullo stesso host del Gateway, pertanto la chiave del gruppo non può corrispondere a una macchina diversa. I token delle righe ritirate vengono invalidati immediatamente; ogni voce legacy corrispondente relativa all'associazione del Node viene cancellata e viene trasmesso un evento di rimozione node.pair.resolved.

Limiti:

  • Sono idonei, sia come origine sia come destinazione, soltanto i record la cui approvazione più recente è avvenuta localmente sullo stesso host (silent). Le associazioni tramite CIDR attendibili e quelle verificate tramite SSH attraversano host in cui i metadati di visualizzazione non rappresentano un'identità della macchina, quindi non vengono mai rimosse automaticamente: per queste, utilizzare la pulizia della Control UI o openclaw nodes remove.
  • Le associazioni approvate dal proprietario e tramite codice QR/codice di configurazione (bootstrap) non vengono mai rimosse automaticamente. I record approvati prima dell'introduzione della provenienza restano protetti, anche dopo una successiva riapprovazione silenziosa dello stesso ID del dispositivo.
  • I dispositivi attualmente connessi vengono ignorati, così le sessioni locali simultanee con directory di stato separate mantengono i propri token mentre sono attive. Vengono ignorati anche i record approvati nell'ultimo minuto, affinché gli handshake di associazione simultanei non possano ritirarsi reciprocamente prima che le rispettive connessioni vengano registrate.
  • Per costruzione, i client interessati sono locali, quindi alla connessione successiva eseguono nuovamente l'associazione in modo silenzioso.

Approvazione automatica degli aggiornamenti dei metadati

Quando un dispositivo già associato si riconnette presentando soltanto modifiche non sensibili ai metadati (ad esempio il nome visualizzato o indicazioni sulla piattaforma del client), OpenClaw considera l'operazione un metadata-upgrade. L'approvazione automatica silenziosa è limitata: si applica soltanto alle riconnessioni locali attendibili non provenienti da browser che hanno già dimostrato il possesso di credenziali locali o condivise, incluse le riconnessioni delle app native sullo stesso host dopo modifiche ai metadati della versione del sistema operativo. I client browser/Control UI e i client remoti continuano a utilizzare il flusso esplicito di riapprovazione. Gli ampliamenti di ambito (da lettura a scrittura/amministrazione) e le modifiche alla chiave pubblica non sono idonei all'approvazione automatica degli aggiornamenti dei metadati; restano richieste esplicite di riapprovazione.

Strumenti per l'associazione tramite codice QR

/pair qr visualizza il payload di associazione come contenuto multimediale strutturato, affinché i client mobili e browser possano scansionarlo direttamente.

L'eliminazione di un dispositivo rimuove anche eventuali richieste di associazione in sospeso obsolete per quell'ID dispositivo, affinché nodes pending non mostri righe orfane dopo una revoca.

Località e intestazioni inoltrate

L'associazione del Gateway considera una connessione come local loopback solo quando sia il socket originario sia qualsiasi evidenza proveniente da proxy a monte concordano. Se una richiesta arriva tramite local loopback ma contiene evidenze nelle intestazioni Forwarded, X-Forwarded-* o X-Real-IP, tali evidenze delle intestazioni inoltrate invalidano la dichiarazione di località local loopback e il percorso di associazione richiede un'approvazione esplicita anziché considerare implicitamente la richiesta come una connessione proveniente dallo stesso host. Consultare Autenticazione tramite proxy attendibile per la regola equivalente relativa all'autenticazione dell'operatore.

Archiviazione (locale, privata)

Lo stato dell'associazione risiede nei record dei dispositivi associati nel database di stato SQLite condiviso, all'interno della directory di stato del Gateway (impostazione predefinita: ~/.openclaw):

  • ~/.openclaw/state/openclaw.sqlite (dispositivi associati con autenticazione del dispositivo, superfici dei Node approvate, richieste di superfici in sospeso, richieste di associazione dei dispositivi in sospeso e token di bootstrap)

Se si ridefinisce OPENCLAW_STATE_DIR, il database viene spostato insieme a essa. I Gateway aggiornati da versioni che utilizzavano archivi JSON li importano all'avvio e conservano gli archivi devices/*.json.migrated e nodes/*.json.migrated.

Note sulla sicurezza:

  • I token dei dispositivi sono segreti; trattare il database di stato come sensibile.
  • Per ruotare il token di un dispositivo si utilizzano openclaw devices rotate / device.token.rotate.

Comportamento del trasporto

  • Il trasporto è senza stato; non memorizza le appartenenze.
  • Se il Gateway è offline o l'associazione è disabilitata, i Node non possono eseguire l'associazione.
  • In modalità remota, l'associazione avviene nell'archivio del Gateway remoto.

Correlati

Was this useful?
On this page

On this page