Abbinamento gestito dal Gateway

Nel pairing gestito dal Gateway, il Gateway è la fonte di verità per stabilire quali nodi sono autorizzati a unirsi. Le UI (app macOS, client futuri) sono solo frontend che approvano o rifiutano le richieste in sospeso.

Importante: i nodi WS usano il pairing del dispositivo (ruolo node) durante connect. node.pair.* è un archivio di pairing separato e non controlla l'handshake WS. Solo i client che chiamano esplicitamente node.pair.* usano questo flusso.

# Concetti

• Richiesta in sospeso: un nodo ha chiesto di unirsi; richiede approvazione.
• Nodo associato: nodo approvato con un token di autenticazione emesso.
• Trasporto: l'endpoint WS del Gateway inoltra le richieste ma non decide l'appartenenza. (Il supporto legacy del bridge TCP è stato rimosso.)

# Come funziona il pairing

1. Un nodo si connette al WS del Gateway e richiede il pairing.
2. Il Gateway archivia una richiesta in sospeso ed emette node.pair.requested.
3. Approvi o rifiuti la richiesta (CLI o UI).
4. All'approvazione, il Gateway emette un nuovo token (i token vengono ruotati al nuovo pairing).
5. Il nodo si riconnette usando il token ed è ora "associato".

Le richieste in sospeso scadono automaticamente dopo 5 minuti.

# Flusso di lavoro CLI (adatto ad ambienti headless)

openclaw nodes pending
openclaw nodes approve <requestId>
openclaw nodes reject <requestId>
openclaw nodes status
openclaw nodes remove --node <id|name|ip>
openclaw nodes rename --node <id|name|ip> --name "Living Room iPad"

nodes status mostra i nodi associati/connessi e le loro capacità.

# 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/scaduta.

Metodi:

• node.pair.request - crea o riusa una richiesta in sospeso.
• node.pair.list - elenca nodi in sospeso + associati (operator.pairing).
• node.pair.approve - approva una richiesta in sospeso (emette token).
• node.pair.reject - rifiuta una richiesta in sospeso.
• node.pair.remove - rimuove una voce obsoleta di nodo associato.
• node.pair.verify - verifica { nodeId, token }.

Note:

• node.pair.request è idempotente per nodo: le chiamate ripetute restituiscono la stessa richiesta in sospeso.
• Le richieste ripetute per lo stesso nodo in sospeso aggiornano anche i metadati del nodo archiviati e l'ultima istantanea dichiarata dei comandi in allowlist per la visibilità dell'operatore.
• L'approvazione genera sempre un token nuovo; nessun token viene mai restituito da node.pair.request.
• I livelli degli ambiti operatore e i controlli al momento dell'approvazione sono riassunti in Ambiti operatore.
• Le richieste possono includere silent: true come suggerimento per flussi di approvazione automatica.
• node.pair.approve usa i comandi dichiarati della richiesta in sospeso per applicare ambiti di approvazione aggiuntivi:
  • richiesta senza comandi: operator.pairing
  • richiesta di comando non exec: operator.pairing + operator.write
  • richiesta system.run / system.run.prepare / system.which: operator.pairing + operator.admin

# Controllo dei comandi Node (2026.3.31+)

Quando un nodo si connette per la prima volta, il pairing viene richiesto automaticamente. Finché la richiesta di pairing non viene approvata, tutti i comandi del nodo in sospeso provenienti da quel nodo vengono filtrati e non verranno eseguiti. Una volta stabilita la fiducia tramite approvazione del pairing, i comandi dichiarati del nodo diventano disponibili in base alla normale policy dei comandi.

Questo significa:

• I nodi che in precedenza si affidavano al solo pairing del dispositivo per esporre comandi devono ora completare il pairing del nodo.
• I comandi accodati prima dell'approvazione del pairing vengono eliminati, non rinviati.

# Confini di fiducia degli eventi Node (2026.3.31+)

I riepiloghi originati dal nodo e gli eventi di sessione correlati sono limitati alla superficie attendibile prevista. I flussi guidati da notifiche o attivati dal nodo che in precedenza dipendevano da un accesso più ampio agli strumenti dell'host o della sessione potrebbero richiedere adeguamenti. Questo rafforzamento garantisce che gli eventi del nodo non possano scalare ad accesso agli strumenti a livello host oltre quanto consentito dal confine di fiducia del nodo.

