OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Agent coordination

Sandbox e ferramentas multiagente

Status: active

Cada agente em uma configuração multiagente pode substituir a política global de sandbox e ferramentas. Esta página aborda a configuração por agente, as regras de precedência e exemplos.

Isolamento em sandbox

Backends e modos — referência completa de sandbox.
Sandbox vs. política de ferramentas vs. modo elevado

Depure "por que isso está bloqueado?"
Modo elevado

Execução elevada para remetentes confiáveis.

Exemplos de configuração

Exemplo 1: Agente pessoal + agente familiar restrito
json
{  "agents": {    "list": [      {        "id": "main",        "default": true,        "name": "Personal Assistant",        "workspace": "~/.openclaw/workspace",        "sandbox": { "mode": "off" }      },      {        "id": "family",        "name": "Family Bot",        "workspace": "~/.openclaw/workspace-family",        "sandbox": {          "mode": "all",          "scope": "agent"        },        "tools": {          "allow": ["read", "message"],          "deny": ["exec", "write", "edit", "apply_patch", "process", "browser"],          "message": {            "crossContext": {              "allowWithinProvider": false,              "allowAcrossProviders": false            }          }        }      }    ]  },  "bindings": [    {      "agentId": "family",      "match": {        "provider": "whatsapp",        "accountId": "*",        "peer": {          "kind": "group",          "id": "120363424282127706@g.us"        }      }    }  ]}

Resultado:

  • Agente main: é executado no host, com acesso completo às ferramentas.
  • Agente family: é executado no Docker (um contêiner por agente), somente com read e envio de mensagens na conversa atual.
Exemplo 2: Agente de trabalho com sandbox compartilhada
json
{  "agents": {    "list": [      {        "id": "personal",        "workspace": "~/.openclaw/workspace-personal",        "sandbox": { "mode": "off" }      },      {        "id": "work",        "workspace": "~/.openclaw/workspace-work",        "sandbox": {          "mode": "all",          "scope": "shared",          "workspaceRoot": "/tmp/work-sandboxes"        },        "tools": {          "allow": ["read", "write", "apply_patch", "exec"],          "deny": ["browser", "gateway", "discord"]        }      }    ]  }}
Exemplo 2b: Perfil global de programação + agente somente para mensagens
json
{  "tools": { "profile": "coding" },  "agents": {    "list": [      {        "id": "support",        "tools": { "profile": "messaging", "allow": ["slack"] }      }    ]  }}

Resultado:

  • Os agentes padrão recebem ferramentas de programação.
  • O agente support é somente para mensagens (+ ferramenta do Slack).
Exemplo 3: Modos de sandbox diferentes por agente
json
{  "agents": {    "defaults": {      "sandbox": {        "mode": "non-main",        "scope": "session"      }    },    "list": [      {        "id": "main",        "workspace": "~/.openclaw/workspace",        "sandbox": {          "mode": "off"        }      },      {        "id": "public",        "workspace": "~/.openclaw/workspace-public",        "sandbox": {          "mode": "all",          "scope": "agent"        },        "tools": {          "allow": ["read"],          "deny": ["exec", "write", "edit", "apply_patch"]        }      }    ]  }}

Precedência da configuração

Quando existem configurações globais (agents.defaults.*) e específicas do agente (agents.list[].*):

Configuração da sandbox

As configurações específicas do agente substituem as globais:

text
agents.list[].sandbox.mode > agents.defaults.sandbox.modeagents.list[].sandbox.scope > agents.defaults.sandbox.scopeagents.list[].sandbox.workspaceRoot > agents.defaults.sandbox.workspaceRootagents.list[].sandbox.workspaceAccess > agents.defaults.sandbox.workspaceAccessagents.list[].sandbox.docker.* > agents.defaults.sandbox.docker.*agents.list[].sandbox.browser.* > agents.defaults.sandbox.browser.*agents.list[].sandbox.prune.* > agents.defaults.sandbox.prune.*

Restrições de ferramentas

