Aislamiento de procesos

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.list[].sandbox (por agente). El proceso del 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 aislado opcional (agents.defaults.sandbox.browser).

No se ejecutan en el entorno aislado:

• El propio proceso del Gateway.
• Cualquier herramienta a la que se permita explícitamente ejecutarse fuera del entorno aislado mediante tools.elevated. La ejecución con privilegios elevados 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. Consulta Modo con privilegios elevados.

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: aísla 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 grupo/canal usan sus propias claves, por lo que siempre se consideran no principales y se ejecutan de forma aislada.
• 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 de docker/ssh/browser por agente 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 habilitado el aislamiento. Ejecuta las herramientas y los navegadores aislados localmente mediante el socket del daemon de Docker (/var/run/docker.sock); el aislamiento proviene 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, establece 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 (para garantizar que CDP sea accesible) cuando la herramienta de navegador lo necesita. Configúralo mediante agents.defaults.sandbox.browser.autoStart (valor predeterminado: true) y autoStartTimeoutMs (valor predeterminado: 12 s).
• Los contenedores del navegador aislado usan una red de Docker dedicada (openclaw-sandbox-browser) en lugar de la red global bridge. Configúrala mediante agents.defaults.sandbox.browser.network.
• agents.defaults.sandbox.browser.cdpSourceRange restringe la entrada de CDP en el perímetro del contenedor mediante una lista de CIDR permitidos (por ejemplo, 172.21.0.1/32).
• El acceso de observación mediante noVNC está protegido con contraseña de forma predeterminada; OpenClaw emite una URL con un 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 encabezados).
• agents.defaults.sandbox.browser.allowHostControl (valor predeterminado: false) permite que las sesiones aisladas se dirijan explícitamente al navegador del host.
• Las listas de permitidos opcionales restringen target: "custom": allowedControlUrls, allowedControlHosts, allowedControlPorts.

Backend de SSH

Usa backend: "ssh" para aislar exec, las herramientas de archivos y las lecturas multimedia en cualquier máquina 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",          // O usa SecretRefs o 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. En el primer uso después de crearla o volver a crearla, inicializa una vez ese espacio de trabajo remoto a partir del espacio de trabajo local. Después, exec, read, write, edit, apply_patch, las lecturas multimedia de solicitudes y la preparación de contenido multimedia entrante operan directamente sobre 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 habitual del entorno de ejecución de secretos, se escriben en archivos temporales con el modo 0600 y se eliminan cuando finaliza la sesión SSH. Si se establecen las variantes *File y *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. Las modificaciones locales del host realizadas fuera de OpenClaw después de la inicialización no serán visibles de forma remota hasta que vuelvas 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

Usa backend: "openshell" para aislar las herramientas en un entorno remoto administrado por OpenShell. OpenShell reutiliza el mismo transporte SSH y el mismo puente de 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), además de 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", // mirror | remote        },      },    },  },}

mode: "mirror" (valor predeterminado) mantiene el espacio de trabajo local como canónico: OpenClaw sincroniza el contenido local con el entorno aislado antes de exec y lo sincroniza de vuelta después. mode: "remote" inicializa una vez el espacio de trabajo remoto desde el local y, a continuación, ejecuta exec/read/write/edit/apply_patch directamente sobre el espacio de trabajo remoto sin volver a sincronizarlo; los cambios locales posteriores a la inicialización no serán visibles hasta que ejecutes openclaw sandbox recreate. Con scope: "agent" o scope: "shared", ese espacio de trabajo remoto se comparte en el mismo ámbito. Limitaciones actuales: el navegador aislado aún no es compatible y sandbox.docker.binds no se aplica a este backend.

openclaw sandbox list/recreate/prune tratan los entornos de ejecución de OpenShell igual que los 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 los modos del espacio de trabajo y los detalles del ciclo de vida, consulta OpenShell.

Acceso al espacio de trabajo

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

Con el backend 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 fuente canónica después de la inicialización, y workspaceAccess: "ro"/"none" sigue restringiendo el comportamiento de escritura de la misma manera.

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

Montajes bind 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 montajes bind globales y por agente se combinan (no se reemplazan). Con scope: "shared", se ignoran los montajes bind por agente.

agents.defaults.sandbox.browser.binds monta directorios adicionales del host únicamente en el contenedor del navegador del sandbox. Cuando se establece (incluido []), reemplaza 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 sandbox de Docker se ejecutan sin red. Puede anularlo mediante agents.defaults.sandbox.docker.network.

Las instalaciones de Docker y el Gateway en contenedores se describen aquí: Docker

Para implementaciones del Gateway con Docker, scripts/docker/setup.sh puede inicializar la configuración del sandbox. Establezca OPENCLAW_SANDBOX=1 (o true/yes/on) para habilitar esa ruta. Anule la ubicación del socket con OPENCLAW_DOCKER_SOCKET. Referencia completa de la configuración y las variables de entorno: Docker.

setupCommand (configuración única del contenedor)

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

Rutas:

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

Política de herramientas y vías de escape

Las políticas de permisos y denegaciones de herramientas siguen aplicándose antes que las reglas del sandbox. Si una herramienta está denegada globalmente o para un agente concreto, el sandbox no vuelve a habilitarla.

tools.elevated es una vía de escape explícita que ejecuta exec fuera del sandbox (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 durante la sesión; para deshabilitar por completo exec, use una denegación en la política de herramientas (consulte Sandbox frente a política de herramientas frente a ejecución elevada).

Depuración:

• openclaw sandbox list muestra los contenedores del sandbox, su estado, la coincidencia de la imagen, su 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 sandbox, 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 conserva la raíz configurada del sandbox; effectiveHostWorkspaceRoot muestra dónde se encuentra realmente el espacio de trabajo activo.
• openclaw sandbox recreate [--all | --session <key> | --agent <id>] [--browser] [--force] elimina contenedores o entornos para que se vuelvan a crear con la configuración actual la próxima vez que se usen.
• Consulte Sandbox frente a política de herramientas frente a ejecución elevada para entender el modelo mental de «¿por qué está bloqueado esto?».

Anulaciones para varios agentes

Cada agente puede anular la configuración del sandbox y de las herramientas: agents.list[].sandbox y agents.list[].tools (además de agents.list[].tools.sandbox.tools para la política de herramientas del sandbox). Consulte Sandbox y herramientas para varios agentes para conocer la precedencia.

Ejemplo mínimo de habilitación

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

Relacionado

• Entorno aislado y herramientas multiagente -- anulaciones 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 esto?»
• Seguridad