Sandboxing

OpenClaw può eseguire strumenti all'interno di backend sandbox per ridurre il raggio d'impatto. Questo è opzionale ed è controllato dalla configurazione (agents.defaults.sandbox o agents.list[].sandbox). Se il sandboxing è disattivato, gli strumenti vengono eseguiti sull'host. Il Gateway resta sull'host; l'esecuzione degli strumenti avviene in una sandbox isolata quando è abilitata.

Cosa viene sandboxato

• Esecuzione degli strumenti (exec, read, write, edit, apply_patch, process, ecc.).
• Browser sandboxato opzionale (agents.defaults.sandbox.browser).

Non sandboxato:

• Il processo Gateway stesso.
• Qualsiasi strumento esplicitamente autorizzato a essere eseguito fuori dalla sandbox (ad es. tools.elevated).
  • Elevated exec aggira il sandboxing e usa il percorso di escape configurato (gateway per impostazione predefinita, oppure node quando il target exec è node).
  • Se il sandboxing è disattivato, tools.elevated non modifica l'esecuzione (già sull'host). Vedi Modalità elevata.

Modalità

agents.defaults.sandbox.mode controlla quando viene usato il sandboxing:

Ambito

agents.defaults.sandbox.scope controlla quanti container vengono creati:

• "agent" (predefinito): un container per agente.
• "session": un container per sessione.
• "shared": un container condiviso da tutte le sessioni sandboxate.

Backend

agents.defaults.sandbox.backend controlla quale runtime fornisce la sandbox:

• "docker" (predefinito quando il sandboxing è abilitato): runtime sandbox locale basato su Docker.
• "ssh": runtime sandbox remoto generico basato su SSH.
• "openshell": runtime sandbox basato su OpenShell.

La configurazione specifica per SSH si trova in agents.defaults.sandbox.ssh. La configurazione specifica per OpenShell si trova in plugins.entries.openshell.config.

Scegliere un backend

Backend Docker

Il sandboxing è disattivato per impostazione predefinita. Se abiliti il sandboxing e non scegli un backend, OpenClaw usa il backend Docker. Esegue strumenti e browser sandboxati localmente tramite il socket del daemon Docker (/var/run/docker.sock). L'isolamento del container sandbox è determinato dai namespace Docker.

Per esporre le GPU dell'host alle sandbox Docker, imposta agents.defaults.sandbox.docker.gpus o l'override per agente agents.list[].sandbox.docker.gpus. Il valore viene passato al flag --gpus di Docker come argomento separato, per esempio "all" o "device=GPU-uuid", e richiede un runtime host compatibile come NVIDIA Container Toolkit.

Backend SSH

Usa backend: "ssh" quando vuoi che OpenClaw sandboxi exec, gli strumenti file e le letture multimediali su una macchina arbitraria accessibile via 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",          // Or use SecretRefs / inline contents instead of local files:          // 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" },        },      },    },  },}

Backend OpenShell

Usa backend: "openshell" quando vuoi che OpenClaw sandboxi gli strumenti in un ambiente remoto gestito da OpenShell. Per la guida completa alla configurazione, il riferimento di configurazione e il confronto tra modalità workspace, vedi la pagina OpenShell dedicata.

OpenShell riusa lo stesso trasporto SSH core e lo stesso bridge del filesystem remoto del backend SSH generico, e aggiunge il ciclo di vita specifico di OpenShell (sandbox create/get/delete, sandbox ssh-config) più la modalità workspace opzionale mirror.

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

Modalità OpenShell:

• mirror (predefinita): il workspace locale resta canonico. OpenClaw sincronizza i file locali in OpenShell prima di exec e sincronizza il workspace remoto dopo exec.
• remote: il workspace OpenShell è canonico dopo la creazione della sandbox. OpenClaw inizializza il workspace remoto una volta dal workspace locale, poi gli strumenti file ed exec vengono eseguiti direttamente sulla sandbox remota senza sincronizzare le modifiche indietro.

Modalità workspace

OpenShell ha due modelli di workspace. Questa è la parte che conta di più nella pratica.

