​

Sandboxing

​

Qué se ejecuta en sandbox

• Ejecución de herramientas (exec, read, write, edit, apply_patch, process, etc.).
• Navegador opcional en sandbox (agents.defaults.sandbox.browser).
  • De forma predeterminada, el navegador del sandbox se inicia automáticamente (garantiza que CDP sea accesible) cuando la herramienta de navegador lo necesita. Configúralo mediante agents.defaults.sandbox.browser.autoStart y agents.defaults.sandbox.browser.autoStartTimeoutMs.
  • De forma predeterminada, los contenedores del navegador del sandbox usan una red de Docker dedicada (openclaw-sandbox-browser) en lugar de la red global bridge. Configúralo con agents.defaults.sandbox.browser.network.
  • agents.defaults.sandbox.browser.cdpSourceRange opcional restringe el ingreso de CDP en el borde del contenedor con una lista de permitidos CIDR (por ejemplo 172.21.0.1/32).
  • El acceso de observador noVNC está protegido por contraseña de forma predeterminada; OpenClaw emite una URL con token de corta duración que sirve una página bootstrap local y abre noVNC con la contraseña en el fragmento de la URL (no en los logs de query/header).
  • 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.

• El propio proceso Gateway.
• Cualquier herramienta permitida explícitamente para ejecutarse fuera del sandbox (por ejemplo tools.elevated).
  • Elevated exec omite el sandboxing y usa la ruta de escape configurada (gateway de forma predeterminada, o node cuando el destino de exec es node).
  • Si el sandboxing está desactivado, tools.elevated no cambia la ejecución (ya está en el host). Consulta Modo Elevated.

​

Modos

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

​

Alcance

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

​

Backend

• "docker" (predeterminado cuando el sandboxing está activado): runtime de sandbox local respaldado por Docker.
• "ssh": runtime de sandbox remoto genérico respaldado por SSH.
• "openshell": runtime de sandbox respaldado por OpenShell.

​

Elegir un backend

​

Backend Docker

• La configuración requiere rutas del host: la configuración workspace en openclaw.json DEBE contener la ruta absoluta del host (por ejemplo /home/user/.openclaw/workspaces), no la ruta interna del contenedor Gateway. Cuando OpenClaw pide al daemon de Docker que cree un sandbox, el daemon evalúa las rutas en relación con el espacio de nombres del sistema operativo del host, no con el espacio de nombres del Gateway.
• Paridad de puente FS (mapa de volúmenes idéntico): el proceso nativo OpenClaw Gateway también escribe archivos de heartbeat y bridge en el directorio workspace. Como el Gateway evalúa la misma cadena exacta (la ruta del host) desde dentro de su propio entorno en contenedor, la implementación del Gateway DEBE incluir un mapa de volúmenes idéntico que enlace el espacio de nombres del host de forma nativa (-v /home/user/.openclaw:/home/user/.openclaw).

​

Backend SSH

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "ssh",
        scope: "session",
        workspaceAccess: "rw",
        ssh: {
          target: "user@gateway-host:22",
          workspaceRoot: "/tmp/openclaw-sandboxes",
          strictHostKeyChecking: true,
          updateHostKeys: true,
          identityFile: "~/.ssh/id_ed25519",
          certificateFile: "~/.ssh/id_ed25519-cert.pub",
          knownHostsFile: "~/.ssh/known_hosts",
          // Or use SecretRefs / inline contents instead of local files:
          // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" },
          // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" },
          // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" },
        },
      },
    },
  },
}

• OpenClaw crea una raíz remota por alcance en sandbox.ssh.workspaceRoot.
• En el primer uso después de crear o recrear, OpenClaw inicializa ese workspace remoto desde el workspace local una vez.
• Después de eso, exec, read, write, edit, apply_patch, lecturas de medios del prompt y el staging de medios entrantes se ejecutan directamente contra el workspace remoto por SSH.
• OpenClaw no sincroniza automáticamente los cambios remotos de vuelta al workspace local.

• identityFile, certificateFile, knownHostsFile: usan archivos locales existentes y los pasan mediante la configuración de OpenSSH.
• identityData, certificateData, knownHostsData: usan cadenas inline o SecretRefs. OpenClaw las resuelve mediante la instantánea normal del runtime de secretos, las escribe en archivos temporales con 0600 y las elimina cuando termina la sesión SSH.
• Si *File y *Data están definidos para el mismo elemento, *Data prevalece para esa sesión SSH.

