Desplegar OpenClaw en una Instancia WEC con Docker Compose

++

Despliega un agente de IA autoalojado de OpenClaw en una Instancia WEC con Docker Compose — desde levantar la VM hasta un agente que de verdad responde, usando tu propia clave de API del modelo. Cada comando, versión y error que aparece abajo fue capturado de un despliegue real en un Instancia WEC.

Reproducibilidad

Tú aportas tu propia clave de API del modelo (OpenAI en esta guía); WiLine se encarga del alojamiento. Esto se reprodujo en un Instancia WEC — Ubuntu 22.04.5 LTS, 8 vCPU, 15 GiB de RAM, 25 GB de disco libre. Versión de OpenClaw 2026.6.8, imagen ghcr.io/openclaw/openclaw:latest.

---

Lo que vas a construir

Un único contenedor gateway de OpenClaw, configurado con tu proveedor de modelo, accesible a través de su Control UI web y de la CLI.

---

Requisitos previos

• Una cuenta de WiLine Edge Cloud
• Una clave de API de un modelo — esta guía usa OpenAI; Anthropic y los modelos locales también funcionan
• Un par de claves SSH en tu máquina (~/.ssh/id_ed25519 o similar)
• Unos 20 minutos

---

Paso 1 — Aprovisionar la VM en WiLine

Levanta una VM de WiLine que cumpla estos requisitos:

Requisito	Valor
SO	Ubuntu 22.04 LTS (o 24.04 LTS)
Cómputo	≥ 2 vCPU / 4 GB de RAM — OpenClaw necesita ≥ 2 GB; la primera ejecución puede morir por falta de memoria (exit 137) en hosts de 1 GB
Disco	30 GB NVMe — 10 GB se llenan rápido en cuanto llegan las imágenes de Docker y los logs
Acceso	Tu clave pública SSH añadida al desplegar, para poder entrar sin contraseña

El recorrido por el portal ya está documentado — sigue estos pasos y vuelve:

• Desplegar una máquina virtual →
• Configurar una clave SSH →

Cuando esté en marcha, conéctate por SSH:

ssh ubuntu@<ip-de-tu-vm>

---

Paso 2 — Verificar la máquina

Antes de instalar nada, confirma con qué estás trabajando — la versión del SO y los recursos disponibles. Anota estos números; son útiles cuando luego compares rendimiento o abras un ticket de soporte.

lsb_release -a
nproc
free -h
df -h /

En nuestra Instancia WEC: Ubuntu 22.04.5 LTS, 8 vCPU, ~15 GiB de RAM, 25 GB de disco libre.

---

Paso 3 — Instalar Docker + Compose

Comprueba si Docker ya está presente:

docker --version
docker compose version

Si no está instalado, sigue la guía oficial de Docker para tu distribución — Instalar Docker Engine en Ubuntu. La vía más rápida es el script de conveniencia de Docker, seguido de añadir tu usuario al grupo docker para poder ejecutarlo sin sudo:

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
newgrp docker

Necesitas Docker Compose v2 (el subcomando docker compose, no el antiguo binario docker-compose).

nota

Si Docker ya está presente, el script get.docker.com lo detecta y avisa en lugar de reinstalar — no lo fuerces en una máquina con contenedores en ejecución. En una VM limpia instala desde cero. Este despliegue se ejecutó en un host donde Docker 29.1.3 / Compose v5.0.2 ya estaba instalado.

---

Paso 4 — Obtener el archivo Compose

Crea un directorio para el proyecto y descarga el docker-compose.yml oficial de OpenClaw:

mkdir openclaw && cd openclaw
curl -fsSL https://raw.githubusercontent.com/openclaw/openclaw/main/docker-compose.yml -o docker-compose.yml

El archivo define dos servicios — openclaw-gateway (el gateway del agente de larga duración) y openclaw-cli (una CLI de un solo uso que comparte la red del gateway). Por defecto compila desde el código fuente; en su lugar lo apuntaremos a la imagen precompilada.

---

Paso 5 — Configurar .env

Crea un .env junto al archivo compose. Fija la imagen precompilada y establece un token para el panel:

OPENCLAW_IMAGE=ghcr.io/openclaw/openclaw:latest
OPENCLAW_GATEWAY_TOKEN=<pega la salida de: openssl rand -hex 32>

Mantén .env fuera de git

Contiene tu token del gateway (y cualquier clave). Añádelo a .gitignore. En su lugar, sube un .env.example con valores de marcador.

Descarga la imagen:

docker compose pull

---

Paso 6 — Crear de antemano el directorio de configuración

OpenClaw monta ~/.openclaw dentro del contenedor mediante bind-mount. Créalo primero con tu propio usuario — de lo contrario Docker lo crea como root y el contenedor (que se ejecuta como el usuario node, uid 1000) no puede escribir en él:

