Vai al contenuto principale
Gestisci i runtime sandbox per l’esecuzione isolata degli agenti.

​
Panoramica

OpenClaw può eseguire agenti in runtime sandbox isolati per sicurezza. I comandi sandbox ti aiutano a ispezionare e ricreare questi runtime dopo aggiornamenti o modifiche di configurazione. Oggi questo di solito significa:
  • Container sandbox Docker
  • Runtime sandbox SSH quando agents.defaults.sandbox.backend = "ssh"
  • Runtime sandbox OpenShell quando agents.defaults.sandbox.backend = "openshell"
Per ssh e OpenShell remote, la ricreazione è più importante che con Docker:
  • l’area di lavoro remota è canonica dopo il seed iniziale
  • openclaw sandbox recreate elimina quell’area di lavoro remota canonica per l’ambito selezionato
  • l’uso successivo la inizializza di nuovo dall’area di lavoro locale corrente

​
Comandi

​
openclaw sandbox explain

Ispeziona la modalità, l’ambito e l’accesso all’area di lavoro sandbox effettivi, la policy degli strumenti sandbox e i gate elevati (con percorsi delle chiavi di configurazione per la correzione). 
openclaw sandbox explain
openclaw sandbox explain --session agent:main:main
openclaw sandbox explain --agent work
openclaw sandbox explain --json

​
openclaw sandbox list

Elenca tutti i runtime sandbox con il relativo stato e la configurazione. 
openclaw sandbox list
openclaw sandbox list --browser  # List only browser containers
openclaw sandbox list --json     # JSON output
L’output include:
  • Nome e stato del runtime
  • Backend (docker, openshell, ecc.)
  • Etichetta di configurazione e se corrisponde alla configurazione corrente
  • Età (tempo dalla creazione)
  • Tempo di inattività (tempo dall’ultimo utilizzo)
  • Sessione/agente associato

​
openclaw sandbox recreate

Rimuovi i runtime sandbox per forzarne la ricreazione con la configurazione aggiornata. 
openclaw sandbox recreate --all                # Recreate all containers
openclaw sandbox recreate --session main       # Specific session
openclaw sandbox recreate --agent mybot        # Specific agent
openclaw sandbox recreate --browser            # Only browser containers
openclaw sandbox recreate --all --force        # Skip confirmation
Opzioni:
  • --all: ricrea tutti i container sandbox
  • --session <key>: ricrea il container per una sessione specifica
  • --agent <id>: ricrea i container per un agente specifico
  • --browser: ricrea solo i container del browser
  • --force: salta la richiesta di conferma
I runtime vengono ricreati automaticamente al successivo utilizzo dell’agente.

​
Casi d’uso

​
Dopo l’aggiornamento di un’immagine Docker

# Pull new image
docker pull openclaw-sandbox:latest
docker tag openclaw-sandbox:latest openclaw-sandbox:bookworm-slim

# Update config to use new image
# Edit config: agents.defaults.sandbox.docker.image (or agents.list[].sandbox.docker.image)

# Recreate containers
openclaw sandbox recreate --all

​
Dopo la modifica della configurazione sandbox

# Edit config: agents.defaults.sandbox.* (or agents.list[].sandbox.*)

# Recreate to apply new config
openclaw sandbox recreate --all

​
Dopo la modifica del target SSH o del materiale di autenticazione SSH

# Edit config:
# - agents.defaults.sandbox.backend
# - agents.defaults.sandbox.ssh.target
# - agents.defaults.sandbox.ssh.workspaceRoot
# - agents.defaults.sandbox.ssh.identityFile / certificateFile / knownHostsFile
# - agents.defaults.sandbox.ssh.identityData / certificateData / knownHostsData

openclaw sandbox recreate --all
Per il backend ssh core, la ricreazione elimina la radice dell’area di lavoro remota per ambito sul target SSH. L’esecuzione successiva la inizializza di nuovo dall’area di lavoro locale.

​
Dopo la modifica della sorgente, della policy o della modalità OpenShell

# Edit config:
# - agents.defaults.sandbox.backend
# - plugins.entries.openshell.config.from
# - plugins.entries.openshell.config.mode
# - plugins.entries.openshell.config.policy

openclaw sandbox recreate --all
Per la modalità OpenShell remote, la ricreazione elimina l’area di lavoro remota canonica per quell’ambito. L’esecuzione successiva la inizializza di nuovo dall’area di lavoro locale.

​
Dopo la modifica di setupCommand

openclaw sandbox recreate --all
# or just one agent:
openclaw sandbox recreate --agent family

​
Solo per un agente specifico

# Update only one agent's containers
openclaw sandbox recreate --agent alfred

​
Perché è necessario

Quando aggiorni la configurazione sandbox:
  • I runtime esistenti continuano a funzionare con le vecchie impostazioni.
  • I runtime vengono eliminati solo dopo 24 ore di inattività.
  • Gli agenti usati regolarmente mantengono vivi i vecchi runtime a tempo indefinito.
Usa openclaw sandbox recreate per forzare la rimozione dei vecchi runtime. Verranno ricreati automaticamente con le impostazioni correnti quando saranno di nuovo necessari.
Preferisci openclaw sandbox recreate alla pulizia manuale specifica del backend. Usa il registro dei runtime del Gateway ed evita disallineamenti quando cambiano l’ambito o le chiavi di sessione.

​
Migrazione del registro

OpenClaw archivia i metadati dei runtime sandbox nel database di stato SQLite condiviso. Le installazioni più vecchie potrebbero avere ancora file di registro sandbox legacy:
  • ~/.openclaw/sandbox/containers.json
  • ~/.openclaw/sandbox/browsers.json
Alcuni aggiornamenti potrebbero anche avere uno shard JSON per container/browser sotto ~/.openclaw/sandbox/containers/ o ~/.openclaw/sandbox/browsers/. Le normali letture dei runtime sandbox non riscrivono queste sorgenti legacy. Esegui openclaw doctor --fix per migrare le voci legacy valide in SQLite. I file legacy non validi vengono messi in quarantena, così un vecchio registro difettoso non può nascondere le voci di runtime correnti.

​
Configurazione

Le impostazioni sandbox si trovano in ~/.openclaw/openclaw.json sotto agents.defaults.sandbox (gli override per agente vanno in agents.list[].sandbox): 
{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "all", // off, non-main, all
        "backend": "docker", // docker, ssh, openshell
        "scope": "agent", // session, agent, shared
        "docker": {
          "image": "openclaw-sandbox:bookworm-slim",
          "containerPrefix": "openclaw-sbx-",
          // ... more Docker options
        },
        "prune": {
          "idleHours": 24, // Auto-prune after 24h idle
          "maxAgeDays": 7, // Auto-prune after 7 days
        },
      },
    },
  },
}

​
Correlati