Isolamento em ambiente restrito

O OpenClaw pode executar ferramentas dentro de backends de sandbox para reduzir o raio de impacto. Isso é opcional e controlado por configuração (agents.defaults.sandbox ou agents.list[].sandbox). Se o isolamento em sandbox estiver desativado, as ferramentas serão executadas no host. O Gateway permanece no host; a execução de ferramentas ocorre em uma sandbox isolada quando habilitada.

O que entra em sandbox

• Execução de ferramentas (exec, read, write, edit, apply_patch, process, etc.).
• Navegador opcional em sandbox (agents.defaults.sandbox.browser).

Não entram em sandbox:

• O próprio processo do Gateway.
• Qualquer ferramenta explicitamente autorizada a ser executada fora da sandbox (por exemplo, tools.elevated).
  • Execução elevada ignora o isolamento em sandbox e usa o caminho de escape configurado (gateway por padrão, ou node quando o destino de execução é node).
  • Se o isolamento em sandbox estiver desativado, tools.elevated não altera a execução (já está no host). Consulte Modo Elevado.

Modos

agents.defaults.sandbox.mode controla quando o isolamento em sandbox é usado:

Escopo

agents.defaults.sandbox.scope controla quantos contêineres são criados:

• "agent" (padrão): um contêiner por agente.
• "session": um contêiner por sessão.
• "shared": um contêiner compartilhado por todas as sessões em sandbox.

Backend

agents.defaults.sandbox.backend controla qual runtime fornece a sandbox:

• "docker" (padrão quando o isolamento em sandbox está habilitado): runtime de sandbox local baseado em Docker.
• "ssh": runtime genérico de sandbox remoto baseado em SSH.
• "openshell": runtime de sandbox baseado em OpenShell.

A configuração específica de SSH fica em agents.defaults.sandbox.ssh. A configuração específica de OpenShell fica em plugins.entries.openshell.config.

Como escolher um backend

Backend Docker

O isolamento em sandbox fica desativado por padrão. Se você habilitar o isolamento em sandbox e não escolher um backend, o OpenClaw usa o backend Docker. Ele executa ferramentas e navegadores em sandbox localmente via socket do daemon Docker (/var/run/docker.sock). O isolamento do contêiner de sandbox é determinado pelos namespaces do Docker.

Para expor GPUs do host a sandboxes Docker, defina agents.defaults.sandbox.docker.gpus ou a substituição por agente agents.list[].sandbox.docker.gpus. O valor é passado para a flag --gpus do Docker como um argumento separado, por exemplo "all" ou "device=GPU-uuid", e exige um runtime de host compatível, como NVIDIA Container Toolkit.

Backend SSH

Use backend: "ssh" quando quiser que o OpenClaw coloque exec, ferramentas de arquivo e leituras de mídia em sandbox em uma máquina arbitrária acessível por SSH.

