OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

CLI commands

CLI sandbox

Status: active

Gestisci i runtime sandbox per l'esecuzione isolata degli agenti: container Docker, destinazioni SSH o backend OpenShell.

Comandi

openclaw sandbox list

Elenca i runtime sandbox con stato, backend, corrispondenza della configurazione, età, tempo di inattività e sessione/agente associato.

bash
openclaw sandbox listopenclaw sandbox list --browser  # solo container del browseropenclaw sandbox list --json

openclaw sandbox recreate

Rimuove i runtime sandbox per forzarne la ricreazione con la configurazione corrente. I runtime vengono ricreati automaticamente al successivo utilizzo dell'agente.

bash
openclaw sandbox recreate --allopenclaw sandbox recreate --agent mybot        # include le sottosessioni agent:mybot:*openclaw sandbox recreate --session "agent:main:main"openclaw sandbox recreate --browser --all      # solo container del browseropenclaw sandbox recreate --all --force        # ignora la conferma

Opzioni:

  • --all: ricrea tutti i container sandbox
  • --session <key>: ricrea il runtime con questa chiave di ambito esatta (come mostrata da sandbox list); nessuna espansione dei nomi abbreviati
  • --agent <id>: ricrea i runtime per un agente (corrisponde a agent:<id> e agent:<id>:*)
  • --browser: interessa solo i container del browser
  • --force: ignora la richiesta di conferma

Specifica esattamente una tra --all, --session e --agent.

Per ssh e OpenShell remote, la ricreazione è più rilevante che con Docker: dopo il popolamento iniziale, lo spazio di lavoro remoto è quello canonico; recreate elimina tale spazio di lavoro remoto canonico per l'ambito selezionato e l'esecuzione successiva lo ripopola dallo spazio di lavoro locale corrente.

openclaw sandbox explain

Esamina la modalità e l'ambito sandbox effettivi, l'accesso allo spazio di lavoro, i criteri degli strumenti sandbox e i controlli per gli strumenti con privilegi elevati (con i percorsi delle chiavi di configurazione da correggere).

Il rapporto mantiene workspaceRoot come radice sandbox configurata e mostra separatamente lo spazio di lavoro host effettivo, la directory di lavoro del runtime del backend e la tabella dei montaggi Docker. Con workspaceAccess: "rw", lo spazio di lavoro host effettivo è lo spazio di lavoro dell'agente anziché una directory sotto workspaceRoot.

bash
openclaw sandbox explainopenclaw sandbox explain --session agent:main:mainopenclaw sandbox explain --agent workopenclaw sandbox explain --json

A differenza di recreate --session, questo comando accetta nomi di sessione abbreviati (ad esempio main) e li espande in base all'agente risolto.

Perché è necessaria la ricreazione

L'aggiornamento della configurazione sandbox non influisce sui container in esecuzione: i runtime esistenti mantengono le impostazioni precedenti e quelli inattivi vengono rimossi solo dopo prune.idleHours (valore predefinito: 24 ore). Gli agenti utilizzati regolarmente possono mantenere attivi indefinitamente runtime obsoleti. openclaw sandbox recreate rimuove il vecchio runtime affinché, al successivo utilizzo, venga ricostruito dalla configurazione corrente.

Cause comuni

Modifica Comando
Aggiornamento dell'immagine Docker (agents.defaults.sandbox.docker.image) openclaw sandbox recreate --all
Configurazione sandbox (agents.defaults.sandbox.*) openclaw sandbox recreate --all
Destinazione/autenticazione SSH (agents.defaults.sandbox.ssh.{target,workspaceRoot,identityFile,certificateFile,knownHostsFile,identityData,certificateData,knownHostsData}) openclaw sandbox recreate --all
Origine/criteri/modalità OpenShell (plugins.entries.openshell.config.{from,mode,policy}) openclaw sandbox recreate --all
setupCommand openclaw sandbox recreate --all (o --agent <id> per un solo agente)

Migrazione del registro

I metadati dei runtime sandbox risiedono nel database di stato SQLite condiviso. Le installazioni meno recenti possono contenere file di registro legacy che le normali operazioni di lettura non riscrivono più:

  • ~/.openclaw/sandbox/containers.json
  • ~/.openclaw/sandbox/browsers.json
  • un frammento JSON per ogni container/browser in ~/.openclaw/sandbox/containers/ o ~/.openclaw/sandbox/browsers/

Esegui openclaw doctor --fix per migrare in SQLite le voci legacy valide. I file legacy non validi vengono messi in quarantena, così un vecchio registro danneggiato non può nascondere le voci dei runtime correnti.

Configurazione

Le impostazioni sandbox si trovano in ~/.openclaw/openclaw.json, sotto agents.defaults.sandbox (le sostituzioni specifiche per agente vanno in agents.list[].sandbox):

jsonc
{  "agents": {    "defaults": {      "sandbox": {        "mode": "all", // off, non-main, all        "backend": "docker", // docker, ssh, openshell (fornito dal plugin)        "scope": "agent", // session, agent, shared        "docker": {          "image": "openclaw-sandbox:bookworm-slim",          "containerPrefix": "openclaw-sbx-",          // ... altre opzioni Docker        },        "prune": {          "idleHours": 24, // rimozione automatica dopo 24 ore di inattività          "maxAgeDays": 7, // rimozione automatica dopo 7 giorni        },      },    },  },}

Argomenti correlati

Was this useful?
On this page

On this page