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 reemplazar la política global de aislamiento y herramientas. Esta página abarca la configuración por agente, las reglas de precedencia y ejemplos.

Aislamiento

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

Depure «¿por qué está bloqueado?»
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, con acceso completo a las herramientas.
  • Agente family: se ejecuta en Docker (un contenedor por agente), solo read y envíos de mensajes en la conversación actual.
Ejemplo 2: Agente de trabajo con aislamiento 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 es solo de mensajería (+ herramienta de Slack).
Ejemplo 3: Distintos modos de aislamiento 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.entries.*.*):

Configuración del aislamiento

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

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

Restricciones de herramientas

El orden de filtrado es:

  • Perfil de herramientas

    tools.profile o agents.entries.*.tools.profile.

  • Perfil de herramientas del proveedor

    tools.byProvider[provider].profile o agents.entries.*.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.entries.*.tools.allow/deny.

  • Política del proveedor del agente

    agents.entries.*.tools.byProvider[provider].allow/deny.

  • Política de herramientas del aislamiento

    tools.sandbox.tools o agents.entries.*.tools.sandbox.tools.

  • Política de herramientas del subagente

    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.entries.*.tools.sandbox.tools, reemplaza tools.sandbox.tools para ese agente.
    • Si se establece agents.entries.*.tools.profile, reemplaza 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 intencional: un agente configurado con una herramienta ausente como agents.entries.*.tools.allow: ["query_db"] debe fallar de forma explícita hasta que se habilite el plugin que registra query_db, en lugar de continuar como agente solo de texto.

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

    Las sustituciones elevadas por agente (agents.entries.*.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"]  }}

    sessions_history en este perfil sigue devolviendo una vista de recuperación limitada y saneada en lugar de un volcado de la transcripción sin procesar. La recuperación del asistente elimina etiquetas de razonamiento, estructuras auxiliares <relevant-memories>, cargas 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 bloques truncados de llamadas a herramientas), estructuras auxiliares degradadas de llamadas a herramientas, tokens de control del modelo ASCII/de ancho completo filtrados y XML malformado de llamadas a herramientas de MiniMax antes de la ocultación/truncamiento.

    Error común: "non-main"

    Pruebas

    Después de configurar el aislamiento y las herramientas multiagente:

  • Comprobar la resolución de agentes

    bash
    openclaw agents list --bindings

  • Verificar los contenedores de aislamiento

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

  • Probar las restricciones de herramientas

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

  • Supervisar los registros

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

    • Solución de problemas

    El agente no está aislado a pesar de `mode: 'all'`
    • Compruebe si existe un agents.defaults.sandbox.mode global que lo reemplace.
    • La configuración específica del agente tiene precedencia, por lo que debe establecer agents.entries.*.sandbox.mode: "all".
    Herramientas aún disponibles pese a la lista de denegación
    El contenedor no está aislado por agente
    • El valor predeterminado de scope es "agent" (un contenedor por id. de agente).
    • Establezca scope: "session" para usar un contenedor por sesión, o scope: "shared" para reutilizar un contenedor entre agentes.

    Temas relacionados

    Was this useful?
    On this page

    On this page