Ir al contenido
OpenClaw Docs

Sandboxing

OpenClaw puede ejecutar herramientas dentro de backends de sandbox para reducir el radio de explosión. Esto es opcional y está controlado por la configuración (agents.defaults.sandbox o agents.list[].sandbox). Si el sandboxing está desactivado, las herramientas se ejecutan en el host. La Gateway se mantiene en el host; la ejecución de herramientas se ejecuta en un sandbox aislado cuando está habilitada.

Qué se pone en sandbox

Sección titulada «Qué se pone en sandbox»
  • Ejecución de herramientas (exec, read, write, edit, apply_patch, process, etc.).
  • Navegador con sandbox opcional (agents.defaults.sandbox.browser).
Detalles del navegador con sandbox
  • De forma predeterminada, el navegador sandbox se inicia automáticamente (asegura que CDP sea accesible) cuando la herramienta del navegador lo necesita. Configurarlo mediante agents.defaults.sandbox.browser.autoStart y agents.defaults.sandbox.browser.autoStartTimeoutMs.
  • De forma predeterminada, los contenedores del navegador sandbox usan una red Docker dedicada (openclaw-sandbox-browser) en lugar de la red global bridge. Configúrelo con agents.defaults.sandbox.browser.network.
  • Opcional agents.defaults.sandbox.browser.cdpSourceRange 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 de token de corta duración que sirve una página de arranque local y abre noVNC con la contraseña en el fragmento de la URL (no en registros de consulta/cabecera).
  • agents.defaults.sandbox.browser.allowHostControl permite que las sesiones con sandbox apunten explícitamente al navegador del host.
  • Las listas de permitidos opcionales controlan target: "custom": allowedControlUrls, allowedControlHosts, allowedControlPorts.

No aislado:

  • El propio proceso de la Gateway.
  • Cualquier herramienta explícitamente permitida para ejecutarse fuera del sandbox (por ejemplo, tools.elevated).
    • La ejecución elevada omite el sandboxing y utiliza la ruta de escape configurada (gateway por defecto, o node cuando el objetivo de ejecución es node).
    • Si el sandboxing está desactivado, tools.elevated no cambia la ejecución (ya está en el host). Consulte Modo elevado.

Modos

Sección titulada «Modos»

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

Sin sandboxing.

Ámbito

Sección titulada «Ámbito»

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

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

Backend

Sección titulada «Backend»

agents.defaults.sandbox.backend controla qué tiempo de ejecución proporciona el sandbox:

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

La configuración específica de SSH se encuentra bajo agents.defaults.sandbox.ssh. La configuración específica de OpenShell se encuentra bajo plugins.entries.openshell.config.

Elegir un backend

Sección titulada «Elegir un backend»
DockerSSHOpenShell
Dónde se ejecutaContenedor localCualquier host accesible por SSHSandbox administrado por OpenShell
Configuraciónscripts/sandbox-setup.shClave SSH + host de destinoComplemento OpenShell habilitado
Modelo de espacio de trabajoBind-mount o copiaRemoto canónico (sembrar una vez)mirror o remote
Control de reddocker.network (predeterminado: ninguno)Depende del host remotoDepende de OpenShell
Sandbox de navegadorCompatibleNo compatibleAún no compatible
Montajes de enlace (bind mounts)docker.bindsN/AN/A
Lo mejor paraDesarrollo local, aislamiento completoDescarga en una máquina remotaSandboxes remotos gestionados con sincronización bidireccional opcional

Backend de Docker

Sección titulada «Backend de Docker»

El aislamiento (sandboxing) está desactivado por defecto. Si habilita el aislamiento y no elige un backend, OpenClaw utiliza el backend de Docker. Ejecuta herramientas y navegadores de aislamiento localmente a través del socket del demonio Docker (/var/run/docker.sock). El aislamiento del contenedor de aislamiento está determinado por los espacios de nombres (namespaces) de Docker.

Para exponer las GPUs del anfitrión a los entornos aislados de Docker, establezca agents.defaults.sandbox.docker.gpus o la anulación agents.list[].sandbox.docker.gpus por agente. El valor se pasa al indicador --gpus de Docker como un argumento separado, por ejemplo "all" o "device=GPU-uuid", y requiere un tiempo de ejecución del anfitrión compatible, como NVIDIA Container Toolkit.

Backend SSH

Sección titulada «Backend SSH»

