--- read_when: You want a dedicated explanation of sandboxing or need to tune agents.defaults.sandbox. sidebarTitle: Sandboxing status: active summary: 'Cómo funciona el aislamiento de OpenClaw: modos, ámbitos, acceso al espacio de trabajo e imágenes' title: Aislamiento x-i18n: generated_at: "2026-05-11T20:36:50Z" model: gpt-5.5 provider: openai source_hash: 9a90a68fdab1fdaef462bc6be589cb510d89c01138a0d43927e29d55bbb6e3ea source_path: gateway/sandboxing.md workflow: 16 --- 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 ejecuta en un sandbox aislado cuando está habilitado. Este no es un límite de seguridad perfecto, pero limita de forma material el acceso al sistema de archivos y a los procesos cuando el modelo hace algo poco inteligente. ## 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`). - De forma predeterminada, 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` y `agents.defaults.sandbox.browser.autoStartTimeoutMs`. - De forma predeterminada, los contenedores del navegador en sandbox usan una red Docker dedicada (`openclaw-sandbox-browser`) en lugar de la red global `bridge`. Configúralo con `agents.defaults.sandbox.browser.network`. - El ajuste opcional `agents.defaults.sandbox.browser.cdpSourceRange` restringe la entrada 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 por 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 URL (no en registros de consulta/cabecera). - `agents.defaults.sandbox.browser.allowHostControl` permite que las sesiones en sandbox apunten explícitamente al navegador del host. - Las listas de permitidos opcionales controlan `target: "custom"`: `allowedControlUrls`, `allowedControlHosts`, `allowedControlPorts`. 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 exec es `node`).** - Si el sandboxing está desactivado, `tools.elevated` no cambia la ejecución (ya está en el host). Consulta [Modo elevado](/es/tools/elevated). ## Modos `agents.defaults.sandbox.mode` controla **cuándo** se usa el sandboxing: Sin sandboxing. Ejecuta en sandbox solo las sesiones **non-main** (valor predeterminado si quieres chats normales en el host). `"non-main"` se basa en `session.mainKey` (valor predeterminado `"main"`), no en el id del agente. Las sesiones de grupo/canal usan sus propias claves, por lo que cuentan como non-main y se ejecutarán en sandbox. Todas las sesiones se ejecutan en un sandbox. ## 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 vive bajo `agents.defaults.sandbox.ssh`. La configuración específica de OpenShell vive bajo `plugins.entries.openshell.config`. ### Elegir un backend | | Docker | SSH | OpenShell | | ------------------- | -------------------------------- | ------------------------------ | --------------------------------------------------- | | **Dónde se ejecuta** | Contenedor local | Cualquier host accesible por SSH | Sandbox gestionado por OpenShell | | **Configuración** | `scripts/sandbox-setup.sh` | Clave SSH + host de destino | Plugin OpenShell habilitado | | **Modelo de workspace** | Bind-mount o copia | Canónico remoto (sembrar una vez) | `mirror` o `remote` | | **Control de red** | `docker.network` (predeterminado: none) | Depende del host remoto | Depende de OpenShell | | **Sandbox de navegador** | Compatible | No compatible | Aún no compatible | | **Bind mounts** | `docker.binds` | N/A | N/A | | **Ideal para** | Desarrollo local, aislamiento completo | Descargar trabajo en una máquina remota | Sandboxes remotos gestionados con sincronización bidireccional opcional | ### 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 los contenedores de sandbox está determinado por 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 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. **Restricciones de Docker-out-of-Docker (DooD)** Si despliegas el propio OpenClaw Gateway como contenedor Docker, orquesta contenedores de sandbox hermanos usando el socket Docker del host (DooD). Esto introduce una restricción específica de mapeo de rutas: - **La configuración requiere rutas del host**: La configuración `workspace` de `openclaw.json` DEBE contener la **ruta absoluta del host** (por ejemplo, `/home/user/.openclaw/workspaces`), no la ruta interna del contenedor del Gateway. Cuando OpenClaw pide al daemon de Docker que genere un sandbox, el daemon evalúa las rutas en relación con el namespace del SO host, no con el namespace del Gateway. - **Paridad del puente FS (mapa de volúmenes idéntico)**: El proceso nativo del OpenClaw Gateway también escribe archivos de Heartbeat y de puente en el directorio `workspace`. Como el Gateway evalúa exactamente la misma cadena (la ruta del host) desde dentro de su propio entorno contenedorizado, el despliegue del Gateway DEBE incluir un mapa de volúmenes idéntico que enlace el namespace del host de forma nativa (`-v /home/user/.openclaw:/home/user/.openclaw`). - **Modo de código Codex**: Cuando un sandbox de OpenClaw está activo, OpenClaw restringe los turnos del servidor de aplicaciones de Codex al sandboxing `workspace-write` de Codex, incluso si el valor predeterminado del Plugin Codex es `danger-full-access`. No montes el socket Docker del host en contenedores de sandbox de agente ni en sandboxes Codex personalizados. Si mapeas rutas internamente sin paridad absoluta con el host, OpenClaw lanza de forma nativa un error de permisos `EACCES` al intentar escribir su Heartbeat dentro del entorno del contenedor porque la cadena de ruta completamente cualificada no existe de forma nativa. ### Backend SSH Usa `backend: "ssh"` cuando quieras que OpenClaw ejecute en sandbox `exec`, herramientas de archivos y lecturas de medios en una máquina arbitraria accesible por SSH. ```json5 { 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" }, }, }, }, }, } ``` - OpenClaw crea una raíz remota por alcance bajo `sandbox.ssh.workspaceRoot`. - En el primer uso después de crear o recrear, OpenClaw siembra ese workspace remoto desde el workspace local una vez. - Después de eso, `exec`, `read`, `write`, `edit`, `apply_patch`, las lecturas de medios del 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. - `identityFile`, `certificateFile`, `knownHostsFile`: usan archivos locales existentes y los pasan por la configuración de OpenSSH. - `identityData`, `certificateData`, `knownHostsData`: usan cadenas en línea o SecretRefs. OpenClaw los resuelve mediante la instantánea normal del runtime de secretos, los escribe en archivos temporales con `0600` y los elimina cuando termina la sesión SSH. - Si tanto `*File` como `*Data` están configurados para el mismo elemento, `*Data` gana para esa sesión SSH. Este es un modelo **canónico remoto**. El workspace SSH remoto se convierte en el estado real del sandbox después de la siembra inicial. - Las ediciones locales del host hechas fuera de OpenClaw después del paso de siembra no son visibles remotamente hasta que recreas el sandbox. - `openclaw sandbox recreate` elimina la raíz remota por alcance y vuelve a sembrar desde local en el siguiente uso. - El sandboxing de navegador no es compatible con el backend SSH. - Los ajustes `sandbox.docker.*` no se aplican al backend SSH. ### Backend OpenShell Usa `backend: "openshell"` cuando quieras que OpenClaw ejecute herramientas en sandbox en un entorno remoto gestionado por OpenShell. Para la guía de configuración completa, la referencia de configuración y la comparación de modos de workspace, consulta la [página de OpenShell](/es/gateway/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 agrega el ciclo de vida específico de OpenShell (`sandbox create/get/delete`, `sandbox ssh-config`) más el modo de workspace opcional `mirror`. ```json5 { 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 los 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 que se crea 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. - OpenClaw pide a OpenShell una configuración SSH específica del sandbox mediante `openshell sandbox ssh-config `. - Core escribe esa configuración SSH en un archivo temporal, abre la sesión SSH y reutiliza el mismo puente de sistema de archivos remoto usado por `backend: "ssh"`. - En modo `mirror`, solo difiere el ciclo de vida: sincroniza local a remoto antes de exec y luego sincroniza de vuelta después de exec. - el navegador en sandbox aún no es compatible - `sandbox.docker.binds` no es compatible con el backend OpenShell - los controles de runtime específicos de Docker bajo `sandbox.docker.*` siguen aplicándose solo al backend Docker #### Modos de workspace OpenShell tiene dos modelos de workspace. Esta es la parte que más importa en la práctica. Usa `plugins.entries.openshell.config.mode: "mirror"` cuando quieras que el **workspace local permanezca canónico**. Comportamiento: - Antes de `exec`, OpenClaw sincroniza el espacio de trabajo local con el sandbox de OpenShell. - Después de `exec`, OpenClaw sincroniza el espacio de trabajo remoto de vuelta al espacio de trabajo local. - Las herramientas de archivos siguen operando mediante el puente del sandbox, pero el espacio de trabajo local sigue siendo la fuente de verdad entre turnos. Usa esto cuando: - edites archivos localmente fuera de OpenClaw y quieras que esos cambios aparezcan automáticamente en el sandbox - quieras que el sandbox de OpenShell se comporte lo más parecido posible al backend de Docker - quieras que el espacio de trabajo del host refleje las escrituras del sandbox después de cada turno de exec Contrapartida: coste adicional de sincronización antes y después de exec. Usa `plugins.entries.openshell.config.mode: "remote"` cuando quieras que el **espacio de trabajo de OpenShell pase a ser canónico**. Comportamiento: - Cuando el sandbox se crea por primera vez, OpenClaw inicializa una vez el espacio de trabajo remoto a partir del espacio de trabajo local. - Después de eso, `exec`, `read`, `write`, `edit` y `apply_patch` operan directamente sobre el espacio de trabajo remoto de OpenShell. - OpenClaw **no** sincroniza los cambios remotos de vuelta al espacio de trabajo local después de exec. - Las lecturas de medios en tiempo de prompt siguen funcionando porque las herramientas de archivos y medios leen mediante el puente del sandbox, en lugar de asumir una ruta local del host. - El transporte es SSH hacia el sandbox de OpenShell devuelto por `openshell sandbox ssh-config`. Consecuencias importantes: - Si editas archivos en el host fuera de OpenClaw después del paso de inicialización, el sandbox remoto **no** verá esos cambios automáticamente. - Si se recrea el sandbox, el espacio de trabajo remoto se vuelve a inicializar desde el espacio de trabajo local. - Con `scope: "agent"` o `scope: "shared"`, ese espacio de trabajo remoto se comparte en ese mismo ámbito. Usa esto cuando: - el sandbox deba vivir principalmente en el lado remoto de OpenShell - quieras menor sobrecarga de sincronización por turno - no quieras que las ediciones locales del host sobrescriban silenciosamente el estado del sandbox remoto Elige `mirror` si piensas en el sandbox como un entorno de ejecución temporal. Elige `remote` si piensas en el sandbox como el espacio de trabajo 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 además de 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 es consciente del backend Para el modo `remote`, recrear es especialmente importante: - recrear elimina el espacio de trabajo remoto canónico para ese ámbito - el siguiente uso inicializa un espacio de trabajo remoto nuevo desde el espacio de trabajo local Para el modo `mirror`, recrear principalmente restablece el entorno de ejecución remoto, porque el espacio de trabajo local sigue siendo canónico de todos modos. ## Acceso al espacio de trabajo `agents.defaults.sandbox.workspaceAccess` controla **qué puede ver el sandbox**: Las herramientas ven un espacio de trabajo del sandbox bajo `~/.openclaw/sandboxes`. Monta el espacio de trabajo del agente en modo solo lectura en `/agent` (desactiva `write`/`edit`/`apply_patch`). Monta el espacio de trabajo del agente en modo lectura/escritura en `/workspace`. Con el backend de OpenShell: - el modo `mirror` sigue usando el espacio de trabajo local como fuente canónica entre turnos de exec - el modo `remote` usa el espacio de trabajo 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 forma Los medios entrantes se copian en el espacio de trabajo activo del sandbox (`media/inbound/*`). **Nota sobre Skills:** la herramienta `read` está anclada a la raíz del sandbox. Con `workspaceAccess: "none"`, OpenClaw refleja las Skills aptas en el espacio de trabajo del sandbox (`.../skills`) para que se puedan leer. Con `"rw"`, las Skills del espacio de trabajo se pueden leer desde `/workspace/skills`. ## 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): ```json5 { 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"], }, }, }, ], }, } ``` **Seguridad de bind** - Los binds evitan el sistema de archivos del sandbox: exponen rutas del host con el modo que definas (`:ro` o `:rw`). - OpenClaw bloquea fuentes de bind peligrosas (por ejemplo: `docker.sock`, `/etc`, `/proc`, `/sys`, `/dev` y montajes padre que las expondrían). - OpenClaw también bloquea raíces habituales de credenciales del directorio personal, como `~/.aws`, `~/.cargo`, `~/.config`, `~/.docker`, `~/.gnupg`, `~/.netrc`, `~/.npm` y `~/.ssh`. - La validación de bind no es solo coincidencia de cadenas. OpenClaw normaliza la ruta de origen y luego la vuelve a resolver mediante el ancestro existente más profundo antes de volver a comprobar las rutas bloqueadas y las raíces permitidas. - Eso significa que los escapes mediante padres de symlink siguen fallando de forma cerrada incluso cuando la hoja final aún no existe. Ejemplo: `/workspace/run-link/new-file` sigue resolviéndose como `/var/run/...` si `run-link` apunta allí. - Las raíces de origen permitidas se canonicalizan de la misma forma, por lo que una ruta que solo parece estar dentro de la lista de permitidos antes de la resolución de symlinks se rechaza igualmente como `outside allowed roots`. - Los montajes sensibles (secretos, claves SSH, credenciales de servicio) deberían ser `:ro` salvo que sea absolutamente necesario. - Combínalo con `workspaceAccess: "ro"` si solo necesitas acceso de lectura al espacio de trabajo; los modos de bind siguen siendo independientes. - Consulta [Sandbox frente a política de herramientas frente a elevado](/es/gateway/sandbox-vs-tool-policy-vs-elevated) para ver cómo interactúan los binds con la política de herramientas y exec elevado. ## Imágenes y configuración Imagen Docker predeterminada: `openclaw-sandbox:bookworm-slim` **Checkout de código fuente frente a instalación npm** Los scripts auxiliares `scripts/sandbox-setup.sh`, `scripts/sandbox-common-setup.sh` y `scripts/sandbox-browser-setup.sh` solo están disponibles cuando se ejecuta desde un [checkout de código fuente](https://github.com/openclaw/openclaw). No se incluyen en el paquete npm. Si instalaste OpenClaw mediante `npm install -g openclaw`, usa en su lugar los comandos `docker build` en línea que se muestran a continuación. Desde un checkout de código fuente: ```bash scripts/sandbox-setup.sh ``` Desde una instalación npm (no se necesita checkout de código fuente): ```bash 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 ``` La imagen predeterminada **no** incluye Node. Si una Skill necesita Node (u otros runtimes), incorpora una imagen personalizada o instala mediante `sandbox.docker.setupCommand` (requiere salida de red + raíz escribible + usuario root). OpenClaw no sustituye silenciosamente por `debian:bookworm-slim` sin modificar cuando falta `openclaw-sandbox:bookworm-slim`. Las ejecuciones de sandbox dirigidas a la imagen predeterminada fallan rápido con una instrucción de compilación hasta que la compiles, porque la imagen incluida aporta `python3` para los ayudantes de escritura/edición del sandbox. Para una imagen de sandbox más funcional con herramientas comunes (por ejemplo `curl`, `jq`, `nodejs`, `python3`, `git`): Desde un checkout de código fuente: ```bash scripts/sandbox-common-setup.sh ``` Desde una instalación npm, compila primero la imagen predeterminada (ver arriba) y luego compila la imagen común encima usando el [`scripts/docker/sandbox/Dockerfile.common`](https://github.com/openclaw/openclaw/blob/main/scripts/docker/sandbox/Dockerfile.common) del repositorio. Luego establece `agents.defaults.sandbox.docker.image` en `openclaw-sandbox-common:bookworm-slim`. Desde un checkout de código fuente: ```bash scripts/sandbox-browser-setup.sh ``` Desde una instalación npm, compila usando el [`scripts/docker/sandbox/Dockerfile.browser`](https://github.com/openclaw/openclaw/blob/main/scripts/docker/sandbox/Dockerfile.browser) del repositorio. De forma predeterminada, los contenedores de sandbox de Docker se ejecutan **sin red**. Sobrescríbelo con `agents.defaults.sandbox.docker.network`. La imagen incluida del navegador del sandbox también aplica valores de inicio conservadores de Chromium para cargas de trabajo en contenedores. Los valores predeterminados actuales del contenedor incluyen: - `--remote-debugging-address=127.0.0.1` - `--remote-debugging-port=` - `--user-data-dir=${HOME}/.chrome` - `--no-first-run` - `--no-default-browser-check` - `--disable-3d-apis` - `--disable-gpu` - `--disable-dev-shm-usage` - `--disable-background-networking` - `--disable-extensions` - `--disable-features=TranslateUI` - `--disable-breakpad` - `--disable-crash-reporter` - `--disable-software-rasterizer` - `--no-zygote` - `--metrics-recording-only` - `--renderer-process-limit=2` - `--no-sandbox` cuando `noSandbox` está habilitado. - Las tres marcas de endurecimiento gráfico (`--disable-3d-apis`, `--disable-software-rasterizer`, `--disable-gpu`) son opcionales y son útiles cuando los contenedores carecen de soporte de GPU. Establece `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` si tu carga de trabajo requiere WebGL u otras funciones 3D/del navegador. - `--disable-extensions` está habilitado de forma predeterminada y se puede deshabilitar con `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` para flujos que dependen de extensiones. - `--renderer-process-limit=2` se controla mediante `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`, donde `0` conserva el valor predeterminado de Chromium. Si necesitas un perfil de runtime diferente, usa una imagen de navegador personalizada y proporciona tu propio entrypoint. Para perfiles locales (no en contenedor) de Chromium, usa `browser.extraArgs` para anexar marcas de inicio adicionales. - `network: "host"` está bloqueado. - `network: "container:"` está bloqueado de forma predeterminada (riesgo de omisión por unión de namespace). - Anulación de emergencia: `agents.defaults.sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`. Las instalaciones de Docker y el Gateway en contenedor viven aquí: [Docker](/es/install/docker) Para despliegues del Gateway de 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 sobrescribir la ubicación del socket con `OPENCLAW_DOCKER_SOCKET`. Configuración completa y referencia de entorno: [Docker](/es/install/docker#agent-sandbox). ## setupCommand (configuración de contenedor de una sola vez) `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` - El valor predeterminado de `docker.network` es `"none"` (sin egreso), por lo que las instalaciones de paquetes fallarán. - `docker.network: "container:"` requiere `dangerouslyAllowContainerNamespaceJoin: true` y es solo para casos de emergencia. - `readOnlyRoot: true` impide las escrituras; define `readOnlyRoot: false` o crea una imagen personalizada. - `user` debe ser root para las instalaciones de paquetes (omite `user` o define `user: "0:0"`). - La ejecución del entorno aislado **no** hereda `process.env` del host. Usa `agents.defaults.sandbox.docker.env` (o una imagen personalizada) para las claves de API de skill. ## Política de herramientas y vías de escape Las políticas de permitir/denegar herramientas siguen aplicándose antes que las reglas de aislamiento. Si una herramienta se deniega de forma global o por agente, el aislamiento no la recupera. `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 [Aislamiento vs. política de herramientas vs. elevación](/es/gateway/sandbox-vs-tool-policy-vs-elevated)). Depuración: - Usa `openclaw sandbox explain` para inspeccionar el modo de aislamiento efectivo, la política de herramientas y las claves de configuración de corrección. - Consulta [Aislamiento vs. política de herramientas vs. elevación](/es/gateway/sandbox-vs-tool-policy-vs-elevated) para el modelo mental de "¿por qué está bloqueado esto?". Manténlo bloqueado. ## Sobrescrituras multiagente Cada agente puede sobrescribir aislamiento + 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 [Aislamiento y herramientas multiagente](/es/tools/multi-agent-sandbox-tools) para la precedencia. ## Ejemplo mínimo de habilitación ```json5 { agents: { defaults: { sandbox: { mode: "non-main", scope: "session", workspaceAccess: "none", }, }, }, } ``` ## Relacionado - [Aislamiento y herramientas multiagente](/es/tools/multi-agent-sandbox-tools) — sobrescrituras por agente y precedencia - [OpenShell](/es/gateway/openshell) — configuración del backend de aislamiento gestionado, modos de espacio de trabajo y referencia de configuración - [Configuración de aislamiento](/es/gateway/config-agents#agentsdefaultssandbox) - [Aislamiento vs. política de herramientas vs. elevación](/es/gateway/sandbox-vs-tool-policy-vs-elevated) — depuración de "¿por qué está bloqueado esto?" - [Seguridad](/es/gateway/security)