Requisitos de OpenClaw y errores comunes al instalar

Antes de instalar OpenClaw conviene saber qué pide de verdad, y qué hacer cuando algo falla. Este es el resumen de requisitos y los problemas más comunes al instalarlo. Para los pasos por plataforma, está la cómo instalar OpenClaw.

Requisitos mínimos

El script de instalación oficial resuelve Node por ti, así que en la mayoría de los casos solo necesitas el sistema operativo soportado y la API key. Para correrlo en hardware chico, mira la guía de OpenClaw en Raspberry Pi.

Antes de nada: openclaw doctor

Ante cualquier falla, el primer comando que debes correr es el diagnóstico integrado:

openclaw doctor

Revisa la versión de Node, el estado del gateway, los puertos, los permisos y la configuración del proveedor, y te dice exactamente qué falta en vez de fallar en silencio. La mayoría de los errores de abajo los detecta doctor antes de que tengas que investigar a mano. Para ver si el gateway está corriendo, suma:

openclaw gateway status

Actualiza con una comprobación antes y otra después

No actualices OpenClaw como si fuera una dependencia invisible. El gateway guarda configuración, credenciales y estado local; una release puede incorporar migraciones o cambiar el diagnóstico que usa doctor. La actualización no tiene por qué ser complicada, pero sí debe ser verificable.

Antes de tocar la instalación, guarda la versión y deja el diagnóstico limpio:

openclaw --version
openclaw doctor
openclaw gateway status

Si lo corres con Docker Compose, conserva los volúmenes y actualiza la imagen como explico en la guía de Docker. No uses down -v: ese sufijo borra los volúmenes donde vive la configuración.

Después de actualizar, repite openclaw doctor, revisa los avisos de migración y confirma que el gateway responde antes de volver a conectar canales o automatizaciones. Las notas de release 2026.6.11, por ejemplo, documentan cambios de mantenimiento y almacenamiento: es justo el tipo de actualización que conviene leer antes de asumir que un reinicio basta.

Errores comunes y cómo resolverlos

1. El comando falla o pide una versión de Node más nueva

Es el problema número uno, y tiene trampa: no basta con "tener Node 22", el mínimo de esa rama es la 22.22.3, así que un v22.14 parece cumplir y no cumple. Las ramas válidas son 22.22.3+, 24.15+ y 25.9+. Verifica:

node --version

Si te quedas corto, actualiza a Node 26 (con fnm o NodeSource) o reinstala con el script oficial, que resuelve la versión correcta automáticamente.

2. El daemon no arranca o OpenClaw no responde tras reiniciar

Si registraste el servicio con --install-daemon pero el agente no aparece, revisa su estado y sus logs. En Linux:

openclaw status
systemctl status openclaw
journalctl -u openclaw -f

En macOS el daemon corre con launchd. Si quedó mal registrado, vuelve a correr openclaw onboard --install-daemon.

3. El puerto 18789 está ocupado

El gateway escucha en 127.0.0.1:18789. Si otro proceso ya usa ese puerto, OpenClaw no levanta. Libera el puerto o configura el gateway en otro durante el onboarding.

4. No conecta con el modelo de IA

Casi siempre es la API key sin configurar o vencida. Vuelve a correr el wizard y carga la clave del proveedor:

openclaw onboard

5. En macOS pide permisos de administrador

Es esperado: la documentación oficial avisa que "first run may need an Administrator for Homebrew". La primera ejecución puede necesitar permisos de administrador para instalar dependencias con Homebrew. Concédelos esa vez y listo.

6. En Windows el script no corre

El install.sh es un script bash y no corre en PowerShell. En Windows usa el instalador de PowerShell, la app nativa Windows Hub o WSL2: lo explico en la instalar OpenClaw en Windows 10 y 11.

7. En Docker no conecta con un modelo local

Si corres OpenClaw en Docker y apuntas tu modelo local a 127.0.0.1, fallará: dentro del contenedor esa dirección es el contenedor mismo, no tu host. Apunta el proveedor a host.docker.internal (y en Linux agrega extra_hosts: ["host.docker.internal:host-gateway"] al compose).

8. La instalación con pnpm no compila

Si instalas con pnpm de forma global, los scripts de build de algunas dependencias quedan bloqueados por defecto. Habilítalos una vez con:

pnpm approve-builds -g

Para el gateway, de todos modos, la documentación recomienda Node por sobre otros runtimes; bun sirve para la CLI.

Con los requisitos claros, el siguiente paso es elegir cómo instalarlo: las rutas están ordenadas en la guía de OpenClaw.

Preguntas frecuentes

Cierre

La mayoría de los problemas al instalar OpenClaw se reducen a tres cosas: una versión de Node vieja, el daemon mal registrado o la API key sin configurar. Con los requisitos claros y estos chequeos, la instalación es directa. Los pasos por plataforma están en la guía completa de OpenClaw.

Fuente

• Documentación oficial de OpenClaw
• Notas de release 2026.6.11