Docker es opcional. Úsalo solo si quieres un Gateway en contenedor o validar el flujo de Docker.Documentation Index
Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
¿Docker es adecuado para mí?
- Sí: quieres un entorno de Gateway aislado y desechable, o ejecutar OpenClaw en un host sin instalaciones locales.
- No: estás ejecutándolo en tu propia máquina y solo quieres el ciclo de desarrollo más rápido. Usa el flujo de instalación normal en su lugar.
- Nota sobre aislamiento en sandbox: el backend de sandbox predeterminado usa Docker cuando el aislamiento en sandbox está habilitado, pero el aislamiento en sandbox está desactivado de forma predeterminada y no requiere que todo el Gateway se ejecute en Docker. Los backends de sandbox SSH y OpenShell también están disponibles. Consulta Aislamiento en sandbox.
Requisitos previos
- Docker Desktop (o Docker Engine) + Docker Compose v2
- Al menos 2 GB de RAM para compilar la imagen (
pnpm installpuede ser finalizado por falta de memoria en hosts de 1 GB con salida 137) - Suficiente disco para imágenes y registros
- Si lo ejecutas en un VPS/host público, revisa
Refuerzo de seguridad para exposición de red,
especialmente la política de firewall
DOCKER-USERde Docker.
Gateway en contenedor
Compilar la imagen
main, latest, <version> (por ejemplo, 2026.2.26).Completar la incorporación
- solicitar claves de API del proveedor
- generar un token de Gateway y escribirlo en
.env - crear el directorio de clave secreta del perfil de autenticación
- iniciar el Gateway mediante Docker Compose
openclaw-gateway. openclaw-cli es para comandos que ejecutas después de que
el contenedor del Gateway ya existe.Abrir la interfaz de control
http://127.0.0.1:18789/ en tu navegador y pega el secreto compartido
configurado en Ajustes. El script de configuración escribe un token en .env de forma
predeterminada; si cambias la configuración del contenedor a autenticación por contraseña, usa esa
contraseña en su lugar.¿Necesitas la URL otra vez?Flujo manual
Si prefieres ejecutar cada paso por tu cuenta en lugar de usar el script de configuración:docker compose desde la raíz del repositorio. Si habilitaste OPENCLAW_EXTRA_MOUNTS
u OPENCLAW_HOME_VOLUME, el script de configuración escribe docker-compose.extra.yml;
inclúyelo con -f docker-compose.yml -f docker-compose.extra.yml.openclaw-cli comparte el espacio de nombres de red de openclaw-gateway, es una
herramienta posterior al inicio. Antes de docker compose up -d openclaw-gateway, ejecuta la incorporación
y las escrituras de configuración durante la configuración mediante openclaw-gateway con
--no-deps --entrypoint node.Variables de entorno
El script de configuración acepta estas variables de entorno opcionales:| Variable | Propósito |
|---|---|
OPENCLAW_IMAGE | Usar una imagen remota en lugar de compilar localmente |
OPENCLAW_DOCKER_APT_PACKAGES | Instalar paquetes apt adicionales durante la compilación (separados por espacios) |
OPENCLAW_EXTENSIONS | Incluir ayudantes de plugins incluidos seleccionados durante la compilación |
OPENCLAW_EXTRA_MOUNTS | Montajes bind de host adicionales (separados por comas source:target[:opts]) |
OPENCLAW_HOME_VOLUME | Persistir /home/node en un volumen Docker con nombre |
OPENCLAW_SANDBOX | Optar por el arranque de sandbox (1, true, yes, on) |
OPENCLAW_SKIP_ONBOARDING | Omitir el paso de incorporación interactiva (1, true, yes, on) |
OPENCLAW_DOCKER_SOCKET | Sobrescribir la ruta del socket de Docker |
OPENCLAW_DISABLE_BONJOUR | Desactivar la publicidad Bonjour/mDNS (predeterminado en 1 para Docker) |
OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS | Desactivar las superposiciones de montaje bind de código fuente de plugins incluidos |
OTEL_EXPORTER_OTLP_ENDPOINT | Endpoint compartido del recopilador OTLP/HTTP para exportación de OpenTelemetry |
OTEL_EXPORTER_OTLP_*_ENDPOINT | Endpoints OTLP específicos de señal para trazas, métricas o registros |
OTEL_EXPORTER_OTLP_PROTOCOL | Sobrescritura del protocolo OTLP. Hoy solo se admite http/protobuf |
OTEL_SERVICE_NAME | Nombre de servicio usado para recursos de OpenTelemetry |
OTEL_SEMCONV_STABILITY_OPT_IN | Optar por los atributos semánticos experimentales GenAI más recientes |
OPENCLAW_OTEL_PRELOADED | Omitir el inicio de un segundo SDK de OpenTelemetry cuando ya hay uno precargado |
OPENCLAW_EXTRA_MOUNTS=/path/to/fork/extensions/synology-chat:/app/extensions/synology-chat:ro.
Ese directorio de código fuente montado sobrescribe el paquete compilado
/app/dist/extensions/synology-chat correspondiente para el mismo id de plugin.
Observabilidad
La exportación de OpenTelemetry es saliente desde el contenedor del Gateway hacia tu recopilador OTLP. No requiere un puerto Docker publicado. Si compilas la imagen localmente y quieres que el exportador de OpenTelemetry incluido esté disponible dentro de la imagen, incluye sus dependencias en tiempo de ejecución:@openclaw/diagnostics-otel desde ClawHub en
instalaciones Docker empaquetadas antes de habilitar la exportación. Las imágenes personalizadas compiladas desde código fuente
todavía pueden incluir el código fuente del plugin local con
OPENCLAW_EXTENSIONS=diagnostics-otel. Para habilitar la exportación, permite y habilita el
plugin diagnostics-otel en la configuración y luego establece
diagnostics.otel.enabled=true o usa el ejemplo de configuración en exportación de OpenTelemetry. Los encabezados de autenticación del recopilador se configuran mediante
diagnostics.otel.headers, no mediante variables de entorno de Docker.
Las métricas de Prometheus usan el puerto ya publicado del Gateway. Instala
clawhub:@openclaw/diagnostics-prometheus, habilita el
plugin diagnostics-prometheus y luego recopila:
/metrics separado ni una ruta de proxy inverso sin autenticación. Consulta
Métricas de Prometheus.
Comprobaciones de estado
Endpoints de sondeo del contenedor (no requieren autenticación):HEALTHCHECK integrado que hace ping a /healthz.
Si las comprobaciones siguen fallando, Docker marca el contenedor como unhealthy y
los sistemas de orquestación pueden reiniciarlo o reemplazarlo.
Instantánea de estado profunda autenticada:
LAN frente a loopback
scripts/docker/setup.sh establece OPENCLAW_GATEWAY_BIND=lan de forma predeterminada para que el acceso del host a
http://127.0.0.1:18789 funcione con la publicación de puertos de Docker.
lan(predeterminado): el navegador del host y la CLI del host pueden alcanzar el puerto publicado del Gateway.loopback: solo los procesos dentro del espacio de nombres de red del contenedor pueden alcanzar el Gateway directamente.
gateway.bind (lan / loopback / custom /
tailnet / auto), no alias de host como 0.0.0.0 o 127.0.0.1.Proveedores locales del host
Cuando OpenClaw se ejecuta en Docker,127.0.0.1 dentro del contenedor es el propio contenedor,
no tu máquina host. Usa host.docker.internal para proveedores de IA que
se ejecutan en el host:
| Proveedor | URL predeterminada del host | URL de configuración de Docker |
|---|---|---|
| LM Studio | http://127.0.0.1:1234 | http://host.docker.internal:1234 |
| Ollama | http://127.0.0.1:11434 | http://host.docker.internal:11434 |
docker-compose.yml asigna host.docker.internal al
Gateway del host de Docker para Docker Engine en Linux. Docker Desktop ya proporciona
el mismo nombre de host en macOS y Windows.
Los servicios del host también deben escuchar en una dirección alcanzable desde Docker:
docker run, añade tú mismo la misma
asignación de host, por ejemplo
--add-host=host.docker.internal:host-gateway.
Bonjour / mDNS
Las redes bridge de Docker normalmente no reenvían de forma fiable multicast Bonjour/mDNS (224.0.0.251:5353). Por eso, la configuración Compose incluida establece de forma predeterminada
OPENCLAW_DISABLE_BONJOUR=1 para que el Gateway no entre en bucle de fallos ni reinicie
repetidamente la publicidad cuando el bridge descarte el tráfico multicast.
Usa la URL publicada del Gateway, Tailscale o DNS-SD de área amplia para hosts Docker.
Establece OPENCLAW_DISABLE_BONJOUR=0 solo cuando ejecutes con redes de host, macvlan
u otra red donde se sepa que multicast mDNS funciona.
Para problemas habituales y solución de problemas, consulta descubrimiento Bonjour.
Almacenamiento y persistencia
Docker Compose monta mediante bindOPENCLAW_CONFIG_DIR en /home/node/.openclaw,
OPENCLAW_WORKSPACE_DIR en /home/node/.openclaw/workspace y
OPENCLAW_AUTH_PROFILE_SECRET_DIR en /home/node/.config/openclaw, por lo que esas
rutas sobreviven al reemplazo del contenedor. Cuando alguna variable no está definida, el
docker-compose.yml incluido usa como respaldo una ruta bajo ${HOME}, o /tmp cuando HOME también
falta. Eso evita que docker compose up emita una especificación de volumen con origen vacío
en entornos básicos.
Ese directorio de configuración montado es donde OpenClaw mantiene:
openclaw.jsonpara la configuración de comportamientoagents/<agentId>/agent/auth-profiles.jsonpara autenticación OAuth/clave de API de proveedores almacenada.envpara secretos de tiempo de ejecución respaldados por variables de entorno, comoOPENCLAW_GATEWAY_TOKEN
OPENCLAW_CONFIG_DIR.
Los plugins descargables instalados almacenan su estado de paquete bajo el directorio
home de OpenClaw montado, por lo que los registros de instalación de plugins y
las raíces de paquetes sobreviven al reemplazo del contenedor. El inicio del
Gateway no genera árboles de dependencias de plugins incluidos.
Para ver todos los detalles de persistencia en despliegues de VM, consulta
Tiempo de ejecución de VM Docker - Qué persiste dónde.
Puntos críticos de crecimiento del disco: vigila media/, los archivos JSONL de sesión,
cron/runs/*.jsonl, las raíces de paquetes de plugins instalados y los registros
de archivo rotativos bajo /tmp/openclaw/.
Ayudantes de shell (opcional)
Para facilitar la gestión diaria de Docker, instalaClawDock:
scripts/shell-helpers/clawdock-helpers.sh, vuelve a ejecutar el comando de instalación anterior para que tu archivo de ayudante local siga la nueva ubicación.
Luego usa clawdock-start, clawdock-stop, clawdock-dashboard, etc. Ejecuta
clawdock-help para ver todos los comandos.
Consulta ClawDock para ver la guía completa del ayudante.
Habilitar el sandbox de agente para el Gateway de Docker
Habilitar el sandbox de agente para el Gateway de Docker
docker.sock solo después de que los prerrequisitos del sandbox se cumplan. Si
la configuración del sandbox no puede completarse, el script restablece agents.defaults.sandbox.mode
a off. Los turnos de modo de código de Codex siguen estando restringidos a
workspace-write de Codex mientras el sandbox de OpenClaw está activo; no montes el
socket de Docker del host en contenedores de sandbox de agente.Automatización / CI (no interactivo)
Automatización / CI (no interactivo)
-T:Nota de seguridad de red compartida
Nota de seguridad de red compartida
openclaw-cli usa network_mode: "service:openclaw-gateway" para que los comandos de la CLI
puedan llegar al Gateway por 127.0.0.1. Trátalo como un límite de confianza
compartido. La configuración de Compose elimina NET_RAW/NET_ADMIN y habilita
no-new-privileges tanto en openclaw-gateway como en openclaw-cli.Errores de DNS de Docker Desktop en openclaw-cli
Errores de DNS de Docker Desktop en openclaw-cli
openclaw-cli de red compartida después de eliminar NET_RAW, lo que aparece como
EAI_AGAIN durante comandos respaldados por npm como openclaw plugins install.
Mantén el archivo de Compose reforzado predeterminado para la operación normal del Gateway. La
sobrescritura local de abajo relaja la postura de seguridad del contenedor de la CLI al
restaurar las capacidades predeterminadas de Docker, así que úsala solo para el comando puntual de la CLI
que necesita acceso al registro de paquetes, no como tu invocación de Compose predeterminada:openclaw-cli de larga duración, recréalo
con la misma sobrescritura. docker compose exec y docker exec no pueden
cambiar las capacidades de Linux en un contenedor ya creado.Permisos y EACCES
Permisos y EACCES
node (uid 1000). Si ves errores de permisos en
/home/node/.openclaw, asegúrate de que tus montajes bind del host sean propiedad del uid 1000:blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root)
seguida de plugin present but blocked. Eso significa que el uid del proceso y el propietario
del directorio de plugin montado no coinciden. Prefiere ejecutar el contenedor con el
uid 1000 predeterminado y corregir la propiedad del montaje bind. Solo aplica chown
a /path/to/openclaw-config/npm como root:root si ejecutas intencionalmente
OpenClaw como root a largo plazo.Reconstrucciones más rápidas
Reconstrucciones más rápidas
pnpm install a menos que cambien los lockfiles:Opciones de contenedor para usuarios avanzados
Opciones de contenedor para usuarios avanzados
node no root. Para un contenedor con
más funciones:- Persistir
/home/node:export OPENCLAW_HOME_VOLUME="openclaw_home" - Incluir dependencias del sistema:
export OPENCLAW_DOCKER_APT_PACKAGES="git curl jq" - Incluir Playwright Chromium:
export OPENCLAW_INSTALL_BROWSER=1 - O instalar navegadores de Playwright en un volumen persistente:
- Persistir descargas de navegadores: usa
OPENCLAW_HOME_VOLUMEoOPENCLAW_EXTRA_MOUNTS. OpenClaw detecta automáticamente el Chromium gestionado por Playwright de la imagen Docker en Linux.
OAuth de OpenAI Codex (Docker sin interfaz)
OAuth de OpenAI Codex (Docker sin interfaz)
Metadatos de la imagen base
Metadatos de la imagen base
node:24-bookworm-slim e incluye tini como proceso init de punto de entrada (PID 1) para asegurar que los procesos zombi se recojan y que las señales se gestionen correctamente en contenedores de larga duración. Publica anotaciones de imagen base OCI, incluidas org.opencontainers.image.base.name,
org.opencontainers.image.source y otras. El digest base de Node se
actualiza mediante PRs de imagen base Docker de Dependabot; las compilaciones de lanzamiento no ejecutan
una capa de actualización de distribución. Consulta
anotaciones de imagen OCI.¿Ejecutando en un VPS?
Consulta Hetzner (VPS Docker) y Tiempo de ejecución de VM Docker para pasos de despliegue de VM compartidos, incluidas la inclusión de binarios, la persistencia y las actualizaciones.Sandbox de agente
Cuandoagents.defaults.sandbox está habilitado con el backend de Docker, el Gateway
ejecuta la ejecución de herramientas del agente (shell, lectura/escritura de archivos, etc.) dentro de contenedores Docker
aislados mientras el propio Gateway permanece en el host. Esto te da un muro sólido
alrededor de sesiones de agente no confiables o multiinquilino sin contenerizar todo el
Gateway.
El alcance del sandbox puede ser por agente (predeterminado), por sesión o compartido. Cada alcance
obtiene su propio espacio de trabajo montado en /workspace. También puedes configurar
políticas de permitir/denegar herramientas, aislamiento de red, límites de recursos y contenedores de
navegador.
Para la configuración completa, imágenes, notas de seguridad y perfiles multiagente, consulta:
- Sandboxing — referencia completa de sandbox
- OpenShell — acceso de shell interactivo a contenedores de sandbox
- Sandbox y herramientas multiagente — sobrescrituras por agente
Habilitación rápida
docker build en línea.
Solución de problemas
Falta la imagen o el contenedor de sandbox no inicia
Falta la imagen o el contenedor de sandbox no inicia
scripts/sandbox-setup.sh
(checkout de código fuente) o el comando docker build en línea de Sandboxing § Imágenes y configuración (instalación npm),
o establece agents.defaults.sandbox.docker.image en tu imagen personalizada.
Los contenedores se crean automáticamente por sesión bajo demanda.Errores de permisos en el sandbox
Errores de permisos en el sandbox
docker.user en un UID:GID que coincida con la propiedad de tu espacio de trabajo montado,
o aplica chown a la carpeta del espacio de trabajo.Herramientas personalizadas no encontradas en el sandbox
Herramientas personalizadas no encontradas en el sandbox
sh -lc (shell de inicio de sesión), que carga
/etc/profile y puede restablecer PATH. Establece docker.env.PATH para anteponer tus
rutas de herramientas personalizadas, o agrega un script bajo /etc/profile.d/ en tu Dockerfile.Eliminado por OOM durante la compilación de imagen (salida 137)
Eliminado por OOM durante la compilación de imagen (salida 137)
No autorizado o emparejamiento requerido en la IU de Control
No autorizado o emparejamiento requerido en la IU de Control
El destino del Gateway muestra ws://172.x.x.x o errores de emparejamiento desde la CLI de Docker
El destino del Gateway muestra ws://172.x.x.x o errores de emparejamiento desde la CLI de Docker
Relacionado
- Resumen de instalación — todos los métodos de instalación
- Podman — alternativa de Podman a Docker
- ClawDock — configuración comunitaria de Docker Compose
- Actualización — mantener OpenClaw actualizado
- Configuración — configuración del Gateway después de la instalación