Gli aggiornamenti durevoli della presenza del nodo seguono lo stesso confine di identità. L'evento node.presence.alive viene accettato solo da sessioni di dispositivi nodo autenticati e aggiorna i metadati di pairing solo quando l'identità dispositivo/nodo è già associata. I valori client.id autodichiarati non sono sufficienti per scrivere lo stato dell'ultima visualizzazione.

# Approvazione automatica (app macOS)

L'app macOS può facoltativamente tentare una approvazione silenziosa quando:

• la richiesta è contrassegnata con silent, e
• l'app può verificare una connessione SSH all'host gateway usando lo stesso utente.

Se l'approvazione silenziosa non riesce, torna al normale prompt "Approva/Rifiuta".

# Approvazione automatica dei dispositivi con CIDR attendibili

Il pairing dei dispositivi WS per role: node resta manuale per impostazione predefinita. Per le reti di nodi private in cui il Gateway considera già attendibile il percorso di rete, gli operatori possono aderire con CIDR espliciti o IP esatti:

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

Confine di sicurezza:

• Disabilitato quando gateway.nodes.pairing.autoApproveCidrs non è impostato.
• Non esiste una modalità di approvazione automatica indiscriminata per LAN o rete privata.
• È idoneo solo il pairing di un dispositivo role: node nuovo senza ambiti richiesti.
• I client operatore, browser, Control UI e WebChat restano manuali.
• Gli upgrade di ruolo, ambito, metadati e chiave pubblica restano manuali.
• I percorsi con intestazione trusted-proxy su local loopback dello stesso host non sono idonei perché quel percorso può essere falsificato da chiamanti locali.

# Approvazione automatica degli upgrade dei metadati

Quando un dispositivo già associato si riconnette con sole modifiche ai metadati non sensibili (per esempio, nome visualizzato o suggerimenti sulla piattaforma client), OpenClaw tratta questo come un metadata-upgrade. L'approvazione automatica silenziosa è ristretta: si applica solo alle riconnessioni locali attendibili non browser che hanno già dimostrato il possesso di credenziali locali o condivise, incluse le riconnessioni di app native sullo stesso host dopo modifiche dei metadati della versione del sistema operativo. I client browser/Control UI e i client remoti continuano a usare il flusso esplicito di nuova approvazione. Gli upgrade di ambito (da lettura a scrittura/admin) e le modifiche della chiave pubblica non sono idonei per l'approvazione automatica dei metadata-upgrade - restano richieste esplicite di nuova approvazione.

# Helper per pairing QR

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

L'eliminazione di un dispositivo elimina anche eventuali richieste di pairing in sospeso obsolete per quell' ID dispositivo, quindi nodes pending non mostra righe orfane dopo una revoca.

# Località e intestazioni inoltrate

Il pairing del Gateway tratta una connessione come loopback solo quando sia il socket grezzo sia qualsiasi evidenza di proxy upstream concordano. Se una richiesta arriva su loopback ma contiene intestazioni X-Forwarded-For / X-Forwarded-Host / X-Forwarded-Proto che puntano a un'origine non locale, tale evidenza da intestazioni inoltrate invalida l'affermazione di località loopback. Il percorso di pairing richiede quindi approvazione esplicita invece di trattare silenziosamente la richiesta come una connessione dallo stesso host. Vedi Autenticazione proxy attendibile per la regola equivalente sull' autenticazione operatore.

# Archiviazione (locale, privata)

Lo stato di pairing è archiviato sotto la directory di stato del Gateway (predefinita ~/.openclaw):

• ~/.openclaw/nodes/paired.json
• ~/.openclaw/nodes/pending.json

Se sovrascrivi OPENCLAW_STATE_DIR, la cartella nodes/ si sposta con essa.

Note di sicurezza:

• I token sono segreti; tratta paired.json come sensibile.
• La rotazione di un token richiede una nuova approvazione (o l'eliminazione della voce del nodo).

# Comportamento del trasporto

• Il trasporto è stateless; non archivia l'appartenenza.
• Se il Gateway è offline o il pairing è disabilitato, i nodi non possono associarsi.
• Se il Gateway è in modalità remota, il pairing avviene comunque nell'archivio del Gateway remoto.

# Correlati

• Pairing dei canali
• Nodi
• CLI dispositivi