Aislamiento en entorno seguro

OpenClaw puede ejecutar herramientas dentro de un backend de entorno aislado para reducir el radio de impacto. El aislamiento está desactivado de forma predeterminada y se controla mediante agents.defaults.sandbox (global) o agents.entries.*.sandbox (por agente). El proceso Gateway siempre permanece en el host; cuando se habilita el aislamiento, solo la ejecución de herramientas se traslada al entorno aislado.

Qué se ejecuta en el entorno aislado

• Ejecución de herramientas: exec, read, write, edit, apply_patch, process, etc.
• El navegador opcional del entorno aislado (agents.defaults.sandbox.browser).

No se ejecutan en el entorno aislado:

• El propio proceso Gateway.
• Cualquier herramienta a la que se permita explícitamente ejecutarse fuera del entorno aislado mediante tools.elevated. La ejecución elevada omite el aislamiento y se ejecuta en la ruta de escape configurada (gateway de forma predeterminada, o node cuando el destino de ejecución es node). Si el aislamiento está desactivado, tools.elevated no cambia nada, ya que la ejecución se realiza en el host. Consulte Modo elevado.

Modos, ámbito y backend

Tres ajustes independientes controlan el comportamiento del entorno aislado:

El modo controla cuándo se aplica el aislamiento:

• off: sin aislamiento.
• non-main: ejecuta en un entorno aislado todas las sesiones excepto la sesión principal del agente. La clave de la sesión principal siempre es agent:<agentId>:main (o global cuando session.scope es "global"); no se puede configurar. Las sesiones de grupos o canales usan sus propias claves, por lo que siempre se consideran no principales y se ejecutan en un entorno aislado.
• all: todas las sesiones se ejecutan en un entorno aislado.

El ámbito controla cuántos contenedores o entornos se crean:

• agent: un contenedor por agente.
• session: un contenedor por sesión.
• shared: un contenedor compartido por todas las sesiones aisladas (las anulaciones por agente docker/ssh/browser se ignoran en este ámbito).

El backend controla qué entorno de ejecución ejecuta las herramientas aisladas. La configuración específica de SSH se encuentra en agents.defaults.sandbox.ssh; la configuración específica de OpenShell se encuentra en plugins.entries.openshell.config.

Backend de Docker

Docker es el backend predeterminado una vez que se habilita el aislamiento. Ejecuta las herramientas y los navegadores aislados localmente a través del socket del daemon de Docker (/var/run/docker.sock); el aislamiento procede de los espacios de nombres de Docker.

Valores predeterminados: network: "none" (sin salida), readOnlyRoot: true, capDrop: ["ALL"], imagen openclaw-sandbox:bookworm-slim.

Para exponer las GPU del host, establezca agents.defaults.sandbox.docker.gpus (o la anulación por agente) en un valor como "all" o "device=GPU-uuid". Este valor se pasa a la opción --gpus de Docker y requiere un entorno de ejecución de host compatible, como NVIDIA Container Toolkit.

Navegador aislado

• El navegador aislado se inicia automáticamente (garantiza que CDP sea accesible) cuando la herramienta de navegador lo necesita. Configúrelo mediante agents.defaults.sandbox.browser.autoStart (valor predeterminado: true) y autoStartTimeoutMs (valor predeterminado: 12s).
• Los contenedores de navegadores aislados usan una red de Docker dedicada (openclaw-sandbox-browser) en lugar de la red global bridge. Configúrela mediante agents.defaults.sandbox.browser.network.
• agents.defaults.sandbox.browser.cdpSourceRange restringe la entrada de CDP en el borde del contenedor mediante una lista de CIDR permitidos (por ejemplo, 172.21.0.1/32).
• El acceso de observador de noVNC está protegido mediante contraseña de forma predeterminada; OpenClaw emite una URL con 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 la cadena de consulta ni en los registros de cabeceras).
• agents.defaults.sandbox.browser.allowHostControl (valor predeterminado: false) permite que las sesiones aisladas seleccionen explícitamente el navegador del host.
• Las listas de permitidos opcionales controlan target: "custom": allowedControlUrls, allowedControlHosts, allowedControlPorts.

Backend de SSH

Use backend: "ssh" para ejecutar en un entorno aislado exec, las herramientas de archivos y las lecturas de medios en cualquier máquina accesible mediante 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",          // O use SecretRefs / contenido en línea en lugar de archivos locales:          // 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" },        },      },    },  },}

Valores predeterminados: command: "ssh", workspaceRoot: "/tmp/openclaw-sandboxes", strictHostKeyChecking: true, updateHostKeys: true.

