Containers

Docker

Edit source

Docker es opcional. Úsalo solo si quieres un Gateway en contenedor o validar el flujo de Docker.

¿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 install puede 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-USER de Docker.

Gateway en contenedor

Compilar la imagen

Desde la raíz del repositorio, ejecuta el script de configuración:

bash

./scripts/docker/setup.sh

Esto compila la imagen del Gateway localmente. Para usar una imagen precompilada en su lugar:

bash

export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"./scripts/docker/setup.sh

Las imágenes precompiladas se publican en GitHub Container Registry. Etiquetas comunes: main, latest, <version> (por ejemplo, 2026.2.26).

Completar la incorporación

El script de configuración ejecuta la incorporación automáticamente. Hará lo siguiente:

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

Durante la configuración, la incorporación previa al inicio y las escrituras de configuración se ejecutan directamente mediante openclaw-gateway. openclaw-cli es para comandos que ejecutas después de que el contenedor del Gateway ya existe.

Abrir la interfaz de control

Abre 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?

bash

docker compose run --rm openclaw-cli dashboard --no-open

Configurar canales (opcional)

Usa el contenedor de la CLI para añadir canales de mensajería:

bash

# WhatsApp (QR)docker compose run --rm openclaw-cli channels login # Telegramdocker compose run --rm openclaw-cli channels add --channel telegram --token "<token>" # Discorddocker compose run --rm openclaw-cli channels add --channel discord --token "<token>"

Documentación: WhatsApp, Telegram, Discord

Flujo manual

Si prefieres ejecutar cada paso por tu cuenta en lugar de usar el script de configuración:

bash

docker build -t openclaw:local -f Dockerfile .docker compose run --rm --no-deps --entrypoint node openclaw-gateway \  dist/index.js onboard --mode local --no-install-daemondocker compose run --rm --no-deps --entrypoint node openclaw-gateway \  dist/index.js config set --batch-json '[{"path":"gateway.mode","value":"local"},{"path":"gateway.bind","value":"lan"},{"path":"gateway.controlUi.allowedOrigins","value":["http://localhost:18789","http://127.0.0.1:18789"]}]'docker compose up -d openclaw-gateway

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

Los mantenedores pueden probar el código fuente de plugins incluidos contra una imagen empaquetada montando un directorio de código fuente de plugin sobre su ruta de código fuente empaquetada, por ejemplo 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:

bash

export OPENCLAW_EXTENSIONS="diagnostics-otel"export OTEL_EXPORTER_OTLP_ENDPOINT="http://otel-collector:4318"export OTEL_SERVICE_NAME="openclaw-gateway"./scripts/docker/setup.sh

Instala el plugin oficial @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:

text

http://<gateway-host>:18789/api/diagnostics/prometheus

La ruta está protegida por la autenticación del Gateway. No expongas un puerto público /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):

bash

curl -fsS http://127.0.0.1:18789/healthz   # livenesscurl -fsS http://127.0.0.1:18789/readyz     # readiness

La imagen Docker incluye un 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:

bash

