OpenClaw de cero a producción — sin perder una noche en resolución de problemas

La demo tomó tres minutos. Tu instalación tomó tres horas. No estás solo, y no es tu culpa.

OpenClaw es una herramienta potente, pero la documentación asume que ya sabes qué puede salir mal. Esta guía no lo hace. Comienza con lo que realmente detiene a la gente y cómo solucionarlo al primer intento.

Los cimientos: tres comandos que lo revelan todo

Antes de instalar cualquier cosa, ejecuta esto:

• node --version
• npm --version
• git --version

Lo que necesitas:

• Node 22+ — esto no es negociable
• Git — instalado y disponible en el PATH
• Docker — solo si realmente planeas usar contenedores/sandbox (la mayoría no lo necesita el primer día)

La mayoría de los problemas de instalación que vemos comienzan con la versión incorrecta de Node. Esto genera mensajes de error que apuntan al lugar equivocado, y puedes pasar horas depurando sin darte cuenta de que el problema base es una versión tres veces más antigua.

El camino recomendado: funciona para el 90% de los casos

Ejecuta el script de instalación oficial:

curl -fsSL https://openclaw.ai/install.sh | bash

Luego, tres comandos en orden:

El panel de control normalmente se abre en el navegador. Si no: ve manualmente a http://127.0.0.1:18789/ en la máquina que ejecuta el gateway.

Windows: donde mueren la mayoría de las configuraciones

La documentación de OpenClaw señala a WSL2 por una muy buena razón. La instalación nativa en Windows es un camino de dolor con resultados impredecibles.

La receta que realmente funciona:

El error clásico de Windows: mitad de la configuración en PowerShell, mitad en WSL. Entonces nada funciona.

Es tentador empezar en PowerShell porque resulta familiar. Resiste la tentación. En el momento en que mezclas dos entornos, obtienes conflictos de rutas (path), versiones de Node incorrectas y un gateway que arranca en un entorno y muere en el otro.

Docker: potente, pero no para el primer día

Docker es la opción correcta cuando necesitas aislamiento, ejecutas en un VPS o necesitas operar de forma estable a largo plazo. Pero para una primera instalación local, suele ser excesivo.

Si quieres hacerlo de todos modos:

• Vía rápida: ./docker-setup.sh desde el repo
• Requiere Docker + Compose v2

La regla de oro: consigue que la instalación normal esté en verde primero. Después considera Docker para producción.

Los cinco errores que más detienen a la gente — y sus soluciones

1. openclaw: command not found

El CLI no está en el PATH o la instalación se detuvo a la mitad. Ocurre más a menudo de lo que se cree.

Solución: Ejecuta el script de instalación de nuevo. Abre una nueva terminal (importante — la terminal vieja tiene el PATH viejo). Verifica con which openclaw y openclaw --version.

2. El gateway no arranca o muere tras el inicio de sesión

Estado antiguo de una instalación previa o una migración que se quedó estancada.

Solución: Empieza con openclaw doctor. Para entornos headless/CI: openclaw doctor --repair --yes. Reinicia el gateway con openclaw gateway restart. Lee los logs con openclaw logs --follow — casi siempre dicen qué falló realmente.

3. El panel de control en 127.0.0.1:18789 está muerto

O el gateway no se está ejecutando, el puerto es incorrecto o el demonio nunca se configuró correctamente durante el onboarding.

Solución: Comprueba openclaw gateway status. Prueba el modo foreground: openclaw gateway --port 18789. Ejecuta openclaw dashboard de nuevo.

4. Una actualización rompió algo que funcionaba ayer

La configuración y el estado cambian entre versiones. OpenClaw está en desarrollo activo — esto sucede.

Solución: Actualiza mediante el script de instalación oficial (no con git pull manual). Ejecuta openclaw doctor inmediatamente después. Prueba el gateway + dashboard antes de activar la automatización.

5. El sandboxing bloquea todo lo que intentas hacer

La política y la configuración de Docker aún no coinciden con las cargas de trabajo. Esto se debe a que el sandboxing es lo último que debes configurar, no lo primero.

Solución: Comienza con el modo sandbox en off. Activa gradualmente (non-main primero). Usa openclaw sandbox explain para entender exactamente qué está bloqueando.

Operación que no explota tras la segunda semana

La instalación es el día 1. La operación es el resto. Algunas reglas para mantener la estabilidad:

• Mantén ~/.openclaw privado — esto contiene configuración y credenciales, no es algo que deba estar en una carpeta compartida
• Mínimos privilegios posibles en claves y tokens — no des acceso de administrador donde baste con el de observador
• No des acceso total al host si el sandbox es suficiente para tu carga de trabajo
• Ejecuta openclaw doctor regularmente — no solo cuando todo ya esté en rojo. El mantenimiento preventivo es más barato que apagar incendios.

Lista de verificación: ¿estás realmente operativo?

Antes de declararte terminado, revisa esto:

• openclaw --version responde con la versión correcta
• openclaw gateway status está en verde
• openclaw dashboard abre sin errores
• Un mensaje de prueba pasa por todo el pipeline
• openclaw doctor da verde o advertencias manejables

Cuando esta lista está en verde, no solo estás instalado. Estás operativo con control — y hay una diferencia sustancial.

Cuando todo se ilumina en verde, tienes una configuración que soporta actualizaciones, que puedes depurar sistemáticamente y que no colapsa la primera vez que algo cambia. Esa es la diferencia entre "funciona en mi máquina" y una infraestructura realmente lista para producción.