Agent coordination

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 configuração por agente, regras de precedência e exemplos.

Isolamento em sandbox

Backends e modos — referência completa de sandbox.

Sandbox vs política de ferramentas vs elevado

Depure "por que isto está bloqueado?"

Modo elevado

Exec elevado para remetentes confiáveis.

Exemplos de configuração

Exemplo 1: Agente pessoal + 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"],
          "deny": ["exec", "write", "edit", "apply_patch", "process", "browser"]
        }
      }
    ]
  },
  "bindings": [
    {
      "agentId": "family",
      "match": {
        "provider": "whatsapp",
        "accountId": "*",
        "peer": {
          "kind": "group",
          "id": "[email protected]"
        }
      }
    }
  ]
}

Resultado:

Agente main: roda no host, com acesso completo às ferramentas.
Agente family: roda no Docker (um contêiner por agente), apenas a ferramenta read.

Exemplo 2: Agente de trabalho com sandbox compartilhado

{
  "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 codificação + agente apenas de mensagens

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

Resultado:

agentes padrão recebem ferramentas de codificação.
o agente support é apenas de mensagens (+ ferramenta Slack).

Exemplo 3: Diferentes modos de sandbox 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 de configuração

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

Configuração de 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.*

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 do sandbox

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

Política de ferramentas de subagente

tools.subagents.tools, se aplicável.

Regras de precedência

Cada nível pode restringir ainda mais as ferramentas, mas não pode reabilitar ferramentas negadas por 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 do provedor aceitam provider (por exemplo, google-antigravity) ou provider/model (por exemplo, openai/gpt-5.4).

Comportamento de lista de permissões vazia

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 explicitamente até que o Plugin que registra query_db esteja habilitado, em vez de continuar como um agente apenas de texto.

Políticas de ferramentas oferecem suporte a atalhos 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 o exec elevado para agentes específicos. Consulte Modo elevado para detalhes.

Migração de agente único

Antes (agente único)

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

Depois (multiagente)

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

Exemplos de restrição de ferramentas

Agente somente leitura

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

Execução segura (sem modificações de arquivo)

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

Apenas comunicação

{
  "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 pensamento, estrutura auxiliar <relevant-memories>, payloads XML de chamadas de ferramenta 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 ferramenta), estrutura auxiliar rebaixada de chamadas de ferramenta, tokens de controle de modelo ASCII/largura total vazados e XML de chamadas de ferramenta MiniMax malformado antes da redação/truncamento.

Armadilha comum: "non-main"

Testes

Depois de configurar sandbox e ferramentas multiagente:

Verificar 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, então 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 reabilitar.
Verifique com 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.

Relacionados

Modo elevado
Roteamento multiagente
Configuração de sandbox
Sandbox vs política de ferramentas vs elevado — depurando "por que isto está bloqueado?"
Isolamento em sandbox — referência completa de sandbox (modos, escopos, backends, imagens)
Gerenciamento de sessões

# Exemplos de configuração

# Precedência de configuração

# Configuração de sandbox

# Restrições de ferramentas

Perfil de ferramentas

Perfil de ferramentas do provedor

Política global de ferramentas

Política de ferramentas do provedor

Política de ferramentas específica do agente

Política de provedor do agente

Política de ferramentas do sandbox

Política de ferramentas de subagente

# Migração de agente único

Antes (agente único)

Depois (multiagente)

# Exemplos de restrição de ferramentas

Agente somente leitura

Execução segura (sem modificações de arquivo)

Apenas comunicação

# Armadilha comum: "non-main"

# Testes

Verificar resolução de agentes

Verificar contêineres de sandbox

Testar restrições de ferramentas

Monitorar logs

# Solução de problemas

# Relacionados

Exemplos de configuração

Precedência de 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

Relacionados