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 y desechables, o para un host donde no quieres instalar nada localmente.

Esta es la vía Docker; si buscas el panorama completo (script, npm, plataformas), está en cómo instalar 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)
• 1 GB de RAM como mínimo y 2 GB o más recomendados; si compilas la imagen localmente en vez de bajar la precompilada, la documentación pide al menos 6 GB

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: según la documentación, cada release estable mueve latest y main, y además se publican tags de versión fijos con el formato año.mes.día (por ejemplo 2026.9.3). La misma imagen está en Docker Hub como openclaw/openclaw. 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). El docker-compose.yml oficial ya mapea ese nombre al host en Linux (Docker Desktop lo trae de serie en macOS y Windows); si usas un compose propio, agrega tú el extra host:

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 oficial se publica para linux/amd64 y linux/arm64, así que funciona en una Pi con un OS de 64 bits. Dicho eso, en una Raspberry Pi el script nativo con Node 24 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, y el mapa de todas las rutas en la guía de OpenClaw.

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.

El compose de arriba también corre en una Raspberry Pi, con la única condición de un OS de 64 bits. En Windows va sobre WSL2 aunque uses Docker Desktop, así que conviene saber cuál de las tres vías estás usando antes de depurar un problema de red.

Fuente

• Documentación oficial de OpenClaw: Docker
• OpenClaw: variables de entorno de Docker
• OpenClaw: red y almacenamiento en Docker