Isolamento in sandbox

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

Cosa viene isolato in sandbox

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

Non isolato in sandbox:

• Il processo Gateway stesso.
• Qualsiasi strumento autorizzato esplicitamente a essere eseguito fuori dalla sandbox (ad es. tools.elevated).
  • Elevated exec bypassa il sandboxing e usa il percorso di escape configurato (gateway per impostazione predefinita, oppure node quando la destinazione 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 isolate in sandbox.

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 sotto agents.defaults.sandbox.ssh. La configurazione specifica per OpenShell si trova sotto plugins.entries.openshell.config.

Scelta di 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 in sandbox localmente tramite il socket del demone Docker (/var/run/docker.sock). L'isolamento dei 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, ad 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 isoli in sandbox exec, strumenti file e letture media 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 isoli gli strumenti in sandbox in un ambiente remoto gestito da OpenShell. Per la guida completa alla configurazione, il riferimento di configurazione e il confronto delle modalità workspace, vedi la pagina OpenShell dedicata.

OpenShell riusa lo stesso trasporto SSH principale 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 rimane 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 esegue una sola volta il seed del workspace remoto 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 l'ambiente isolato come un ambiente di esecuzione temporaneo. Scegli remote se consideri l'ambiente isolato come il vero spazio di lavoro.

Ciclo di vita OpenShell

Gli ambienti isolati OpenShell sono comunque gestiti tramite il normale ciclo di vita degli ambienti isolati:

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

Per la modalità remote, la ricreazione è particolarmente importante:

• la ricreazione elimina lo spazio di lavoro remoto canonico per quell'ambito
• l'utilizzo successivo inizializza un nuovo spazio di lavoro remoto dallo spazio di lavoro locale

Per la modalità mirror, la ricreazione reimposta principalmente l'ambiente di esecuzione remoto perché lo spazio di lavoro locale rimane comunque canonico.

Accesso allo spazio di lavoro

agents.defaults.sandbox.workspaceAccess controlla cosa può vedere l'ambiente isolato:

Con il backend OpenShell:

• la modalità mirror usa ancora lo spazio di lavoro locale come fonte canonica tra i turni exec
• la modalità remote usa lo spazio di lavoro 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 nello spazio di lavoro dell'ambiente isolato attivo (media/inbound/*).

Montaggi bind personalizzati

agents.defaults.sandbox.docker.binds monta directory host aggiuntive nel contenitore. 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 contenitore del browser dell'ambiente isolato.

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

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

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

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

Per le distribuzioni del Gateway Docker, scripts/docker/setup.sh può inizializzare la configurazione dell'ambiente isolato. Imposta OPENCLAW_SANDBOX=1 (o true/yes/on) per abilitare quel percorso. Puoi sovrascrivere la posizione del socket con OPENCLAW_DOCKER_SOCKET. Configurazione completa e riferimento delle variabili d'ambiente: Docker.

setupCommand (configurazione una tantum del contenitore)

setupCommand viene eseguito una volta dopo la creazione del contenitore dell'ambiente isolato (non a ogni esecuzione). Viene eseguito dentro il 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/negazione degli strumenti continuano ad applicarsi prima delle regole della sandbox. Se uno strumento viene negato globalmente o per agente, la sandbox non lo rende di nuovo disponibile.

tools.elevated è una via di fuga esplicita che esegue exec fuori dalla sandbox (gateway per impostazione predefinita, oppure node quando la destinazione di esecuzione è node). Le direttive /exec si applicano solo ai mittenti autorizzati e persistono per sessione; per disabilitare completamente exec, usa la negazione nei criteri degli strumenti (vedi Sandbox vs criteri degli strumenti 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 criteri degli strumenti vs Elevated per il modello mentale di "perché è bloccato?".

Mantieni tutto bloccato.

Override multi-agente

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

Esempio minimo di abilitazione

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

Correlati

• Sandbox e strumenti multi-agente — override per agente e precedenza
• OpenShell — configurazione del backend sandbox gestito, modalità workspace e riferimento di configurazione
• Configurazione della sandbox
• Sandbox vs criteri degli strumenti vs Elevated — debug di "perché è bloccato?"
• Sicurezza