​

Sandboxing

​

O que é colocado em sandbox

• Execução de ferramentas (exec, read, write, edit, apply_patch, process, etc.).
• Navegador em sandbox opcional (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 com agents.defaults.sandbox.browser.autoStart e agents.defaults.sandbox.browser.autoStartTimeoutMs.
  • Por padrão, os contêineres do navegador em sandbox usam uma rede Docker dedicada (openclaw-sandbox-browser) em vez da rede global bridge. Configure com agents.defaults.sandbox.browser.network.
  • O agents.defaults.sandbox.browser.cdpSourceRange opcional restringe a entrada de CDP na borda do contêiner com uma allowlist CIDR (por exemplo 172.21.0.1/32).
  • O acesso de observador noVNC é protegido por senha por padrão; o OpenClaw emite uma URL com token de curta duração que serve uma página local de bootstrap 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 executar 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 for node).
  • Se o sandboxing estiver desativado, tools.elevated não altera a execução (já ocorre no host). Veja Modo elevado.

​

Modos

• "off": sem sandboxing.
• "non-main": aplica sandbox apenas a sessões não principais (padrão se você quiser chats normais no host).
• "all": toda sessão é executada 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 serão colocadas 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 com Docker.
• "ssh": runtime de sandbox remoto genérico com SSH.
• "openshell": runtime de sandbox com OpenShell.

​

Escolhendo um backend

​

Backend Docker

• A configuração exige caminhos do host: a configuração workspace em openclaw.json DEVE conter o caminho absoluto do Host (por exemplo /home/user/.openclaw/workspaces), não o caminho interno do contêiner do Gateway. Quando o OpenClaw solicita ao daemon Docker que crie um sandbox, o daemon avalia caminhos em relação ao namespace do sistema operacional do Host, não ao namespace do Gateway.
• Paridade da ponte de sistema de arquivos (mapeamento de volume idêntico): o processo nativo do Gateway do OpenClaw também grava arquivos de heartbeat e bridge no diretório workspace. Como o Gateway avalia a mesma string exata (o caminho do host) dentro de seu próprio ambiente em contêiner, a implantação do Gateway DEVE incluir um mapeamento de volume idêntico que conecte o namespace do host de forma nativa (-v /home/user/.openclaw:/home/user/.openclaw).

​

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 criar ou recriar, o OpenClaw faz um seed desse workspace remoto a partir do workspace local uma vez.
• Depois disso, exec, read, write, edit, apply_patch, leituras de mídia no prompt e staging de mídia de entrada são executados diretamente no workspace remoto via SSH.
• O OpenClaw não sincroniza automaticamente as 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 as resolve pelo snapshot normal do runtime de segredos, 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 seed não ficam visíveis remotamente até que você recrie o sandbox.
• openclaw sandbox recreate exclui a raiz remota por escopo e faz o seed novamente a partir do local no próximo uso.
• O navegador em sandbox não é compatível com o backend SSH.
• As 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 permanece canônico. O OpenClaw sincroniza arquivos locais com o OpenShell antes do exec e sincroniza o workspace remoto de volta depois do exec.
• remote: o workspace do OpenShell é canônico depois que o sandbox é criado. O OpenClaw faz o seed do workspace remoto uma vez a partir do workspace local, depois ferramentas de arquivo e exec operam diretamente no sandbox remoto sem sincronizar as 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 bridge de sistema de arquivos remoto usada por backend: "ssh".
• No modo mirror, apenas o ciclo de vida difere: sincroniza do local para o remoto antes do exec e sincroniza de volta depois do exec.

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

​

Modos de workspace

mirror

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

• você edita arquivos localmente fora do OpenClaw e quer que essas alterações apareçam automaticamente no sandbox
• você quer que o sandbox do 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 do exec

remote

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

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

• o sandbox deve existir 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 do OpenShell assim como 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 é compatível com backends

• recriar exclui o workspace remoto canônico desse escopo
• no próximo uso, um novo workspace remoto recebe seed 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 com 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 o seed inicial
• workspaceAccess: "ro" e "none" ainda restringem o comportamento de gravação da mesma forma

​

Bind mounts personalizados

• 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).

{
  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 mounts pai que as exporiam).
• O OpenClaw também bloqueia raízes comuns de credenciais em diretórios home, como ~/.aws, ~/.cargo, ~/.config, ~/.docker, ~/.gnupg, ~/.netrc, ~/.npm e ~/.ssh.
• A validação de bind não é apenas correspondência de strings. O OpenClaw normaliza o caminho de origem e depois o resolve novamente pelo ancestral existente mais profundo antes de verificar de novo caminhos bloqueados e raízes permitidas.
• Isso significa que escapes por pai com symlink ainda falham de forma segura, mesmo quando a folha final ainda não existe. Exemplo: /workspace/run-link/new-file ainda resolve 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.
• Mounts 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.
• Veja Sandbox vs Política de ferramenta vs Modo elevado para saber 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 está ativado.
• As três flags de endurecimento gráfico (--disable-3d-apis, --disable-software-rasterizer, --disable-gpu) são opcionais e são úteis quando 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 é 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>, em que 0 mantém o padrão do Chromium.

• network: "host" é bloqueado.
• network: "container:<id>" é bloqueado por padrão (risco de desvio por união de namespace).
• Substituição de emergência: 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 de rede), então instalações de pacotes falharão.
• docker.network: "container:<id>" requer dangerouslyAllowContainerNamespaceJoin: true e é apenas para uso de emergência.
• 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 do sandbox não herda o process.env do host. Use agents.defaults.sandbox.docker.env (ou uma imagem personalizada) para chaves de API de Skills.

​

Política de ferramentas + rotas de escape

• Use openclaw sandbox explain para inspecionar o modo efetivo de sandbox, a política de ferramentas e as chaves de configuração para correção.
• Veja Sandbox vs Política de ferramenta vs Modo elevado para o modelo mental de “por que isso está bloqueado?”. Mantenha tudo restrito.

​

Substituições por multiagente

​

Exemplo mínimo de ativação

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

​

Documentos relacionados

• OpenShell — configuração do backend de sandbox gerenciado, modos de workspace e referência de configuração
• Configuração de sandbox
• Sandbox vs Política de ferramenta vs Modo elevado — depuração de “por que isso está bloqueado?”
• Sandbox e ferramentas em multiagente — substituições por agente e precedência
• Segurança