Isolamento em sandbox

O OpenClaw pode executar ferramentas em um backend de sandbox para reduzir o raio de impacto. O uso de sandbox fica desativado por padrão e é controlado por agents.defaults.sandbox (globalmente) ou agents.list[].sandbox (por agente). O processo do Gateway sempre permanece no host; somente a execução de ferramentas é transferida para o sandbox quando habilitado.

O que é executado no sandbox

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

Não é executado no sandbox:

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

Modos, escopo e backend

Três configurações independentes controlam o comportamento do sandbox:

O modo controla quando o sandbox é aplicado:

• off: sem sandbox.
• non-main: executa no sandbox todas as sessões, exceto a sessão principal do agente. A chave da sessão principal é sempre agent:<agentId>:main (ou global quando session.scope é "global"); ela não é configurável. As sessões de grupo/canal usam chaves próprias, portanto são sempre consideradas não principais e executadas no sandbox.
• all: todas as sessões são executadas em um sandbox.

O escopo controla quantos contêineres/ambientes são criados:

• agent: um contêiner por agente.
• session: um contêiner por sessão.
• shared: um contêiner compartilhado por todas as sessões em sandbox (as substituições de docker/ssh/browser por agente são ignoradas neste escopo).

O backend controla qual ambiente de execução executa as ferramentas no sandbox. A configuração específica de SSH fica em agents.defaults.sandbox.ssh; a configuração específica do OpenShell fica em plugins.entries.openshell.config.

Backend Docker

O Docker é o backend padrão quando o sandbox é habilitado. Ele executa ferramentas e navegadores em sandbox localmente por meio do soquete do daemon do Docker (/var/run/docker.sock); o isolamento é fornecido pelos namespaces do Docker.

Padrões: network: "none" (sem saída de rede), readOnlyRoot: true, capDrop: ["ALL"], imagem openclaw-sandbox:bookworm-slim.

Para expor as GPUs do host, defina agents.defaults.sandbox.docker.gpus (ou a substituição por agente) como um valor semelhante a "all" ou "device=GPU-uuid". Esse valor é passado para a opção --gpus do Docker e exige um ambiente de execução de host compatível, como o NVIDIA Container Toolkit.

Navegador em sandbox

• O navegador em sandbox é iniciado automaticamente (garantindo que o CDP esteja acessível) quando a ferramenta de navegador precisa dele. Configure-o por meio de agents.defaults.sandbox.browser.autoStart (padrão: true) e autoStartTimeoutMs (padrão: 12 s).
• Os contêineres do navegador em sandbox usam uma rede Docker dedicada (openclaw-sandbox-browser) em vez da rede global bridge. Configure-a com agents.defaults.sandbox.browser.network.
• agents.defaults.sandbox.browser.cdpSourceRange restringe a entrada do CDP na borda do contêiner com uma lista de permissões CIDR (por exemplo, 172.21.0.1/32).
• O acesso de observador pelo noVNC é protegido por senha por padrão; o OpenClaw emite uma URL com token de curta duração que fornece uma página de inicialização local e abre o noVNC com a senha no fragmento da URL (não na string de consulta nem nos logs de cabeçalhos).
• agents.defaults.sandbox.browser.allowHostControl (padrão: false) permite que sessões em sandbox controlem explicitamente o navegador do host.
• Listas de permissões opcionais controlam target: "custom": allowedControlUrls, allowedControlHosts, allowedControlPorts.

Backend SSH

Use backend: "ssh" para executar exec, ferramentas de arquivos e leituras de mídia em sandbox em qualquer máquina 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",          // Ou use SecretRefs / conteúdo em linha em vez de arquivos locais:          // 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" },        },      },    },  },}

Padrões: command: "ssh", workspaceRoot: "/tmp/openclaw-sandboxes", strictHostKeyChecking: true, updateHostKeys: true.

• Ciclo de vida: o OpenClaw cria uma raiz remota por escopo em sandbox.ssh.workspaceRoot. No primeiro uso após a criação ou recriação, ele carrega uma vez esse workspace remoto a partir do workspace local. Depois disso, exec, read, write, edit, apply_patch, as leituras de mídia do prompt e o preparo de mídias recebidas operam diretamente no workspace remoto por SSH. O OpenClaw não sincroniza automaticamente as alterações remotas de volta com o workspace local.
• Material de autenticação: identityFile/certificateFile/knownHostsFile fazem referência a arquivos locais existentes. identityData/certificateData/knownHostsData aceitam strings em linha ou SecretRefs, resolvidas por meio do snapshot normal do ambiente de execução de segredos, gravadas em arquivos temporários com o modo 0600 e excluídas quando a sessão SSH termina. Se uma variante *File e uma variante *Data estiverem definidas para o mesmo item, *Data terá precedência nessa sessão.
• Consequências do estado remoto como fonte canônica: o workspace SSH remoto se torna o estado real do sandbox após a carga inicial. Edições locais no host feitas fora do OpenClaw após a etapa de carga inicial não ficam visíveis remotamente até que você recrie o sandbox. openclaw sandbox recreate exclui a raiz remota por escopo e realiza uma nova carga a partir do workspace local no próximo uso. O sandbox do navegador não é compatível com esse backend, e as configurações sandbox.docker.* não se aplicam a ele.

