---
read_when: You hit 'sandbox jail' or see a tool/elevated refusal and want the exact config key to change.
status: active
summary: 'Por que uma ferramenta é bloqueada: runtime de sandbox, política de permissão/negação de ferramentas e controles de exec elevado'
title: Sandbox vs política de ferramentas vs elevado
x-i18n:
    generated_at: "2026-05-10T19:35:58Z"
    model: gpt-5.5
    provider: openai
    source_hash: 9d670aa4f2e0f2265590e0de6198de841e744d210bbc54d291cb448d368e63b6
    source_path: gateway/sandbox-vs-tool-policy-vs-elevated.md
    workflow: 16
---

OpenClaw tem três controles relacionados (mas diferentes):

1. **Sandbox** (`agents.defaults.sandbox.*` / `agents.list[].sandbox.*`) decide **onde as ferramentas executam** (backend do sandbox vs host).
2. **Política de ferramentas** (`tools.*`, `tools.sandbox.tools.*`, `agents.list[].tools.*`) decide **quais ferramentas estão disponíveis/permitidas**.
3. **Elevated** (`tools.elevated.*`, `agents.list[].tools.elevated.*`) é uma **saída de emergência somente para exec** para executar fora do sandbox quando você está em sandbox (`gateway` por padrão, ou `node` quando o destino de exec está configurado como `node`).

## Depuração rápida

Use o inspetor para ver o que o OpenClaw está _realmente_ fazendo:

```bash
openclaw sandbox explain
openclaw sandbox explain --session agent:main:main
openclaw sandbox explain --agent work
openclaw sandbox explain --json
```

Ele imprime:

- modo/escopo/acesso ao workspace efetivos do sandbox
- se a sessão está atualmente em sandbox (main vs non-main)
- allow/deny efetivo de ferramentas do sandbox (e se veio de agente/global/padrão)
- gates de Elevated e caminhos de chaves de correção

## Sandbox: onde as ferramentas executam

O sandbox é controlado por `agents.defaults.sandbox.mode`:

- `"off"`: tudo executa no host.
- `"non-main"`: somente sessões non-main ficam em sandbox (uma "surpresa" comum para grupos/canais).
- `"all"`: tudo fica em sandbox.

Veja [Sandboxing](/pt-BR/gateway/sandboxing) para a matriz completa (escopo, montagens de workspace, imagens).

### Montagens bind (checagem rápida de segurança)

- `docker.binds` _perfura_ o sistema de arquivos do sandbox: o que você montar fica visível dentro do contêiner com o modo que você definir (`:ro` ou `:rw`).
- O padrão é leitura e gravação se você omitir o modo; prefira `:ro` para código-fonte/segredos.
- `scope: "shared"` ignora binds por agente (somente binds globais se aplicam).
- O OpenClaw valida origens de bind duas vezes: primeiro no caminho de origem normalizado, depois novamente após resolver pelo ancestral existente mais profundo. Escapes por pais com symlink não contornam checagens de caminhos bloqueados ou raízes permitidas.
- Caminhos de folha inexistentes ainda são checados com segurança. Se `/workspace/alias-out/new-file` resolve por um pai com symlink para um caminho bloqueado ou para fora das raízes permitidas configuradas, o bind é rejeitado.
- Montar `/var/run/docker.sock` efetivamente entrega controle do host ao sandbox; faça isso somente de forma intencional.
- O acesso ao workspace (`workspaceAccess: "ro"`/`"rw"`) é independente dos modos de bind.

## Política de ferramentas: quais ferramentas existem/podem ser chamadas

Duas camadas importam:

- **Perfil de ferramentas**: `tools.profile` e `agents.list[].tools.profile` (allowlist base)
- **Perfil de ferramentas do provedor**: `tools.byProvider[provider].profile` e `agents.list[].tools.byProvider[provider].profile`
- **Política de ferramentas global/por agente**: `tools.allow`/`tools.deny` e `agents.list[].tools.allow`/`agents.list[].tools.deny`
- **Política de ferramentas do provedor**: `tools.byProvider[provider].allow/deny` e `agents.list[].tools.byProvider[provider].allow/deny`
- **Política de ferramentas do sandbox** (aplica-se somente quando em sandbox): `tools.sandbox.tools.allow`/`tools.sandbox.tools.deny` e `agents.list[].tools.sandbox.tools.*`

Regras práticas:

