---
read_when: You want a dedicated explanation of sandboxing or need to tune agents.defaults.sandbox.
status: active
summary: 'Como funciona o sandboxing do OpenClaw: modos, escopos, acesso ao workspace e imagens'
title: Sandboxing
x-i18n:
    generated_at: "2026-04-14T02:08:33Z"
    model: gpt-5.4
    provider: openai
    source_hash: 2573d0d7462f63a68eb1750e5432211522ff5b42989a17379d3e188468bbce52
    source_path: gateway/sandboxing.md
    workflow: 15
---

# Sandboxing

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 serão executadas no host.
O Gateway permanece no host; a execução de ferramentas roda em um sandbox isolado
quando ativada.

Isso não é uma barreira de segurança perfeita, mas limita de forma material o acesso
ao sistema de arquivos e a processos quando o modelo faz algo imprudente.

## 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`.

Não ficam em sandbox:

- 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](/pt-BR/tools/elevated).

## Modos

`agents.defaults.sandbox.mode` controla **quando** o sandboxing é usado:

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

`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): runtime de sandbox local com Docker.
- `"ssh"`: runtime de sandbox remoto genérico com SSH.
- `"openshell"`: runtime de sandbox com 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

|                     | Docker                           | SSH                            | OpenShell                                                  |
| ------------------- | -------------------------------- | ------------------------------ | ---------------------------------------------------------- |
| **Onde executa**    | Contêiner local                  | Qualquer host acessível via SSH | Sandbox gerenciado pelo OpenShell                          |
| **Configuração**    | `scripts/sandbox-setup.sh`       | Chave SSH + host de destino    | Plugin OpenShell ativado                                   |
| **Modelo de workspace** | Bind-mount ou cópia          | Remoto-canônico (seed uma vez) | `mirror` ou `remote`                                       |
| **Controle de rede** | `docker.network` (padrão: none) | Depende do host remoto         | Depende do OpenShell                                       |
| **Navegador em sandbox** | Compatível                 | Não compatível                 | Ainda não compatível                                       |
| **Bind mounts**     | `docker.binds`                   | N/A                            | N/A                                                        |
| **Melhor para**     | Desenvolvimento local, isolamento completo | Descarregar para uma máquina remota | Sandboxes remotos gerenciados com sincronização bidirecional opcional |

### Backend Docker

O backend Docker é o runtime padrão, executando 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.

**Restrições de Docker-out-of-Docker (DooD)**:
Se você implantar o próprio Gateway do OpenClaw como um contêiner Docker, ele orquestra contêineres de sandbox irmãos usando o socket Docker do host (DooD). Isso introduz uma restrição específica de mapeamento de caminhos:

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

Se você mapear caminhos internamente sem paridade absoluta com o host, o OpenClaw lançará nativamente um erro de permissão `EACCES` ao tentar gravar seu heartbeat dentro do ambiente do contêiner, porque a string de caminho totalmente qualificada não existe nativamente.

### Backend SSH

Use `backend: "ssh"` quando quiser que o OpenClaw coloque em sandbox `exec`, ferramentas de arquivo e leituras de mídia
em uma máquina arbitrária acessível via SSH.

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

Como funciona:

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

Material de autenticação:

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

Este é um modelo **remoto-canônico**. O workspace SSH remoto se torna o estado real do sandbox após o seed inicial.

Consequências importantes:

- 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

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 dos modos de workspace, veja a
[página do OpenShell](/pt-BR/gateway/openshell).

O OpenShell reutiliza o mesmo transporte SSH principal e a mesma bridge de sistema de arquivos remoto do
backend SSH genérico, e adiciona o ciclo de vida específico do OpenShell
(`sandbox create/get/delete`, `sandbox ssh-config`) mais o modo de workspace
opcional `mirror`.

```json5
{
  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 do OpenShell:

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

Detalhes do transporte remoto:

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

Limitações atuais do OpenShell:

- 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

O OpenShell tem dois modelos de workspace. Esta é a parte que mais importa na prática.

##### `mirror`

Use `plugins.entries.openshell.config.mode: "mirror"` quando quiser que o **workspace local permaneça canônico**.

Comportamento:

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

Use isto quando:

- 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

Tradeoff:

- custo extra de sincronização antes e depois do exec

##### `remote`

Use `plugins.entries.openshell.config.mode: "remote"` quando quiser que o **workspace do OpenShell se torne canônico**.

Comportamento:

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

Consequências importantes:

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

Use isto quando:

- 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

Escolha `mirror` se você pensa no sandbox como um ambiente temporário de execução.
Escolha `remote` se você pensa no sandbox como o workspace real.

#### Ciclo de vida do OpenShell

Os sandboxes do OpenShell ainda são gerenciados pelo ciclo de vida normal do sandbox:

- `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

Para o modo `remote`, recriar é especialmente importante:

- recriar exclui o workspace remoto canônico desse escopo
- no próximo uso, um novo workspace remoto recebe seed a partir do workspace local

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

## Acesso ao workspace

`agents.defaults.sandbox.workspaceAccess` controla **o que o sandbox pode ver**:

- `"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`.

Com o backend OpenShell:

- 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

A mídia de entrada é copiada para o workspace ativo do sandbox (`media/inbound/*`).
Observação sobre Skills: a ferramenta `read` é enraizada no sandbox. Com `workspaceAccess: "none"`,
o OpenClaw espelha Skills elegíveis no workspace do sandbox (`.../skills`) para que
possam ser lidas. Com `"rw"`, as Skills do workspace podem ser lidas em
`/workspace/skills`.

## Bind mounts personalizados

`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 apenas no contêiner do **navegador em 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):

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

Observações de segurança:

- 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](/pt-BR/gateway/sandbox-vs-tool-policy-vs-elevated) para saber como binds interagem com a política de ferramentas e exec elevado.

## Imagens + configuração

Imagem Docker padrão: `openclaw-sandbox:bookworm-slim`

Faça o build uma vez:

```bash
scripts/sandbox-setup.sh
```

Observação: a imagem padrão **não** inclui Node. Se uma Skill precisar de Node (ou
outros runtimes), você pode criar uma imagem personalizada ou instalar via
`sandbox.docker.setupCommand` (requer saída de rede + raiz gravável +
usuário root).

Se você quiser uma imagem de sandbox mais funcional com ferramentas comuns (por exemplo
`curl`, `jq`, `nodejs`, `python3`, `git`), faça o build:

```bash
scripts/sandbox-common-setup.sh
```

Depois defina `agents.defaults.sandbox.docker.image` como
`openclaw-sandbox-common:bookworm-slim`.

Imagem do navegador em sandbox:

```bash
scripts/sandbox-browser-setup.sh
```

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

A imagem agrupada do navegador em sandbox também aplica padrões conservadores de inicialização do Chromium
para cargas de trabalho em contêiner. Os padrões atuais do contêiner incluem:

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

Se você precisar de um perfil de runtime diferente, use uma imagem personalizada do navegador e forneça
seu próprio entrypoint. Para perfis locais (não conteinerizados) do Chromium, use
`browser.extraArgs` para acrescentar flags adicionais de inicialização.

Padrões de segurança:

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

Instalações Docker e o gateway conteinerizado ficam aqui:
[Docker](/pt-BR/install/docker)

Para implantações do Gateway com Docker, `scripts/docker/setup.sh` pode inicializar a configuração de sandbox.
Defina `OPENCLAW_SANDBOX=1` (ou `true`/`yes`/`on`) para ativar esse caminho. Você pode
substituir o local do socket com `OPENCLAW_DOCKER_SOCKET`. Referência completa de
configuração e variáveis de ambiente: [Docker](/pt-BR/install/docker#agent-sandbox).

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

`setupCommand` é executado **uma vez** após a criação do contêiner do sandbox (não em toda execução).
Ele é executado dentro do contêiner via `sh -lc`.

Caminhos:

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

Armadilhas comuns:

- 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

As políticas de permitir/negar ferramentas ainda se aplicam antes das regras de sandbox. Se uma ferramenta for negada
globalmente ou por agente, o sandboxing não a trará de volta.

`tools.elevated` é uma rota de escape explícita que executa `exec` fora do sandbox (`gateway` por padrão, ou `node` quando o destino de exec é `node`).
Diretivas `/exec` só se aplicam a remetentes autorizados e persistem por sessão; para desativar
`exec` de forma rígida, use negar na política de ferramentas (veja [Sandbox vs Política de ferramenta vs Modo elevado](/pt-BR/gateway/sandbox-vs-tool-policy-vs-elevated)).

Depuração:

- 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](/pt-BR/gateway/sandbox-vs-tool-policy-vs-elevated) para o modelo mental de “por que isso está bloqueado?”.
  Mantenha tudo restrito.

## Substituições por multiagente

Cada agente pode substituir sandbox + ferramentas:
`agents.list[].sandbox` e `agents.list[].tools` (além de `agents.list[].tools.sandbox.tools` para a política de ferramentas do sandbox).
Veja [Sandbox e ferramentas em multiagente](/pt-BR/tools/multi-agent-sandbox-tools) para precedência.

## Exemplo mínimo de ativação

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

## Documentos relacionados

- [OpenShell](/pt-BR/gateway/openshell) -- configuração do backend de sandbox gerenciado, modos de workspace e referência de configuração
- [Configuração de sandbox](/pt-BR/gateway/configuration-reference#agentsdefaultssandbox)
- [Sandbox vs Política de ferramenta vs Modo elevado](/pt-BR/gateway/sandbox-vs-tool-policy-vs-elevated) -- depuração de “por que isso está bloqueado?”
- [Sandbox e ferramentas em multiagente](/pt-BR/tools/multi-agent-sandbox-tools) -- substituições por agente e precedência
- [Segurança](/pt-BR/gateway/security)
