Sandboxing

OpenClaw puede ejecutar herramientas dentro de contenedores Docker para reducir el radio de impacto. Esto es opcional y se controla mediante configuración (agents.defaults.sandbox o agents.list[].sandbox). Si el sandboxing está desactivado, las herramientas se ejecutan en el host. El Gateway permanece en el host; la ejecución de herramientas se ejecuta en un sandbox aislado cuando está habilitado.

Esta no es una frontera de seguridad perfecta, pero limita materialmente el acceso al sistema de archivos y a los procesos cuando el modelo hace algo imprudente.

Qué se ejecuta en sandbox

  • Ejecución de herramientas (exec, read, write, edit, apply_patch, process, etc.).
  • Navegador en sandbox opcional (agents.defaults.sandbox.browser).
    • Por defecto, el navegador del sandbox se inicia automáticamente (asegura que CDP sea alcanzable) cuando la herramienta de navegador lo necesita. Configúralo vía agents.defaults.sandbox.browser.autoStart y agents.defaults.sandbox.browser.autoStartTimeoutMs.
    • Por defecto, los contenedores del navegador en sandbox usan una red Docker dedicada (openclaw-sandbox-browser) en lugar de la red bridge global. Configúralo con agents.defaults.sandbox.browser.network.
    • El opcional agents.defaults.sandbox.browser.cdpSourceRange restringe el ingreso CDP en el borde del contenedor con una lista CIDR de permitidos (por ejemplo 172.21.0.1/32).
    • El acceso de observador noVNC está protegido por contraseña por defecto; OpenClaw emite una URL de token de corta duración que sirve una página bootstrap local y abre noVNC con la contraseña en el fragmento de URL (no en query/header de logs).
    • agents.defaults.sandbox.browser.allowHostControl permite que las sesiones en sandbox apunten explícitamente al navegador del host.
    • Las listas de permitidos opcionales controlan target: "custom": allowedControlUrls, allowedControlHosts, allowedControlPorts.

No se ejecuta en sandbox:

  • El proceso del Gateway en sí.
  • Cualquier herramienta explícitamente permitida para ejecutarse en el host (ej. tools.elevated).
    • La ejecución elevada se ejecuta en el host y omite el sandboxing.
    • Si el sandboxing está desactivado, tools.elevated no cambia la ejecución (ya está en el host). Consulta Modo elevado.

Modos

agents.defaults.sandbox.mode controla cuándo se usa el sandboxing:

  • "off": sin sandboxing.
  • "non-main": sandbox solo para sesiones no-main (por defecto si quieres chats normales en el host).
  • "all": cada sesión se ejecuta en un sandbox. Nota: "non-main" se basa en session.mainKey (por defecto "main"), no en el id del agente. Las sesiones de grupo/canal usan sus propias claves, así que cuentan como no-main y serán ejecutadas en sandbox.

Alcance

agents.defaults.sandbox.scope controla cuántos contenedores se crean:

  • "session" (por defecto): un contenedor por sesión.
  • "agent": un contenedor por agente.
  • "shared": un contenedor compartido por todas las sesiones en sandbox.

Acceso al workspace

agents.defaults.sandbox.workspaceAccess controla qué puede ver el sandbox:

  • "none" (por defecto): las herramientas ven un workspace de sandbox bajo ~/.openclaw/sandboxes.
  • "ro": monta el workspace del agente como solo lectura en /agent (deshabilita write/edit/apply_patch).
  • "rw": monta el workspace del agente con lectura/escritura en /workspace.

