Sandboxing

OpenClaw può eseguire gli strumenti all'interno di un backend sandbox per ridurre il raggio d'impatto. L'uso della sandbox è disattivato per impostazione predefinita ed è controllato da agents.defaults.sandbox (globale) o agents.list[].sandbox (per agente). Il processo Gateway rimane sempre sull'host; quando la sandbox è abilitata, solo l'esecuzione degli strumenti viene spostata al suo interno.

Cosa viene eseguito nella sandbox

• Esecuzione degli strumenti: exec, read, write, edit, apply_patch, process e così via.
• Il browser opzionale eseguito nella sandbox (agents.defaults.sandbox.browser).

Non vengono eseguiti nella sandbox:

• Il processo Gateway stesso.
• Qualsiasi strumento esplicitamente autorizzato a essere eseguito all'esterno della sandbox tramite tools.elevated. L'esecuzione con privilegi elevati elude la sandbox e utilizza il percorso di uscita configurato (gateway per impostazione predefinita oppure node quando la destinazione di esecuzione è node). Se la sandbox è disattivata, tools.elevated non cambia nulla, poiché l'esecuzione avviene già sull'host. Consulta Modalità con privilegi elevati.

Modalità, ambito e backend

Tre impostazioni indipendenti controllano il comportamento della sandbox:

La modalità controlla quando viene applicata la sandbox:

• off: nessuna sandbox.
• non-main: esegue nella sandbox ogni sessione tranne la sessione principale dell'agente. La chiave della sessione principale è sempre agent:<agentId>:main (oppure global quando session.scope è "global"); non è configurabile. Le sessioni di gruppo/canale utilizzano chiavi proprie, quindi sono sempre considerate non principali e vengono eseguite nella sandbox.
• all: ogni sessione viene eseguita in una sandbox.

L'ambito controlla quanti contenitori/ambienti vengono creati:

• agent: un contenitore per agente.
• session: un contenitore per sessione.
• shared: un contenitore condiviso da tutte le sessioni eseguite nella sandbox (con questo ambito, le sostituzioni docker/ssh/browser per agente vengono ignorate).

Il backend controlla quale runtime esegue gli strumenti nella sandbox. La configurazione specifica per SSH si trova in agents.defaults.sandbox.ssh; quella specifica per OpenShell si trova in plugins.entries.openshell.config.

Backend Docker

Docker è il backend predefinito quando viene abilitata la sandbox. Esegue localmente gli strumenti e i browser nella sandbox tramite il socket del daemon Docker (/var/run/docker.sock); l'isolamento è fornito dagli spazi dei nomi Docker.

Valori predefiniti: network: "none" (nessun traffico in uscita), readOnlyRoot: true, capDrop: ["ALL"], immagine openclaw-sandbox:bookworm-slim.

Per rendere disponibili le GPU dell'host, imposta agents.defaults.sandbox.docker.gpus (o la sostituzione per agente) su un valore come "all" o "device=GPU-uuid". Il valore viene passato al flag --gpus di Docker e richiede un runtime host compatibile, come NVIDIA Container Toolkit.

Browser nella sandbox

• Il browser nella sandbox si avvia automaticamente (assicurando che CDP sia raggiungibile) quando lo strumento browser ne ha bisogno. Configuralo tramite agents.defaults.sandbox.browser.autoStart (valore predefinito true) e autoStartTimeoutMs (valore predefinito 12 s).
• I contenitori del browser nella sandbox utilizzano una rete Docker dedicata (openclaw-sandbox-browser) invece della rete globale bridge. Configurala con agents.defaults.sandbox.browser.network.
• agents.defaults.sandbox.browser.cdpSourceRange limita l'ingresso CDP al confine del contenitore tramite un elenco CIDR consentito (ad esempio 172.21.0.1/32).
• Per impostazione predefinita, l'accesso dell'osservatore noVNC è protetto da password; OpenClaw genera un URL con token di breve durata che fornisce una pagina di avvio locale e apre noVNC con la password nel frammento dell'URL, non nella stringa di query o nei log delle intestazioni.
• agents.defaults.sandbox.browser.allowHostControl (valore predefinito false) consente alle sessioni nella sandbox di selezionare esplicitamente il browser dell'host come destinazione.
• Elenchi consentiti opzionali controllano target: "custom": allowedControlUrls, allowedControlHosts, allowedControlPorts.

Backend SSH

Usa backend: "ssh" per eseguire nella sandbox exec, gli strumenti per i file e le letture multimediali su una macchina arbitraria accessibile tramite SSH.