{  agents: {    defaults: {      sandbox: {        mode: "all",        backend: "ssh",        scope: "session",        workspaceAccess: "rw",        ssh: {          target: "user@gateway-host:22",          workspaceRoot: "/tmp/openclaw-sandboxes",          strictHostKeyChecking: true,          updateHostKeys: true,          identityFile: "~/.ssh/id_ed25519",          certificateFile: "~/.ssh/id_ed25519-cert.pub",          knownHostsFile: "~/.ssh/known_hosts",          // Or use SecretRefs / inline contents instead of local files:          // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" },          // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" },          // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" },        },      },    },  },}

Backend OpenShell

Use backend: "openshell" quando quiser que o OpenClaw coloque ferramentas em sandbox em um ambiente remoto gerenciado pelo OpenShell. Para o guia completo de configuração, a referência de configuração e a comparação de modos de workspace, consulte a página do OpenShell dedicada.

O OpenShell reutiliza o mesmo transporte SSH central e a mesma ponte de sistema de arquivos remoto do backend SSH genérico, e adiciona ciclo de vida específico do OpenShell (sandbox create/get/delete, sandbox ssh-config) mais o modo de workspace mirror opcional.

{  agents: {    defaults: {      sandbox: {        mode: "all",        backend: "openshell",        scope: "session",        workspaceAccess: "rw",      },    },  },  plugins: {    entries: {      openshell: {        enabled: true,        config: {          from: "openclaw",          mode: "remote", // mirror | remote          remoteWorkspaceDir: "/sandbox",          remoteAgentWorkspaceDir: "/agent",        },      },    },  },}

Modos do OpenShell:

• mirror (padrão): o workspace local permanece canônico. O OpenClaw sincroniza arquivos locais para o OpenShell antes de exec e sincroniza o workspace remoto de volta após exec.
• remote: o workspace do OpenShell é canônico depois que a sandbox é criada. O OpenClaw semeia o workspace remoto uma vez a partir do workspace local; depois disso, ferramentas de arquivo e exec são executados diretamente na sandbox remota sem sincronizar alterações de volta.

Modos de workspace

O OpenShell tem dois modelos de workspace. Esta é a parte que mais importa na prática.

Escolha mirror se você pensa no sandbox como um ambiente de execução temporário. Escolha remote se você pensa no sandbox como o workspace real.

Ciclo de vida do OpenShell

Sandboxes do OpenShell ainda são gerenciados pelo ciclo de vida normal do sandbox:

• openclaw sandbox list mostra runtimes do OpenShell e runtimes Docker
• openclaw sandbox recreate exclui o runtime atual e permite que o OpenClaw o recrie no próximo uso
• a lógica de limpeza também é ciente do backend

Para o modo remote, recriar é especialmente importante:

• recriar exclui o workspace remoto canônico para esse escopo
• o próximo uso inicializa um workspace remoto novo a partir do workspace local

Para o modo mirror, recriar principalmente redefine o ambiente de execução remoto, porque o workspace local continua sendo canônico de qualquer forma.

Acesso ao workspace

agents.defaults.sandbox.workspaceAccess controla o que o sandbox pode ver:

Com o backend OpenShell:

• o modo mirror ainda usa o workspace local como a fonte canônica entre turnos de exec
• o modo remote usa o workspace remoto do OpenShell como a fonte canônica após a inicialização inicial
• workspaceAccess: "ro" e "none" ainda restringem o comportamento de escrita da mesma forma

Mídia de entrada é copiada para o workspace de sandbox ativo (media/inbound/*).

Montagens bind personalizadas

agents.defaults.sandbox.docker.binds monta diretórios adicionais do host no contêiner. Formato: host:container:mode (por exemplo, "/home/user/source:/source:rw").

Binds globais e por agente são mesclados (não substituídos). Em scope: "shared", binds por agente são ignorados.

agents.defaults.sandbox.browser.binds monta diretórios adicionais do host apenas no contêiner do navegador do sandbox.

• Quando definido (incluindo []), ele substitui agents.defaults.sandbox.docker.binds para o contêiner do navegador.
• Quando omitido, o contêiner do navegador recorre a agents.defaults.sandbox.docker.binds (compatível com versões anteriores).

Exemplo (código-fonte somente leitura + um diretório de dados extra):

{  agents: {    defaults: {      sandbox: {        docker: {          binds: ["/home/user/source:/source:ro", "/var/data/myapp:/data:ro"],        },      },    },    list: [      {        id: "build",        sandbox: {          docker: {            binds: ["/mnt/cache:/cache:rw"],          },        },      },    ],  },}

Imagens e configuração

Imagem Docker padrão: openclaw-sandbox:bookworm-slim

scripts/sandbox-setup.sh

docker build -t openclaw-sandbox:bookworm-slim - <<'DOCKERFILE'FROM debian:bookworm-slimENV DEBIAN_FRONTEND=noninteractiveRUN apt-get update && apt-get install -y --no-install-recommends \  bash ca-certificates curl git jq python3 ripgrep \  && rm -rf /var/lib/apt/lists/*RUN useradd --create-home --shell /bin/bash sandboxUSER sandboxWORKDIR /home/sandboxCMD ["sleep", "infinity"]DOCKERFILE

scripts/sandbox-common-setup.sh

scripts/sandbox-browser-setup.sh

Por padrão, contêineres de sandbox Docker executam com sem rede. Sobrescreva com agents.defaults.sandbox.docker.network.

Instalações Docker e o Gateway conteinerizado ficam aqui: Docker

Para implantações de Gateway Docker, scripts/docker/setup.sh pode inicializar a configuração do sandbox. Defina OPENCLAW_SANDBOX=1 (ou true/yes/on) para habilitar esse caminho. Você pode sobrescrever o local do socket com OPENCLAW_DOCKER_SOCKET. Configuração completa e referência de env: Docker.

setupCommand (configuração única do contêiner)

setupCommand executa uma vez após o contêiner do sandbox ser criado (não a cada execução). Ele executa dentro do contêiner via sh -lc.

Caminhos:

• Global: agents.defaults.sandbox.docker.setupCommand
• Por agente: agents.list[].sandbox.docker.setupCommand

Política de ferramentas e rotas de escape

As políticas de permissão/negação de ferramentas ainda se aplicam antes das regras do sandbox. Se uma ferramenta for negada globalmente ou por agente, o sandbox não a traz de volta.

tools.elevated é uma rota de escape explícita que executa exec fora do sandbox (gateway por padrão, ou node quando o destino de execução é node). As diretivas /exec se aplicam apenas a remetentes autorizados e persistem por sessão; para desabilitar exec de forma rígida, use a negação na política de ferramentas (consulte Sandbox vs Tool Policy vs Elevated).

Depuração:

• Use openclaw sandbox explain para inspecionar o modo de sandbox efetivo, a política de ferramentas e as chaves de configuração de correção.
• Consulte Sandbox vs Tool Policy vs Elevated para o modelo mental de "por que isto está bloqueado?".

Mantenha tudo bloqueado.

Substituições multiagente

Cada agente pode substituir sandbox + ferramentas: agents.list[].sandbox e agents.list[].tools (mais agents.list[].tools.sandbox.tools para a política de ferramentas do sandbox). Consulte Multi-Agent Sandbox & Tools para precedência.

Exemplo mínimo de habilitação

{  agents: {    defaults: {      sandbox: {        mode: "non-main",        scope: "session",        workspaceAccess: "none",      },    },  },}

Relacionados

• Multi-Agent Sandbox & Tools — substituições por agente e precedência
• OpenShell — configuração do backend de sandbox gerenciado, modos de workspace e referência de configuração
• Configuração de sandbox
• Sandbox vs Tool Policy vs Elevated — depuração de "por que isto está bloqueado?"
• Segurança