mkdir -p ~/.openclaw ~/.openclaw-auth-profile-secrets

Si te lo saltas, te toparás con un error de permisos en la primera ejecución — mira la Solución de problemas.

---

Paso 7 — Onboarding

Aquí es donde aportas tu propio modelo — el onboarding te pide tu proveedor y tu clave de API. Esta guía usa OpenAI, pero Anthropic y los modelos locales funcionan igual.

Ejecuta el onboarding de OpenClaw a través del contenedor gateway. Es interactivo — te pregunta tu proveedor y clave de API y escribe la configuración:

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

Avanza por las preguntas:

• Continuar tras el aviso de seguridad de uso personal → Yes
• Setup mode → QuickStart
• Provider → OpenAI (o tu proveedor), luego pega tu clave de API
• Default model → mantén el sugerido (openai/gpt-5.5)
• Channel → busca skip → Skip for now (los canales de mensajería son una guía posterior)
• Skills / Hooks → No / Skip for now (configúralos luego con openclaw configure)
• Hatch your agent → Hatch later (a continuación iniciamos el gateway como servicio)

Termina con Onboarding complete.

---

Paso 8 — Aplicar la configuración del gateway e iniciarlo

El onboarding escribió tu proveedor y modelo. Ahora establece las opciones de ejecución del gateway — modo de ejecución, bind de red y los orígenes que aceptará la Control UI — y luego inícialo como servicio en segundo plano.

docker 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

---

Paso 9 — Comprobación de funcionamiento

Salud del contenedor:

docker compose ps

Quieres ver Up ... (healthy). Luego consulta el endpoint de salud:

curl http://127.0.0.1:18789/healthz
# {"ok":true,"status":"live"}

Confirma que tu clave del proveedor es utilizable:

docker compose run --rm openclaw-cli models status
# openai ... api_key=1 ... status=usable

Censura antes de capturar la pantalla

models status imprime un prefijo de clave enmascarado (sk-proj-…). Recórtalo o difumínalo antes de publicar la captura.

Ahora la prueba real de extremo a extremo. El comando agent necesita un destino, así que primero lista los agentes y luego envía un mensaje al predeterminado (main):

docker compose run --rm openclaw-cli agents list
# - main (default)

docker compose run --rm openclaw-cli agent --agent main \
  --message "Reply with exactly one word: working"
# working

Si responde working, toda la cadena — gateway → OpenAI → respuesta — está activa.

La Control UI está en http://<ip-de-tu-instancia>:18789/; pega tu OPENCLAW_GATEWAY_TOKEN en Ajustes para iniciar sesión.

Abrirla desde otra máquina

Los navegadores bloquean la Control UI sobre HTTP plano en una IP remota ("Secure browser context required"). Accede mediante un túnel SSH para que se cargue como 127.0.0.1 — mira la Solución de problemas #3.

---

Solución de problemas (errores reales)

Estos son errores que realmente encontramos durante este despliegue — no son hipotéticos.

1. EACCES: permission denied, mkdir '/home/node/.openclaw/state'

Apareció en la primera ejecución del onboarding cuando ~/.openclaw no existía de antemano:

[openclaw] The CLI command failed.
[openclaw] Reason: Failed to open the plugin state database.
| EACCES: permission denied, mkdir '/home/node/.openclaw/state' | EACCES

Causa: Docker creó automáticamente el origen del bind-mount ~/.openclaw con propietario root (0:0). El contenedor se ejecuta como el usuario node (uid 1000), por lo que no puede escribir dentro de ese directorio propiedad de root.

Solución: asigna el directorio al uid 1000 (que también es tu usuario ubuntu):

sudo chown -R 1000:1000 ~/.openclaw

Crear el directorio tú mismo de antemano (Paso 6) evita esto por completo.

2. No target session selected

La primera vez que ejecutamos agent sin especificar con quién hablar:

Error: No target session selected. Use --agent <id>, --session-key <key>,
--session-id <id>, or --to <E.164>. Run openclaw agents list to see agents.

Causa: openclaw agent ejecuta un turno contra un agente/sesión específico; sin ningún canal configurado no hay un destino implícito.

Solución: lista los agentes y pasa el id explícitamente:

docker compose run --rm openclaw-cli agents list          # muestra: main (default)
docker compose run --rm openclaw-cli agent --agent main --message "..."

3. Control UI: "Secure browser context required"

Al abrir la Control UI desde otra máquina (p. ej. macOS) en la IP de la instancia sobre HTTP plano, la página se niega a conectar:

Secure browser context required
This page is running over plain HTTP, so the browser cannot create the
device identity the Gateway expects.

