Associazione del Node

• Associazione del dispositivo (ruolo node) controlla l’handshake connect. Consultare Approvazione automatica dei dispositivi tramite CIDR attendibili più avanti 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, interfaccia di controllo) sono frontend che approvano o rifiutano le richieste in sospeso.

​

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 dichiarato di funzionalità/comandi 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 per i comandi.

​

Flusso di lavoro CLI (adatto agli 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"

​

Superficie API (protocollo del Gateway)

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

• 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. Ciò revoca il ruolo node del dispositivo nell’archivio dei dispositivi associati, elimina contestualmente la superficie approvata del Node e invalida/disconnette le sessioni del ruolo Node di tale dispositivo. Un dispositivo con ruoli misti (ad esempio, uno che possiede anche operator) conserva la propria riga e perde soltanto il ruolo node; la riga di un dispositivo esclusivamente Node viene eliminata. Autorizzazione: operator.pairing può rimuovere le righe dei Node non operatori; un chiamante con token del dispositivo che revoca il proprio ruolo Node su un dispositivo con ruoli misti necessita inoltre di operator.admin.
• node.rename - rinomina il nome visualizzato di un Node associato destinato all’operatore.

• Le riconnessioni con una superficie invariata riutilizzano la richiesta in sospeso; le richieste ripetute aggiornano i metadati del Node memorizzati e l’ultima istantanea dichiarata dei comandi inclusi nell’elenco consentito, per consentirne la visibilità all’operatore.
• I livelli di ambito dell’operatore e i controlli eseguiti al momento dell’approvazione sono riepilogati in Ambiti dell’operatore.
• node.pair.approve usa i comandi dichiarati della richiesta in sospeso per applicare ambiti di approvazione aggiuntivi:
  • richiesta senza comandi: operator.pairing
  • richiesta di comandi ordinari: operator.pairing + operator.write
  • richiesta sensibile per l’amministrazione contenente system.run, system.run.prepare, system.which, browser.proxy, fs.listDir o system.execApprovals.get/set: operator.pairing + operator.admin

​

Controllo dei comandi del Node (2026.3.31+)

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

​

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

​

Approvazione automatica dei dispositivi verificata tramite SSH (impostazione predefinita)

• L’utente del processo Gateway (o sshVerify.user) può collegarsi tramite SSH all’host del Node senza interazione (chiavi/agente; funziona anche Tailscale SSH) e la chiave dell’host è già attendibile.
• openclaw viene risolto sul PATH remoto per sh -lc non interattivo.
• L’IP di connessione è un indirizzo diretto (senza proxy e non loopback) privato, ULA, link-local o CGNAT, oppure corrisponde a sshVerify.cidrs quando impostato.
• Stessa soglia di idoneità dell’approvazione tramite CIDR attendibili: solo associazioni iniziali dei Node senza ambiti; aggiornamenti, browser, interfaccia di controllo e WebChat richiedono sempre conferma.

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

​

Approvazione automatica (app macOS)

• la richiesta è contrassegnata come silent (il Gateway contrassegna come silenziosa la prima superficie di funzionalità quando l’associazione del dispositivo è stata approvata senza interazione) e
• l’app può verificare una connessione SSH all’host del Gateway usando lo stesso utente.

​

Approvazione automatica dei dispositivi tramite CIDR attendibili

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

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

​

Pulizia delle associazioni silenziose sostituite

• Sono idonei, sia come origine sia come destinazione, solo i record la cui approvazione più recente è avvenuta localmente sullo stesso host (silent). Gli abbinamenti verificati tramite CIDR attendibile e SSH attraversano host in cui i metadati di visualizzazione non costituiscono un’identità della macchina, pertanto non vengono mai rimossi automaticamente: per questi, utilizzare la pulizia nella UI di controllo o openclaw nodes remove.
• Gli abbinamenti approvati dal proprietario e quelli tramite QR/codice di configurazione (bootstrap) non vengono mai rimossi automaticamente. I record approvati prima che esistesse la provenienza restano protetti, anche dopo una successiva riapprovazione silenziosa dello stesso ID dispositivo.
• I dispositivi attualmente connessi vengono ignorati, quindi le sessioni locali simultanee con directory di stato separate mantengono i propri token finché sono attive. Vengono ignorati anche i record approvati nell’ultimo minuto, così gli handshake di abbinamento simultanei non possono revocarsi a vicenda prima che le rispettive connessioni vengano registrate.
• Per definizione, i client interessati sono locali, quindi si abbinano nuovamente in modo silenzioso alla connessione successiva.

​

Approvazione automatica degli aggiornamenti dei metadati

​

Strumenti per l’abbinamento tramite QR

​

Località e intestazioni inoltrate

​

Archiviazione (locale, privata)

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

• I token dei dispositivi sono segreti; il database di stato deve essere trattato come sensibile.
• La rotazione del token di un dispositivo utilizza openclaw devices rotate / device.token.rotate.

​

Comportamento del trasporto

• Il trasporto è senza stato; non memorizza l’appartenenza.
• Se il Gateway non è in linea o l’abbinamento è disabilitato, i Node non possono essere abbinati.
• In modalità remota, l’abbinamento avviene nell’archivio del Gateway remoto.

​

Argomenti correlati

• Abbinamento dei canali
• CLI dei Node
• CLI dei dispositivi