Use backend: "ssh" cuando desee que OpenClaw aplique sandboxing a exec, herramientas de archivos y lecturas de medios en una máquina arbitraria accesible por 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" },
        },
      },
    },
  },
}
Cómo funciona
  • OpenClaw crea una raíz remota por ámbito bajo sandbox.ssh.workspaceRoot.
  • En el primer uso después de crear o recrear, OpenClaw propaga ese espacio de trabajo remoto desde el espacio de trabajo local una vez.
  • Después de eso, exec, read, write, edit, apply_patch, las lecturas de medios de instrucciones y la transferencia de medios entrantes se ejecutan directamente contra el espacio de trabajo remoto a través de SSH.
  • OpenClaw no sincroniza los cambios remotos de vuelta al espacio de trabajo local automáticamente.
Material de autenticación
  • identityFile, certificateFile, knownHostsFile: usan archivos locales existentes y los pasan a través de la configuración de OpenSSH.
  • identityData, certificateData, knownHostsData: usan cadenas en línea o SecretRefs. OpenClaw las resuelve a través de la instantánea de tiempo de ejecución de secretos normal, las escribe en archivos temporales con 0600 y las elimina cuando termina la sesión SSH.
  • Si se establecen tanto *File como *Data para el mismo elemento, *Data tiene prioridad para esa sesión SSH.
Consecuencias canónicas remotas

Este es un modelo remoto-canónico. El espacio de trabajo SSH remoto se convierte en el estado real del entorno restringido después de la propagación inicial.

  • Las ediciones locales en el host realizadas fuera de OpenClaw después del paso de propagación no son visibles de forma remota hasta que se vuelva a crear el entorno restringido.
  • openclaw sandbox recreate elimina la raíz remota por ámbito y propaga nuevamente desde el local en el siguiente uso.
  • El aislamiento del navegador no es compatible con el backend SSH.
  • La configuración de sandbox.docker.* no se aplica al backend SSH.

Backend OpenShell

Sección titulada «Backend OpenShell»

Use backend: "openshell" cuando quieras que OpenClaw aisle las herramientas en un entorno remoto gestionado por OpenShell. Para la guía de configuración completa, la referencia de configuración y la comparación de modos de espacio de trabajo, consulta la página dedicada de OpenShell.

OpenShell reutiliza el mismo transporte SSH central y puente de sistema de archivos remoto que el backend SSH genérico, y añade un ciclo de vida específico de OpenShell (sandbox create/get/delete, sandbox ssh-config) más el modo de espacio de trabajo opcional mirror.

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

Modos de OpenShell:

  • mirror (predeterminado): el espacio de trabajo local se mantiene canónico. OpenClaw sincroniza los archivos locales en OpenShell antes de la ejecución y sincroniza el espacio de trabajo remoto de vuelta después de la ejecución.
  • remote: el espacio de trabajo de OpenShell es canónico después de que se crea el sandbox. OpenClaw siembra el espacio de trabajo remoto una vez desde el espacio de trabajo local, luego las herramientas de archivos y la ejecución se ejecutan directamente contra el sandbox remoto sin sincronizar los cambios de vuelta.
Detalles del transporte remoto
  • OpenClaw solicita a OpenShell la configuración SSH específica del sandbox a través de `openshell sandbox ssh-config

. - Core escribe esa configuración SSH en un archivo temporal, abre la sesión SSH y reutiliza el mismo puente de sistema de archivos remoto utilizado por backend: “ssh”. - En el modo mirror` solo difiere el ciclo de vida: sincronizar de local a remoto antes de la ejecución, luego sincronizar de vuelta después de la ejecución.

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

Modos de espacio de trabajo

Sección titulada «Modos de espacio de trabajo»

OpenShell tiene dos modelos de espacio de trabajo. Esta es la parte más importante en la práctica.

Use plugins.entries.openshell.config.mode: "mirror" cuando desee que el espacio de trabajo local se mantenga canónico.

Comportamiento:

  • Antes de exec, OpenClaw sincroniza el espacio de trabajo local en el espacio aislado OpenShell.
  • Después de exec, OpenClaw sincroniza el espacio de trabajo remoto de vuelta al espacio de trabajo local.
  • Las herramientas de archivos aún operan a través del puente del espacio aislado, pero el espacio de trabajo local sigue siendo la fuente de verdad entre turnos.

Use esto cuando:

  • edite archivos localmente fuera de OpenClaw y desea que esos cambios aparezcan automáticamente en el espacio aislado
  • desea que el espacio aislado OpenShell se comporte tanto como sea posible como el backend de Docker
  • desea que el espacio de trabajo del host refleje las escrituras del espacio aislado después de cada turno de ejecución

