Gateway

Sandbox vs criteri degli strumenti vs privilegi elevati

Status: active

OpenClaw dispone di tre controlli correlati ma distinti:

Sandbox (agents.defaults.sandbox.* / agents.list[].sandbox.*) determina dove vengono eseguiti gli strumenti (backend della sandbox oppure host).
Criteri degli strumenti (tools.*, tools.sandbox.tools.*, agents.list[].tools.*) determina quali strumenti sono disponibili/consentiti.
Modalità con privilegi elevati (tools.elevated.*, agents.list[].tools.elevated.*) è una via di fuga riservata a exec per eseguire operazioni all'esterno della sandbox quando la sessione è isolata (gateway per impostazione predefinita oppure node quando la destinazione di exec è configurata come node).

Debug rapido

Usa lo strumento di ispezione per vedere cosa sta facendo effettivamente OpenClaw:

bash

openclaw sandbox explainopenclaw sandbox explain --session agent:main:mainopenclaw sandbox explain --agent workopenclaw sandbox explain --json

Mostra:

modalità, ambito e accesso all'area di lavoro effettivi della sandbox
se la sessione è attualmente isolata nella sandbox (principale o non principale)
regole effettive di autorizzazione/negazione degli strumenti nella sandbox (e se derivano dall'agente, dalla configurazione globale o da quella predefinita)
vincoli della modalità con privilegi elevati e percorsi delle chiavi da correggere

Sandbox: dove vengono eseguiti gli strumenti

L'isolamento nella sandbox è controllato da agents.defaults.sandbox.mode:

"off": tutto viene eseguito sull'host.
"non-main": solo le sessioni non principali sono isolate nella sandbox (una comune "sorpresa" per gruppi/canali).
"all": tutto viene isolato nella sandbox.

agents.defaults.sandbox.workspaceAccess controlla ciò che la sandbox può vedere: "none", "ro" o "rw".

Consulta Isolamento nella sandbox per la matrice completa (ambito, montaggi dell'area di lavoro, immagini).

Montaggi bind (controllo rapido della sicurezza)

docker.binds perfora il file system della sandbox: tutto ciò che monti è visibile all'interno del contenitore con la modalità impostata (:ro o :rw).
Se ometti la modalità, l'impostazione predefinita è lettura-scrittura; preferisci :ro per codice sorgente/segreti.
scope: "shared" ignora i montaggi specifici per agente (si applicano solo quelli globali).
OpenClaw convalida due volte le origini dei montaggi bind: prima sul percorso di origine normalizzato, poi nuovamente dopo averlo risolto attraverso l'antenato esistente più profondo. Le vie di fuga tramite directory principali costituite da collegamenti simbolici non eludono i controlli sui percorsi bloccati o sulle radici consentite.
Anche i percorsi foglia inesistenti vengono controllati in modo sicuro. Se /workspace/alias-out/new-file viene risolto attraverso una directory principale simbolica verso un percorso bloccato o esterno alle radici consentite configurate, il montaggio bind viene rifiutato.
Il montaggio di /var/run/docker.sock concede di fatto alla sandbox il controllo dell'host; fallo solo intenzionalmente.
L'accesso all'area di lavoro (workspaceAccess) è indipendente dalle modalità dei montaggi bind.

Criteri degli strumenti: quali strumenti esistono/possono essere richiamati

Sono rilevanti due livelli:

Profilo degli strumenti: tools.profile e agents.list[].tools.profile (elenco base dei consentiti)
Profilo degli strumenti del provider: tools.byProvider[provider].profile e agents.list[].tools.byProvider[provider].profile
Criteri globali/per agente degli strumenti: tools.allow/tools.deny e agents.list[].tools.allow/agents.list[].tools.deny
Criteri degli strumenti del provider: tools.byProvider[provider].allow/deny e agents.list[].tools.byProvider[provider].allow/deny
Criteri degli strumenti della sandbox (si applicano solo durante l'isolamento nella sandbox): tools.sandbox.tools.allow/tools.sandbox.tools.deny e agents.list[].tools.sandbox.tools.*

Regole pratiche:

deny prevale sempre.
Se allow non è vuoto, tutto il resto viene considerato bloccato.
I criteri degli strumenti costituiscono il blocco definitivo: /exec non può ignorare il divieto dello strumento exec.
I criteri degli strumenti filtrano la disponibilità degli strumenti in base al nome; non esaminano gli effetti collaterali all'interno di exec. Se exec è consentito, negare write, edit o apply_patch non rende i comandi della shell di sola lettura.
/exec modifica solo le impostazioni predefinite della sessione per i mittenti autorizzati; non concede l'accesso agli strumenti.
Le chiavi degli strumenti del provider accettano provider (ad esempio google-antigravity) oppure provider/model (ad esempio openai/gpt-5.4).
I log del Gateway includono voci di controllo agents/tool-policy quando un passaggio dei criteri degli strumenti rimuove degli strumenti o quando i criteri degli strumenti della sandbox bloccano una chiamata. Usa openclaw logs per visualizzare l'etichetta della regola, la chiave di configurazione e i nomi degli strumenti interessati.

Gruppi di strumenti (abbreviazioni)

I criteri degli strumenti (globali, dell'agente e della sandbox) supportano voci group:* che si espandono in più strumenti:

json5

{  tools: {    sandbox: {      tools: {        allow: ["group:runtime", "group:fs", "group:sessions", "group:memory"],      },    },  },}

Gruppi disponibili:

Gruppo	Strumenti
`group:runtime`	`exec`, `process`, `code_execution` (`bash` è accettato come alias di `exec`)
`group:fs`	`read`, `write`, `edit`, `apply_patch`
`group:sessions`	`sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status`
`group:memory`	`memory_search`, `memory_get`
`group:web`	`web_search`, `x_search`, `web_fetch`
`group:ui`	`browser`, `canvas`
`group:automation`	`heartbeat_respond`, `cron`, `gateway`
`group:messaging`	`message`
`group:nodes`	`nodes`, `computer`
`group:agents`	`agents_list`, `get_goal`, `create_goal`, `update_goal`, `update_plan`, `skill_workshop`
`group:media`	`image`, `image_generate`, `music_generate`, `video_generate`, `tts`
`group:openclaw`	la maggior parte degli strumenti integrati di OpenClaw (esclude le primitive di file system e runtime `read`/`write`/`edit`/`apply_patch`/`exec`/`process`, `canvas` e i plugin dei provider)
`group:plugins`	tutti gli strumenti caricati di proprietà dei plugin, inclusi i server MCP configurati esposti tramite `bundle-mcp`

Per gli agenti di sola lettura, nega group:runtime oltre agli strumenti che modificano il file system, a meno che i criteri del file system della sandbox o un confine host separato non impongano il vincolo di sola lettura.

Per i server MCP isolati nella sandbox, i criteri degli strumenti della sandbox costituiscono un secondo controllo di autorizzazione. Se mcp.servers è configurato ma le interazioni isolate nella sandbox mostrano solo gli strumenti integrati, aggiungi bundle-mcp, group:plugins oppure un nome/glob di strumento MCP con prefisso del server, come outlook__send_mail o outlook__*, a tools.sandbox.tools.alsoAllow, quindi riavvia/ricarica il Gateway e acquisisci nuovamente l'elenco degli strumenti. I glob dei server utilizzano il prefisso del server MCP sicuro per il provider: i caratteri diversi da [A-Za-z0-9_-] diventano -, i nomi che non iniziano con una lettera ricevono il prefisso mcp- e i prefissi lunghi o duplicati possono essere troncati o ricevere un suffisso.

Attualmente openclaw doctor controlla questa struttura per i server gestiti da OpenClaw in mcp.servers. I server MCP caricati dai manifest dei plugin inclusi o da .mcp.json di Claude utilizzano lo stesso controllo della sandbox, ma questa diagnostica non elenca ancora tali origini; usa le stesse voci dell'elenco dei consentiti se i relativi strumenti scompaiono nelle interazioni isolate nella sandbox.

Modalità con privilegi elevati: "esecuzione sull'host" riservata a exec

La modalità con privilegi elevati non concede strumenti aggiuntivi; influisce solo su exec.

Se la sessione è isolata nella sandbox, /elevated on (oppure exec con elevated: true) esegue le operazioni all'esterno della sandbox (potrebbero comunque essere necessarie approvazioni).
Usa /elevated full per ignorare le approvazioni di exec per la sessione.
Se l'esecuzione è già diretta, la modalità con privilegi elevati di fatto non produce alcun effetto (rimane comunque soggetta ai controlli).
La modalità con privilegi elevati non è limitata alle Skills e non ignora le regole di autorizzazione/negazione degli strumenti.
La modalità con privilegi elevati non concede sostituzioni arbitrarie tra host diversi da host=auto; segue le normali regole della destinazione di exec e mantiene node solo quando la destinazione configurata/della sessione è già node.
/exec è separato dalla modalità con privilegi elevati. Regola solo le impostazioni predefinite di exec per sessione per i mittenti autorizzati.

Controlli:

Attivazione: tools.elevated.enabled (e facoltativamente agents.list[].tools.elevated.enabled)
Elenchi dei mittenti consentiti: tools.elevated.allowFrom.<provider> (e facoltativamente agents.list[].tools.elevated.allowFrom.<provider>)

Consulta Modalità con privilegi elevati.

Correzioni comuni per la "prigione della sandbox"

"Strumento X bloccato dai criteri degli strumenti della sandbox"

Chiavi da correggere (scegline una):

Disabilita la sandbox: agents.defaults.sandbox.mode=off (oppure, per agente, agents.list[].sandbox.mode=off)
Consenti lo strumento all'interno della sandbox:
- rimuovilo da tools.sandbox.tools.deny (oppure, per agente, agents.list[].tools.sandbox.tools.deny)
- oppure aggiungilo a tools.sandbox.tools.allow (o all'elenco dei consentiti per agente)
Controlla openclaw logs per la voce agents/tool-policy. Registra la modalità della sandbox e indica se lo strumento è stato bloccato dalla regola di autorizzazione o di negazione.

"Pensavo che questa fosse la sessione principale: perché è isolata nella sandbox?"

In modalità "non-main", le chiavi di gruppo/canale non sono principali. Usa la chiave della sessione principale (mostrata da sandbox explain) oppure imposta la modalità su "off".

Contenuti correlati

Isolamento nella sandbox -- riferimento completo sulla sandbox (modalità, ambiti, backend, immagini)
Sandbox e strumenti multi-agente -- sostituzioni per agente e precedenza
Modalità con privilegi elevati

Was this useful?