Skip to main content
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.

​
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.
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.
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.
Prefira openclaw sandbox recreate à limpeza manual específica do backend. Ele usa o registro de runtimes do Gateway e evita incompatibilidades quando o escopo ou as chaves de sessão mudam.

​
Motivos comuns

Os runtimes são recriados automaticamente na próxima vez que o agente é usado.

​
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):

​
Relacionados