Sandbox y herramientas multiagente

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.

La autenticación se limita por agente: cada agente tiene su propio almacén de autenticación agentDir en ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite. Nunca reutilice agentDir entre agentes. Los agentes pueden consultar los perfiles de autenticación del agente predeterminado/principal cuando no tienen un perfil local, pero los tokens de actualización de OAuth no se clonan en los almacenes de agentes secundarios. Si copia las credenciales manualmente, copie únicamente perfiles estáticos portátiles api_key o token.

Ejemplos de configuración

Ejemplo 1: Agente personal + agente familiar restringido

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

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

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

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

agents.entries.*.sandbox.mode > agents.defaults.sandbox.mode
agents.entries.*.sandbox.scope > agents.defaults.sandbox.scope
agents.entries.*.sandbox.workspaceRoot > agents.defaults.sandbox.workspaceRoot
agents.entries.*.sandbox.workspaceAccess > agents.defaults.sandbox.workspaceAccess
agents.entries.*.sandbox.docker.* > agents.defaults.sandbox.docker.*
agents.entries.*.sandbox.browser.* > agents.defaults.sandbox.browser.*
agents.entries.*.sandbox.prune.* > agents.defaults.sandbox.prune.*

agents.entries.*.sandbox.{docker,browser,prune}.* reemplaza agents.defaults.sandbox.{docker,browser,prune}.* para ese agente (se ignora cuando el ámbito del aislamiento se resuelve como "shared").

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)
Después (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" }
      }
    ]
  }
}

Las claves de configuración heredadas agents.defaults.*/agents.entries.*.* (como sandbox.perSession, agentRuntime, embeddedPi) se migran mediante openclaw doctor; de ahora en adelante, se recomienda usar agents.defaults + agents.entries.

Ejemplos de restricciones de herramientas

Agente de solo lectura
Ejecución de shell con las herramientas del sistema de archivos deshabilitadas
Solo comunicación

{
  "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 deshabilita las herramientas del sistema de archivos de OpenClaw, pero exec sigue siendo un shell y puede escribir archivos en cualquier lugar que permita el sistema de archivos del host o aislamiento seleccionado. Para un agente de solo lectura, deniegue exec y process, o combine el acceso al shell con controles del sistema de archivos del aislamiento, como agents.defaults.sandbox.workspaceAccess: "ro" o "none".

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

agents.defaults.sandbox.mode: "non-main" comprueba la clave de sesión con respecto a la clave de la sesión principal (siempre "main"; session.mainKey no es configurable por el usuario, y OpenClaw advierte e ignora cualquier otro valor), no el identificador del agente. Las sesiones de grupo/canal siempre obtienen sus propias claves, por lo que se tratan como no principales y se aislarán. Si desea que un agente nunca se aísle, establezca agents.entries.*.sandbox.mode: "off".

Pruebas

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

Comprobar la resolución de agentes

openclaw agents list --bindings

Verificar los contenedores de aislamiento

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

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

Consulte el orden de filtrado completo: perfil → perfil del proveedor → política global → política del proveedor → política del agente → política del proveedor del agente → entorno aislado → subagente.
Cada nivel solo puede imponer más restricciones, no volver a conceder permisos.
Consulte Entorno aislado frente a política de herramientas frente a modo elevado para depurar paso a paso.

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

Modo elevado
Enrutamiento multiagente
Configuración del entorno aislado
Entorno aislado frente a política de herramientas frente a modo elevado — depuración de «¿por qué está bloqueado?»
Aislamiento — referencia completa del entorno aislado (modos, ámbitos, backends e imágenes)
Gestión de sesiones

Overview

Plugins

Plugin guides

Building plugins

Skills

Automation

Tools

Agent coordination

Sandbox y herramientas multiagente

Aislamiento

Aislamiento frente a política de herramientas frente a modo elevado

Modo elevado

Ejemplos de configuración

Precedencia de la configuración

Configuración del aislamiento

Restricciones de herramientas

Migración desde un único agente

Ejemplos de restricciones de herramientas

Error común: “non-main”

Pruebas

Solución de problemas

Temas relacionados

Aislamiento

Aislamiento frente a política de herramientas frente a modo elevado

Modo elevado

​Ejemplos de configuración

​Precedencia de la configuración

​Configuración del aislamiento

​Restricciones de herramientas

​Migración desde un único agente

​Ejemplos de restricciones de herramientas

​Error común: “non-main”

​Pruebas

​Solución de problemas

​Temas relacionados

Ejemplos de configuración

Precedencia de la configuración

Configuración del aislamiento

Restricciones de herramientas

Migración desde un único agente

Ejemplos de restricciones de herramientas

Error común: “non-main”

Pruebas

Solución de problemas

Temas relacionados