Causa: los navegadores solo exponen las APIs de cifrado que OpenClaw necesita en un contexto seguro — HTTPS, o localhost/127.0.0.1. Un http://<ip>:18789 remoto no es ninguno, así que el navegador lo bloquea, independientemente del flag del servidor gateway.controlUi.allowInsecureAuth.

Solución: tuneliza el puerto por SSH para que el navegador hable con 127.0.0.1 (un contexto seguro). En tu máquina local:

ssh -L 18789:127.0.0.1:18789 ubuntu@<ip-de-tu-vm>

Luego abre http://127.0.0.1:18789/#token=<tu-token> localmente. La solución definitiva a largo plazo es HTTPS mediante un proxy inverso — la próxima guía.

---

Notas de seguridad

Al arrancar, el gateway registró advertencias que conviene atender antes de cualquier exposición pública:

• Bind a una dirección no-loopback — el gateway escucha en la LAN. No expongas el puerto 18789 a la Internet pública sin autenticación por delante.
• gateway.controlUi.allowInsecureAuth=true — marcado como peligroso. Ejecuta docker compose run --rm openclaw-cli security audit.
• plugins.allow está vacío — pueden autocargarse plugins no incluidos (p. ej. codex). Define una lista explícita de ids de plugins de confianza.

Endurecer esto detrás de un proxy inverso con HTTPS es el tema de la próxima guía.

---

Lo que has logrado

Pasaste de una Instancia WEC a un agente de IA autoalojado y funcional:

• Aprovisionaste y verificaste una VM Ubuntu en WEC
• Levantaste el gateway de OpenClaw con Docker Compose y la imagen precompilada oficial
• Conectaste tu propio proveedor de modelo (OpenAI) y lo confirmaste de extremo a extremo — el agente respondió por la CLI y por la Control UI
• Te topaste con (y resolviste) los problemas reales de permisos, sesión y contexto seguro por el camino

El agente es tuyo: tu clave, tu máquina, tus datos. A partir de aquí se trata de hacerlo seguro, accesible y útil.

---

¿Qué puedes hacer con ello?

OpenClaw no es un chatbot — es un agente autónomo que puede actuar en tu máquina. Ahora que está en marcha, esto es lo que desbloquea (algunas funciones necesitan configuración adicional, y cubrimos las principales más adelante en esta serie):

• Ejecuta trabajo real en la máquina. Puede ejecutar comandos de shell y leer/escribir archivos — "revisa qué está ocupando el disco," "muestra los logs y resume los errores" — con sandboxing configurable para cuánto le permites tocar.
• Háblale desde tu teléfono. OpenClaw se conecta a WhatsApp, Telegram, Discord, Slack, Signal e iMessage, así que delegas tareas conversando, sin SSH. (Conectamos Telegram en la siguiente guía.)
• Navega y actúa en la web. La automatización de navegador integrada le permite navegar sitios, rellenar formularios y extraer datos de forma autónoma.
• Escribe y ejecuta código. Se integra con Claude Code para programación autónoma — escribir y modificar código, ejecutar pruebas e incluso abrir PRs.
• Trabaja en segundo plano, de forma proactiva. Funciona 24/7, puede ejecutar tareas en segundo plano y hace "latidos" (heartbeat) en vez de solo reaccionar cuando le escribes.
• Crece contigo. Una biblioteca comunitaria de habilidades (ClawHub), herramientas autogeneradas y orquestación multiagente lo hacen más capaz con el tiempo — respaldado por memoria persistente que mantiene el contexto entre conversaciones.

Usos reales típicos: gestión de correo y calendario, procesamiento de documentos, tareas de infraestructura en la máquina, pipelines de contenido y pruebas de código autónomas.

---

Qué sigue

Esta es la Parte 1 de la serie Self-hosting OpenClaw sobre ejecutar infraestructura de IA de nivel producción en una Instancia WEC. Próximamente:

• Parte 2 — Asegura OpenClaw con un proxy inverso Caddy + HTTPS (siguiente) — pon HTTPS por delante del gateway para eliminar el truco de allowInsecureAuth y acceder a la Control UI desde cualquier lugar, de forma segura.
• Parte 3 — Añade un canal de Telegram — habla con tu agente desde el móvil.
• Parte 4 — Haz OpenClaw privado con una VPN mesh NetBird — ponlo en una mesh privada y cierra los puertos públicos.

Los archivos complementarios de esta guía — docker-compose.yml y .env.example — viven en el repo de manifiestos de WiLine (enlace pendiente con el repo).

---

Desmontaje

docker compose down              # detiene y elimina los contenedores
docker compose down --rmi all -v # también elimina la imagen y los volúmenes

Para eliminar la configuración/estado del host: rm -rf ~/.openclaw ~/.openclaw-auth-profile-secrets. Para detener la facturación por completo, elimina la VM desde el portal de WiLine.