Sandbox y herramientas multiagente

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

Sandboxing

Backends y modos: referencia completa de sandbox.

Sandbox vs política de herramientas vs elevado

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

Modo elevado

Exec elevado para remitentes de confianza.

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": "[email protected]"
        }
      }
    }
  ]
}

Resultado:

El agente main: se ejecuta en el host, acceso completo a las herramientas.
El 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 de codificación global + agente solo de mensajería

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

Resultado:

los agentes predeterminados obtienen herramientas de codificación.
el agente support es solo de mensajería (+ herramienta 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 tanto configuraciones globales (agents.defaults.*) como específicas del agente (agents.list[].*):

Configuración de sandbox

La configuración específica del agente anula 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.*

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 del 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 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 otorgar herramientas denegadas de niveles anteriores.
Si se establece agents.list[].tools.sandbox.tools, reemplaza a tools.sandbox.tools para ese agente.
Si se establece agents.list[].tools.profile, anula a tools.profile para ese agente.
Las claves de herramientas del proveedor aceptan provider (p. ej., google-antigravity) o provider/model (p. ej., openai/gpt-5.4).

Comportamiento de lista de permitidos vacía

Si alguna lista de permitidos explícita en esa cadena deja la ejecución sin herramientas invocables, OpenClaw se detiene antes de enviar el mensaje al modelo. Esto es intencional: un agente configurado con una herramienta faltante como agents.list[].tools.allow: ["query_db"] debería fallar claramente hasta que se habilite el complemento que registra query_db, no continuar como un agente de solo texto.

Las políticas de herramientas admiten atajos group:* que se expanden a múltiples herramientas. Consulte Grupos de herramientas para obtener la lista completa.

Las anulaciones elevadas 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 detalles.

Migración desde un solo agente

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

Ejemplos de restricción de herramientas

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

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

{
  "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 todavía devuelve una vista de recuerdo delimitada y saneada en lugar de un volcado de transcripción sin procesar. El recuerdo del asistente elimina las etiquetas de pensamiento, el andamiaje `

, las cargas útiles XML de llamadas a herramientas en texto plano (incluyendo

…

,

…

,

…

,

…

` y bloques de llamadas a herramientas truncados), andamiaje de llamadas a herramientas degradado, tokens de control de modelo ASCII/ancho completo filtrados y XML de llamadas a herramientas de MiniMax mal formados antes de la redacción/truncamiento.

Error común: “non-main”

Pruebas

Después de configurar el sandbox y las herramientas de múltiples agentes:

Verificar la resolución del agente
Ventana de terminal
```
openclaw agents list --bindings
```
Verificar los contenedores de sandbox
Ventana de terminal
```
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 usar las herramientas denegadas.

Monitorear los registros

tail -f "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/logs/gateway.log" | grep -E "routing|sandbox|tools"

Solución de problemas

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

Compruebe si hay un agents.defaults.sandbox.mode global que lo anule.
La configuración específica del agente tiene prioridad, así que establezca agents.list[].sandbox.mode: "all".

Herramientas todavía disponibles a pesar de la lista de denegación

Compruebe el orden de filtrado de herramientas: global → agente → sandbox → subagente.
Cada nivel solo puede restringir más, no otorgar permisos de nuevo.
Verifique con los registros: [tools] filtering tools for agent:${agentId}.

Contenedor no aislado por agente

Establezca scope: "agent" en la configuración de sandbox específica del agente.
El valor predeterminado es "session", que crea un contenedor por sesión.

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?”
Aislamiento (sandbox) — referencia completa del sandbox (modos, alcances, backends, imágenes)
Gestión de sesiones