Gateway

Sandbox vs política de ferramentas vs elevado

Status: active

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

Sandbox (agents.defaults.sandbox.* / agents.list[].sandbox.*) decide onde as ferramentas rodam (backend de sandbox vs host).
Política de ferramentas (tools.*, tools.sandbox.tools.*, agents.list[].tools.*) decide quais ferramentas estão disponíveis/permitidas.
Elevado (tools.elevated.*, agents.list[].tools.elevated.*) é uma saída de emergência apenas para exec para rodar fora da 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 explainopenclaw sandbox explain --session agent:main:mainopenclaw sandbox explain --agent workopenclaw sandbox explain --json

Ele imprime:

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

Sandbox: onde as ferramentas rodam

Sandboxing é controlado por agents.defaults.sandbox.mode:

"off": tudo roda no host.
"non-main": apenas sessões não main ficam em sandbox (uma "surpresa" comum para grupos/canais).
"all": tudo fica em sandbox.

Veja Sandboxing para a matriz completa (escopo, montagens de workspace, imagens).

Bind mounts (verificação rápida de segurança)

docker.binds perfura o sistema de arquivos da sandbox: tudo que você montar fica visível dentro do contêiner com o modo definido (:ro ou :rw).
O padrão é leitura e escrita se você omitir o modo; prefira :ro para código-fonte/segredos.
scope: "shared" ignora binds por agente (apenas binds globais se aplicam).
O OpenClaw valida fontes 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 burlam verificações de caminhos bloqueados ou raízes permitidas.
Caminhos de folha inexistentes ainda são verificados com segurança. Se /workspace/alias-out/new-file resolver por meio de um pai com symlink para um caminho bloqueado ou para fora das raízes permitidas configuradas, o bind será rejeitado.
Vincular /var/run/docker.sock efetivamente entrega o controle do host à sandbox; faça isso apenas intencionalmente.
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 (lista base de permissões)
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 da 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 será tratado como bloqueado.
A política de ferramentas é a trava final: /exec não pode substituir 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 só altera padrões de sessão para remetentes autorizados; ele não concede acesso a ferramentas. Chaves de ferramentas de provedor aceitam provider (por exemplo, google-antigravity) ou provider/model (por exemplo, openai/gpt-5.4).
Logs do Gateway incluem entradas de auditoria agents/tool-policy quando uma etapa da política de ferramentas remove ferramentas ou uma política de ferramentas da sandbox bloqueia uma chamada. Use openclaw logs para ver o rótulo da regra, a chave de configuração e os nomes das ferramentas afetadas.

Grupos de ferramentas (atalhos)

Políticas de ferramentas (global, agente, 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 assim como ferramentas de sistema de arquivos mutáveis, a menos que a política de sistema de arquivos da sandbox ou um limite de host separado aplique 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)
group:plugins: todas as ferramentas carregadas pertencentes a plugins, incluindo servidores MCP configurados expostos por meio de bundle-mcp

Para servidores MCP em sandbox, a política de ferramentas da sandbox é uma segunda barreira de permissão. Se mcp.servers estiver configurado, mas turnos em sandbox mostrarem apenas ferramentas integradas, adicione bundle-mcp, group:plugins ou um nome/glob de ferramenta MCP prefixado pelo servidor, como outlook__send_mail ou outlook__*, a tools.sandbox.tools.alsoAllow; depois reinicie/recarregue o gateway e recapture a lista de ferramentas. Globs de servidor usam o prefixo de servidor MCP seguro para provedor: caracteres que não sejam [A-Za-z0-9_-] viram -, nomes que não começam com uma letra recebem um prefixo mcp-, e prefixos longos ou duplicados podem ser truncados ou receber sufixo.

openclaw doctor atualmente verifica esse formato para servidores gerenciados pelo OpenClaw em mcp.servers. Servidores MCP carregados de manifestos de plugins empacotados ou de .mcp.json do Claude usam a mesma barreira de sandbox, mas este diagnóstico ainda não enumera essas fontes; use as mesmas entradas de lista de permissões se as ferramentas deles desaparecerem em turnos em sandbox.

Elevado: "rodar no host" apenas para exec

Elevado não concede ferramentas extras; ele afeta apenas exec.

Se você estiver em sandbox, /elevated on (ou exec com elevated: true) roda fora da sandbox (aprovações ainda podem se aplicar).
Use /elevated full para pular aprovações de exec na sessão.
Se você já estiver rodando direto, elevado é efetivamente um no-op (ainda controlado).
Elevado não é limitado a Skills e não substitui allow/deny de ferramentas.
Elevado não concede substituições 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 elevado. Ele apenas ajusta padrões de exec por sessão para remetentes autorizados.

Controles:

Habilitação: tools.elevated.enabled (e opcionalmente agents.list[].tools.elevated.enabled)
Listas de permissões de remetentes: tools.elevated.allowFrom.<provider> (e opcionalmente agents.list[].tools.elevated.allowFrom.<provider>)

Veja Modo elevado.

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

"Ferramenta X bloqueada pela política de ferramentas da 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 da 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 à permissão por agente)
Verifique openclaw logs para a entrada agents/tool-policy. Ela registra o modo de sandbox e se a regra de allow ou deny bloqueou a ferramenta.

"Eu 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 -- referência completa de sandbox (modos, escopos, backends, imagens)
Sandbox e ferramentas multiagente -- substituições e precedência por agente
Modo elevado

Was this useful?