Aislamiento en entorno seguro

​

Qué se ejecuta en el entorno aislado

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

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

​

Modos, ámbito y backend

• off: sin aislamiento.
• non-main: ejecuta en un entorno aislado 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 grupos o canales usan sus propias claves, por lo que siempre se consideran no principales y se ejecutan en un entorno aislado.
• all: todas las sesiones se ejecutan en un entorno aislado.

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

​

Backend de Docker

​

Navegador aislado

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

​

Backend de 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 use SecretRefs / 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" },
        },
      },
    },
  },
}

• Ciclo de vida: OpenClaw crea una raíz remota por ámbito en sandbox.ssh.workspaceRoot. La primera vez que se usa después de crearla o volver a crearla, inicializa una vez ese espacio de trabajo remoto desde el espacio de trabajo local. Después, exec, read, write, edit, apply_patch, las lecturas de medios de solicitudes y la preparación de medios entrantes se ejecutan directamente en 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 normal del entorno de ejecución de secretos, se escriben en archivos temporales con el modo 0600 y se eliminan cuando termina la sesión SSH. Si se definen tanto una variante *File como una variante *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 inicial. Las ediciones locales del host realizadas fuera de OpenClaw después de la inicialización no son visibles de forma remota hasta que se vuelve 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

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

​

Acceso al espacio de trabajo

​

Varias carpetas para un agente

directorio-del-host:directorio-del-contenedor:ro
directorio-del-host:directorio-del-contenedor:rw

• ro hace que la carpeta montada sea de solo lectura dentro del entorno aislado.
• rw permite que las herramientas y los procesos del entorno aislado modifiquen la carpeta del host.
• La ruta del contenedor es la ruta que utiliza el agente. Las rutas del host no se exponen automáticamente.

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        scope: "agent",
      },
    },
    list: [
      {
        id: "research",
        workspace: "/srv/openclaw/research-workspace",
        sandbox: {
          workspaceAccess: "rw",
          docker: {
            binds: ["/srv/shared/reference:/reference:ro", "/srv/shared/drafts:/drafts:rw"],
            // Obligatorio porque estos orígenes están fuera del espacio de trabajo del agente.
            dangerouslyAllowExternalBindSources: true,
          },
        },
      },
    ],
  },
}

openclaw sandbox recreate --agent research

​

Otros comportamientos de los enlaces

{
  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.entries.*.sandbox.docker.setupCommand

​

Política de herramientas y vías de escape

• openclaw sandbox list muestra los contenedores de los entornos aislados, su estado, la coincidencia de imagen, la 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 entorno aislado, 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 continúa siendo la raíz configurada del entorno aislado; effectiveHostWorkspaceRoot muestra dónde se encuentra realmente el espacio de trabajo activo.
• openclaw sandbox recreate [--all | --session <key> | --agent <id>] [--browser] [--force] elimina los contenedores y entornos para que se vuelvan a crear con la configuración actual la próxima vez que se utilicen.
• Consulte Entorno aislado frente a política de herramientas y modo elevado para entender por qué algo está bloqueado.

​

Sobrescrituras multiagente

​

Ejemplo mínimo de habilitación

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

​

Temas relacionados

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