​

Sandboxing

​

O que é colocado em sandbox

• Execução de ferramentas (exec, read, write, edit, apply_patch, process etc.).
• Navegador opcional em sandbox (agents.defaults.sandbox.browser).
  • Por padrão, o navegador em sandbox inicia automaticamente (garante que o CDP esteja acessível) quando a ferramenta de navegador precisa dele. Configure via agents.defaults.sandbox.browser.autoStart e agents.defaults.sandbox.browser.autoStartTimeoutMs.
  • Por padrão, contêineres de navegador em sandbox usam uma rede Docker dedicada (openclaw-sandbox-browser) em vez da rede global bridge. Configure com agents.defaults.sandbox.browser.network.
  • agents.defaults.sandbox.browser.cdpSourceRange opcional restringe o ingresso CDP na borda do contêiner com uma allowlist CIDR (por exemplo 172.21.0.1/32).
  • O acesso de observação via noVNC é protegido por senha por padrão; o OpenClaw emite uma URL com token de curta duração que serve uma página de bootstrap local e abre o noVNC com a senha no fragmento da URL (não em logs de query/header).
  • agents.defaults.sandbox.browser.allowHostControl permite que sessões em sandbox direcionem explicitamente o navegador do host.
  • Allowlists opcionais controlam target: "custom": allowedControlUrls, allowedControlHosts, allowedControlPorts.

• O próprio processo do Gateway.
• Qualquer ferramenta explicitamente permitida para rodar fora do sandbox (por exemplo tools.elevated).
  • Exec elevado ignora o sandboxing e usa o caminho de escape configurado (gateway por padrão, ou node quando o destino de exec é node).
  • Se o sandboxing estiver desativado, tools.elevated não altera a execução (já está no host). Consulte Elevated Mode.

​

Modos

• "off": sem sandboxing.
• "non-main": sandbox apenas para sessões não principais (padrão se você quiser chats normais no host).
• "all": toda sessão roda em um sandbox. Observação: "non-main" se baseia em session.mainKey (padrão "main"), não no id do agente. Sessões de grupo/canal usam suas próprias chaves, então contam como não principais e entrarão em sandbox.

​

Escopo

• "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

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

​

Escolhendo um backend

​

Backend 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 inline 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" },
        },
      },
    },
  },
}

• O OpenClaw cria uma raiz remota por escopo em sandbox.ssh.workspaceRoot.
• No primeiro uso após create ou recreate, o OpenClaw inicializa esse workspace remoto a partir do workspace local uma única vez.
• Depois disso, exec, read, write, edit, apply_patch, leituras de mídia no prompt e preparação de mídia de entrada são executados diretamente no workspace remoto por SSH.
• O OpenClaw não sincroniza automaticamente alterações remotas de volta para o workspace local.

• identityFile, certificateFile, knownHostsFile: usam arquivos locais existentes e os passam pela configuração do OpenSSH.
• identityData, certificateData, knownHostsData: usam strings inline ou SecretRefs. O OpenClaw os resolve pelo snapshot normal de segredos em runtime, grava em arquivos temporários com 0600 e os exclui quando a sessão SSH termina.
• Se *File e *Data estiverem definidos para o mesmo item, *Data tem prioridade nessa sessão SSH.

• Edições locais no host feitas fora do OpenClaw após a etapa de inicialização não ficam visíveis remotamente até que você recrie o sandbox.
• openclaw sandbox recreate exclui a raiz remota por escopo e inicializa novamente a partir do local no próximo uso.
• O navegador em sandbox não é compatível com o backend SSH.
• Configurações sandbox.docker.* não se aplicam ao backend SSH.

​

Backend OpenShell

{
  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",
        },
      },
    },
  },
}

• mirror (padrão): o workspace local continua sendo o canônico. O OpenClaw sincroniza arquivos locais com o OpenShell antes de exec e sincroniza o workspace remoto de volta após exec.
• remote: o workspace OpenShell se torna o canônico após a criação do sandbox. O OpenClaw inicializa o workspace remoto uma vez a partir do workspace local, então ferramentas de arquivo e exec rodam diretamente no sandbox remoto sem sincronizar alterações de volta.

• O OpenClaw solicita ao OpenShell a configuração SSH específica do sandbox por meio de openshell sandbox ssh-config <name>.
• O núcleo grava essa configuração SSH em um arquivo temporário, abre a sessão SSH e reutiliza a mesma ponte de sistema de arquivos remoto usada por backend: "ssh".
• No modo mirror, apenas o ciclo de vida difere: sincroniza de local para remoto antes de exec e depois sincroniza de volta após exec.

• navegador em sandbox ainda não é compatível
• sandbox.docker.binds não é compatível com o backend OpenShell
• parâmetros de runtime específicos do Docker em sandbox.docker.* continuam se aplicando apenas ao backend Docker

​

Modos de workspace

mirror

• Antes de exec, o OpenClaw sincroniza o workspace local com o sandbox OpenShell.
• Depois de exec, o OpenClaw sincroniza o workspace remoto de volta para o workspace local.
• As ferramentas de arquivo ainda operam por meio da ponte do sandbox, mas o workspace local permanece como fonte da verdade entre turnos.

• você edita arquivos localmente fora do OpenClaw e quer que essas alterações apareçam no sandbox automaticamente
• você quer que o sandbox OpenShell se comporte o máximo possível como o backend Docker
• você quer que o workspace do host reflita gravações do sandbox após cada turno de exec

• custo extra de sincronização antes e depois de exec

