Gli scope dell’operatore in OpenClaw

Ogni client WebSocket del gateway si connette con un ruolo, operator o node, e ogni metodo operatore controlla poi uno scope. La pagina degli scope è la mappa di questa seconda barriera: cosa significa ogni scope, come i ruoli con nome li limitano, come un’identità verificata li ottiene e perché approvare l’accesso di qualcun altro non concede mai più di quanto possiedi tu. È anche esplicita sul fatto che nulla di tutto ciò è isolamento tra tenant.

Ruoli e livelli di scope

• operator è il ruolo del piano di controllo per la CLI, la Control UI, l’automazione e gli helper attendibili, node il ruolo di host di capacità per host macOS, iOS, Android e headless che espongono comandi tramite node.invoke; i metodi RPC operatore richiedono il ruolo operator e i metodi originati da un nodo il ruolo node.
• operator.read copre stato, elenchi, catalogo, log, letture di sessione e diagnostica di audit conservata; operator.write copre l’invio di messaggi, l’invocazione di strumenti, le impostazioni talk e voce e l’inoltro di comandi ai nodi, e soddisfa anche read; operator.admin soddisfa ogni scope operatore ed è richiesto per le modifiche alla configurazione, gli aggiornamenti, gli hook nativi, i namespace riservati e le approvazioni ad alto rischio.
• operator.pairing gestisce l’abbinamento di dispositivi e nodi, operator.approvals le API di approvazione exec e dei plugin, operator.questions le domande interattive, operator.talk crea, guida e chiude sessioni Talk senza accesso generale in scrittura (anche write lo soddisfa) e operator.talk.secrets legge la configurazione Talk con i segreti; gli scope futuri sconosciuti richiedono una corrispondenza esatta, a meno che il chiamante non possieda già admin.
• La gestione della connessione GitHub personale è l’unica eccezione, limitata a se stessi, al comportamento in sola lettura: richiede operator.read più il profilo durevole autenticato esatto, così una persona può collegare, interrogare o scollegare solo il proprio account, mentre le modifiche GitHub di sistema e per agente restano admin e la pubblicazione resta write più l’autorizzazione di sessione.

Gli scope dell’operatore limitano ciò che un client del Gateway può fare dopo l’autenticazione.

Ruoli con nome e concessioni per identità

I gateway di team associano profili durevoli autenticati a ruoli con nome sotto gateway.roles, ciascuno dei quali combina quattro policy chiuse: l’accesso alle sessioni altrui (none, view, suggest o write), gli agenti disponibili per la creazione di sessioni e le esecuzioni (un elenco, un asterisco o un array vuoto), un insieme massimo di scope e l’obbligo o meno della sandbox per le nuove sessioni. users.setRole assegna un ruolo e chiude immediatamente le connessioni di quel profilo, gateway.roles.default è obbligatorio non appena esistono ruoli, e quando i ruoli sono configurati gli operatori autenticati tramite identità non ricevono più token di dispositivo o di bootstrap riutilizzabili, perché questi non sono legati a una persona. Una sandbox obbligatoria è isolata per creatore della sessione, riduce uno spazio di lavoro in lettura e scrittura a sola lettura con un avviso, viene marcata in modo immutabile con il creatore prima della prima esecuzione, viene ereditata dai figli delegati, non ripiega mai sul gateway o su un nodo e non può essere aggirata dalla modalità elevata, dagli override dell’host exec o dalle destinazioni host configurate. gateway.auth.identityScopes concede poi scope alle identità verificate provenienti dall’autenticazione tramite proxy attendibile o da Tailscale WhoIs, con le chiavi email confrontate senza distinzione tra maiuscole e minuscole; le connessioni con token, con password o senza autenticazione non portano alcuna identità e non ricevono alcuna concessione, e le connessioni dei nodi non ne ricevono mai.

Il controllo sul metodo e ciò che viene dopo

• Ogni RPC ha uno scope di metodo a privilegio minimo, ricavato prima del dispatch: agent richiede write per i turni ordinari e admin per i comandi di ciclo di vita new o reset; node.invoke richiede write per l’inoltro ordinario e admin quando inoltra a un nodo il proxy del browser, l’elenco delle directory o l’upload da terminale; sessions.create richiede write per la creazione ordinaria e admin per le sessioni in incognito o per qualsiasi execNode; il dispatch e lo spostamento di sessione ricavano il proprio scope dalla destinazione, write per i dispositivi e admin per i profili.
• I gestori applicano poi controlli più rigorosi sull’oggetto concreto: device.pair.approve è raggiungibile con pairing, ma approvare un dispositivo operatore può solo concedere o mantenere scope che il chiamante possiede già, node.pair.approve ricava scope aggiuntivi dai comandi dichiarati dal nodo in attesa (write per i comandi ordinari, admin per system.run, il proxy del browser, l’elenco delle directory o i comandi di approvazione exec), e i comandi chat config set e unset richiedono admin oltre all’invio in chat.
• L’autorità della connessione si risolve in quest’ordine: l’header x-openclaw-scopes limita prima le richieste di registrazione o di upgrade del dispositivo, vi si unisce una concessione per identità lato server corrispondente, l’header limita poi l’unione finale (assente significa nessun limite, presente ma vuoto significa nessuno scope) e un ruolo con nome effettivo interseca il risultato con il proprio tetto; il risultato alimenta sia hello.auth.scopes sia l’autorizzazione dei metodi.

L’abbinamento in OpenClaw è il punto in cui vengono registrate queste approvazioni, mentre gli scope fanno parte dell’insieme più ampio dei controlli di sicurezza del gateway OpenClaw.

Cosa non sono gli scope

La pagina ripete un confine in più punti: gli scope sono una salvaguardia del piano di controllo all’interno di un unico dominio operatore del gateway attendibile, non un isolamento multi-tenant contro utenti ostili. I ruoli con nome organizzano la collaborazione all’interno di quel dominio; i metodi di audit diagnostico restano superfici di lettura del dominio condiviso, non filtrate in base al ruolo di sessione; operator.write autorizza comunque l’invocazione di strumenti e l’inoltro ai nodi su tutto il gateway; e l’autenticazione con token o password a segreto condiviso è trattata come accesso operatore attendibile, che ripristina l’insieme completo degli scope predefiniti sulle superfici compatibili con OpenAI, sulla route di invocazione degli strumenti e sugli endpoint della cronologia delle sessioni, anche quando un chiamante dichiara scope più ristretti. Per una separazione forte tra persone, team o macchine, la risposta sono gateway separati sotto utenti del sistema operativo o host separati. Per la sandbox per creatore che un ruolo può richiedere leggi la guida alla sandbox di OpenClaw, e per la superficie HTTP a cui si applica la regola del segreto condiviso vedi l’API HTTP di OpenClaw compatibile con OpenAI.

Su Diali

Su Diali ogni cliente esegue il proprio gateway, che è esattamente la separazione raccomandata dalla documentazione, con la configurazione del motore generata dalla dashboard e sostituita a ogni rilascio. OpenClaw ospitato su Diali descrive l’assistente ospitato, mentre la pagina sulla sicurezza di Diali illustra il confine attorno a ogni motore.

• Write implica read e talk; admin implica tutto.
• Un’approvazione non concede mai scope che chi approva non possiede.
• Gli scope sono una salvaguardia, non un isolamento tra tenant; i gateway separati lo sono.