A ordem de filtragem é:

  • Perfil de ferramentas

    tools.profile ou agents.list[].tools.profile.

  • Perfil de ferramentas do provedor

    tools.byProvider[provider].profile ou agents.list[].tools.byProvider[provider].profile.

  • Política global de ferramentas

    tools.allow / tools.deny.

  • Política de ferramentas do provedor

    tools.byProvider[provider].allow/deny.

  • Política de ferramentas específica do agente

    agents.list[].tools.allow/deny.

  • Política de provedor do agente

    agents.list[].tools.byProvider[provider].allow/deny.

  • Política de ferramentas da sandbox

    tools.sandbox.tools ou agents.list[].tools.sandbox.tools.

  • Política de ferramentas de subagentes

    tools.subagents.tools, se aplicável.

    • Regras de precedência
    • Cada nível pode restringir ainda mais as ferramentas, mas não pode conceder novamente ferramentas negadas em níveis anteriores.
    • Se agents.list[].tools.sandbox.tools estiver definido, ele substituirá tools.sandbox.tools para esse agente.
    • Se agents.list[].tools.profile estiver definido, ele substituirá tools.profile para esse agente.
    • As chaves de ferramentas do provedor aceitam provider (por exemplo, google-antigravity) ou provider/model (por exemplo, openai/gpt-5.4).
    Comportamento de uma lista de permissões vazia

    Se qualquer lista de permissões explícita nessa cadeia deixar a execução sem ferramentas que possam ser chamadas, o OpenClaw interromperá o processo antes de enviar o prompt ao modelo. Isso é intencional: um agente configurado com uma ferramenta ausente, como agents.list[].tools.allow: ["query_db"], deve falhar de forma explícita até que o Plugin que registra query_db seja habilitado, em vez de continuar como um agente somente de texto.

    As políticas de ferramentas aceitam abreviações group:* que se expandem para várias ferramentas. Consulte Grupos de ferramentas para ver a lista completa.

    As substituições de modo elevado por agente (agents.list[].tools.elevated) podem restringir ainda mais a execução elevada para agentes específicos. Consulte Modo elevado para obter detalhes.

    Migração de um único agente

    Antes (um único agente)

    json
    {  "agents": {    "defaults": {      "workspace": "~/.openclaw/workspace",      "sandbox": {        "mode": "non-main"      }    }  },  "tools": {    "sandbox": {      "tools": {        "allow": ["read", "write", "apply_patch", "exec"],        "deny": []      }    }  }}

    Depois (multiagente)

    json
    {  "agents": {    "list": [      {        "id": "main",        "default": true,        "workspace": "~/.openclaw/workspace",        "sandbox": { "mode": "off" }      }    ]  }}

    Exemplos de restrição de ferramentas

    Agente somente leitura

    json
    {  "tools": {    "allow": ["read"],    "deny": ["exec", "write", "edit", "apply_patch", "process"]  }}

    Execução de shell com ferramentas do sistema de arquivos desabilitadas

    json
    {  "tools": {    "allow": ["read", "exec", "process"],    "deny": ["write", "edit", "apply_patch", "browser", "gateway"]  }}

    Somente comunicação

    json
    {  "tools": {    "sessions": { "visibility": "tree" },    "allow": ["sessions_list", "sessions_send", "sessions_history", "session_status"],    "deny": ["exec", "write", "edit", "apply_patch", "read", "browser"]  }}

    sessions_history neste perfil ainda retorna uma visualização de recuperação limitada e sanitizada, em vez de um despejo bruto da transcrição. A recuperação do assistente remove tags de raciocínio, estruturas auxiliares <relevant-memories>, cargas XML de chamadas de ferramentas em texto simples (incluindo <tool_call>...</tool_call>, <function_call>...</function_call>, <tool_calls>...</tool_calls>, <function_calls>...</function_calls> e blocos truncados de chamadas de ferramentas), estruturas auxiliares degradadas de chamadas de ferramentas, tokens de controle de modelo ASCII/de largura completa que tenham vazado e XML malformado de chamadas de ferramentas do MiniMax antes da ocultação/truncamento.

    Armadilha comum: "non-main"

    Testes

    Depois de configurar a sandbox e as ferramentas multiagente:

  • Verificar a resolução dos agentes

    bash
    openclaw agents list --bindings

  • Verificar os contêineres da sandbox

    bash
    docker ps --filter "name=openclaw-sbx-"

  • Testar as restrições de ferramentas

    • Envie uma mensagem que exija ferramentas restritas.
    • Verifique se o agente não consegue usar as ferramentas negadas.

  • Monitorar os logs

    bash
    openclaw logs --follow | grep -E "routing|sandbox|tools"

    • Solução de problemas

    O agente não é executado em sandbox apesar de `mode: 'all'`
    • Verifique se há um agents.defaults.sandbox.mode global que o substitui.
    • A configuração específica do agente tem precedência, portanto defina agents.list[].sandbox.mode: "all".
    Ferramentas ainda disponíveis apesar da lista de negação
    Contêiner não isolado por agente
    • O scope padrão é "agent" (um contêiner por ID de agente).
    • Defina scope: "session" para ter um contêiner por sessão ou scope: "shared" para reutilizar um contêiner entre agentes.

    Relacionados

    Was this useful?
    On this page

    On this page