• Las ediciones locales en el host realizadas fuera de OpenClaw después del paso de siembra no son visibles de forma remota hasta que recrees el sandbox.
• openclaw sandbox recreate elimina la raíz remota por alcance y vuelve a inicializar desde local en el siguiente uso.
• El sandboxing del navegador no es compatible con el backend SSH.
• La configuración sandbox.docker.* no se aplica al backend SSH.

​

Backend OpenShell

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "openshell",
        scope: "session",
        workspaceAccess: "rw",
      },
    },
  },
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          from: "openclaw",
          mode: "remote", // mirror | remote
          remoteWorkspaceDir: "/sandbox",
          remoteAgentWorkspaceDir: "/agent",
        },
      },
    },
  },
}

• mirror (predeterminado): el workspace local sigue siendo el canónico. OpenClaw sincroniza los archivos locales en OpenShell antes de exec y sincroniza de vuelta el workspace remoto después de exec.
• remote: el workspace de OpenShell es canónico después de crear el sandbox. OpenClaw inicializa el workspace remoto una vez desde el workspace local; luego las herramientas de archivos y exec se ejecutan directamente contra el sandbox remoto sin sincronizar los cambios de vuelta.

• OpenClaw pide a OpenShell una configuración SSH específica del sandbox mediante openshell sandbox ssh-config <name>.
• El núcleo escribe esa configuración SSH en un archivo temporal, abre la sesión SSH y reutiliza el mismo puente de sistema de archivos remoto usado por backend: "ssh".
• Solo en modo mirror cambia el ciclo de vida: sincroniza local a remoto antes de exec, y luego sincroniza de vuelta.

• el navegador en sandbox aún no es compatible
• sandbox.docker.binds no es compatible con el backend OpenShell
• los controles de runtime específicos de Docker bajo sandbox.docker.* siguen aplicándose solo al backend Docker

​

Modos de workspace

mirror

• Antes de exec, OpenClaw sincroniza el workspace local en el sandbox de OpenShell.
• Después de exec, OpenClaw sincroniza el workspace remoto de vuelta al workspace local.
• Las herramientas de archivos siguen operando a través del puente del sandbox, pero el workspace local sigue siendo la fuente de verdad entre turnos.

• editas archivos localmente fuera de OpenClaw y quieres que esos cambios aparezcan automáticamente en el sandbox
• quieres que el sandbox de OpenShell se comporte lo más parecido posible al backend Docker
• quieres que el workspace del host refleje las escrituras del sandbox después de cada turno de exec

• costo adicional de sincronización antes y después de exec

remote

• Cuando el sandbox se crea por primera vez, OpenClaw inicializa el workspace remoto desde el workspace local una vez.
• Después de eso, exec, read, write, edit y apply_patch operan directamente contra el workspace remoto de OpenShell.
• OpenClaw no sincroniza los cambios remotos de vuelta al workspace local después de exec.
• Las lecturas de medios en tiempo de prompt siguen funcionando porque las herramientas de archivos y medios leen a través del puente del sandbox en lugar de asumir una ruta local del host.
• El transporte es SSH hacia el sandbox de OpenShell devuelto por openshell sandbox ssh-config.

• Si editas archivos en el host fuera de OpenClaw después del paso de siembra, el sandbox remoto no verá esos cambios automáticamente.
• Si el sandbox se recrea, el workspace remoto se vuelve a inicializar desde el workspace local.
• Con scope: "agent" o scope: "shared", ese workspace remoto se comparte en ese mismo alcance.

• el sandbox debe vivir principalmente del lado remoto de OpenShell
• quieres una menor sobrecarga de sincronización por turno
• no quieres que las ediciones locales del host sobrescriban silenciosamente el estado remoto del sandbox

​

Ciclo de vida de OpenShell

• openclaw sandbox list muestra runtimes de OpenShell además de runtimes de Docker
• openclaw sandbox recreate elimina el runtime actual y deja que OpenClaw lo recree en el siguiente uso
• la lógica de prune también distingue por backend

• recreate elimina el workspace remoto canónico para ese alcance
• el siguiente uso inicializa un workspace remoto nuevo desde el workspace local

​

