Sandbox e ferramentas multiagente

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

Sandboxing

Backends e modos — referência completa de sandbox.

Sandbox vs tool policy vs elevated

Depure “por que isto está bloqueado?”

Elevated mode

Execução elevada para remetentes confiáveis.

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

Exemplos de configuração

Example 1: Personal + restricted family agent

{
  "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: executa no host, com acesso completo às ferramentas.
agente family: executa no Docker (um contêiner por agente), apenas read e envios de mensagem na conversa atual.

Example 2: Work agent with shared sandbox

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

Example 2b: Global coding profile + messaging-only agent

{
  "tools": { "profile": "coding" },
  "agents": {
    "list": [
      {
        "id": "support",
        "tools": { "profile": "messaging", "allow": ["slack"] }
      }
    ]
  }
}

Resultado:

agentes padrão recebem ferramentas de programação.
o agente support é somente para mensagens (+ ferramenta Slack).

Example 3: Different sandbox modes per agent

{
  "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 de agente (agents.list[].*):

Configuração de sandbox

As configurações específicas de 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 resolve para "shared").

Restrições de ferramentas

A ordem de filtragem é:

Tool profile

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

Provider tool profile

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

Global tool policy

tools.allow / tools.deny.

Provider tool policy

tools.byProvider[provider].allow/deny.

Agent-specific tool policy

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

Agent provider policy

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

Sandbox tool policy

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

Subagent tool policy

tools.subagents.tools, se aplicável.

Precedence rules

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 substitui tools.sandbox.tools para esse agente.
Se agents.list[].tools.profile estiver definido, ele substitui tools.profile para esse agente.
Chaves de ferramentas de provedor aceitam provider (por exemplo, google-antigravity) ou provider/model (por exemplo, openai/gpt-5.4).

Empty allowlist behavior

Se qualquer lista de permissões explícita nessa cadeia deixar a execução sem ferramentas chamáveis, o OpenClaw para 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 clara até que o plugin que registra query_db seja habilitado, em vez de continuar como um agente apenas de texto.

Políticas de ferramentas oferecem suporte a abreviações group:*, que se expandem para várias ferramentas. Consulte Grupos de ferramentas para ver a lista completa. Substituições elevadas 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 agente único

Antes (agente único)
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" }
      }
    ]
  }
}

Configurações legadas agent.* são migradas pelo openclaw doctor; prefira agents.defaults + agents.list daqui em diante.

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 host ou o sistema de arquivos de sandbox selecionado permita. Para um agente somente leitura, negue exec e process, ou combine acesso ao shell com controles de 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 de transcrição. A recuperação do assistente remove tags de pensamento, estrutura <relevant-memories>, payloads 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), estrutura de chamadas de ferramentas rebaixada, tokens vazados de controle do modelo em ASCII/largura total e XML malformado de chamadas de ferramentas do MiniMax antes da redação/truncamento.

Armadilha comum: “non-main”

agents.defaults.sandbox.mode: "non-main" é baseado em session.mainKey (padrão "main"), não no id do agente. Sessões de grupo/canal sempre recebem suas próprias chaves, portanto são tratadas como não principais e serão colocadas em sandbox. Se você quiser que um agente nunca use sandbox, defina agents.list[].sandbox.mode: "off".

Testes

Depois de configurar sandbox e ferramentas multiagente:

Verificar a resolução de agentes

openclaw agents list --bindings

Verificar contêineres de sandbox

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

Testar restrições de ferramentas

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

Monitorar logs

tail -f "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/logs/gateway.log" | grep -E "routing|sandbox|tools"

Solução de problemas

Agente não está 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

Verifique a ordem de filtragem de ferramentas: global → agente → sandbox → subagente.
Cada nível só pode restringir ainda mais, não conceder de volta.
Verifique com os logs: [tools] filtering tools for agent:${agentId}.

Contêiner não isolado por agente

Defina scope: "agent" na configuração de sandbox específica do agente.
O padrão é "session", que cria um contêiner por sessão.

Relacionado

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

Overview

Plugins

Bundled plugin guides

Building plugins

Skills

Automation

Tools

Agent coordination

Sandbox e ferramentas multiagente

Sandboxing

Sandbox vs tool policy vs elevated

Elevated mode

Exemplos de configuração

Precedência da configuração

Configuração de sandbox

Restrições de ferramentas

Migração de agente único

Exemplos de restrição de ferramentas

Armadilha comum: “non-main”

Testes

Solução de problemas

Relacionado

Overview

Plugins

Bundled plugin guides

Building plugins

Skills

Automation

Tools

Agent coordination

Documentation Index

Sandboxing

Sandbox vs tool policy vs elevated

Elevated mode

​Exemplos de configuração

​Precedência da configuração

​Configuração de sandbox

​Restrições de ferramentas

​Migração de agente único

​Exemplos de restrição de ferramentas

​Armadilha comum: “non-main”

​Testes

​Solução de problemas

​Relacionado

Exemplos de configuração

Precedência da configuração

Configuração de sandbox

Restrições de ferramentas

Migração de agente único

Exemplos de restrição de ferramentas

Armadilha comum: “non-main”

Testes

Solução de problemas

Relacionado