​

Sandbox vs criteri degli strumenti vs Elevated

1. Sandbox (agents.defaults.sandbox.* / agents.list[].sandbox.*) decide dove vengono eseguiti gli strumenti (Docker o host).
2. Criteri degli strumenti (tools.*, tools.sandbox.tools.*, agents.list[].tools.*) decidono quali strumenti sono disponibili/consentiti.
3. Elevated (tools.elevated.*, agents.list[].tools.elevated.*) è una via di fuga solo per exec per eseguire fuori dalla sandbox quando sei in sandbox (gateway per impostazione predefinita, oppure node quando il target exec è configurato su node).

​

Debug rapido

openclaw sandbox explain
openclaw sandbox explain --session agent:main:main
openclaw sandbox explain --agent work
openclaw sandbox explain --json

• modalità/ambito/accesso workspace effettivi della sandbox
• se la sessione è attualmente in sandbox (main vs non-main)
• allow/deny effettivi degli strumenti nella sandbox (e se provengono da agent/global/default)
• gate elevated e percorsi chiave per la correzione

​

Sandbox: dove vengono eseguiti gli strumenti

• "off": tutto viene eseguito sull’host.
• "non-main": solo le sessioni non-main sono in sandbox (la comune “sorpresa” per gruppi/canali).
• "all": tutto è in sandbox.

​

Bind mount (controllo rapido di sicurezza)

• docker.binds buca il filesystem della sandbox: tutto ciò che monti è visibile all’interno del container con la modalità che imposti (:ro o :rw).
• Il valore predefinito è lettura-scrittura se ometti la modalità; preferisci :ro per codice sorgente/segreti.
• scope: "shared" ignora i bind per-agent (si applicano solo i bind globali).
• OpenClaw convalida le sorgenti bind due volte: prima sul percorso sorgente normalizzato, poi di nuovo dopo la risoluzione tramite l’antenato esistente più profondo. Le evasioni tramite symlink-parent non aggirano i controlli dei percorsi bloccati o delle radici consentite.
• I percorsi leaf inesistenti vengono comunque controllati in modo sicuro. Se /workspace/alias-out/new-file viene risolto tramite un parent con symlink verso un percorso bloccato o fuori dalle radici consentite configurate, il bind viene rifiutato.
• Fare bind di /var/run/docker.sock consegna di fatto il controllo dell’host alla sandbox; fallo solo intenzionalmente.
• L’accesso al workspace (workspaceAccess: "ro"/"rw") è indipendente dalle modalità di bind.

​

Criteri degli strumenti: quali strumenti esistono/sono invocabili

• Profilo strumenti: tools.profile e agents.list[].tools.profile (allowlist di base)
• Profilo strumenti del provider: tools.byProvider[provider].profile e agents.list[].tools.byProvider[provider].profile
• Criteri strumenti globali/per-agent: tools.allow/tools.deny e agents.list[].tools.allow/agents.list[].tools.deny
• Criteri strumenti del provider: tools.byProvider[provider].allow/deny e agents.list[].tools.byProvider[provider].allow/deny
• Criteri strumenti della sandbox (si applicano solo in sandbox): tools.sandbox.tools.allow/tools.sandbox.tools.deny e agents.list[].tools.sandbox.tools.*

• deny vince sempre.
• Se allow non è vuoto, tutto il resto viene trattato come bloccato.
• I criteri degli strumenti sono il blocco rigido: /exec non può aggirare uno strumento exec negato.
• /exec cambia solo i valori predefiniti della sessione per i mittenti autorizzati; non concede accesso agli strumenti. Le chiavi degli strumenti del provider accettano sia provider (ad esempio google-antigravity) sia provider/model (ad esempio openai/gpt-5.4).

​

Gruppi di strumenti (shorthand)

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

• 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: cron, gateway
• group:messaging: message
• group:nodes: nodes
• group:agents: agents_list
• group:media: image, image_generate, video_generate, tts
• group:openclaw: tutti gli strumenti OpenClaw integrati (esclude i plugin provider)

​

Elevated: “esegui sull’host” solo per exec

• Se sei in sandbox, /elevated on (o exec con elevated: true) viene eseguito fuori dalla sandbox (le approvazioni possono comunque applicarsi).
• Usa /elevated full per saltare le approvazioni exec per la sessione.
• Se stai già eseguendo direttamente, elevated è di fatto un no-op (comunque soggetto a gate).
• Elevated non è limitato allo scope delle Skills e non sovrascrive allow/deny degli strumenti.
• Elevated non concede override arbitrari cross-host da host=auto; segue le normali regole del target exec e preserva node solo quando il target configurato/di sessione è già node.
• /exec è separato da elevated. Regola solo i valori predefiniti exec per sessione per i mittenti autorizzati.

• Abilitazione: tools.elevated.enabled (e facoltativamente agents.list[].tools.elevated.enabled)
• Allowlist mittenti: tools.elevated.allowFrom.<provider> (e facoltativamente agents.list[].tools.elevated.allowFrom.<provider>)

​

Correzioni comuni per la “prigione della sandbox"

​

"Lo strumento X è bloccato dai criteri degli strumenti della sandbox”

• Disabilita la sandbox: agents.defaults.sandbox.mode=off (o per-agent agents.list[].sandbox.mode=off)
• Consenti lo strumento all’interno della sandbox:
  • rimuovilo da tools.sandbox.tools.deny (o per-agent agents.list[].tools.sandbox.tools.deny)
  • oppure aggiungilo a tools.sandbox.tools.allow (o all’allow per-agent)

​

“Pensavo che fosse main, perché è in sandbox?”

​

Vedi anche

• Sandboxing — riferimento completo della sandbox (modalità, ambiti, backend, immagini)
• Sandbox e strumenti multi-agent — override per-agent e precedenza
• Elevated Mode