Backend OpenShell

Use backend: "openshell" para executar ferramentas em sandbox em um ambiente remoto gerenciado pelo OpenShell. O OpenShell reutiliza o mesmo transporte SSH e a mesma ponte de sistema de arquivos remoto do backend SSH genérico, além de adicionar o ciclo de vida do OpenShell (sandbox create/get/delete/ssh-config) e um modo opcional de sincronização de workspace mirror.

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

mode: "mirror" (padrão) mantém o workspace local como fonte canônica: o OpenClaw sincroniza os dados locais com o sandbox antes de exec e sincroniza as alterações de volta depois. mode: "remote" carrega uma vez o workspace remoto a partir do local e, em seguida, executa exec/read/write/edit/apply_patch diretamente no workspace remoto sem sincronizar as alterações de volta; as edições locais após a carga inicial ficam invisíveis até que você execute openclaw sandbox recreate. Com scope: "agent" ou scope: "shared", esse workspace remoto é compartilhado no mesmo escopo. Limitações atuais: o navegador em sandbox ainda não é compatível, e sandbox.docker.binds não se aplica a esse backend.

openclaw sandbox list/recreate/prune tratam os ambientes de execução do OpenShell da mesma forma que os ambientes de execução do Docker; a lógica de remoção reconhece o backend.

Para conhecer todos os pré-requisitos, a referência de configuração, a comparação dos modos de workspace e os detalhes do ciclo de vida, consulte OpenShell.

Acesso ao workspace

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

Com o backend OpenShell, o modo mirror ainda usa o espaço de trabalho local como fonte canônica entre execuções de exec, o modo remote usa o espaço de trabalho remoto do OpenShell como canônico após a carga inicial, e workspaceAccess: "ro"/"none" ainda restringe o comportamento de gravação da mesma forma.

A mídia recebida é copiada para o espaço de trabalho ativo do sandbox (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").

As montagens bind globais e por agente são mescladas (não substituídas). Com scope: "shared", as montagens bind por agente são ignoradas.

agents.defaults.sandbox.browser.binds monta diretórios adicionais do host somente no contêiner do navegador do sandbox. Quando definido (inclusive como []), ele substitui docker.binds no contêiner do navegador; quando omitido, o contêiner do navegador recorre a docker.binds.

{  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 padrão do Docker: 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, os contêineres de sandbox do Docker são executados sem rede. Substitua esse comportamento com agents.defaults.sandbox.docker.network.

As instalações do Docker e o Gateway em contêiner ficam aqui: Docker

Para implantações do Gateway com Docker, scripts/docker/setup.sh pode inicializar a configuração do sandbox. Defina OPENCLAW_SANDBOX=1 (ou true/yes/on) para habilitar esse caminho. Substitua a localização do socket com OPENCLAW_DOCKER_SOCKET. Referência completa de configuração e variáveis de ambiente: Docker.

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

setupCommand é executado uma vez após a criação do contêiner do sandbox (não em cada execução). Ele é executado dentro do contêiner por meio de sh -lc.

Caminhos:

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

Política de ferramentas e mecanismos de escape

As políticas de permissão/negação de ferramentas ainda são aplicadas antes das regras do sandbox. Se uma ferramenta for negada globalmente ou por agente, o sandbox não a torna disponível novamente.

tools.elevated é um mecanismo de escape explícito que executa exec fora do sandbox (no gateway por padrão ou no node quando o destino da execução é node). As diretivas /exec só se aplicam a remetentes autorizados e persistem por sessão; para desabilitar completamente exec, use a negação na política de ferramentas (consulte Sandbox vs. política de ferramentas vs. modo elevado).

Depuração:

• openclaw sandbox list mostra contêineres de sandbox, status, correspondência da imagem, idade, tempo de inatividade e sessão/agente associado.
• openclaw sandbox explain [--session <key>] [--agent <id>] inspeciona o modo efetivo do sandbox, o espaço de trabalho do host, o diretório de trabalho do ambiente de execução, as montagens do Docker, a política de ferramentas e as chaves de configuração para correção. O campo workspaceRoot permanece como a raiz configurada do sandbox; effectiveHostWorkspaceRoot mostra onde o espaço de trabalho ativo realmente está.
• openclaw sandbox recreate [--all | --session <key> | --agent <id>] [--browser] [--force] remove contêineres/ambientes para que sejam recriados com a configuração atual no próximo uso.
• Consulte Sandbox vs. política de ferramentas vs. modo elevado para entender o modelo mental de "por que isso está bloqueado?".

Substituições para vários agentes

Cada agente pode substituir as configurações de sandbox e ferramentas: agents.list[].sandbox e agents.list[].tools (além de agents.list[].tools.sandbox.tools para a política de ferramentas do sandbox). Consulte Sandbox e ferramentas para vários agentes para ver a precedência.

Exemplo mínimo de habilitação

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

Relacionado

• Sandbox e ferramentas multiagente -- substituições por agente e precedência
• OpenShell -- configuração do backend de sandbox gerenciado, modos de espaço de trabalho e referência de configuração
• Configuração do sandbox
• Sandbox vs. política de ferramentas vs. modo elevado -- depuração de "por que isto está bloqueado?"
• Segurança