Aislamiento en entorno limitado

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 (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 ejecución es node).
  • Si el sandboxing está desactivado, tools.elevated no cambia la ejecución (ya se ejecuta 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 está en agents.defaults.sandbox.ssh. La configuración específica de OpenShell está en 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 contenedores de sandbox está determinado por los namespaces de Docker.

Para exponer GPUs del host a sandboxes de Docker, configura agents.defaults.sandbox.docker.gpus o la sobrescritura 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 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, 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 añade ciclo de vida específico de OpenShell (sandbox create/get/delete, sandbox ssh-config) más el modo de workspace mirror opcional.

{
  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 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 inicializa 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 los 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 siguen gestionándose mediante el ciclo de vida normal del sandbox:

• openclaw sandbox list muestra runtimes de OpenShell, así como 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 conoce el backend

Para el modo remote, recrear es especialmente importante:

• recrear 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, recrear restablece principalmente 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 del sandbox activo (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 define (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 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

Imagen Docker predeterminada: openclaw-sandbox:bookworm-slim

scripts/sandbox-setup.sh

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

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 de Gateway Docker, scripts/docker/setup.sh puede inicializar la configuración de sandbox. Define OPENCLAW_SANDBOX=1 (o true/yes/on) para habilitar esa ruta. Puedes sobrescribir la ubicación del socket con OPENCLAW_DOCKER_SOCKET. Referencia completa de configuración y 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 entorno aislado. Si una herramienta se deniega globalmente o por agente, el aislamiento no la vuelve a habilitar.

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 Entorno aislado vs. política de herramientas vs. elevado).

Depuración:

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

Mantenlo bloqueado.

# Sobrescrituras multiagente

Cada agente puede sobrescribir entorno aislado + 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 Entorno aislado y herramientas multiagente para ver la precedencia.

# Ejemplo mínimo de habilitación

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

# Relacionado

• Entorno aislado y herramientas multiagente — sobrescrituras por agente y precedencia
• OpenShell — configuración del backend de entorno aislado administrado, modos de workspace y referencia de configuración
• Configuración del entorno aislado
• Entorno aislado vs. política de herramientas vs. elevado — depuración de "¿por qué está bloqueado esto?"
• Seguridad