Isolamento em sandbox

​

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

• 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

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

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

​

Backend Docker

​

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

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

• 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

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

​

Acesso ao workspace

​

Montagens bind personalizadas

{
  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

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

​

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

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

​

Política de ferramentas e mecanismos de escape

• 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

​

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