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

CLI commands

CLI de sandbox

Status: active

Gerencie runtimes de sandbox para execução isolada de agentes: contêineres Docker, destinos SSH ou backends OpenShell.

Comandos

openclaw sandbox list

Liste os runtimes de sandbox com status, backend, correspondência de configuração, idade, tempo de inatividade e sessão/agente associado.

bash
openclaw sandbox listopenclaw sandbox list --browser  # somente contêineres de navegadoropenclaw sandbox list --json

openclaw sandbox recreate

Remova runtimes de sandbox para forçar sua recriação com a configuração atual. Os runtimes são recriados automaticamente na próxima vez que o agente for usado.

bash
openclaw sandbox recreate --allopenclaw sandbox recreate --agent mybot        # inclui subsessões agent:mybot:*openclaw sandbox recreate --session "agent:main:main"openclaw sandbox recreate --browser --all      # somente contêineres de navegadoropenclaw sandbox recreate --all --force        # ignora a confirmação

Opções:

  • --all: recria todos os contêineres de sandbox
  • --session <key>: recria o runtime com esta chave de escopo exata (conforme exibida por sandbox list); sem expansão de nome curto
  • --agent <id>: recria os runtimes de um agente (corresponde a agent:<id> e agent:<id>:*)
  • --browser: afeta somente contêineres de navegador
  • --force: ignora a solicitação de confirmação

Forneça exatamente uma das opções --all, --session ou --agent.

Para ssh e remote do OpenShell, a recriação é mais importante do que com o Docker: o espaço de trabalho remoto passa a ser a fonte canônica após a carga inicial, recreate exclui esse espaço de trabalho remoto canônico para o escopo selecionado e a próxima execução o recarrega a partir do espaço de trabalho local atual.

openclaw sandbox explain

Inspecione o modo e o escopo efetivos do sandbox, o acesso ao espaço de trabalho, a política de ferramentas do sandbox e os controles de ferramentas elevadas (com caminhos de chaves de configuração para correção).

O relatório mantém workspaceRoot como a raiz de sandbox configurada e exibe separadamente o espaço de trabalho efetivo do host, o diretório de trabalho do runtime do backend e a tabela de montagens do Docker. Para workspaceAccess: "rw", o espaço de trabalho efetivo do host é o espaço de trabalho do agente, em vez de um diretório abaixo de workspaceRoot.

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

Diferentemente de recreate --session, este comando aceita nomes curtos de sessão (por exemplo, main) e os expande com base no agente resolvido.

Por que a recriação é necessária

A atualização da configuração de sandbox não afeta os contêineres em execução: os runtimes existentes mantêm suas configurações antigas, e runtimes inativos só são removidos após prune.idleHours (padrão: 24 h). Agentes usados regularmente podem manter runtimes desatualizados ativos indefinidamente. openclaw sandbox recreate remove o runtime antigo para que o próximo uso o reconstrua com a configuração atual.

Motivos comuns

Alteração Comando
Atualização da imagem Docker (agents.defaults.sandbox.docker.image) openclaw sandbox recreate --all
Configuração de sandbox (agents.defaults.sandbox.*) openclaw sandbox recreate --all
Destino/autenticação SSH (agents.defaults.sandbox.ssh.{target,workspaceRoot,identityFile,certificateFile,knownHostsFile,identityData,certificateData,knownHostsData}) openclaw sandbox recreate --all
Origem/política/modo do OpenShell (plugins.entries.openshell.config.{from,mode,policy}) openclaw sandbox recreate --all
setupCommand openclaw sandbox recreate --all (ou --agent <id> para um agente)

Migração do registro

Os metadados dos runtimes de sandbox ficam no banco de dados de estado SQLite compartilhado. Instalações mais antigas podem ter arquivos de registro legados que as leituras regulares não regravam mais:

  • ~/.openclaw/sandbox/containers.json
  • ~/.openclaw/sandbox/browsers.json
  • um fragmento JSON por contêiner/navegador em ~/.openclaw/sandbox/containers/ ou ~/.openclaw/sandbox/browsers/

Execute openclaw doctor --fix para migrar entradas legadas válidas para o SQLite. Arquivos legados inválidos são colocados em quarentena para que um registro antigo corrompido não possa ocultar as entradas de runtime atuais.

Configuração

As configurações de sandbox ficam em ~/.openclaw/openclaw.json, em agents.defaults.sandbox (substituições por agente ficam em agents.list[].sandbox):

jsonc
{  "agents": {    "defaults": {      "sandbox": {        "mode": "all", // off, non-main, all        "backend": "docker", // docker, ssh, openshell (fornecido por Plugin)        "scope": "agent", // session, agent, shared        "docker": {          "image": "openclaw-sandbox:bookworm-slim",          "containerPrefix": "openclaw-sbx-",          // ... mais opções do Docker        },        "prune": {          "idleHours": 24, // remoção automática após 24 h de inatividade          "maxAgeDays": 7, // remoção automática após 7 dias        },      },    },  },}

Relacionados

Was this useful?
On this page

On this page