remote

• Quando o sandbox é criado pela primeira vez, o OpenClaw inicializa o workspace remoto a partir do workspace local uma vez.
• Depois disso, exec, read, write, edit e apply_patch operam diretamente sobre o workspace remoto do OpenShell.
• O OpenClaw não sincroniza alterações remotas de volta para o workspace local após exec.
• Leituras de mídia no momento do prompt continuam funcionando porque ferramentas de arquivo e mídia leem por meio da ponte do sandbox em vez de assumir um caminho local do host.
• O transporte é SSH para dentro do sandbox OpenShell retornado por openshell sandbox ssh-config.

• Se você editar arquivos no host fora do OpenClaw após a etapa de inicialização, o sandbox remoto não verá essas alterações automaticamente.
• Se o sandbox for recriado, o workspace remoto será inicializado novamente a partir do workspace local.
• Com scope: "agent" ou scope: "shared", esse workspace remoto será compartilhado nesse mesmo escopo.

• o sandbox deve viver principalmente no lado remoto do OpenShell
• você quer menor sobrecarga de sincronização por turno
• você não quer que edições locais no host sobrescrevam silenciosamente o estado remoto do sandbox

​

Ciclo de vida do OpenShell

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

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

​

Acesso ao workspace

• "none" (padrão): as ferramentas veem um workspace de sandbox em ~/.openclaw/sandboxes.
• "ro": monta o workspace do agente como somente leitura em /agent (desativa write/edit/apply_patch).
• "rw": monta o workspace do agente como leitura/gravação em /workspace.

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

​

Bind mounts personalizados

• Quando definido (inclusive []), ele 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 (compatibilidade retroativa).

{
  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"],
          },
        },
      },
    ],
  },
}

• Binds ignoram o sistema de arquivos do sandbox: eles expõem caminhos do host com o modo que você definir (:ro ou :rw).
• O OpenClaw bloqueia origens de bind perigosas (por exemplo: docker.sock, /etc, /proc, /sys, /dev e montagens pai que os exporiam).
• O OpenClaw também bloqueia raízes comuns de credenciais no diretório home, como ~/.aws, ~/.cargo, ~/.config, ~/.docker, ~/.gnupg, ~/.netrc, ~/.npm e ~/.ssh.
• A validação de bind não é apenas correspondência de string. O OpenClaw normaliza o caminho de origem e depois o resolve novamente pelo ancestral existente mais profundo antes de verificar novamente caminhos bloqueados e raízes permitidas.
• Isso significa que escapes por pai de symlink ainda falham de forma segura, mesmo quando a folha final ainda não existe. Exemplo: /workspace/run-link/new-file ainda é resolvido como /var/run/... se run-link apontar para lá.
• As raízes de origem permitidas são canonizadas da mesma forma, então um caminho que apenas parece estar dentro da allowlist antes da resolução de symlink ainda é rejeitado como outside allowed roots.
• Montagens sensíveis (segredos, chaves SSH, credenciais de serviço) devem ser :ro, a menos que seja absolutamente necessário.
• Combine com workspaceAccess: "ro" se você precisar apenas de acesso de leitura ao workspace; os modos de bind continuam independentes.
• Consulte Sandbox vs Tool Policy vs Elevated para entender como binds interagem com a política de ferramentas e exec elevado.

​

Imagens + configuração

scripts/sandbox-setup.sh

scripts/sandbox-common-setup.sh

scripts/sandbox-browser-setup.sh

• --remote-debugging-address=127.0.0.1
• --remote-debugging-port=<derived from OPENCLAW_BROWSER_CDP_PORT>
• --user-data-dir=${HOME}/.chrome
• --no-first-run
• --no-default-browser-check
• --disable-3d-apis
• --disable-gpu
• --disable-dev-shm-usage
• --disable-background-networking
• --disable-extensions
• --disable-features=TranslateUI
• --disable-breakpad
• --disable-crash-reporter
• --disable-software-rasterizer
• --no-zygote
• --metrics-recording-only
• --renderer-process-limit=2
• --no-sandbox e --disable-setuid-sandbox quando noSandbox estiver ativado.
• As três flags de hardening gráfico (--disable-3d-apis, --disable-software-rasterizer, --disable-gpu) são opcionais e são úteis quando os contêineres não têm suporte a GPU. Defina OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0 se sua carga de trabalho exigir WebGL ou outros recursos 3D/do navegador.
• --disable-extensions fica ativado por padrão e pode ser desativado com OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0 para fluxos que dependem de extensões.
• --renderer-process-limit=2 é controlado por OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N>, onde 0 mantém o padrão do Chromium.

• network: "host" é bloqueado.
• network: "container:<id>" é bloqueado por padrão (risco de ignorar namespace join).
• Substituição break-glass: agents.defaults.sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true.

​

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

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

• O padrão de docker.network é "none" (sem saída), então instalações de pacotes falharão.
• docker.network: "container:<id>" exige dangerouslyAllowContainerNamespaceJoin: true e é apenas break-glass.
• readOnlyRoot: true impede gravações; defina readOnlyRoot: false ou crie uma imagem personalizada.
• user deve ser root para instalações de pacotes (omita user ou defina user: "0:0").
• O exec em sandbox não herda process.env do host. Use agents.defaults.sandbox.docker.env (ou uma imagem personalizada) para chaves de API de Skills.

​

Política de ferramentas + caminhos de escape

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

​

Substituições para vários agentes

​

Exemplo mínimo de ativação

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

​

Documentação relacionada

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