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 24", el mínimo de esa rama es la 24.16, así que un v24.15 parece cumplir y no cumple. Las ramas válidas son 24.16+ y 26.1+; Node 22, 23 y 25 ya no están soportados. 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 el servicio es una unidad de usuario llamada openclaw-gateway.service, así que los comandos llevan --user:

openclaw gateway status
systemctl --user status openclaw-gateway.service
journalctl --user -u openclaw-gateway.service -f

En un servidor headless, la unidad de usuario se detiene al cerrar la sesión SSH salvo que habilites el linger con sudo loginctl enable-linger "$(whoami)". Lo detallo en la guía de Ubuntu.

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 cambia el del gateway (gateway.port) con openclaw configure --section gateway.

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: según la documentación del instalador, en macOS el script instala Homebrew solo si lo necesita para Node o Git, y el instalador de Homebrew comprueba el acceso sudo y puede pedirte la contraseña. Dale el permiso 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 quedan bloqueados por defecto, y pnpm approve-builds -g no sirve para instalaciones globales. Apruébalos en el mismo comando de instalación:

pnpm add -g --allow-build=openclaw openclaw@latest

Para el gateway, de todos modos, la documentación recomienda Node por sobre otros runtimes; Bun 1.4 o posterior puede correr la CLI y el gateway, pero solo como opción explícita.

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
• Compatibilidad de Node.js
• Requisitos de hardware y hosting (FAQ)
• Installer internals
• Notas de release 2026.6.11