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 desees que OpenClaw ponga en exec, herramientas de archivo 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 alcance bajo sandbox.ssh.workspaceRoot.
  • En el primer uso después de crear o recrear, OpenClaw siembra 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 del prompt y la preparación de medios entrantes se ejecutan directamente contra el espacio de trabajo remoto a través de SSH.
  • OpenClaw no sincroniza automáticamente los cambios remotos de vuelta al espacio de trabajo local.
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 los 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 de canonicalidad remota

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

  • Las ediciones locales en el host realizadas fuera de OpenClaw después del paso de siembra no son visibles remotamente hasta que recrees el entorno aislado.
  • openclaw sandbox recreate elimina la raíz remota por alcance y vuelve a sembrar desde lo local en el próximo 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 aísle herramientas en un entorno remoto administrado por OpenShell. Para ver la guía completa de configuración, la referencia de configuración y la comparación de modos de espacio de trabajo, consulta la página dedicada a OpenShell.

OpenShell reutiliza el mismo transporte SSH central y el 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) además del 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 permanece 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 crear el sandbox. OpenClaw inicializa 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 usado por backend: “ssh”. - En el modo mirror` solo difiere el ciclo de vida: sincronizar de local a remoto antes de la ejecución y 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 desees que el espacio de trabajo local se mantenga canónico.

Comportamiento:

  • Antes de exec, OpenClaw sincroniza el espacio de trabajo local en el sandbox 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 sandbox, pero el espacio de trabajo local sigue siendo la fuente de verdad entre turnos.

Usa esto cuando:

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

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

Elija mirror si considera el sandbox como un entorno de ejecución temporal. Elija remote si considera 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 entornos de ejecución de OpenShell así como los entornos de ejecución de Docker
  • openclaw sandbox recreate elimina el entorno 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 sigue utilizando el espacio de trabajo local como fuente canónica entre turnos de ejecución
  • El modo remote utiliza el espacio de trabajo de OpenShell remoto como fuente canónica después de la semilla inicial
  • workspaceAccess: "ro" y "none" todavía 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 adicionales del host en el contenedor. Formato: host:container:mode (por ejemplo, "/home/user/source:/source:rw").

Los enlaces globales y por agente se fusionan (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 una obtención del código fuente:

    Ventana de terminal
    scripts/sandbox-setup.sh

    Desde una instalación de npm (no se necesita obtención del código fuente):

    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 mediante sandbox.docker.setupCommand (requiere salida de red + root escribible + usuario root).

    OpenClaw no sustituye silenciosamente debian:bookworm-slim simple cuando falta openclaw-sandbox:bookworm-slim. Las ejecuciones en sandbox que apuntan a la imagen predeterminada fallan rápidamente con una instrucción de compilación hasta que la construya, porque la imagen empaquetada lleva 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 una obtención del código fuente:

    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 una obtención del código fuente:

    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 manera predeterminada, los contenedores de espacio aislado de Docker se ejecutan sin red. Anule esto con agents.defaults.sandbox.docker.network.

Valores predeterminados de Chromium para el navegador de espacio aislado

La imagen del navegador de espacio aislado incluida también aplica valores predeterminados de inicio de Chromium conservadores para las 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 banderas de endurecimiento de gráficos (—disable-3d-apis, —disable-software-rasterizer, —disable-gpu) son opcionales y son útiles cuando los contenedores no cuentan con soporte de GPU. Establezca OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0si su carga de trabajo requiere WebGL u otras funciones 3D/de navegador. -—disable-extensionsestá habilitado de manera 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 (no en contenedor), use `browser.extraArgs` para agregar banderas de inicio adicionales.
Valores predeterminados de seguridad de red
  • network: "host" está bloqueado.
  • `network: “container:

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

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

Para las implementaciones 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 valor predeterminado de docker.network es "none" (sin salida), por lo que las instalaciones de paquetes fallarán.
  • `docker.network: “container:

“requieredangerouslyAllowContainerNamespaceJoin: truey es solo para casos de emergencia. -readOnlyRoot: trueevita escrituras; establezcareadOnlyRoot: falseo prepare una imagen personalizada. -userdebe ser root para instalaciones de paquetes (omitausero establezcauser: “0:0”). - La ejecución del sandbox **no** hereda el process.envdel host. Useagents.defaults.sandbox.docker.env(o una imagen personalizada) para las claves API de habilidades. - Los valores enagents.defaults.sandbox.docker.envse pasan como variables de entorno explícitas del contenedor Docker. Cualquier persona con acceso al demonio de Docker puede inspeccionarlas 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 una vía de escape explícita 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 para remitentes autorizados y persisten por sesión; para deshabilitar permanentemente exec, use la denegación de 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 arreglo.
  • Consulte Sandbox vs Tool Policy vs Elevated para ver 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 el sandbox y las herramientas: agents.list[].sandbox y agents.list[].tools (más agents.list[].tools.sandbox.tools para la política de herramientas del sandbox). Consulte Multi-Agent Sandbox & Tools para obtener información sobre 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»