Aislamiento

​

Qué se ejecuta en sandbox

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

• El propio proceso Gateway.
• Cualquier herramienta a la que se le permita explícitamente ejecutarse fuera del sandbox mediante tools.elevated. La ejecución elevada omite el sandbox 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 sandbox está desactivado, tools.elevated no cambia nada, ya que exec ya se ejecuta en el host. Consulta Modo elevado.

​

Modos, alcance y backend

• off: sin sandbox.
• non-main: aplica sandbox a 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 es configurable. Las sesiones de grupo/canal usan sus propias claves, por lo que siempre cuentan como no principales y se ejecutan en sandbox.
• all: todas las sesiones se ejecutan en un sandbox.

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

​

Backend Docker

​

Navegador en sandbox

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

​

Backend 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" },
        },
      },
    },
  },
}

• Ciclo de vida: OpenClaw crea una raíz remota por alcance bajo sandbox.ssh.workspaceRoot. En el primer uso después de crear o recrear, siembra ese workspace remoto desde el workspace local una vez. Después de eso, exec, read, write, edit, apply_patch, las lecturas de medios de prompt y la preparación de medios entrantes se ejecutan directamente contra el workspace remoto por SSH. OpenClaw no sincroniza automáticamente los cambios remotos de vuelta al workspace local.
• Material de autenticación: identityFile/certificateFile/knownHostsFile hacen referencia a archivos locales existentes. identityData/certificateData/knownHostsData aceptan cadenas en línea o SecretRefs, resueltas mediante la instantánea normal del runtime de secretos, escritas en archivos temporales con modo 0600 y eliminadas cuando termina la sesión SSH. Si se establecen una variante *File y una variante *Data para el mismo elemento, *Data gana para esa sesión.
• Consecuencias de canonicidad remota: el workspace SSH remoto se convierte en el estado real del sandbox después de la siembra inicial. Las ediciones locales del host realizadas fuera de OpenClaw después del paso de siembra no son visibles remotamente hasta que recrees el sandbox. openclaw sandbox recreate elimina la raíz remota por alcance y vuelve a sembrar desde local en el siguiente uso. El sandbox de navegador no es compatible con este backend, y la configuración sandbox.docker.* no se aplica a él.

​

Backend OpenShell

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

​

Acceso al workspace

​

Montajes bind personalizados

{
  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

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

​

setupCommand (configuración única del contenedor)

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

​

Política de herramientas y vías de escape

• openclaw sandbox list muestra contenedores de sandbox, estado, coincidencia de imagen, antigüedad, tiempo inactivo y sesión/agente asociado.
• openclaw sandbox explain [--session <key>] [--agent <id>] inspecciona el modo de sandbox efectivo, el espacio de trabajo del host, el workdir del runtime, montajes de Docker, política de herramientas y claves de configuración para corrección. Su campo workspaceRoot sigue siendo la raíz de sandbox configurada; effectiveHostWorkspaceRoot muestra dónde vive realmente el espacio de trabajo activo.
• openclaw sandbox recreate [--all | --session <key> | --agent <id>] [--browser] [--force] elimina contenedores/entornos para que se vuelvan a crear con la configuración actual en el siguiente uso.
• Consulta Sandbox vs Tool Policy vs Elevated para el modelo mental de “¿por qué está bloqueado esto?”.

​

Anulaciones multiagente

​

Ejemplo mínimo de habilitación

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

​

Relacionado

• Sandbox y herramientas multiagente — anulaciones por agente y precedencia
• OpenShell — configuración del backend de sandbox gestionado, modos de espacio de trabajo y referencia de configuración
• Configuración de sandbox
• Sandbox frente a política de herramientas frente a elevado — depuración de “¿por qué está bloqueado esto?”
• Seguridad