Sandboxing

​

Cosa viene eseguito nella sandbox

• Esecuzione degli strumenti: exec, read, write, edit, apply_patch, process e così via.
• Il browser opzionale eseguito nella sandbox (agents.defaults.sandbox.browser).

• Il processo Gateway stesso.
• Qualsiasi strumento esplicitamente autorizzato a essere eseguito all’esterno della sandbox tramite tools.elevated. L’esecuzione con privilegi elevati elude la sandbox e utilizza il percorso di uscita configurato (gateway per impostazione predefinita oppure node quando la destinazione di esecuzione è node). Se la sandbox è disattivata, tools.elevated non cambia nulla, poiché l’esecuzione avviene già sull’host. Consulta Modalità con privilegi elevati.

​

Modalità, ambito e backend

• off: nessuna sandbox.
• non-main: esegue nella sandbox ogni sessione tranne la sessione principale dell’agente. La chiave della sessione principale è sempre agent:<agentId>:main (oppure global quando session.scope è "global"); non è configurabile. Le sessioni di gruppo/canale utilizzano chiavi proprie, quindi sono sempre considerate non principali e vengono eseguite nella sandbox.
• all: ogni sessione viene eseguita in una sandbox.

• agent: un contenitore per agente.
• session: un contenitore per sessione.
• shared: un contenitore condiviso da tutte le sessioni eseguite nella sandbox (con questo ambito, le sostituzioni docker/ssh/browser per agente vengono ignorate).

​

Backend Docker

​

Browser nella sandbox

• Il browser nella sandbox si avvia automaticamente (assicurando che CDP sia raggiungibile) quando lo strumento browser ne ha bisogno. Configuralo tramite agents.defaults.sandbox.browser.autoStart (valore predefinito true) e autoStartTimeoutMs (valore predefinito 12 s).
• I contenitori del browser nella sandbox utilizzano una rete Docker dedicata (openclaw-sandbox-browser) invece della rete globale bridge. Configurala con agents.defaults.sandbox.browser.network.
• agents.defaults.sandbox.browser.cdpSourceRange limita l’ingresso CDP al confine del contenitore tramite un elenco CIDR consentito (ad esempio 172.21.0.1/32).
• Per impostazione predefinita, l’accesso dell’osservatore noVNC è protetto da password; OpenClaw genera un URL con token di breve durata che fornisce una pagina di avvio locale e apre noVNC con la password nel frammento dell’URL, non nella stringa di query o nei log delle intestazioni.
• agents.defaults.sandbox.browser.allowHostControl (valore predefinito false) consente alle sessioni nella sandbox di selezionare esplicitamente il browser dell’host come destinazione.
• Elenchi consentiti opzionali controllano target: "custom": allowedControlUrls, allowedControlHosts, allowedControlPorts.

​

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",
          // In alternativa, usa SecretRefs o contenuti inline invece dei file locali:
          // 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" },
        },
      },
    },
  },
}

• Ciclo di vita: OpenClaw crea una radice remota per ambito in sandbox.ssh.workspaceRoot. Al primo utilizzo dopo la creazione o la ricreazione, inizializza una sola volta lo spazio di lavoro remoto a partire da quello locale. Successivamente, exec, read, write, edit, apply_patch, le letture dei contenuti multimediali dei prompt e la predisposizione dei contenuti multimediali in ingresso operano direttamente sullo spazio di lavoro remoto tramite SSH. OpenClaw non sincronizza automaticamente le modifiche remote con lo spazio di lavoro locale.
• Materiale di autenticazione: identityFile/certificateFile/knownHostsFile fanno riferimento a file locali esistenti. identityData/certificateData/knownHostsData accettano stringhe inline o SecretRefs, risolti tramite la normale istantanea del runtime dei segreti, scritti in file temporanei con modalità 0600 ed eliminati al termine della sessione SSH. Se per lo stesso elemento sono impostate sia una variante *File sia una variante *Data, per quella sessione prevale *Data.
• Conseguenze del modello remoto canonico: dopo l’inizializzazione iniziale, lo spazio di lavoro SSH remoto diventa lo stato effettivo della sandbox. Le modifiche locali sull’host apportate all’esterno di OpenClaw dopo la fase di inizializzazione non sono visibili in remoto finché non ricrei la sandbox. openclaw sandbox recreate elimina la radice remota per ambito ed esegue nuovamente l’inizializzazione dal contenuto locale al successivo utilizzo. La sandbox del browser non è supportata su questo backend e le impostazioni sandbox.docker.* non si applicano.

​

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

​

Accesso allo spazio di lavoro

​

Montaggi bind personalizzati

{
  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

• openclaw sandbox list mostra i contenitori sandbox, lo stato, la corrispondenza dell’immagine, l’età, il tempo di inattività e la sessione o l’agente associato.
• openclaw sandbox explain [--session <key>] [--agent <id>] esamina la modalità sandbox effettiva, lo spazio di lavoro dell’host, la directory di lavoro dell’ambiente di esecuzione, i montaggi Docker, i criteri degli strumenti e le chiavi di configurazione per la correzione. Il campo workspaceRoot resta la radice sandbox configurata; effectiveHostWorkspaceRoot indica dove risiede effettivamente lo spazio di lavoro attivo.
• openclaw sandbox recreate [--all | --session <key> | --agent <id>] [--browser] [--force] rimuove contenitori e ambienti affinché vengano ricreati con la configurazione corrente al successivo utilizzo.
• Consultare Sandbox, criteri degli strumenti ed esecuzione con privilegi elevati per il modello mentale che spiega perché un’operazione viene bloccata.

​

Sostituzioni per più agenti

​

Esempio minimo di abilitazione

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

​

Pagine correlate

• Sandbox e strumenti multi-agente — sostituzioni specifiche per agente e precedenza
• OpenShell — configurazione del backend sandbox gestito, modalità dell’area di lavoro e riferimento della configurazione
• Configurazione della sandbox
• Sandbox, criteri degli strumenti e modalità con privilegi elevati a confronto — risoluzione del problema “perché è bloccato?”
• Sicurezza