CLI sandbox

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 explainopenclaw sandbox explain --session agent:main:mainopenclaw sandbox explain --agent workopenclaw sandbox explain --json

openclaw sandbox list

Elenca tutti i runtime sandbox con il relativo stato e la configurazione.

openclaw sandbox listopenclaw sandbox list --browser  # List only browser containersopenclaw 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 containersopenclaw sandbox recreate --session main       # Specific sessionopenclaw sandbox recreate --agent mybot        # Specific agentopenclaw sandbox recreate --browser            # Only browser containersopenclaw 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

Casi d'uso

Dopo l'aggiornamento di un'immagine Docker

# Pull new imagedocker pull openclaw-sandbox:latestdocker 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 containersopenclaw sandbox recreate --all

Dopo la modifica della configurazione sandbox

# Edit config: agents.defaults.sandbox.* (or agents.list[].sandbox.*) # Recreate to apply new configopenclaw 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 containersopenclaw 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.

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

• Riferimento CLI
• Sandboxing
• Area di lavoro dell'agente
• Doctor: controlla la configurazione sandbox.