• Ciclo de vida: OpenClaw crea una raíz remota por ámbito en sandbox.ssh.workspaceRoot. La primera vez que se usa después de crearla o volver a crearla, inicializa una vez ese espacio de trabajo remoto desde el espacio de trabajo local. Después, exec, read, write, edit, apply_patch, las lecturas de medios de solicitudes y la preparación de medios entrantes se ejecutan directamente en el espacio de trabajo remoto mediante SSH. OpenClaw no sincroniza automáticamente los cambios remotos con el espacio de trabajo local.
• Material de autenticación: identityFile/certificateFile/knownHostsFile hacen referencia a archivos locales existentes. identityData/certificateData/knownHostsData aceptan cadenas en línea o SecretRefs, que se resuelven mediante la instantánea normal del entorno de ejecución de secretos, se escriben en archivos temporales con el modo 0600 y se eliminan cuando termina la sesión SSH. Si se definen tanto una variante *File como una variante *Data para el mismo elemento, *Data prevalece durante esa sesión.
• Consecuencias del modelo remoto canónico: el espacio de trabajo SSH remoto se convierte en el estado real del entorno aislado después de la inicialización inicial. Las ediciones locales del host realizadas fuera de OpenClaw después de la inicialización no son visibles de forma remota hasta que se vuelve a crear el entorno aislado. openclaw sandbox recreate elimina la raíz remota por ámbito y vuelve a inicializarla desde el entorno local en el siguiente uso. Este backend no admite el aislamiento del navegador y los ajustes sandbox.docker.* no se aplican.

Backend de OpenShell

Use backend: "openshell" para ejecutar herramientas en un entorno remoto administrado por OpenShell. OpenShell reutiliza el mismo transporte SSH y el mismo puente del sistema de archivos remoto que el backend SSH genérico, y añade el ciclo de vida de OpenShell (sandbox create/get/delete/ssh-config) y un modo opcional de sincronización del espacio de trabajo mirror.

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

mode: "mirror" (predeterminado) mantiene canónico el espacio de trabajo local: OpenClaw sincroniza el contenido local con el entorno aislado antes de exec y lo vuelve a sincronizar después. mode: "remote" inicializa una vez el espacio de trabajo remoto a partir del local y luego ejecuta exec/read/write/edit/apply_patch directamente en el espacio de trabajo remoto sin sincronizarlo de vuelta; las ediciones locales posteriores a la inicialización no son visibles hasta que se ejecuta openclaw sandbox recreate. Con scope: "agent" o scope: "shared", ese espacio de trabajo remoto se comparte en el mismo ámbito. Limitaciones actuales: todavía no se admite el navegador del entorno aislado y sandbox.docker.binds no se aplica a este backend.

openclaw sandbox list/recreate/la depuración tratan los runtimes de OpenShell igual que los runtimes de Docker; la lógica de depuración tiene en cuenta el backend.

Para consultar todos los requisitos previos, la referencia de configuración, la comparación de modos del espacio de trabajo y los detalles del ciclo de vida, véase OpenShell.

Acceso al espacio de trabajo

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

Con el backend de OpenShell, el modo mirror sigue usando el espacio de trabajo local como fuente canónica entre turnos de ejecución, el modo remote usa el espacio de trabajo remoto de OpenShell como canónico después de la inicialización y workspaceAccess: "ro"/"none" siguen restringiendo el comportamiento de escritura de la misma manera.

