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

Agent coordination

Sandbox y herramientas multiagente

Status: active

Cada agente de una configuración multiagente puede anular las políticas globales de sandbox y herramientas. Esta página abarca la configuración por agente, las reglas de precedencia y ejemplos.

Aislamiento en sandbox

Backends y modos: referencia completa del sandbox.
Sandbox frente a política de herramientas frente a modo elevado

Diagnostique «¿por qué está bloqueado esto?».
Modo elevado

Ejecución elevada para remitentes de confianza.

Ejemplos de configuración

Ejemplo 1: Agente personal + agente familiar restringido
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: se ejecuta en el host y tiene acceso completo a las herramientas.
  • Agente family: se ejecuta en Docker (un contenedor por agente) y solo puede usar read y enviar mensajes en la conversación actual.
Ejemplo 2: Agente de trabajo con sandbox compartido
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"]        }      }    ]  }}
Ejemplo 2b: Perfil global de programación + agente solo de mensajería
json
{  "tools": { "profile": "coding" },  "agents": {    "list": [      {        "id": "support",        "tools": { "profile": "messaging", "allow": ["slack"] }      }    ]  }}

Resultado:

  • Los agentes predeterminados obtienen herramientas de programación.
  • El agente support solo dispone de mensajería (+ herramienta de Slack).
Ejemplo 3: Distintos modos de sandbox 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"]        }      }    ]  }}

Precedencia de la configuración

Cuando existen tanto configuraciones globales (agents.defaults.*) como específicas del agente (agents.list[].*):

Configuración del sandbox

La configuración específica del agente prevalece sobre la global:

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.*

Restricciones de herramientas

El orden de filtrado es:

  • Perfil de herramientas

    tools.profile o agents.list[].tools.profile.

  • Perfil de herramientas del proveedor

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

  • Política global de herramientas

    tools.allow / tools.deny.

  • Política de herramientas del proveedor

    tools.byProvider[provider].allow/deny.

  • Política de herramientas específica del agente

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

  • Política de proveedor del agente

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

  • Política de herramientas del sandbox

    tools.sandbox.tools o agents.list[].tools.sandbox.tools.

  • Política de herramientas de subagentes

    tools.subagents.tools, si corresponde.

    • Reglas de precedencia
    • Cada nivel puede restringir aún más las herramientas, pero no puede volver a conceder herramientas denegadas en niveles anteriores.
    • Si se establece agents.list[].tools.sandbox.tools, sustituye a tools.sandbox.tools para ese agente.
    • Si se establece agents.list[].tools.profile, prevalece sobre tools.profile para ese agente.
    • Las claves de herramientas del proveedor aceptan provider (por ejemplo, google-antigravity) o provider/model (por ejemplo, openai/gpt-5.4).
    Comportamiento de una lista de permitidos vacía

    Si alguna lista de permitidos explícita de esa cadena deja la ejecución sin herramientas invocables, OpenClaw se detiene antes de enviar el prompt al modelo. Esto es intencionado: un agente configurado con una herramienta inexistente, como agents.list[].tools.allow: ["query_db"], debe fallar de forma visible hasta que se habilite el Plugin que registra query_db, en lugar de continuar como un agente exclusivamente de texto.

    Las políticas de herramientas admiten abreviaturas group:* que se expanden a varias herramientas. Consulte Grupos de herramientas para ver la lista completa.

    Las anulaciones del modo elevado por agente (agents.list[].tools.elevated) pueden restringir aún más la ejecución elevada para agentes específicos. Consulte Modo elevado para obtener más información.

    Migración desde un único agente

    Antes (un solo agente)

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

    Después (multiagente)

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

    Ejemplos de restricciones de herramientas

    Agente de solo lectura

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

    Ejecución de shell con las herramientas del sistema de archivos deshabilitadas

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

    Solo comunicación

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

    En este perfil, sessions_history sigue devolviendo una vista de recuperación limitada y depurada, en lugar de un volcado de la transcripción sin procesar. La recuperación del asistente elimina las etiquetas de razonamiento, la estructura auxiliar <relevant-memories>, las cargas útiles XML de llamadas a herramientas en texto sin formato (incluidos <tool_call>...</tool_call>, <function_call>...</function_call>, <tool_calls>...</tool_calls>, <function_calls>...</function_calls> y los bloques truncados de llamadas a herramientas), la estructura auxiliar degradada de llamadas a herramientas, los tokens de control del modelo filtrados en ASCII o ancho completo y el XML de llamadas a herramientas de MiniMax con formato incorrecto antes de la ocultación y el truncamiento.

    Error común: "non-main"

    Pruebas

    Después de configurar el sandbox y las herramientas para varios agentes:

  • Comprobar la resolución de agentes

    bash
    openclaw agents list --bindings

  • Verificar los contenedores del sandbox

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

  • Probar las restricciones de herramientas

    • Envíe un mensaje que requiera herramientas restringidas.
    • Verifique que el agente no pueda utilizar las herramientas denegadas.

  • Supervisar los registros

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

    • Solución de problemas

    El agente no se ejecuta en un sandbox a pesar de `mode: 'all'`
    • Compruebe si existe un agents.defaults.sandbox.mode global que lo anule.
    • La configuración específica del agente tiene precedencia, así que establezca agents.list[].sandbox.mode: "all".
    Herramientas aún disponibles pese a la lista de denegación
    El contenedor no está aislado por agente
    • El scope predeterminado es "agent" (un contenedor por id. de agente).
    • Establece scope: "session" para usar un contenedor por sesión, o scope: "shared" para reutilizar un contenedor entre agentes.

    Contenido relacionado

    Was this useful?
    On this page

    On this page