Compromiso: costo de sincronización adicional antes y después de la ejecución.

Elija mirror si piensa en el sandbox como un entorno de ejecución temporal. Elija remote si piensa en el sandbox como el espacio de trabajo real.

Ciclo de vida de OpenShell

Sección titulada «Ciclo de vida de OpenShell»

Los sandbox de OpenShell aún se gestionan a través del ciclo de vida normal del sandbox:

  • openclaw sandbox list muestra los tiempos de ejecución de OpenShell así como los tiempos de ejecución de Docker
  • openclaw sandbox recreate elimina el tiempo de ejecución actual y permite que OpenClaw lo vuelva a crear en el próximo uso
  • la lógica de poda también es consciente del backend

Para el modo remote, volver a crear es especialmente importante:

  • recrear elimina el espacio de trabajo remoto canónico para ese ámbito
  • el próximo uso inicializa un nuevo espacio de trabajo remoto desde el espacio de trabajo local

Para el modo mirror, volver a crear restablece principalmente el entorno de ejecución remoto porque el espacio de trabajo local sigue siendo canónico de todos modos.

Acceso al espacio de trabajo

Sección titulada «Acceso al espacio de trabajo»

agents.defaults.sandbox.workspaceAccess controla lo que el sandbox puede ver:

Las herramientas ven un espacio de trabajo de sandbox bajo ~/.openclaw/sandboxes.

Con el backend OpenShell:

  • El modo mirror aún usa el espacio de trabajo local como fuente canónica entre turnos de ejecución
  • El modo remote usa el espacio de trabajo de OpenShell remoto como la fuente canónica después de la semilla inicial
  • workspaceAccess: "ro" y "none" aún restringen el comportamiento de escritura de la misma manera

