Sandboxing

​

Cosa viene sandboxato

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

• 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à

​

Ambito

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

​

Backend

• "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.

​

Scegliere un backend

​

Backend Docker

​

Backend 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

{
  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",
        },
      },
    },
  },
}

• 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

​

Ciclo di vita OpenShell

• 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

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

​

Accesso al workspace

• 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

​

Mount bind personalizzati

• 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).

{
  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

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

​

setupCommand (configurazione una tantum del container)

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

​

Criteri degli strumenti e vie di fuga

• 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?”.

​

Override multi-agente

​

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