Los medios entrantes se copian al workspace activo del sandbox (media/inbound/*). Nota sobre skills: la herramienta read tiene raíz en el sandbox. Con workspaceAccess: "none", OpenClaw replica las skills elegibles en el workspace del sandbox (.../skills) para que puedan ser leídas. Con "rw", las skills del workspace son legibles desde /workspace/skills.

Montajes bind personalizados

agents.defaults.sandbox.docker.binds monta directorios adicionales del host en el contenedor. Formato: host:container:mode (ej., "/home/user/source:/source:rw").

Los binds globales y por agente se fusionan (no se reemplazan). Con scope: "shared", los binds por agente se ignoran.

agents.defaults.sandbox.browser.binds monta directorios adicionales del host en el contenedor del navegador en sandbox solamente.

  • Cuando se establece (incluyendo []), reemplaza agents.defaults.sandbox.docker.binds para el contenedor del navegador.
  • Cuando se omite, el contenedor del navegador recurre a agents.defaults.sandbox.docker.binds (compatible con versiones anteriores).

Ejemplo (código fuente solo lectura + un directorio de datos adicional):

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

Notas de seguridad:

  • Los binds omiten el sistema de archivos del sandbox: exponen rutas del host con el modo que configures (:ro o :rw).
  • OpenClaw bloquea fuentes de bind peligrosas (por ejemplo: docker.sock, /etc, /proc, /sys, /dev, y montajes padre que los expondrían).
  • Los montajes sensibles (secretos, claves SSH, credenciales de servicio) deberían ser :ro a menos que sea absolutamente necesario.
  • Combina con workspaceAccess: "ro" si solo necesitas acceso de lectura al workspace; los modos de bind se mantienen independientes.
  • Consulta Sandbox vs Política de herramientas vs Elevado para entender cómo interactúan los binds con la política de herramientas y la ejecución elevada.

Imágenes + configuración

Imagen por defecto: openclaw-sandbox:bookworm-slim

Constrúyela una vez:

scripts/sandbox-setup.sh

Nota: la imagen por defecto no incluye Node. Si una skill necesita Node (u otros runtimes), construye una imagen personalizada o instálalos vía sandbox.docker.setupCommand (requiere egreso de red + root escribible + usuario root).

Si quieres una imagen de sandbox más funcional con herramientas comunes (por ejemplo curl, jq, nodejs, python3, git), construye:

scripts/sandbox-common-setup.sh

Luego establece agents.defaults.sandbox.docker.image a openclaw-sandbox-common:bookworm-slim.

Imagen del navegador en sandbox:

scripts/sandbox-browser-setup.sh

Por defecto, los contenedores sandbox se ejecutan sin red. Sobrescríbelo con agents.defaults.sandbox.docker.network.

La imagen del navegador en sandbox incluida también aplica valores por defecto conservadores de inicio de Chromium para cargas de trabajo en contenedores. Los valores por defecto actuales del contenedor incluyen:

  • --remote-debugging-address=127.0.0.1
  • --remote-debugging-port=<derivado de OPENCLAW_BROWSER_CDP_PORT>
  • --user-data-dir=${HOME}/.chrome
  • --no-first-run
  • --no-default-browser-check
  • --disable-3d-apis
  • --disable-gpu
  • --disable-dev-shm-usage
  • --disable-background-networking
  • --disable-extensions
  • --disable-features=TranslateUI
  • --disable-breakpad
  • --disable-crash-reporter
  • --disable-software-rasterizer
  • --no-zygote
  • --metrics-recording-only
  • --renderer-process-limit=2
  • --no-sandbox y --disable-setuid-sandbox cuando noSandbox está habilitado.
  • Los tres flags de endurecimiento gráfico (--disable-3d-apis, --disable-software-rasterizer, --disable-gpu) son opcionales y son útiles cuando los contenedores carecen de soporte GPU. Establece OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0 si tu carga de trabajo requiere WebGL u otras funciones 3D/navegador.
  • --disable-extensions está habilitado por defecto y puede deshabilitarse con OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0 para flujos que dependen de extensiones.
  • --renderer-process-limit=2 se controla mediante OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N>, donde 0 mantiene el valor por defecto de Chromium.

Si necesitas un perfil de runtime diferente, usa una imagen de navegador personalizada y proporciona tu propio punto de entrada. Para perfiles de Chromium locales (no en contenedor), usa browser.extraArgs para agregar flags de inicio adicionales.

Valores de seguridad por defecto:

  • network: "host" está bloqueado.
  • network: "container:<id>" está bloqueado por defecto (riesgo de bypass por unión de namespace).
  • Solución de emergencia: agents.defaults.sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true.

Las instalaciones de Docker y el gateway en contenedor se encuentran aquí: Docker

Para despliegues de gateway Docker, docker-setup.sh puede configurar automáticamente el sandbox. Establece OPENCLAW_SANDBOX=1 (o true/yes/on) para habilitar esa ruta. Puedes sobrescribir la ubicación del socket con OPENCLAW_DOCKER_SOCKET. Configuración completa y referencia de env: Docker.

setupCommand (configuración única del contenedor)

setupCommand se ejecuta una vez después de crear el contenedor sandbox (no en cada ejecución). Se ejecuta dentro del contenedor vía sh -lc.

Rutas:

  • Global: agents.defaults.sandbox.docker.setupCommand
  • Por agente: agents.list[].sandbox.docker.setupCommand

Problemas comunes:

  • El docker.network por defecto es "none" (sin egreso), así que las instalaciones de paquetes fallarán.
  • docker.network: "container:<id>" requiere dangerouslyAllowContainerNamespaceJoin: true y es solo para emergencias.
  • readOnlyRoot: true impide escrituras; establece readOnlyRoot: false o construye una imagen personalizada.
  • user debe ser root para instalaciones de paquetes (omite user o establece user: "0:0").
  • La ejecución en sandbox no hereda process.env del host. Usa agents.defaults.sandbox.docker.env (o una imagen personalizada) para claves API de skills.

Política de herramientas + válvulas de escape

Las políticas allow/deny de herramientas siguen aplicándose antes que las reglas del sandbox. Si una herramienta está denegada globalmente o por agente, el sandboxing no la recupera.

tools.elevated es una válvula de escape explícita que ejecuta exec en el host. Las directivas /exec solo aplican para remitentes autorizados y persisten por sesión; para deshabilitar exec de forma permanente, usa la política deny de herramientas (consulta Sandbox vs Política de herramientas vs Elevado).

Depuración:

  • Usa openclaw sandbox explain para inspeccionar el modo de sandbox efectivo, política de herramientas y claves de configuración para solucionar.
  • Consulta Sandbox vs Política de herramientas vs Elevado para el modelo mental de “¿por qué está bloqueado esto?”. Mantenlo bloqueado.

Sobrescrituras multi-agente

Cada agente puede sobrescribir sandbox + herramientas: agents.list[].sandbox y agents.list[].tools (más agents.list[].tools.sandbox.tools para la política de herramientas del sandbox). Consulta Sandbox y herramientas multi-agente para la precedencia.

Ejemplo mínimo de habilitación

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

Documentación relacionada

arrow_back
Anterior
Security
Siguiente
Sandbox Vs Tool Policy Vs Elevated
arrow_forward