Isolamento em sandbox

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 sandboxing estiver desativado, as ferramentas rodam no host. O Gateway permanece no host; a execução de ferramentas roda em um sandbox isolado 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 rodar fora do sandbox (por exemplo, tools.elevated).
  • Execução elevada ignora o sandboxing e usa o caminho de escape configurado (gateway por padrão, ou node quando o alvo de execução é node).
  • Se o sandboxing estiver desativado, tools.elevated não altera a execução (já está no host). Veja Modo Elevado.

# Modos

agents.defaults.sandbox.mode controla quando o sandboxing é 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 o sandbox:

• "docker" (padrão quando o sandboxing está habilitado): runtime de sandbox local com backend Docker.
• "ssh": runtime de sandbox remoto genérico com backend SSH.
• "openshell": runtime de sandbox com backend 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.

# Escolhendo um backend

# Backend Docker

O sandboxing fica desativado por padrão. Se você habilitar o sandboxing e não escolher um backend, o OpenClaw usa o backend Docker. Ele executa ferramentas e navegadores em sandbox localmente por meio do 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 aos 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, referência de configuração e comparação de modos de workspace, veja a página do OpenShell.

O OpenShell reutiliza o mesmo transporte SSH principal 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 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 depois de exec.
• remote: o workspace OpenShell é canônico depois que o sandbox é criado. O OpenClaw semeia o workspace remoto uma vez a partir do workspace local; depois, ferramentas de arquivo e exec rodam diretamente no sandbox remoto 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 na sandbox como um ambiente temporário de execução. Escolha remote se você pensa na sandbox como o workspace real.

# Ciclo de vida do OpenShell

As sandboxes OpenShell ainda são gerenciadas pelo ciclo de vida normal da sandbox:

• openclaw sandbox list mostra runtimes 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 é consciente do backend

Para o modo remote, recriar é especialmente importante:

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

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

# Acesso ao workspace

agents.defaults.sandbox.workspaceAccess controla o que a 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 OpenShell como a fonte canônica após a inicialização inicial
• workspaceAccess: "ro" e "none" ainda restringem o comportamento de gravação da mesma forma

Mídia recebida é copiada para o workspace da sandbox ativa (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 somente no contêiner do navegador da sandbox.

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

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

{
  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-slim
ENV DEBIAN_FRONTEND=noninteractive
RUN 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 sandbox
USER sandbox
WORKDIR /home/sandbox
CMD ["sleep", "infinity"]
DOCKERFILE

scripts/sandbox-common-setup.sh

scripts/sandbox-browser-setup.sh

Por padrão, contêineres de sandbox Docker são executados sem rede. Substitua com agents.defaults.sandbox.docker.network.

Instalações Docker e o Gateway em contêiner ficam aqui: Docker

Para implantações de Gateway Docker, scripts/docker/setup.sh pode inicializar a configuração de sandbox. Defina OPENCLAW_SANDBOX=1 (ou true/yes/on) para habilitar esse caminho. Você pode substituir 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 é executado uma vez depois que o contêiner da sandbox é criado (não em toda 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

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 reativa.

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). Diretivas /exec só se aplicam a remetentes autorizados e persistem por sessão; para desativar exec rigidamente, 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 efetivo do sandbox, 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 isso está bloqueado?".

Mantenha tudo bloqueado.

# Sobrescritas multiagente

Cada agente pode sobrescrever 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 ativação

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

# Relacionados

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