Sandbox, Tool Policy y Elevated: Cómo controlar a tus agentes en OpenClaw

Configurar permisos suele ser un dolor de cabeza. A veces quieres que tu agente tenga libertad total en tu máquina para automatizar tareas, pero otras veces necesitas aislarlo para que no borre archivos importantes por accidente. Mantener ese equilibrio entre seguridad y utilidad es difícil si no entiendes dónde terminan los permisos del agente y dónde empieza el aislamiento del sistema.

Si alguna vez has sentido que tu agente está atrapado en una “cárcel” sin acceso a las herramientas que necesita, o si te preocupa que tenga demasiados privilegios, esta guía te ayudará a configurar los límites exactos.

Requisitos previos

• Tener OpenClaw instalado.
• Acceso a los archivos de configuración de tus agentes.
• Acceso a la CLI de OpenClaw.

Inicio rápido

La forma más rápida de entender qué está pasando con los permisos de tu agente es usar el inspector. Ejecuta estos comandos para ver la configuración efectiva en tiempo real:

# Ver la configuración general del sandbox
openclaw sandbox explain

# Inspeccionar una sesión específica
openclaw sandbox explain --session agent:main:main

# Ver la configuración de un agente concreto
openclaw sandbox explain --agent work

# Obtener los detalles en formato JSON para automatización
openclaw sandbox explain --json

Esto te mostrará si el sandbox está activo, qué herramientas están permitidas y si el acceso al workspace es de lectura o escritura.

Sandbox: ¿Dónde corren las herramientas?

El sandbox controla el entorno de ejecución. Se define mediante agents.defaults.sandbox.mode y tiene tres estados principales:

• "off": Todo se ejecuta directamente en el host.
• "non-main": Solo las sesiones que no son principales se ejecutan en el sandbox. Esto es lo que suele causar confusión en grupos o canales.
• "all": Absolutamente todo corre dentro de un contenedor Docker.

Si usas bind mounts en Docker mediante docker.binds, ten cuidado: cualquier cosa que montes será visible dentro del sandbox. Te recomiendo usar siempre el modo :ro (read-only) para archivos sensibles o código fuente para mantener la seguridad.

Tool Policy: ¿Qué herramientas puede usar el agente?

La política de herramientas decide qué funciones tiene permitidas invocar el agente. Hay dos reglas de oro que debes recordar:

1. deny siempre tiene prioridad sobre cualquier permiso.
2. Si defines una lista en allow, cualquier herramienta que no esté en esa lista se bloquea automáticamente.

Puedes agrupar herramientas para facilitar la configuración. Aquí tienes un ejemplo de cómo permitir grupos comunes en el sandbox:

{
  tools: {
    sandbox: {
      tools: {
        allow: ["group:runtime", "group:fs", "group:sessions", "group:memory"],
      },
    },
  },
}

Los grupos disponibles incluyen group:runtime (para exec y bash), group:fs (para lectura y escritura de archivos), group:sessions y group:openclaw (todas las herramientas nativas).

Elevated: El escape para exec

El modo Elevated no es para dar más herramientas al agente, sino para permitir que el comando exec se salte el sandbox y corra en el host.

• Si activas /elevated on, el comando exec se ejecutará en tu máquina real, aunque el agente esté en un sandbox.
• Esto no afecta a otras herramientas ni anula las políticas de allow o deny.
• Debes habilitarlo explícitamente en tools.elevated.enabled y definir quién tiene permiso en allowFrom.

Solución de problemas

”Tool X blocked by sandbox tool policy”

Si recibes este error, tienes dos opciones para solucionarlo:

• Desactiva el sandbox cambiando agents.defaults.sandbox.mode=off.
• Permite la herramienta específica añadiéndola a tools.sandbox.tools.allow (o eliminándola de la lista deny).

”¿Por qué esto está en un sandbox si es la sesión main?”

En el modo "non-main", las claves de grupos o canales no se consideran “main”. Para solucionarlo, usa la clave de sesión principal que te indica el comando sandbox explain o cambia el modo a "off".

¿Necesitas ayuda para configurar un caso específico? Prueba el AI Setup Assistant.

Próximos pasos

• Guía detallada de Sandboxing
• Uso avanzado del modo Elevated