Entorno aislado y herramientas multiagente

Cada agente en una configuración multiagente puede sobrescribir la política global de sandbox y herramientas. Esta página cubre la configuración por agente, las reglas de precedencia y ejemplos.

Sandboxing

Backends y modos: referencia completa de sandbox.

Sandbox frente a política de herramientas frente a elevado

Depurar “¿por qué está bloqueado esto?”

Modo elevado

Exec elevado para remitentes de confianza.

La autenticación tiene ámbito por agente: cada agente tiene su propio almacén de autenticación agentDir en ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite. Nunca reutilices agentDir entre agentes. Los agentes pueden leer 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 copias credenciales manualmente, copia solo perfiles estáticos portátiles api_key o token.

Ejemplos de configuración

Ejemplo 1: Agente personal + 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 herramientas.
Agente family: se ejecuta en Docker (un contenedor por agente), solo read y envíos de mensajes de la conversación actual.

Ejemplo 2: Agente de trabajo con sandbox 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: 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"]
        }
      }
    ]
  }
}

Precedencia de configuración

Cuando existen configuraciones globales (agents.defaults.*) y específicas de agente (agents.list[].*):

Configuración de sandbox

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

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}.* sobrescribe agents.defaults.sandbox.{docker,browser,prune}.* para ese agente (se ignora cuando el ámbito de sandbox se resuelve como "shared").

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

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

Política de herramientas de subagente

tools.subagents.tools, si corresponde.

Reglas de precedencia

Cada nivel puede restringir más las herramientas, pero no puede volver a conceder herramientas denegadas en niveles anteriores.
Si agents.list[].tools.sandbox.tools está definido, reemplaza tools.sandbox.tools para ese agente.
Si agents.list[].tools.profile está definido, sobrescribe tools.profile para ese agente.
Las claves de herramientas de proveedor aceptan provider (por ejemplo, google-antigravity) o provider/model (por ejemplo, openai/gpt-5.4).

Comportamiento de la lista de permitidos vacía

Si cualquier lista de permitidos explícita en 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 faltante como agents.list[].tools.allow: ["query_db"] debe fallar de forma visible hasta que se habilite el plugin que registra query_db, no continuar como agente solo de texto.

Las políticas de herramientas admiten abreviaturas group:* que se expanden a varias herramientas. Consulta Grupos de herramientas para ver la lista completa. Las sobrescrituras elevadas por agente (agents.list[].tools.elevated) pueden restringir aún más el exec elevado para agentes concretos. Consulta Modo elevado para más detalles.

Migración desde agente único

Antes (agente único)
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.list[].* (como sandbox.perSession, agentRuntime, embeddedPi) son migradas por openclaw doctor; prefiere agents.defaults + agents.list de ahora en adelante.

Ejemplos de restricción de herramientas

Agente de solo lectura
Ejecución de shell con herramientas de 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 de sistema de archivos de OpenClaw, pero exec sigue siendo un shell y puede escribir archivos donde lo permita el host seleccionado o el sistema de archivos del sandbox. Para un agente de solo lectura, deniega exec y process, o combina el acceso al shell con controles de sistema de archivos del sandbox 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 recuerdo acotada y saneada, en lugar de un volcado de transcripción sin procesar. El recuerdo del asistente elimina etiquetas de pensamiento, andamiaje <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), andamiaje degradado de llamadas a herramientas, tokens filtrados de control de modelo ASCII/de ancho completo y XML de llamadas a herramientas MiniMax malformado antes de la redacción/truncamiento.

Error común: “non-main”

agents.defaults.sandbox.mode: "non-main" comprueba la clave de sesión frente a la clave de sesión principal (siempre "main"; session.mainKey no es configurable por el usuario, y OpenClaw advierte e ignora cualquier otro valor), no el id del agente. Las sesiones de grupo/canal siempre obtienen sus propias claves, por lo que se tratan como no principales y se ejecutarán en sandbox. Si quieres que un agente nunca use sandbox, establece agents.list[].sandbox.mode: "off".

Pruebas

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

Comprobar resolución de agentes

openclaw agents list --bindings

Verificar contenedores de sandbox

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

Probar restricciones de herramientas

Envía un mensaje que requiera herramientas restringidas.
Verifica que el agente no pueda usar herramientas denegadas.

Monitorizar registros

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

Solución de problemas

El agente no está en sandbox pese a `mode: 'all'`

Comprueba si hay un agents.defaults.sandbox.mode global que lo sobrescriba.
La configuración específica del agente tiene precedencia, así que establece agents.list[].sandbox.mode: "all".

Herramientas aún disponibles a pesar de la lista de denegación

Revisa el orden completo de filtrado: perfil → perfil de proveedor → política global → política de proveedor → política de agente → política de proveedor de agente → sandbox → subagente.
Cada nivel solo puede restringir más, no volver a conceder.
Consulta Sandbox vs política de herramientas vs elevado para depurar paso a paso.

Contenedor no aislado por agente

El scope predeterminado es "agent" (un contenedor por id de agente).
Define scope: "session" para un contenedor por sesión, o scope: "shared" para reutilizar un contenedor entre agentes.

Relacionado

Modo elevado
Enrutamiento multiagente
Configuración del sandbox
Sandbox vs política de herramientas vs elevado — depuración de “¿por qué está bloqueado esto?”
Sandboxing — referencia completa del sandbox (modos, ámbitos, backends, imágenes)
Gestión de sesiones

Sandboxing

Sandbox frente a política de herramientas frente a elevado

Modo elevado

​Ejemplos de configuración

​Precedencia de configuración

​Configuración de sandbox

​Restricciones de herramientas

​Migración desde agente único

​Ejemplos de restricción de herramientas

​Error común: “non-main”

​Pruebas

​Solución de problemas

​Relacionado

Ejemplos de configuración

Precedencia de configuración

Configuración de sandbox

Restricciones de herramientas

Migración desde agente único

Ejemplos de restricción de herramientas

Error común: “non-main”

Pruebas

Solución de problemas

Relacionado