Isolamento in sandbox

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Cosa viene isolato in sandbox

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

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

​

Ambito

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

​

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.

​

Scelta di 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 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

​

Ciclo di vita OpenShell

• 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

• 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

​

Accesso allo spazio di lavoro

• 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

​

Montaggi bind personalizzati

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

{
  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 contenitore)

• 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 criteri degli strumenti 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

• 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