- `deny` sempre vence.
- Se `allow` não estiver vazio, todo o resto é tratado como bloqueado.
- A política de ferramentas é a barreira rígida: `/exec` não consegue sobrescrever uma ferramenta `exec` negada.
- A política de ferramentas filtra a disponibilidade de ferramentas por nome; ela não inspeciona efeitos colaterais dentro de `exec`. Se `exec` for permitido, negar `write`, `edit` ou `apply_patch` não torna comandos shell somente leitura.
- `/exec` apenas altera padrões da sessão para remetentes autorizados; ele não concede acesso a ferramentas.
  Chaves de ferramentas do provedor aceitam `provider` (por exemplo, `google-antigravity`) ou `provider/model` (por exemplo, `openai/gpt-5.4`).

### Grupos de ferramentas (atalhos)

Políticas de ferramentas (globais, de agente, de sandbox) aceitam entradas `group:*` que se expandem para várias ferramentas:

```json5
{
  tools: {
    sandbox: {
      tools: {
        allow: ["group:runtime", "group:fs", "group:sessions", "group:memory"],
      },
    },
  },
}
```

Grupos disponíveis:

- `group:runtime`: `exec`, `process`, `code_execution` (`bash` é aceito como
  um alias para `exec`)
- `group:fs`: `read`, `write`, `edit`, `apply_patch`
  Para agentes somente leitura, negue `group:runtime` além das ferramentas mutáveis do sistema de arquivos, a menos que a política de sistema de arquivos do sandbox ou um limite de host separado imponha a restrição de somente leitura.
- `group:sessions`: `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status`
- `group:memory`: `memory_search`, `memory_get`
- `group:web`: `web_search`, `x_search`, `web_fetch`
- `group:ui`: `browser`, `canvas`
- `group:automation`: `heartbeat_respond`, `cron`, `gateway`
- `group:messaging`: `message`
- `group:nodes`: `nodes`
- `group:agents`: `agents_list`, `update_plan`
- `group:media`: `image`, `image_generate`, `music_generate`, `video_generate`, `tts`
- `group:openclaw`: todas as ferramentas integradas do OpenClaw (exclui plugins de provedor)

## Elevated: "executar no host" somente para exec

Elevated **não** concede ferramentas extras; ele afeta apenas `exec`.

- Se você estiver em sandbox, `/elevated on` (ou `exec` com `elevated: true`) executa fora do sandbox (aprovações ainda podem se aplicar).
- Use `/elevated full` para pular aprovações de exec na sessão.
- Se você já estiver executando diretamente, Elevated é efetivamente um no-op (ainda sujeito a gate).
- Elevated **não** tem escopo de Skills e **não** sobrescreve allow/deny de ferramentas.
- Elevated não concede sobrescritas arbitrárias entre hosts a partir de `host=auto`; ele segue as regras normais de destino de exec e só preserva `node` quando o destino configurado/da sessão já é `node`.
- `/exec` é separado de Elevated. Ele apenas ajusta padrões de exec por sessão para remetentes autorizados.

Gates:

- Habilitação: `tools.elevated.enabled` (e opcionalmente `agents.list[].tools.elevated.enabled`)
- Allowlists de remetentes: `tools.elevated.allowFrom.<provider>` (e opcionalmente `agents.list[].tools.elevated.allowFrom.<provider>`)

Veja [Modo Elevated](/pt-BR/tools/elevated).

## Correções comuns para "prisão de sandbox"

### "Ferramenta X bloqueada pela política de ferramentas do sandbox"

Chaves de correção (escolha uma):

- Desabilitar sandbox: `agents.defaults.sandbox.mode=off` (ou por agente `agents.list[].sandbox.mode=off`)
- Permitir a ferramenta dentro do sandbox:
  - remova-a de `tools.sandbox.tools.deny` (ou por agente `agents.list[].tools.sandbox.tools.deny`)
  - ou adicione-a a `tools.sandbox.tools.allow` (ou allow por agente)

### "Achei que isso era main; por que está em sandbox?"

No modo `"non-main"`, chaves de grupo/canal _não_ são main. Use a chave da sessão main (mostrada por `sandbox explain`) ou altere o modo para `"off"`.

## Relacionados

- [Sandboxing](/pt-BR/gateway/sandboxing) -- referência completa de sandbox (modos, escopos, backends, imagens)
- [Sandbox e Ferramentas Multiagente](/pt-BR/tools/multi-agent-sandbox-tools) -- sobrescritas e precedência por agente
- [Modo Elevated](/pt-BR/tools/elevated)