{  agents: {    defaults: {      sandbox: {        mode: "all",        backend: "ssh",        scope: "session",        workspaceAccess: "rw",        ssh: {          target: "user@gateway-host:22",          workspaceRoot: "/tmp/openclaw-sandboxes",          strictHostKeyChecking: true,          updateHostKeys: true,          identityFile: "~/.ssh/id_ed25519",          certificateFile: "~/.ssh/id_ed25519-cert.pub",          knownHostsFile: "~/.ssh/known_hosts",          // In alternativa, usa SecretRefs o contenuti inline invece dei file locali:          // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" },          // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" },          // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" },        },      },    },  },}

Valori predefiniti: command: "ssh", workspaceRoot: "/tmp/openclaw-sandboxes", strictHostKeyChecking: true, updateHostKeys: true.

• Ciclo di vita: OpenClaw crea una radice remota per ambito in sandbox.ssh.workspaceRoot. Al primo utilizzo dopo la creazione o la ricreazione, inizializza una sola volta lo spazio di lavoro remoto a partire da quello locale. Successivamente, exec, read, write, edit, apply_patch, le letture dei contenuti multimediali dei prompt e la predisposizione dei contenuti multimediali in ingresso operano direttamente sullo spazio di lavoro remoto tramite SSH. OpenClaw non sincronizza automaticamente le modifiche remote con lo spazio di lavoro locale.
• Materiale di autenticazione: identityFile/certificateFile/knownHostsFile fanno riferimento a file locali esistenti. identityData/certificateData/knownHostsData accettano stringhe inline o SecretRefs, risolti tramite la normale istantanea del runtime dei segreti, scritti in file temporanei con modalità 0600 ed eliminati al termine della sessione SSH. Se per lo stesso elemento sono impostate sia una variante *File sia una variante *Data, per quella sessione prevale *Data.
• Conseguenze del modello remoto canonico: dopo l'inizializzazione iniziale, lo spazio di lavoro SSH remoto diventa lo stato effettivo della sandbox. Le modifiche locali sull'host apportate all'esterno di OpenClaw dopo la fase di inizializzazione non sono visibili in remoto finché non ricrei la sandbox. openclaw sandbox recreate elimina la radice remota per ambito ed esegue nuovamente l'inizializzazione dal contenuto locale al successivo utilizzo. La sandbox del browser non è supportata su questo backend e le impostazioni sandbox.docker.* non si applicano.

Backend OpenShell

Usa backend: "openshell" per eseguire gli strumenti in una sandbox all'interno di un ambiente remoto gestito da OpenShell. OpenShell riutilizza lo stesso trasporto SSH e lo stesso bridge del file system remoto del backend SSH generico, aggiungendo il ciclo di vita di OpenShell (sandbox create/get/delete/ssh-config) e una modalità opzionale di sincronizzazione dello spazio di lavoro mirror.

{  agents: {    defaults: {      sandbox: {        mode: "all",        backend: "openshell",        scope: "session",        workspaceAccess: "rw",      },    },  },  plugins: {    entries: {      openshell: {        enabled: true,        config: {          from: "openclaw",          mode: "remote", // mirror | remote        },      },    },  },}

mode: "mirror" (valore predefinito) mantiene canonico lo spazio di lavoro locale: OpenClaw sincronizza il contenuto locale nella sandbox prima di exec e lo sincronizza nuovamente in locale al termine. mode: "remote" inizializza una sola volta lo spazio di lavoro remoto dal contenuto locale, quindi esegue exec/read/write/edit/apply_patch direttamente sullo spazio di lavoro remoto senza sincronizzare le modifiche in locale; le modifiche locali successive all'inizializzazione non sono visibili finché non esegui openclaw sandbox recreate. Con scope: "agent" o scope: "shared", lo spazio di lavoro remoto viene condiviso nello stesso ambito. Limitazioni attuali: la sandbox del browser non è ancora supportata e sandbox.docker.binds non si applica a questo backend.

openclaw sandbox list/recreate/prune trattano tutti i runtime OpenShell allo stesso modo dei runtime Docker; la logica di eliminazione è consapevole del backend.

Per i prerequisiti completi, il riferimento alla configurazione, il confronto tra le modalità dello spazio di lavoro e i dettagli sul ciclo di vita, consulta OpenShell.

Accesso allo spazio di lavoro

agents.defaults.sandbox.workspaceAccess controlla ciò che la sandbox può vedere:

Con il backend OpenShell, la modalità mirror continua a usare lo spazio di lavoro locale come fonte canonica tra le esecuzioni di exec, la modalità remote usa lo spazio di lavoro OpenShell remoto come fonte canonica dopo il popolamento iniziale e workspaceAccess: "ro"/"none" continua a limitare allo stesso modo le operazioni di scrittura.

I contenuti multimediali in ingresso vengono copiati nello spazio di lavoro sandbox attivo (media/inbound/*).

Montaggi bind personalizzati

agents.defaults.sandbox.docker.binds monta nel contenitore directory aggiuntive dell'host. Formato: host:container:mode (ad esempio, "/home/user/source:/source:rw").

I bind globali e quelli per agente vengono uniti, non sostituiti. Con scope: "shared", i bind per agente vengono ignorati.

agents.defaults.sandbox.browser.binds monta directory aggiuntive dell'host solo nel contenitore del browser sandbox. Quando è impostato (anche su []), sostituisce docker.binds per il contenitore del browser; quando è omesso, il contenitore del browser usa docker.binds come ripiego.

{  agents: {    defaults: {      sandbox: {        docker: {          binds: ["/home/user/source:/source:ro", "/var/data/myapp:/data:ro"],        },      },    },    list: [      {        id: "build",        sandbox: {          docker: {            binds: ["/mnt/cache:/cache:rw"],          },        },      },    ],  },}

Immagini e configurazione

Immagine Docker predefinita: openclaw-sandbox:bookworm-slim

scripts/sandbox-setup.sh

docker build -t openclaw-sandbox:bookworm-slim - <<'DOCKERFILE'FROM debian:bookworm-slimENV DEBIAN_FRONTEND=noninteractiveRUN apt-get update && apt-get install -y --no-install-recommends \  bash ca-certificates curl git jq python3 ripgrep \  && rm -rf /var/lib/apt/lists/*RUN useradd --create-home --shell /bin/bash sandboxUSER sandboxWORKDIR /home/sandboxCMD ["sleep", "infinity"]DOCKERFILE

scripts/sandbox-common-setup.sh

scripts/sandbox-browser-setup.sh

Per impostazione predefinita, i contenitori della sandbox Docker vengono eseguiti senza rete. Per modificare questa impostazione, usare agents.defaults.sandbox.docker.network.

Le installazioni Docker e il Gateway in contenitore sono descritti qui: Docker

Per le distribuzioni del Gateway Docker, scripts/docker/setup.sh può inizializzare la configurazione della sandbox. Impostare OPENCLAW_SANDBOX=1 (oppure true/yes/on) per abilitare questo percorso. Per modificare la posizione del socket, usare OPENCLAW_DOCKER_SOCKET. Configurazione completa e riferimento delle variabili di ambiente: Docker.

setupCommand (configurazione una tantum del contenitore)

setupCommand viene eseguito una sola volta dopo la creazione del contenitore sandbox, non a ogni esecuzione. Viene eseguito all'interno del contenitore tramite sh -lc.

Percorsi:

• Globale: agents.defaults.sandbox.docker.setupCommand
• Per agente: agents.list[].sandbox.docker.setupCommand

Criteri degli strumenti e vie di fuga

I criteri di autorizzazione e negazione degli strumenti vengono comunque applicati prima delle regole della sandbox. Se uno strumento è negato a livello globale o per agente, la sandbox non lo rende nuovamente disponibile.

tools.elevated è una via di fuga esplicita che esegue exec all'esterno della sandbox, nel gateway per impostazione predefinita oppure nel node quando la destinazione di esecuzione è node. Le direttive /exec si applicano solo ai mittenti autorizzati e persistono per la sessione; per disabilitare completamente exec, usare il criterio di negazione degli strumenti (consultare Sandbox, criteri degli strumenti ed esecuzione con privilegi elevati).

Debug:

• openclaw sandbox list mostra i contenitori sandbox, lo stato, la corrispondenza dell'immagine, l'età, il tempo di inattività e la sessione o l'agente associato.
• openclaw sandbox explain [--session <key>] [--agent <id>] esamina la modalità sandbox effettiva, lo spazio di lavoro dell'host, la directory di lavoro dell'ambiente di esecuzione, i montaggi Docker, i criteri degli strumenti e le chiavi di configurazione per la correzione. Il campo workspaceRoot resta la radice sandbox configurata; effectiveHostWorkspaceRoot indica dove risiede effettivamente lo spazio di lavoro attivo.
• openclaw sandbox recreate [--all | --session <key> | --agent <id>] [--browser] [--force] rimuove contenitori e ambienti affinché vengano ricreati con la configurazione corrente al successivo utilizzo.
• Consultare Sandbox, criteri degli strumenti ed esecuzione con privilegi elevati per il modello mentale che spiega perché un'operazione viene bloccata.

Sostituzioni per più agenti

Ogni agente può sostituire le impostazioni della sandbox e degli strumenti: agents.list[].sandbox e agents.list[].tools, oltre a agents.list[].tools.sandbox.tools per i criteri degli strumenti della sandbox. Consultare Sandbox e strumenti multi-agente per l'ordine di precedenza.

Esempio minimo di abilitazione

{  agents: {    defaults: {      sandbox: {        mode: "non-main",        scope: "session",        workspaceAccess: "none",      },    },  },}

Pagine correlate

• Sandbox e strumenti multi-agente -- sostituzioni specifiche per agente e precedenza
• OpenShell -- configurazione del backend sandbox gestito, modalità dell'area di lavoro e riferimento della configurazione
• Configurazione della sandbox
• Sandbox, criteri degli strumenti e modalità con privilegi elevati a confronto -- risoluzione del problema "perché è bloccato?"
• Sicurezza