Cómo instalar OpenClaw con Docker Compose

Docker es la forma más limpia de correr OpenClaw cuando quieres aislarlo del resto del sistema: el agente vive en su propio contenedor, las actualizaciones son un comando, y el entorno es idéntico en cualquier máquina. La propia documentación lo describe como una opción pensada para entornos aislados o para validar el flujo antes de instalarlo nativo.

Esta es la vía Docker; si buscas el panorama completo (script, npm, plataformas), está en la guía de instalación de OpenClaw.

¿Docker o instalación nativa?

Si ya trabajas con contenedores o quieres mantener OpenClaw separado del resto, Docker. Si buscas lo más liviano —por ejemplo en una Raspberry Pi— el script con Node nativo suele convenir más.

Requisitos

• Docker y Docker Compose v2 instalados
• Una API key de tu proveedor de IA (Claude, OpenAI o un modelo local)
• Al menos 4 GB de RAM disponibles para el contenedor

Instalación con el script oficial

El soporte de Docker de OpenClaw es basado en Docker Compose: el repositorio ya incluye un docker-compose.yml, así que no tienes que escribirlo a mano. El flujo oficial clona el repo y corre el script de setup, que levanta el contenedor con ese compose y te pide las API keys:

git clone https://github.com/openclaw/openclaw.git
cd openclaw
 
# Usar la imagen precompilada (GitHub Container Registry)
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
 
# Levanta el contenedor y corre el onboarding
./scripts/docker/setup.sh

El script te pregunta las claves de API del proveedor, configura el docker-compose.yml y deja el contenedor corriendo. La interfaz de control queda en http://127.0.0.1:18789/.

Si prefieres construir la imagen localmente en vez de bajarla, omite el export OPENCLAW_IMAGE y el setup compila openclaw:local desde el código del repo.

Variables de entorno del setup

El comportamiento del compose se controla con variables de entorno antes de correr el script. Las más útiles:

Sobre las imágenes: además de latest, el registro publica el tag main (la rama de desarrollo) y tags de versión fijos como 2026.2.26. Para producción conviene fijar una versión en vez de seguir latest, así una actualización no te cambia el comportamiento sin avisar.

Cómo está armado el compose

El docker-compose.yml oficial no es un solo contenedor: define el gateway (el proceso de larga duración que mantiene vivo al agente) y un servicio de CLI para ejecutar comandos puntuales. El servicio de CLI comparte la red del gateway con network_mode: "service:openclaw-gateway", así ambos ven el mismo 127.0.0.1. Por eso ejecutas comandos contra el agente con docker compose run apuntando a ese servicio, sin abrir puertos extra.

Si necesitas correr el onboarding a mano (por ejemplo si lo saltaste con OPENCLAW_SKIP_ONBOARDING), lo lanzas dentro del contenedor del gateway:

docker compose run --rm --no-deps \
  --entrypoint node openclaw-gateway \
  dist/index.js onboard --mode local --no-install-daemon

Dónde se guardan tus datos

Docker Compose monta la configuración en volúmenes, así que tus datos sobreviven a recrear o actualizar el contenedor. Los directorios que persiste:

• OPENCLAW_CONFIG_DIR → /home/node/.openclaw — configuración del agente
• OPENCLAW_WORKSPACE_DIR → /home/node/.openclaw/workspace — espacio de trabajo
• OPENCLAW_AUTH_PROFILE_SECRET_DIR → /home/node/.config/openclaw — secretos de autenticación

Mientras no borres esos volúmenes, puedes destruir y recrear el contenedor sin perder la configuración ni las claves.

Actualizar OpenClaw en Docker

Una de las ventajas del compose: actualizar es bajar la imagen nueva y recrear el contenedor, sin tocar la configuración (vive en los volúmenes):

cd openclaw
docker compose pull
docker compose up -d

Comandos útiles

docker compose ps          # estado del contenedor
docker compose logs -f     # logs en vivo
docker compose down        # detener (conserva los volúmenes)
docker compose up -d       # volver a levantar

Verificar que el gateway está sano

El gateway expone dos endpoints de salud que puedes consultar desde el host para confirmar que arrancó bien:

curl -fsS http://127.0.0.1:18789/healthz   # ¿está vivo el proceso?
curl -fsS http://127.0.0.1:18789/readyz    # ¿está listo para atender?

/healthz responde apenas el proceso está arriba; /readyz solo responde cuando el agente terminó de cargar y está listo para trabajar. Son ideales para un healthcheck en el propio compose o para un monitor externo.

El gotcha del proveedor de IA local

Si usas un modelo local (Ollama, LM Studio, etc.) corriendo en tu máquina, ojo con la dirección: dentro del contenedor, 127.0.0.1 apunta al propio contenedor, no a tu host. El proveedor local no estará ahí y el agente fallará al conectarse.

La solución es apuntar al host con host.docker.internal en la configuración del proveedor (por ejemplo http://host.docker.internal:11434 para Ollama). En Linux, además, asegúrate de que ese nombre resuelva agregando el extra host en el compose:

extra_hosts:
  - "host.docker.internal:host-gateway"

Con un proveedor en la nube (Claude, OpenAI) no aplica: la conexión sale a internet y el contenedor llega sin problema.

Docker en Raspberry Pi

La imagen funciona en una Pi de 64 bits siempre que sea multi-arquitectura (ARM64). Dicho eso, en una Raspberry Pi el script nativo con Node 22 suele ser más liviano que sumar la capa de Docker. El detalle completo —qué modelo sirve y cómo dejarlo 24/7— está en la guía de OpenClaw en Raspberry Pi.

Preguntas frecuentes

Cierre

Con Docker Compose, OpenClaw queda aislado, reproducible y trivial de actualizar (docker compose pull && up -d). Para las demás formas de instalarlo —script, npm, nativo por plataforma— está la guía completa de OpenClaw.

Fuente

• Documentación oficial de OpenClaw — Docker