Sandboxing en OpenClaw: Cómo aislar la ejecución de herramientas con Docker

¿Alguna vez has sentido ese pequeño escalofrío cuando dejas que un modelo de IA ejecute comandos en tu terminal? Es normal. Darle acceso total a tu sistema de archivos puede ser arriesgado si el modelo comete un error o intenta realizar cambios inesperados en tus archivos locales.

OpenClaw resuelve esto permitiendo que las herramientas se ejecuten dentro de contenedores Docker. Esto reduce el radio de impacto: el Gateway se queda en tu host, pero la ejecución de las herramientas ocurre en un sandbox aislado. No es una barrera de seguridad perfecta, pero limita de forma efectiva lo que el modelo puede tocar.

Requisitos previos

Para usar esta funcionalidad, necesitas lo siguiente según la documentación:

• Docker instalado en tu sistema.
• OpenClaw configurado y funcionando.
• Acceso a la terminal para ejecutar scripts de configuración.

Inicio rápido

Puedes activar el sandboxing en menos de 5 minutos siguiendo estos pasos:

1. Construye la imagen base: Ejecuta este script para preparar la imagen por defecto (openclaw-sandbox:bookworm-slim):

   scripts/sandbox-setup.sh

2. Configura el modo mínimo: Añade esto a tu configuración para activar el sandbox en sesiones que no sean la principal:

   {
     agents: {
       defaults: {
         sandbox: {
           mode: "non-main",
           scope: "session",
           workspaceAccess: "none",
         },
       },
     },
   }

3. Verifica la configuración: Usa el CLI para revisar que todo esté en orden:

   openclaw sandbox explain

Configuración detallada

Modos y Alcance

El parámetro agents.defaults.sandbox.mode determina cuándo se usa el aislamiento:

• "off": No hay sandboxing.
• "non-main": Solo sesiones que no son la principal (basado en session.mainKey).
• "all": Todas las sesiones van al sandbox.
• Las sesiones de grupo o canales siempre cuentan como "non-main".

El parámetro agents.defaults.sandbox.scope define cuántos contenedores se crean:

• "session": Un contenedor por cada sesión.
• "agent": Un contenedor por cada agente.
• "shared": Un único contenedor compartido por todas las sesiones.

Acceso al Workspace

Puedes controlar qué archivos puede ver el sandbox con agents.defaults.sandbox.workspaceAccess:

• "none": Las herramientas ven un workspace vacío en ~/.openclaw/sandboxes.
• "ro": Monta el workspace del agente como solo lectura en /agent.
• "rw": Monta el workspace del agente con permisos de lectura y escritura en /workspace.

Montajes personalizados (Binds)

Si necesitas carpetas específicas del host, usa agents.defaults.sandbox.docker.binds:

{
  agents: {
    defaults: {
      sandbox: {
        docker: {
          binds: ["/home/user/source:/source:ro", "/var/run/docker.sock:/var/run/docker.sock"],
        },
      },
    },
    list: [
      {
        id: "build",
        sandbox: {
          docker: {
            binds: ["/mnt/cache:/cache:rw"],
          },
        },
      },
    ],
  },
}

Solución de problemas

Si encuentras problemas, revisa estos puntos comunes:

• Instalación de paquetes falla: Por defecto, docker.network es "none". Si necesitas instalar algo en el contenedor, cambia la configuración de red para permitir salida a internet.
• Error de escritura en root: Si readOnlyRoot está en true, no podrás escribir en el sistema de archivos raíz. Cámbialo a false o crea una imagen personalizada.
• Permisos de usuario: Para instalar paquetes mediante setupCommand, necesitas ser root. Asegúrate de no definir un user o usa "0:0".
• Variables de entorno: El sandbox no hereda el process.env del host. Debes definir las API keys o secretos en agents.defaults.sandbox.docker.env.
• Node.js no encontrado: La imagen por defecto es slim y no incluye Node.js. Debes instalarlo vía setupCommand o preparar una imagen propia.

Para más ayuda, consulta el AI Setup Assistant.

Próximos pasos

• Sandbox Configuration
• Multi-Agent Sandbox & Tools
• Security
• Elevated Mode