Sandbox e ferramentas multiagente

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.

A autenticação tem escopo por agente: cada agente tem seu próprio armazenamento de autenticação agentDir em ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite. Nunca reutilize o agentDir entre agentes. Os agentes podem consultar os perfis de autenticação do agente padrão/principal quando não têm um perfil local, mas os tokens de atualização OAuth não são clonados para os armazenamentos dos agentes secundários. Se você copiar credenciais manualmente, copie somente perfis estáticos portáteis de api_key ou token.

Exemplos de configuração

Exemplo 1: Agente pessoal + agente familiar restrito

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

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

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

{
  "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:

agents.list[].sandbox.mode > agents.defaults.sandbox.mode
agents.list[].sandbox.scope > agents.defaults.sandbox.scope
agents.list[].sandbox.workspaceRoot > agents.defaults.sandbox.workspaceRoot
agents.list[].sandbox.workspaceAccess > agents.defaults.sandbox.workspaceAccess
agents.list[].sandbox.docker.* > agents.defaults.sandbox.docker.*
agents.list[].sandbox.browser.* > agents.defaults.sandbox.browser.*
agents.list[].sandbox.prune.* > agents.defaults.sandbox.prune.*

agents.list[].sandbox.{docker,browser,prune}.* substitui agents.defaults.sandbox.{docker,browser,prune}.* para esse agente (é ignorado quando o escopo da sandbox é resolvido como "shared").

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)
Depois (multiagente)

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

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

As chaves de configuração legadas agents.defaults.*/agents.list[].* (como sandbox.perSession, agentRuntime, embeddedPi) são migradas por openclaw doctor; daqui em diante, prefira agents.defaults + agents.list.

Exemplos de restrição de ferramentas

Agente somente leitura
Execução de shell com ferramentas do sistema de arquivos desabilitadas
Somente comunicação

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

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

Esta política desabilita as ferramentas de sistema de arquivos do OpenClaw, mas exec ainda é um shell e pode gravar arquivos onde quer que o sistema de arquivos do host ou da sandbox selecionada permita. Para um agente somente leitura, negue exec e process ou combine o acesso ao shell com controles do sistema de arquivos da sandbox, como agents.defaults.sandbox.workspaceAccess: "ro" ou "none".

{
  "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”

agents.defaults.sandbox.mode: "non-main" compara a chave da sessão com a chave da sessão principal (sempre "main"; session.mainKey não pode ser configurada pelo usuário, e o OpenClaw avisa e ignora qualquer outro valor), e não com o ID do agente. Sessões de grupo/canal sempre recebem suas próprias chaves, portanto são tratadas como não principais e executadas em sandbox. Se você quiser que um agente nunca seja executado em sandbox, defina agents.list[].sandbox.mode: "off".

Testes

Depois de configurar a sandbox e as ferramentas multiagente:

Verificar a resolução dos agentes

openclaw agents list --bindings

Verificar os contêineres da sandbox

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

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

Confira a ordem completa de filtragem: perfil → perfil do provedor → política global → política do provedor → política do agente → política do provedor do agente → sandbox → subagente.
Cada nível só pode restringir ainda mais, não conceder novamente.
Consulte Sandbox vs. política de ferramentas vs. modo elevado para uma depuração passo a passo.

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

Modo elevado
Roteamento multiagente
Configuração do sandbox
Sandbox vs. política de ferramentas vs. modo elevado — depuração de “por que isto está bloqueado?”
Sandbox — referência completa do sandbox (modos, escopos, backends, imagens)
Gerenciamento de sessões

Overview

Plugins

Plugin guides

Building plugins

Skills

Automation

Tools

Agent coordination

Sandbox e ferramentas multiagente

Isolamento em sandbox

Sandbox vs. política de ferramentas vs. modo elevado

Modo elevado

Exemplos de configuração

Precedência da configuração

Configuração da sandbox

Restrições de ferramentas

Migração de um único agente

Exemplos de restrição de ferramentas

Armadilha comum: “non-main”

Testes

Solução de problemas

Relacionados

Isolamento em sandbox

Sandbox vs. política de ferramentas vs. modo elevado

Modo elevado

​Exemplos de configuração

​Precedência da configuração

​Configuração da sandbox

​Restrições de ferramentas

​Migração de um único agente

​Exemplos de restrição de ferramentas

​Armadilha comum: “non-main”

​Testes

​Solução de problemas

​Relacionados

Exemplos de configuração

Precedência da configuração

Configuração da sandbox

Restrições de ferramentas

Migração de um único agente

Exemplos de restrição de ferramentas

Armadilha comum: “non-main”

Testes

Solução de problemas

Relacionados