Isolamento in sandbox

OpenClaw può eseguire strumenti all'interno di backend sandbox per ridurre il raggio d'azione. Questo è facoltativo 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 eseguito in sandbox

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

Non in sandbox:

• Il processo Gateway stesso.
• Qualsiasi strumento esplicitamente autorizzato a essere eseguito fuori dalla sandbox (ad es. tools.elevated).
  • L'exec elevato 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 cambia 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 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.

# 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 sandbox localmente tramite il socket del daemon Docker (/var/run/docker.sock). L'isolamento dei container sandbox è determinato dai namespace Docker.

Per esporre GPU 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 esegua in sandbox exec, strumenti file e 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 esegua 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 core e lo stesso bridge 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 facoltativa 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 indietro 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 lo spazio di lavoro reale.

# Ciclo di vita di 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 pruning è consapevole del backend

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

• la ricreazione elimina lo spazio di lavoro remoto canonico per quello scope
• 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 resta comunque canonico.

# Accesso allo spazio di lavoro

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

Con il backend OpenShell:

• la modalità mirror continua a usare lo spazio di lavoro locale come sorgente canonica tra i turni di exec
• la modalità remote usa lo spazio di lavoro OpenShell remoto come sorgente 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 sandbox attivo (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 sandbox.

• Quando è impostato (incluso []), sostituisce agents.defaults.sandbox.docker.binds per il container del browser.
• Quando è omesso, il container del browser usa come fallback 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-slim
ENV DEBIAN_FRONTEND=noninteractive
RUN 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 sandbox
USER sandbox
WORKDIR /home/sandbox
CMD ["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 sono qui: Docker

Per distribuzioni 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 env: Docker.

# setupCommand (configurazione del container una tantum)

setupCommand viene eseguito una volta dopo la creazione del container sandbox (non a ogni esecuzione). Viene eseguito all'interno del 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 di autorizzazione/blocco degli strumenti si applicano comunque prima delle regole della sandbox. Se uno strumento è bloccato globalmente o per agente, la sandbox non lo riabilita.

tools.elevated è una via di fuga esplicita che esegue exec fuori dalla sandbox (gateway per impostazione predefinita, o node quando la destinazione di exec è node). Le direttive /exec si applicano solo ai mittenti autorizzati e persistono per sessione; per disabilitare in modo rigido exec, usa il blocco tramite criterio degli strumenti (vedi Sandbox vs criteri degli strumenti vs privilegi elevati).

Debug:

• Usa openclaw sandbox explain per ispezionare la modalità sandbox effettiva, il criterio degli strumenti e le chiavi di configurazione per la correzione.
• Vedi Sandbox vs criteri degli strumenti vs privilegi elevati per il modello mentale di "perché è bloccato?".

Mantienilo bloccato.

# Override multi-agente

Ogni agente può sovrascrivere sandbox + strumenti: agents.list[].sandbox e agents.list[].tools (più agents.list[].tools.sandbox.tools per il criterio degli strumenti della sandbox). Vedi 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à dell'area di lavoro e riferimento di configurazione
• Configurazione della sandbox
• Sandbox vs criteri degli strumenti vs privilegi elevati — debug di "perché è bloccato?"
• Sicurezza