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 realiza en un sandbox aislado cuando está habilitada.

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 (p. ej., 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" (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" (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 de sandbox localmente mediante el socket del demonio Docker (/var/run/docker.sock). El aislamiento del contenedor de sandbox lo determinan 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 al flag --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 multimedia 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 completa de configuración inicial, 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 puente de sistema de archivos remoto que el backend SSH genérico, y añade ciclo de vida específico de OpenShell (sandbox create/get/delete, sandbox ssh-config) además del 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 (predeterminado): el workspace local permanece canónico. OpenClaw sincroniza 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 crear 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 workspace real.

Ciclo de vida de OpenShell

Los sandboxes de OpenShell se siguen gestionando 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 vuelva a crear en el siguiente uso
• la lógica de depuración también conoce el backend

Para el modo remote, recreate es especialmente importante:

• recreate elimina el workspace remoto canónico para ese ámbito
• el siguiente uso inicializa un workspace remoto nuevo desde el workspace local

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

Acceso al workspace

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

Con el backend de OpenShell:

• el modo mirror sigue usando el workspace local como fuente canónica entre turnos de exec
• el modo remote usa el workspace 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 manera

Los medios entrantes se copian en el workspace 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 de 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. Anúlalo con agents.defaults.sandbox.docker.network.

Las instalaciones de Docker y el gateway en contenedor están aquí: Docker

Para despliegues del gateway con 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 anular la ubicación del socket con OPENCLAW_DOCKER_SOCKET. Configuración completa y referencia 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 permitir/denegar herramientas siguen aplicándose antes que las reglas del sandbox. Si una herramienta se deniega globalmente o por agente, el sandbox no la vuelve a habilitar.

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 exec es node). Las directivas /exec solo se aplican a remitentes autorizados y persisten por sesión; para deshabilitar exec por completo, usa una política de denegación de herramientas (consulta Sandbox vs Tool Policy vs Elevated).

Depuración:

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

Mantenlo bloqueado.

Anulaciones multiagente

Cada agente puede anular sandbox + herramientas: agents.list[].sandbox y agents.list[].tools (además de agents.list[].tools.sandbox.tools para la política de herramientas del sandbox). Consulta Sandbox multiagente y herramientas para la precedencia.

Ejemplo mínimo de habilitación

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

Relacionado

• Sandbox multiagente y herramientas — anulaciones por agente y precedencia
• OpenShell — configuración del backend de sandbox administrado, modos de espacio de trabajo y referencia de configuración
• Configuración de sandbox
• Sandbox vs Tool Policy vs Elevated — depuración de "¿por qué está bloqueado esto?"
• Seguridad