Isolamento em ambiente restrito

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

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

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

​

Modos

​

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 quando o isolamento em sandbox está habilitado): runtime de sandbox local baseado em Docker.
• "ssh": runtime genérico de sandbox remoto baseado em SSH.
• "openshell": runtime de sandbox baseado em OpenShell.

​

Como escolher um backend

​

Backend Docker

​

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",
          // 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

{
  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 para o OpenShell antes de exec e sincroniza o workspace remoto de volta após exec.
• remote: o workspace do OpenShell é canônico depois que a sandbox é criada. O OpenClaw semeia o workspace remoto uma vez a partir do workspace local; depois disso, ferramentas de arquivo e exec são executados diretamente na sandbox remota sem sincronizar alterações de volta.

​

Modos de workspace

​

Ciclo de vida do OpenShell

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

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

​

Acesso ao workspace

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

​

Montagens bind personalizadas

• Quando definido (incluindo []), ele substitui agents.defaults.sandbox.docker.binds para o contêiner do navegador.
• Quando omitido, o contêiner do navegador recorre a agents.defaults.sandbox.docker.binds (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"],
          },
        },
      },
    ],
  },
}

​

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 rotas de escape

• Use openclaw sandbox explain para inspecionar o modo de sandbox efetivo, 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 isto está bloqueado?”.

​

Substituições multiagente

​

Exemplo mínimo de habilitação

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

​

Relacionados

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