Los archivos multimedia entrantes se copian en el espacio de trabajo activo del entorno aislado (media/inbound/*).

Varias carpetas para un agente

Utilice montajes enlazados de Docker cuando un agente en un entorno aislado necesite más carpetas además de su espacio de trabajo principal. Cada entrada asigna una carpeta del host a una ruta del contenedor con un modo de acceso explícito:

directorio-del-host:directorio-del-contenedor:rodirectorio-del-host:directorio-del-contenedor:rw

• ro hace que la carpeta montada sea de solo lectura dentro del entorno aislado.
• rw permite que las herramientas y los procesos del entorno aislado modifiquen la carpeta del host.
• La ruta del contenedor es la ruta que utiliza el agente. Las rutas del host no se exponen automáticamente.

Este ejemplo proporciona al agente research un espacio de trabajo principal con permisos de escritura, material de referencia de solo lectura en /reference y una carpeta de salida independiente con permisos de escritura en /drafts:

{  agents: {    defaults: {      sandbox: {        mode: "all",        scope: "agent",      },    },    list: [      {        id: "research",        workspace: "/srv/openclaw/research-workspace",        sandbox: {          workspaceAccess: "rw",          docker: {            binds: ["/srv/shared/reference:/reference:ro", "/srv/shared/drafts:/drafts:rw"],            // Obligatorio porque estos orígenes están fuera del espacio de trabajo del agente.            dangerouslyAllowExternalBindSources: true,          },        },      },    ],  },}

workspaceAccess y los modos de enlace son independientes:

Cambiar workspaceAccess no cambia un enlace adicional de ro a rw, ni viceversa. Los valores globales y por agente de docker.binds se combinan. Mantenga scope: "agent" o "session" para los enlaces por agente; scope: "shared" ignora todas las sustituciones de Docker por agente y utiliza únicamente los enlaces globales.

Los montajes enlazados son el límite admitido para varias carpetas porque Docker construye la vista del sistema de archivos del contenedor con aislamiento de montajes, y el modo ro/rw se aplica a todos los procesos del entorno aislado. Ese límite abarca exec, las herramientas del sistema de archivos, los procesos secundarios y las bibliotecas sin duplicar las comprobaciones de autorización de rutas en cada ruta de código de OpenClaw. Una lista de rutas permitidas en el host no puede proporcionar el mismo límite completo cuando un shell o una dependencia permitidos pueden acceder directamente a los archivos.

La opción de participación voluntaria dangerouslyAllowExternalBindSources solo permite orígenes situados fuera de las raíces del espacio de trabajo. No deshabilita las comprobaciones de OpenClaw sobre el sistema, las credenciales, el socket de Docker, los directorios superiores con enlaces simbólicos ni los destinos reservados. Utilice la carpeta más pequeña posible, use ro salvo que se requieran escrituras y vuelva a crear el entorno aislado después de cambiar los montajes:

openclaw sandbox recreate --agent research

Otros comportamientos de los enlaces

agents.defaults.sandbox.docker.binds configura los montajes globales. El formato es el mismo host:container:mode (por ejemplo, "/home/user/source:/source:rw").

agents.defaults.sandbox.browser.binds monta directorios adicionales del host únicamente en el contenedor del navegador del entorno aislado. Cuando se establece (incluido []), sustituye a docker.binds para el contenedor del navegador; cuando se omite, el contenedor del navegador recurre a docker.binds.

{  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

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

scripts/sandbox-setup.sh

docker build -t openclaw-sandbox:bookworm-slim - <<'DOCKERFILE'FROM debian:bookworm-slimENV DEBIAN_FRONTEND=noninteractiveRUN 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 sandboxUSER sandboxWORKDIR /home/sandboxCMD ["sleep", "infinity"]DOCKERFILE

scripts/sandbox-common-setup.sh

scripts/sandbox-browser-setup.sh

De forma predeterminada, los contenedores del entorno aislado de Docker se ejecutan sin red. Sustituya este comportamiento con agents.defaults.sandbox.docker.network.

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

Para las implementaciones del Gateway con Docker, scripts/docker/setup.sh puede inicializar la configuración del entorno aislado. Establezca OPENCLAW_SANDBOX=1 (o true/yes/on) para habilitar esa ruta. Sobrescriba 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)

setupCommand se ejecuta una vez después de crear el contenedor del entorno aislado (no en cada ejecución). Se ejecuta dentro del contenedor mediante sh -lc.

Rutas:

• Global: agents.defaults.sandbox.docker.setupCommand
• Por agente: agents.entries.*.sandbox.docker.setupCommand

Política de herramientas y vías de escape

Las políticas de autorización y denegación de herramientas siguen aplicándose antes que las reglas del entorno aislado. Si una herramienta está denegada globalmente o para un agente, el aislamiento no vuelve a habilitarla.

tools.elevated es una vía de escape explícita que ejecuta exec fuera del entorno aislado (gateway de forma predeterminada, o node cuando el destino de ejecución es node). Las directivas /exec solo se aplican a remitentes autorizados y persisten por sesión; para deshabilitar por completo exec, utilice la denegación de la política de herramientas (consulte Entorno aislado frente a política de herramientas y modo elevado).

Depuración:

• openclaw sandbox list muestra los contenedores de los entornos aislados, su estado, la coincidencia de imagen, la antigüedad, el tiempo de inactividad y la sesión o el agente asociados.
• openclaw sandbox explain [--session <key>] [--agent <id>] inspecciona el modo efectivo del entorno aislado, el espacio de trabajo del host, el directorio de trabajo del entorno de ejecución, los montajes de Docker, la política de herramientas y las claves de configuración para corregir problemas. Su campo workspaceRoot continúa siendo la raíz configurada del entorno aislado; effectiveHostWorkspaceRoot muestra dónde se encuentra realmente el espacio de trabajo activo.
• openclaw sandbox recreate [--all | --session <key> | --agent <id>] [--browser] [--force] elimina los contenedores y entornos para que se vuelvan a crear con la configuración actual la próxima vez que se utilicen.
• Consulte Entorno aislado frente a política de herramientas y modo elevado para entender por qué algo está bloqueado.

Sobrescrituras multiagente

Cada agente puede sobrescribir el entorno aislado y las herramientas: agents.entries.*.sandbox y agents.entries.*.tools (además de agents.entries.*.tools.sandbox.tools para la política de herramientas del entorno aislado). Consulte Entorno aislado y herramientas multiagente para conocer la precedencia.

Ejemplo mínimo de habilitación

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

Temas relacionados

• Entorno aislado y herramientas multiagente -- sobrescrituras por agente y precedencia
• OpenShell -- configuración del backend de entorno aislado administrado, modos del espacio de trabajo y referencia de configuración
• Configuración del entorno aislado
• Entorno aislado frente a política de herramientas y modo elevado -- depuración de «¿por qué está bloqueado?»
• Seguridad