Aislamiento

OpenClaw puede ejecutar herramientas dentro de backends de sandbox para reducir el radio de impacto. Esto es opcional y se controla mediante configuración (agents.defaults.sandbox o agents.list[].sandbox). Si el sandboxing está desactivado, las herramientas se ejecutan en el host. El Gateway permanece en el host; la ejecución de herramientas se ejecuta en un sandbox aislado cuando está habilitado.

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).

No se ejecuta en sandbox:

• El propio proceso del Gateway.
• Cualquier herramienta autorizada explícitamente para ejecutarse fuera del sandbox (por ejemplo, tools.elevated).
  • La ejecución elevada 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 elevado.

Modos

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

Alcance

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

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

Backend

agents.defaults.sandbox.backend controla qué runtime proporciona el sandbox:

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

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

Elegir un backend

Backend Docker

El sandboxing está desactivado de forma predeterminada. Si habilitas el sandboxing y no eliges un backend, OpenClaw usa el backend Docker. Ejecuta herramientas y navegadores en sandbox localmente mediante el socket del daemon de Docker (/var/run/docker.sock). El aislamiento de los contenedores de sandbox está determinado por los namespaces de Docker.

Para exponer GPU del host a sandboxes Docker, configura agents.defaults.sandbox.docker.gpus o la anulación por agente agents.list[].sandbox.docker.gpus. El valor se pasa a la marca --gpus de Docker como un argumento separado, por ejemplo "all" o "device=GPU-uuid", y requiere un runtime de host compatible, como NVIDIA Container Toolkit.

Backend SSH

Usa backend: "ssh" cuando quieras que OpenClaw ejecute en sandbox 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" },        },      },    },  },}

Backend OpenShell

Usa backend: "openshell" cuando quieras que OpenClaw ejecute herramientas en sandbox 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 workspace, consulta la página de OpenShell dedicada.

OpenShell reutiliza el mismo transporte SSH central y el mismo puente de sistema de archivos remoto que el backend SSH genérico, y agrega el ciclo de vida específico de OpenShell (sandbox create/get/delete, sandbox ssh-config) más el modo de workspace 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 (valor predeterminado): el workspace local permanece canónico. OpenClaw sincroniza los archivos locales hacia OpenShell antes de exec y sincroniza el workspace remoto de vuelta después de exec.
• remote: el workspace de OpenShell es canónico después de que se crea el sandbox. OpenClaw siembra 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 cambios de vuelta.

Modos de workspace

OpenShell tiene dos modelos de workspace. Esta es la parte que más importa en la práctica.

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

Ciclo de vida de OpenShell

Los sandboxes de OpenShell siguen gestionándose mediante el ciclo de vida normal del sandbox:

• openclaw sandbox list muestra runtimes de OpenShell además de runtimes de Docker
• openclaw sandbox recreate elimina el runtime actual y permite que OpenClaw lo recree en el siguiente uso
• la lógica de limpieza también es consciente del backend

Para el modo remote, recrear es especialmente importante:

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

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

Acceso al espacio de trabajo

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

Con el backend de OpenShell:

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

Los medios 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 binds globales y por agente se fusionan (no se reemplazan). Bajo scope: "shared", los binds por agente se ignoran.

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

• Cuando se establece (incluido []), reemplaza 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 hacia atrás).

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

Imagen Docker predeterminada: 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 de sandbox de Docker se ejecutan sin red. Sobrescríbelo con agents.defaults.sandbox.docker.network.

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

Para despliegues del Gateway de Docker, scripts/docker/setup.sh puede inicializar la configuración del sandbox. Establece OPENCLAW_SANDBOX=1 (o true/yes/on) para habilitar esa ruta. Puedes sobrescribir la ubicación del socket con OPENCLAW_DOCKER_SOCKET. Configuración completa y referencia de entorno: Docker.

setupCommand (configuración de contenedor de una sola vez)

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 permitir/denegar herramientas siguen aplicándose antes que las reglas de aislamiento. Si una herramienta se deniega de forma global o por agente, el aislamiento no la recupera.

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 exec de forma estricta, usa la denegación de la política de herramientas (consulta Aislamiento vs. política de herramientas vs. elevación).

Depuración:

• Usa openclaw sandbox explain para inspeccionar el modo de aislamiento efectivo, la política de herramientas y las claves de configuración de corrección.
• Consulta Aislamiento vs. política de herramientas vs. elevación para el modelo mental de "¿por qué está bloqueado esto?".

Manténlo bloqueado.

Sobrescrituras multiagente

Cada agente puede sobrescribir aislamiento + herramientas: agents.list[].sandbox y agents.list[].tools (más agents.list[].tools.sandbox.tools para la política de herramientas del entorno aislado). Consulta Aislamiento y herramientas multiagente para la precedencia.

Ejemplo mínimo de habilitación

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

Relacionado

• Aislamiento y herramientas multiagente — sobrescrituras por agente y precedencia
• OpenShell — configuración del backend de aislamiento gestionado, modos de espacio de trabajo y referencia de configuración
• Configuración de aislamiento
• Aislamiento vs. política de herramientas vs. elevación — depuración de "¿por qué está bloqueado esto?"
• Seguridad