---
title: "Cómo instalar OpenClaw con Docker Compose"
excerpt: "Instalación de OpenClaw con Docker y Docker Compose paso a paso: imagen oficial en GitHub Container Registry, el script de setup, dónde se persiste la configuración y cómo actualizar sin perder datos."
date: "2026-06-16T11:30:00.000Z"
lastModified: "2026-06-19T10:30:00.000Z"
category: "OpenClaw"
tech_article: true
seo_title: "Instalar OpenClaw con Docker y Docker Compose (2026)"
seo_description: "Guía oficial para correr OpenClaw en Docker Compose: imagen ghcr.io/openclaw/openclaw, el script de setup, volúmenes que persisten tu config y cómo actualizar con docker compose pull."
author:
  name: "Angel Cruz"
  picture: "https://angelcruzdevcdn.nyc3.cdn.digitaloceanspaces.com/images/me/angel-cruz.png"
ogImage:
  url: "https://angelcruzdevcdn.nyc3.cdn.digitaloceanspaces.com/content/5/01KFVJFYG53S1S5DCMGREM3CC2.png"
---

Docker es la forma más limpia de correr [OpenClaw](/post/clawdbot-asistente-ia-personal-open-source) 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](/post/como-instalar-openclaw-guia-completa).

## ¿Docker o instalación nativa?

| | Docker Compose | Script / npm |
| --- | --- | --- |
| Aislamiento | ✅ contenedor propio | ❌ corre sobre tu sistema |
| Actualizar | `docker compose pull` | reinstalar el paquete |
| Peso | Mayor (capa de Docker) | Menor (Node nativo) |
| Reproducible | ✅ idéntico en todos lados | depende del host |

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](/post/instalar-openclaw-en-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:

```bash
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:

| Variable | Para qué sirve |
| --- | --- |
| `OPENCLAW_IMAGE` | Imagen a usar (`ghcr.io/openclaw/openclaw:latest` o un tag fijo) |
| `OPENCLAW_SKIP_ONBOARDING` | Levanta el contenedor sin lanzar el wizard (útil en setups automatizados) |
| `OPENCLAW_SANDBOX` | Controla el modo de aislamiento del agente dentro del contenedor |
| `OPENCLAW_HOME_VOLUME` | Nombre del volumen donde persiste la config del agente |
| `OPENCLAW_DOCKER_SOCKET` | Ruta al socket de Docker si el agente necesita lanzar contenedores |

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:

```bash
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):

```bash
cd openclaw
docker compose pull
docker compose up -d
```

## Comandos útiles

```bash
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:

```bash
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:

```yaml
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](/post/instalar-openclaw-en-raspberry-pi).

## Preguntas frecuentes

### ¿Cuál es la imagen oficial de OpenClaw en Docker?

`ghcr.io/openclaw/openclaw:latest`, alojada en GitHub Container Registry. También puedes construir `openclaw:local` desde el repositorio.

### ¿Necesito escribir un docker-compose.yml?

No. El repositorio ya trae el `docker-compose.yml`; el script `./scripts/docker/setup.sh` lo usa por ti.

### ¿Pierdo mi configuración al actualizar el contenedor?

No, siempre que no borres los volúmenes. La config vive en `/home/node/.openclaw` y se persiste fuera del contenedor.

### ¿En qué puerto queda OpenClaw?

El gateway escucha en `127.0.0.1:18789`. Para llegar desde otra máquina, mejor un túnel (por ejemplo Cloudflare Tunnel) que abrir el puerto.

### ¿Cómo sé si el gateway está sano?

Consulta sus endpoints de salud: `http://127.0.0.1:18789/healthz` responde si el proceso está vivo y `/readyz` si ya está listo para atender. Sirven para un `healthcheck` del compose o un monitor externo.

### Uso un modelo local y el contenedor no se conecta, ¿por qué?

Dentro del contenedor `127.0.0.1` es el contenedor mismo, no tu host. Apunta el proveedor local a `host.docker.internal` (y en Linux agrega `extra_hosts: ["host.docker.internal:host-gateway"]` en el compose).

## 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](/post/como-instalar-openclaw-guia-completa).

## Fuente

- [Documentación oficial de OpenClaw — Docker](https://docs.openclaw.ai/install/docker)

---

## Sitemap

Índice completo del sitio: [/sitemap.md](https://www.angelcruz.dev/sitemap.md)

Canónico HTML: [https://www.angelcruz.dev/post/instalar-openclaw-con-docker-compose](https://www.angelcruz.dev/post/instalar-openclaw-con-docker-compose)