docker compose exec openclaw-gateway node dist/index.js health --token "$OPENCLAW_GATEWAY_TOKEN"

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.

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`

La configuración Docker incluida usa esas URL del host como valores predeterminados de incorporación de LM Studio y Ollama, y 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:

bash

lms server start --port 1234 --bind 0.0.0.0OLLAMA_HOST=0.0.0.0:11434 ollama serve

Si usas tu propio archivo Compose o comando 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 bind OPENCLAW_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.json para la configuración de comportamiento
agents/<agentId>/agent/auth-profiles.json para autenticación OAuth/clave de API de proveedores almacenada
.env para secretos de tiempo de ejecución respaldados por variables de entorno, como OPENCLAW_GATEWAY_TOKEN

El directorio de clave secreta del perfil de autenticación almacena la clave de cifrado local usada para material de tokens de perfil de autenticación respaldado por OAuth. Consérvalo con el estado de tu host Docker, pero separado de 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, instala ClawDock:

bash

mkdir -p ~/.clawdock && curl -sL https://raw.githubusercontent.com/openclaw/openclaw/main/scripts/clawdock/clawdock-helpers.sh -o ~/.clawdock/clawdock-helpers.shecho 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc

Si instalaste ClawDock desde la ruta sin procesar anterior 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

bash

export OPENCLAW_SANDBOX=1./scripts/docker/setup.sh

Ruta de socket personalizada (por ejemplo, Docker sin root):

bash

export OPENCLAW_SANDBOX=1export OPENCLAW_DOCKER_SOCKET=/run/user/1000/docker.sock./scripts/docker/setup.sh

El script monta 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)

Desactiva la asignación de seudo-TTY de Compose con -T:

bash

docker compose run -T --rm openclaw-cli gateway probedocker compose run -T --rm openclaw-cli devices list --json

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

Algunas configuraciones de Docker Desktop fallan en las búsquedas DNS desde el sidecar 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:

bash

printf '%s\n' \  'services:' \  '  openclaw-cli:' \  '    cap_drop: !reset []' \  > docker-compose.cli-no-dropped-caps.local.yml docker compose -f docker-compose.yml -f docker-compose.cli-no-dropped-caps.local.yml run --rm openclaw-cli plugins install <package>

Si ya creaste un contenedor 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

La imagen se ejecuta como 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:

bash

sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace

La misma discrepancia puede aparecer como una advertencia de plugin como 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

Ordena tu Dockerfile para que las capas de dependencias queden en caché. Esto evita volver a ejecutar pnpm install a menos que cambien los lockfiles:

dockerfile

FROM node:24-bookwormRUN curl -fsSL https://bun.sh/install | bashENV PATH="/root/.bun/bin:${PATH}"RUN corepack enableWORKDIR /appCOPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./COPY ui/package.json ./ui/package.jsonCOPY scripts ./scriptsRUN pnpm install --frozen-lockfileCOPY . .RUN pnpm buildRUN pnpm ui:installRUN pnpm ui:buildENV NODE_ENV=productionCMD ["node","dist/index.js"]

Opciones de contenedor para usuarios avanzados

La imagen predeterminada prioriza la seguridad y se ejecuta como 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:

bash

docker compose run --rm openclaw-cli \  node /app/node_modules/playwright-core/cli.js install chromium

Persistir descargas de navegadores: usa OPENCLAW_HOME_VOLUME o OPENCLAW_EXTRA_MOUNTS. OpenClaw detecta automáticamente el Chromium gestionado por Playwright de la imagen Docker en Linux.

OAuth de OpenAI Codex (Docker sin interfaz)

Si eliges OAuth de OpenAI Codex en el asistente, se abre una URL del navegador. En Docker o configuraciones sin interfaz, copia la URL de redirección completa a la que llegues y pégala de nuevo en el asistente para finalizar la autenticación.

Metadatos de la imagen base

La imagen principal de tiempo de ejecución de Docker usa 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

Cuando agents.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

json5

{  agents: {    defaults: {      sandbox: {        mode: "non-main", // off | non-main | all        scope: "agent", // session | agent | shared      },    },  },}

Compila la imagen de sandbox predeterminada (desde un checkout de código fuente):

bash

scripts/sandbox-setup.sh

Para instalaciones npm sin un checkout de código fuente, consulta Sandboxing § Imágenes y configuración para comandos docker build en línea.

Solución de problemas

Falta la imagen o el contenedor de sandbox no inicia

Compila la imagen de sandbox con 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

Establece 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

OpenClaw ejecuta comandos con 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)

La VM necesita al menos 2 GB de RAM. Usa una clase de máquina más grande y reintenta.

No autorizado o emparejamiento requerido en la IU de Control

Obtén un enlace de dashboard nuevo y aprueba el dispositivo del navegador:

bash

docker compose run --rm openclaw-cli dashboard --no-opendocker compose run --rm openclaw-cli devices listdocker compose run --rm openclaw-cli devices approve <requestId>

Más detalles: Dashboard, Dispositivos.

El destino del Gateway muestra ws://172.x.x.x o errores de emparejamiento desde la CLI de Docker

Restablece el modo y el bind del Gateway:

bash

docker compose run --rm openclaw-cli config set --batch-json '[{"path":"gateway.mode","value":"local"},{"path":"gateway.bind","value":"lan"}]'docker compose run --rm openclaw-cli devices list --url ws://127.0.0.1:18789

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

Was this useful?