Los medios entrantes se copian en el espacio de trabajo del sandbox activo (media/inbound/*).

Montajes de enlace personalizados

Sección titulada «Montajes de enlace personalizados»

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

Los enlaces globales y por agente se combinan (no se reemplazan). En scope: "shared", se ignoran los enlaces por agente.

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

  • Cuando se establece (incluyendo []), reemplaza a 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 (fuente de 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"],
          },
        },
      },
    ],
  },
}

Imágenes y configuración

Sección titulada «Imágenes y configuración»

Imagen de Docker predeterminada: openclaw-sandbox:bookworm-slim

  1. Construir la imagen predeterminada

    Desde un source checkout:

    Ventana de terminal
    scripts/sandbox-setup.sh

    Desde una instalación de npm (no se necesita source checkout):

    Ventana de terminal
    docker build -t openclaw-sandbox:bookworm-slim - <<'DOCKERFILE'
    FROM debian:bookworm-slim
    ENV DEBIAN_FRONTEND=noninteractive
    RUN apt-get update && apt-get install -y --no-install-recommends \
      bash ca-certificates curl git jq python3 ripgrep \
      && rm -rf /var/lib/apt/lists/*
    RUN useradd --create-home --shell /bin/bash sandbox
    USER sandbox
    WORKDIR /home/sandbox
    CMD ["sleep", "infinity"]
    DOCKERFILE

    La imagen predeterminada no incluye Node. Si una habilidad necesita Node (u otros tiempos de ejecución), prepare una imagen personalizada o instálela a través de sandbox.docker.setupCommand (requiere salida de red + raíz grabable + usuario root).

    OpenClaw no sustituye silenciosamente el debian:bookworm-slim plano cuando falta openclaw-sandbox:bookworm-slim. Las ejecuciones en sandbox que apuntan a la imagen predeterminada fallan rápidamente con una instrucción de construcción hasta que la construya, porque la imagen empaquetada transporta python3 para los ayudantes de escritura/edición del sandbox.

  2. Opcional: construir la imagen común

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

    Desde un source checkout:

    Ventana de terminal
    scripts/sandbox-common-setup.sh

    Desde una instalación de npm, construya primero la imagen predeterminada (ver arriba) y luego construya la imagen común encima usando el scripts/docker/sandbox/Dockerfile.common del repositorio.

    Luego establezca agents.defaults.sandbox.docker.image en openclaw-sandbox-common:bookworm-slim.

  3. Opcional: construir la imagen del navegador sandbox

    Desde un source checkout:

    Ventana de terminal
    scripts/sandbox-browser-setup.sh

    Desde una instalación de npm, construya usando el scripts/docker/sandbox/Dockerfile.browser del repositorio.

De forma predeterminada, los contenedores de sandbox de Docker se ejecutan sin red. Anule esto con agents.defaults.sandbox.docker.network.

Valores predeterminados de Chromium en el navegador sandbox

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

  • --remote-debugging-address=127.0.0.1
  • `—remote-debugging-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-sandboxcuandonoSandbox está habilitado. - Las tres marcas de endurecimiento de gráficos (—disable-3d-apis, —disable-software-rasterizer, —disable-gpu) son opcionales y son útiles cuando los contenedores no tienen soporte de GPU. Establezca OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0si su carga de trabajo requiere WebGL u otras características de navegador 3D. -—disable-extensionsestá habilitado de forma predeterminada y se puede deshabilitar conOPENCLAW_BROWSER_DISABLE_EXTENSIONS=0para flujos que dependen de extensiones. -—renderer-process-limit=2está controlado porOPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=

, donde 0` mantiene el valor predeterminado de Chromium.

Si necesita un perfil de tiempo de ejecución diferente, use una imagen de navegador personalizada y proporcione su propio punto de entrada. Para los perfiles de Chromium locales (sin contenedor), use `browser.extraArgs` para agregar marcas de inicio adicionales.
Valores predeterminados de seguridad de red
  • network: "host" está bloqueado.
  • `network: “container:

“está bloqueado de forma predeterminada (riesgo de omisión de unión de espacio de nombres). - Anulación de emergencia:agents.defaults.sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`.

Las instalaciones de Docker y el gateway en contenedores viven aquí: Docker

Para los despliegues del gateway Docker, scripts/docker/setup.sh puede arrancar la configuración del sandbox. Establezca OPENCLAW_SANDBOX=1 (o true/yes/on) para habilitar esa ruta. Puede anular la ubicación del socket con OPENCLAW_DOCKER_SOCKET. Configuración completa y referencia de variables de entorno: Docker.

setupCommand (configuración única del contenedor)

Sección titulada «setupCommand (configuración única del contenedor)»

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

Rutas:

  • Global: agents.defaults.sandbox.docker.setupCommand
  • Por agente: agents.list[].sandbox.docker.setupCommand
Errores comunes
  • El docker.network predeterminado es "none" (sin salida), por lo que las instalaciones de paquetes fallarán.
  • `docker.network: “container:

“requieredangerouslyAllowContainerNamespaceJoin: truey es solo para situaciones de emergencia. -readOnlyRoot: trueevita escrituras; establezcareadOnlyRoot: falseo prepare una imagen personalizada. -userdebe ser root para las instalaciones de paquetes (omitausero establezcauser: “0:0”). - La ejecución en el sandbox **no** hereda el process.envdel host. Useagents.defaults.sandbox.docker.env(o una imagen personalizada) para las claves de API de habilidades. - Los valores enagents.defaults.sandbox.docker.envse pasan como variables de entorno explícitas del contenedor Docker. Cualquiera con acceso al demonio de Docker puede inspeccionarlos con comandos de metadatos de Docker comodocker inspect`. Use una imagen personalizada, un archivo secreto montado u otra ruta de entrega de secretos si esa exposición de metadatos no es aceptable.

Política de herramientas y salidas de emergencia

Sección titulada «Política de herramientas y salidas de emergencia»

Las políticas de permiso/denegación de herramientas todavía se aplican antes que las reglas del sandbox. Si una herramienta se deniega globalmente o por agente, el sandbox no la restaura.

tools.elevated es un escape explícito que ejecuta exec fuera del sandbox (gateway de forma predeterminada, o node cuando el objetivo de ejecución es node). Las directivas /exec solo se aplican a remitentes autorizados y persisten por sesión; para deshabilitar exec de forma estricta, use la denegación de la política de herramientas (consulte Sandbox vs Tool Policy vs Elevated).

Depuración:

  • Use openclaw sandbox explain para inspeccionar el modo efectivo de sandbox, la política de herramientas y las claves de configuración de corrección.
  • Consulte Sandbox vs Tool Policy vs Elevated para obtener el modelo mental de “¿por qué está bloqueado esto?”.

Manténgalo protegido.

Invalidaciones de multiagente

Sección titulada «Invalidaciones de multiagente»

Cada agente puede anular sandbox + herramientas: agents.list[].sandbox y agents.list[].tools (más agents.list[].tools.sandbox.tools para la política de herramientas de sandbox). Consulte Multi-Agent Sandbox & Tools para conocer la precedencia.

Ejemplo de habilitación mínima

Sección titulada «Ejemplo de habilitación mínima»
{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",
        scope: "session",
        workspaceAccess: "none",
      },
    },
  },
}

Relacionado

Sección titulada «Relacionado»