Acceso al workspace

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

• el modo mirror sigue usando el workspace local como fuente canónica entre turnos de exec
• el modo remote usa el workspace remoto de OpenShell como fuente canónica después de la siembra inicial
• workspaceAccess: "ro" y "none" siguen restringiendo el comportamiento de escritura de la misma manera

​

Bind mounts personalizados

• Cuando está definido (incluido []), reemplaza agents.defaults.sandbox.docker.binds para el contenedor del navegador.
• Cuando se omite, el contenedor del navegador vuelve a usar agents.defaults.sandbox.docker.binds (compatible hacia atrás).

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

• Los binds omiten el sistema de archivos del sandbox: exponen rutas del host con el modo que configures (:ro o :rw).
• OpenClaw bloquea orígenes de bind peligrosos (por ejemplo: docker.sock, /etc, /proc, /sys, /dev y montajes padre que los expondrían).
• OpenClaw también bloquea raíces comunes de credenciales en el directorio home como ~/.aws, ~/.cargo, ~/.config, ~/.docker, ~/.gnupg, ~/.netrc, ~/.npm y ~/.ssh.
• La validación de binds no se basa solo en coincidencias de cadenas. OpenClaw normaliza la ruta de origen y luego la resuelve otra vez a través del ancestro existente más profundo antes de volver a comprobar rutas bloqueadas y raíces permitidas.
• Eso significa que los escapes por padres con symlink siguen fallando de forma segura incluso cuando la hoja final aún no existe. Ejemplo: /workspace/run-link/new-file sigue resolviéndose como /var/run/... si run-link apunta allí.
• Las raíces de origen permitidas se canonicalizan del mismo modo, así que una ruta que solo parece estar dentro de la lista de permitidos antes de resolver symlinks igualmente se rechaza como outside allowed roots.
• Los montajes sensibles (secretos, claves SSH, credenciales de servicio) deberían ser :ro salvo que sea absolutamente necesario.
• Combínalo con workspaceAccess: "ro" si solo necesitas acceso de lectura al workspace; los modos de bind siguen siendo independientes.
• Consulta Sandbox vs Política de herramientas vs Elevated para ver cómo interactúan los binds con la política de herramientas y elevated exec.

​

Imágenes + configuración

scripts/sandbox-setup.sh

scripts/sandbox-common-setup.sh

scripts/sandbox-browser-setup.sh

• --remote-debugging-address=127.0.0.1
• --remote-debugging-port=<derived from 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á activado.
• Los tres flags de endurecimiento gráfico (--disable-3d-apis, --disable-software-rasterizer, --disable-gpu) son opcionales y son útiles cuando los contenedores no tienen soporte GPU. Establece OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0 si tu carga de trabajo requiere WebGL u otras funciones 3D/del navegador.
• --disable-extensions está activado de forma predeterminada y puede desactivarse con OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0 para flujos que dependan de extensiones.
• --renderer-process-limit=2 se controla con OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N>, donde 0 conserva el valor predeterminado de Chromium.

• network: "host" está bloqueado.
• network: "container:<id>" está bloqueado de forma predeterminada (riesgo de omitir unión de espacio de nombres).
• Reemplazo de último recurso: agents.defaults.sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true.

​

setupCommand (configuración única del contenedor)

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

• docker.network predeterminado es "none" (sin salida), por lo que las instalaciones de paquetes fallarán.
• docker.network: "container:<id>" requiere dangerouslyAllowContainerNamespaceJoin: true y es solo para casos de último recurso.
• readOnlyRoot: true impide escrituras; establece readOnlyRoot: false o incorpora una imagen personalizada.
• user debe ser root para instalaciones de paquetes (omite user o establece user: "0:0").
• El sandbox exec no hereda process.env del host. Usa agents.defaults.sandbox.docker.env (o una imagen personalizada) para las claves API de Skills.

​

Política de herramientas + vías de escape

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

​

Reemplazos multiagente

​

Ejemplo mínimo de activación

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

​

Documentación relacionada

• OpenShell — configuración del backend de sandbox administrado, modos de workspace y referencia de configuración
• Configuración del sandbox
• Sandbox vs Política de herramientas vs Elevated — depuración de “¿por qué está bloqueado esto?”
• Sandbox y herramientas multiagente — reemplazos por agente y precedencia
• Seguridad