Sandboxing
Cómo funciona el sandboxing de OpenClaw: modos, alcances, acceso al espacio de trabajo e imágenes
OpenClaw puede ejecutar ''herramientas dentro de contenedores Docker'' para reducir el radio de explosión. Esto es ''opcional'' y se controla por 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 corre en un sandbox aislado cuando está habilitado.
Esto no es un límite de seguridad perfecto, pero limita materialmente el acceso al sistema de archivos y procesos cuando el modelo hace algo tonto.
ReferenceGatewaySandboxingPage.intro.p4
ReferenceGatewaySandboxingPage.intro.p5
ReferenceGatewaySandboxingPage.intro.p6
ReferenceGatewaySandboxingPage.intro.p7
Qué se sandboxea
- Ejecución de herramientas (''exec'', ''read'', ''write'', ''edit'', ''apply_patch'', ''process'', etc.).
- Navegador sandboxeado opcional (''agents.defaults.sandbox.browser'').
- Por defecto, el navegador sandbox se auto-inicia (asegura que CDP sea alcanzable) cuando la herramienta de navegador lo necesita. Configura via ''agents.defaults.sandbox.browser.autoStart'' y ''agents.defaults.sandbox.browser.autoStartTimeoutMs''.
- ''agents.defaults.sandbox.browser.allowHostControl'' permite que sesiones sandboxeadas apunten explícitamente al navegador del host.
- Listas permitidas opcionales controlan ''target: "custom"'': ''allowedControlUrls'', ''allowedControlHosts'', ''allowedControlPorts''.
- El proceso del Gateway mismo.
No sandboxeado:
- Cualquier herramienta explícitamente permitida para correr en el host (ej. ''tools.elevated'').
- Exec elevado corre en el host y omite el sandboxing.
- Si el sandboxing está desactivado, ''tools.elevated'' no cambia la ejecución (ya está en el host). Ver ''Modo Elevado''.
ReferenceGatewaySandboxingPage.step01.item10
Modos
''agents.defaults.sandbox.mode'' controla ''cuándo'' se usa sandboxing:
- ''"off"'': sin sandboxing.
- ''"non-main"'': sandbox solo sesiones ''no principales'' (predeterminado si quieres chats normales en el host).
- ''"all"'': cada sesión corre en un sandbox.
Nota: ''"non-main"'' se basa en ''session.mainKey'' (predeterminado ''"main"''), no en el id del agente.
Las sesiones de grupo/canal usan sus propias claves, así que cuentan como no principales y serán sandboxeadas.
Alcance
''agents.defaults.sandbox.scope'' controla ''cuántos contenedores'' se crean:
- ''"session"'' (predeterminado): un contenedor por sesión.
- ''"agent"'': un contenedor por agente.
- ''"shared"'': un contenedor compartido por todas las sesiones sandboxeadas.
Acceso al espacio de trabajo
''agents.defaults.sandbox.workspaceAccess'' controla ''qué puede ver el sandbox'':
- ''"none"'' (predeterminado): las herramientas ven un espacio de trabajo sandbox bajo ''~/.openclaw/sandboxes''.
- ''"ro"'': monta el espacio de trabajo del agente solo lectura en ''/agent'' (deshabilita ''write''/''edit''/''apply_patch'').
- ''"rw"'': monta el espacio de trabajo del agente lectura/escritura en ''/workspace''.
Los medios entrantes se copian al espacio de trabajo sandbox activo (''media/inbound/*'').
Nota de skills: la herramienta ''read'' está enraizada en el sandbox. Con ''workspaceAccess: "none"'',
OpenClaw refleja skills elegibles en el espacio de trabajo sandbox (''.../skills'') para que
puedan ser leídas. Con ''"rw"'', las skills del espacio de trabajo son legibles desde
''/workspace/skills''.
Montajes bind personalizados
''agents.defaults.sandbox.docker.binds'' monta directorios adicionales del host en el contenedor. Formato: ''host:contenedor:modo'' (ej., ''"/home/usuario/fuente:/fuente:rw"'').
Los binds globales y por agente se ''fusionan'' (no se reemplazan). Bajo ''scope: "shared"'', los binds por agente se ignoran.
Ejemplo (fuente solo lectura + docker socket):
Notas de seguridad:
{
agents: {
defaults: {
sandbox: {
docker: {
binds: ["/home/usuario/fuente:/fuente:ro", "/var/run/docker.sock:/var/run/docker.sock"],
},
},
},
list: [
{
id: "build",
sandbox: {
docker: {
binds: ["/mnt/cache:/cache:rw"],
},
},
},
],
},
}ReferenceGatewaySandboxingPage.step05.p5
- Los binds omiten el sistema de archivos del sandbox: exponen rutas del host con el modo que configures (:ro o :rw).
- Montajes sensibles (ej., docker.sock, secretos, claves SSH) deben ser :ro a menos que sea absolutamente necesario.
- Combina con ''workspaceAccess: "ro"'' si solo necesitas acceso de lectura al espacio de trabajo; los modos de bind permanecen independientes.
- Ver ''Sandbox vs Política de Herramientas vs Elevado'' para cómo los binds interactúan con la política de herramientas y exec elevado.
Imágenes + configuración
Imagen predeterminada: openclaw-sandbox:bookworm-slim
Constrúyela una vez:
scripts/sandbox-setup.sh
Nota: la imagen predeterminada ''no'' incluye Node. Si una skill necesita Node (u otros runtimes), hornea una imagen personalizada o instala via ''sandbox.docker.setupCommand'' (requiere salida de red + raíz escribible + usuario root).
Imagen de navegador sandboxeado:
Por defecto, los contenedores sandbox corren ''sin red''. Sobrescribe con ''agents.defaults.sandbox.docker.network''.
Las instalaciones Docker y el gateway contenerizado viven aquí: ''Docker''.
Imagen CLIBrowser de Sandbox：
scripts/sandbox-browser-setup.sh
ReferenceGatewaySandboxingPage.step06.p8
ReferenceGatewaySandboxingPage.step06.p9
ReferenceGatewaySandboxingPage.step06.p10
''Docker''
setupCommand (configuración única del contenedor)
''setupCommand'' se ejecuta ''una vez'' después de que el contenedor sandbox es creado (no en cada ejecución). Se ejecuta dentro del contenedor via ''sh -lc''.
Rutas:
Errores comunes:
- Global: ''agents.defaults.sandbox.docker.setupCommand''
- Por agente: ''agents.list[].sandbox.docker.setupCommand''
Errores Comunes：
- El ''docker.network'' predeterminado es ''"none"'' (sin salida), así que las instalaciones de paquetes fallarán.
- ''readOnlyRoot: true'' previene escrituras; configura ''readOnlyRoot: false'' o hornea una imagen personalizada.
- ''user'' debe ser root para instalaciones de paquetes (omite ''user'' o configura ''user: "0:0"'').
- Exec sandbox ''no'' hereda ''process.env'' del host. Usa ''agents.defaults.sandbox.docker.env'' (o una imagen personalizada) para claves API de skills.
Política de herramientas + salidas de emergencia
Las políticas de permitir/denegar herramientas aún aplican antes de las reglas de sandbox. Si una herramienta está denegada globalmente o por agente, el sandboxing no la recupera.
''tools.elevated'' es una salida de emergencia explícita que ejecuta ''exec'' en el host. Las directivas ''/exec'' solo aplican para remitentes autorizados y persisten por sesión; para deshabilitar completamente ''exec'', usa denegación de política de herramientas (ver ''Sandbox vs Política de Herramientas vs Elevado'').
Depuración:
Mantenlo bloqueado.
ReferenceGatewaySandboxingPage.step08.p5
- Usa ''openclaw sandbox explain'' para inspeccionar el modo de sandbox efectivo, política de herramientas y claves de configuración de reparación.
- Ver ''Sandbox vs Política de Herramientas vs Elevado'' para el modelo mental "¿por qué está bloqueado esto?".
Depurar:
Sobreescrituras multi-agente
Cada agente puede sobrescribir sandbox + herramientas: ''agents.list[].sandbox'' y ''agents.list[].tools'' (más ''agents.list[].tools.sandbox.tools'' para política de herramientas sandbox).
Ver ''Sandbox y Herramientas Multi-Agente'' para precedencia.
Ejemplo de habilitación mínima
{
agents: {
defaults: {
sandbox: {
mode: "non-main",
scope: "session",
workspaceAccess: "none",
},
},
},
}