Scegli mirror se consideri la sandbox un ambiente di esecuzione temporaneo. Scegli remote se consideri la sandbox il workspace reale.

Ciclo di vita OpenShell

Le sandbox OpenShell sono comunque gestite tramite il normale ciclo di vita della sandbox:

• openclaw sandbox list mostra i runtime OpenShell oltre ai runtime Docker
• openclaw sandbox recreate elimina il runtime corrente e consente a OpenClaw di ricrearlo al prossimo utilizzo
• anche la logica di prune è consapevole del backend

Per la modalità remote, recreate è particolarmente importante:

• recreate elimina il workspace remoto canonico per quell'ambito
• l'utilizzo successivo inizializza un nuovo workspace remoto dal workspace locale

Per la modalità mirror, recreate reimposta principalmente l'ambiente di esecuzione remoto perché il workspace locale rimane comunque canonico.

Accesso al workspace

agents.defaults.sandbox.workspaceAccess controlla cosa può vedere la sandbox:

Con il backend OpenShell:

• la modalità mirror usa ancora il workspace locale come fonte canonica tra i turni exec
• la modalità remote usa il workspace OpenShell remoto come fonte canonica dopo l'inizializzazione iniziale
• workspaceAccess: "ro" e "none" continuano a limitare il comportamento di scrittura nello stesso modo

I media in ingresso vengono copiati nel workspace della sandbox attiva (media/inbound/*).

Mount bind personalizzati

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

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

agents.defaults.sandbox.browser.binds monta directory host aggiuntive solo nel container del browser della sandbox.

• Quando impostato (incluso []), sostituisce agents.defaults.sandbox.docker.binds per il container del browser.
• Quando omesso, il container del browser ripiega su agents.defaults.sandbox.docker.binds (compatibile con le versioni precedenti).

Esempio (sorgente in sola lettura + una directory dati extra):

{  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 container sandbox Docker vengono eseguiti senza rete. Sovrascrivi con agents.defaults.sandbox.docker.network.

Le installazioni Docker e il Gateway containerizzato si trovano qui: Docker

Per i deployment del Gateway Docker, scripts/docker/setup.sh può inizializzare la configurazione della sandbox. Imposta OPENCLAW_SANDBOX=1 (oppure true/yes/on) per abilitare quel percorso. Puoi sovrascrivere la posizione del socket con OPENCLAW_DOCKER_SOCKET. Configurazione completa e riferimento delle variabili di ambiente: Docker.

setupCommand (configurazione una tantum del container)

setupCommand viene eseguito una volta dopo la creazione del container sandbox (non a ogni esecuzione). Viene eseguito dentro il container 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 allow/deny degli strumenti si applicano comunque prima delle regole della sandbox. Se uno strumento viene negato globalmente o per agente, la sandbox non lo ripristina.

tools.elevated è una via di fuga esplicita che esegue exec fuori dalla sandbox (gateway per impostazione predefinita, oppure node quando la destinazione di exec è node). Le direttive /exec si applicano solo ai mittenti autorizzati e persistono per sessione; per disabilitare rigidamente exec, usa il deny dei criteri degli strumenti (vedi Sandbox vs Tool Policy vs Elevated).

Debug:

• Usa openclaw sandbox explain per ispezionare la modalità sandbox effettiva, i criteri degli strumenti e le chiavi di configurazione per la correzione.
• Consulta Sandbox vs Tool Policy vs Elevated per il modello mentale di "perché è bloccato?".

Mantieni la configurazione restrittiva.

Override multi-agente

Ogni agente può sovrascrivere sandbox + strumenti: agents.list[].sandbox e agents.list[].tools (più agents.list[].tools.sandbox.tools per i criteri degli strumenti della sandbox). Consulta Multi-Agent Sandbox & Tools per la precedenza.

Esempio minimo di abilitazione

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

Correlati

• Multi-Agent Sandbox & Tools — override per agente e precedenza
• OpenShell — configurazione del backend sandbox gestito, modalità workspace e riferimento della configurazione
• Configurazione della sandbox
• Sandbox vs Tool Policy vs Elevated — debug di "perché è bloccato?"
• Sicurezza