CLI de ambiente isolado

Gerencie runtimes de sandbox para execução isolada de agentes.

Visão geral

O OpenClaw pode executar agentes em runtimes de sandbox isolados por segurança. Os comandos sandbox ajudam você a inspecionar e recriar esses runtimes após atualizações ou alterações de configuração.

Hoje isso geralmente significa:

• Contêineres de sandbox do Docker
• Runtimes de sandbox por SSH quando agents.defaults.sandbox.backend = "ssh"
• Runtimes de sandbox do OpenShell quando agents.defaults.sandbox.backend = "openshell"

Para ssh e OpenShell remote, recriar é mais importante do que com Docker:

• o workspace remoto é canônico após a propagação inicial
• openclaw sandbox recreate exclui esse workspace remoto canônico para o escopo selecionado
• o próximo uso o propaga novamente a partir do workspace local atual

Comandos

openclaw sandbox explain

Inspecione o modo/escopo/acesso ao workspace de sandbox efetivo, a política de ferramentas de sandbox e os gates elevados (com caminhos de chaves de configuração para correção).

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

openclaw sandbox list

Liste todos os runtimes de sandbox com seu status e configuração.

openclaw sandbox listopenclaw sandbox list --browser  # List only browser containersopenclaw sandbox list --json     # JSON output

A saída inclui:

• Nome e status do runtime
• Backend (docker, openshell, etc.)
• Rótulo de configuração e se ele corresponde à configuração atual
• Idade (tempo desde a criação)
• Tempo ocioso (tempo desde o último uso)
• Sessão/agente associado

openclaw sandbox recreate

Remova runtimes de sandbox para forçar a recriação com a configuração atualizada.

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

Opções:

• --all: Recria todos os contêineres de sandbox
• --session <key>: Recria o contêiner de uma sessão específica
• --agent <id>: Recria contêineres de um agente específico
• --browser: Recria somente contêineres de navegador
• --force: Ignora o prompt de confirmação

Casos de uso

Depois de atualizar uma imagem 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

Depois de alterar a configuração de sandbox

# Edit config: agents.defaults.sandbox.* (or agents.list[].sandbox.*) # Recreate to apply new configopenclaw sandbox recreate --all

Depois de alterar o destino SSH ou o material de autenticação 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

Para o backend ssh principal, recriar exclui a raiz do workspace remoto por escopo no destino SSH. A próxima execução a propaga novamente a partir do workspace local.

Depois de alterar a origem, a política ou o modo do 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

Para o modo remote do OpenShell, recriar exclui o workspace remoto canônico desse escopo. A próxima execução o propaga novamente a partir do workspace local.

Depois de alterar setupCommand

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

Somente para um agente específico

# Update only one agent's containersopenclaw sandbox recreate --agent alfred

Por que isso é necessário

Quando você atualiza a configuração de sandbox:

• Runtimes existentes continuam em execução com as configurações antigas.
• Runtimes só são removidos após 24h de inatividade.
• Agentes usados regularmente mantêm runtimes antigos ativos indefinidamente.

Use openclaw sandbox recreate para forçar a remoção de runtimes antigos. Eles são recriados automaticamente com as configurações atuais quando forem necessários novamente.

Migração de registro

O OpenClaw armazena metadados de runtime de sandbox como um fragmento JSON por entrada de contêiner/navegador no diretório de estado do sandbox. Instalações mais antigas ainda podem ter arquivos legados monolíticos:

• ~/.openclaw/sandbox/containers.json
• ~/.openclaw/sandbox/browsers.json

Leituras regulares de runtime de sandbox não reescrevem esses arquivos. Execute openclaw doctor --fix para migrar entradas legadas válidas para os diretórios de registro fragmentado. Arquivos legados inválidos são colocados em quarentena para que um registro antigo problemático não oculte entradas de runtime atuais.

Configuração

As configurações de sandbox ficam em ~/.openclaw/openclaw.json sob agents.defaults.sandbox (substituições por agente ficam em 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        },      },    },  },}

Relacionado

• Referência da CLI
• Sandboxing
• Workspace do agente
• Doctor: verifica a configuração de sandbox.