📋 Cómo actualizar OpenClaw sin romper nada

Después de pasar más de 6 horas arreglando una actualización de OpenClaw que salió mal - una historia que documenté en Actualicé OpenClaw y todo se rompió - construí el procedimiento correcto para que no vuelva a pasar. Desde entonces lo he puesto a prueba en múltiples actualizaciones, incluyendo un salto de v2026.3.31 a v2026.4.2 que tomó 15 minutos sin un solo error.

Este procedimiento está pensado para OpenClaw desplegado en un VPS Linux con systemd. Lo armé combinando experiencia real con el flujo que hoy recomienda la documentación oficial: actualizar, correr openclaw doctor, reiniciar el gateway y verificar antes de volver a confiar en producción.

Antes de empezar

Necesitas tener claras tres cosas:

1. Cómo está instalado OpenClaw: instalador oficial, npm global, pnpm global o checkout del repositorio. El método de actualización depende de eso.
2. Cómo corre tu gateway: foreground manual, systemd user service o system service. Necesitas saber cómo reiniciarlo y con qué usuario corre.
3. Dónde vive tu estado: como mínimo ~/.openclaw/openclaw.json, ~/.openclaw/credentials/, ~/.openclaw/agents/, ~/.openclaw/workspace y, si lo usas, ~/.openclaw/.env.

El procedimiento

Paso 1: Haz un backup de verdad

Antes de tocar nada, crea un backup completo de OpenClaw. La forma más limpia hoy es usar el comando nativo:

openclaw backup create --verify

Si además usas variables de entorno fuera del estado normal de OpenClaw, respáldalas también:

[ -f ~/.openclaw/.env ] && cp ~/.openclaw/.env ~/.openclaw/.env.backup-$(date +%Y%m%d-%H%M%S)

Ese backup te da una salida ordenada si algo sale mal. No improvises este paso.

Paso 2: Documenta la versión actual

Antes de actualizar, deja registrado qué versión estás corriendo ahora:

openclaw --version

Yo también recomiendo capturar una foto rápida del estado actual:

openclaw status
openclaw gateway status

Si necesitas hacer rollback, esa línea base te ahorra muchas dudas.

Paso 3: Revisa changelog y documentación antes de ejecutar nada

Lee la guía oficial de updating y ten abierta la de troubleshooting. Busca específicamente:

• cambios incompatibles entre tu versión actual y la target
• cambios en auth-profiles.json o en la resolución de credenciales
• cambios en el comportamiento del servicio o del restart
• cambios en discovery, bind, auth y guardrails del gateway
• nuevas dependencias o requisitos de runtime

Si vas a saltar varias versiones, revisa las intermedias. Un breaking change intermedio te afecta igual.

Paso 4: Elige el método correcto de actualización

No mezcles métodos. Usa el que corresponde a tu instalación:

# Instalador oficial (ruta recomendada)
curl -fsSL https://openclaw.ai/install.sh | bash

# Instalación global con npm
npm i -g openclaw@latest

# Instalación global con pnpm
pnpm add -g openclaw@latest

# Checkout del repositorio
openclaw update

Si usas checkout del repo o quieres ver qué hará OpenClaw antes de tocar nada, empieza con:

openclaw update --dry-run

Paso 5: Corre openclaw doctor

Este es el paso que más valor me ha dado. Empieza con una revisión normal:

openclaw doctor

Si te propone una reparación concreta y entiendes el cambio, entonces sí:

openclaw doctor --fix

Hazlo como el mismo usuario que corre el gateway. Si tu servicio vive bajo un usuario específico, no corras esto como root “por si acaso”. openclaw doctor puede migrar configuración, detectar servicios heredados y advertirte sobre conflictos que no vas a ver solo mirando systemd.

Paso 6: Verifica que no tengas dos servicios peleando entre sí

Usa primero la vista oficial:

openclaw gateway status
openclaw gateway status --deep

Si estás en Linux, valida también la capa de systemd que realmente usas:

# Si usas systemd user service
systemctl --user status openclaw-gateway.service

# Si mantienes un system service custom
systemctl status openclaw-gateway.service

La regla es simple: debe existir un camino de supervisión claro, no dos. Si tienes un servicio heredado y otro creado por el flujo actual de OpenClaw, arréglalo antes de seguir.

Paso 7: Verifica auth y modelos antes del reinicio final

No esperes a descubrir el problema cuando el agente ya no responda. Revisa auth y modelos explícitamente:

openclaw models status

Si quieres una validación real contra el proveedor, puedes hacer una prueba activa:

openclaw models status --probe

Si aquí aparece “missing auth”, revisa de inmediato tus perfiles de autenticación por agente en ~/.openclaw/agents/<agentId>/agent/auth-profiles.json, tus credenciales en ~/.openclaw/credentials/ y cualquier fuente de variables de entorno que tu despliegue todavía dependa.

Paso 8: Reinicia el gateway de la forma correcta

Evita matar procesos a mano si ya estás usando el servicio administrado por OpenClaw. Reinicia desde la CLI:

openclaw gateway restart
openclaw gateway status
openclaw status

Si openclaw gateway status no muestra Runtime: running y RPC probe: ok, todavía no terminaste.

Paso 9: Verifica funcionamiento real, no solo “active (running)”

Un update no está terminado porque systemd diga que el proceso existe. Está terminado cuando OpenClaw responde de verdad.

Valida esto:

• manda un mensaje por tu canal principal
• confirma que el agente responde
• revisa el estado de los canales
• confirma que sesiones, cron jobs y flujos automáticos siguen vivos

Comandos útiles:

openclaw channels status --probe
openclaw status --deep

Paso 10: Mira los logs por al menos 5 minutos

No cierres la sesión apenas veas “running”. Quédate observando:

openclaw logs --follow

Aquí es donde aparecen los problemas tardíos: módulos que fallan a los 30 segundos, conflictos de puertos, auth degradada, canales que conectan pero no entregan, o un proceso duplicado que tumba al legítimo.

Paso 11: Si algo falla, usa la escalera oficial

Cuando OpenClaw se rompe, no improvises. Corre la secuencia de triage en este orden:

openclaw status
openclaw status --all
openclaw gateway probe
openclaw gateway status
openclaw doctor
openclaw channels status --probe
openclaw logs --follow

Esa escalera te dice muy rápido si el problema es reachability, auth, servicio, canales o configuración.

Paso 12: Ten listo el rollback antes de necesitarlo

Si algo no cuadra y no tienes una solución clara en minutos, vuelve atrás.

Para instalaciones globales:

npm i -g openclaw@<version>
# o
pnpm add -g openclaw@<version>

openclaw doctor
openclaw gateway restart

Para checkouts del repositorio:

git fetch origin
git checkout <commit-o-tag-conocido>
pnpm install
pnpm build
openclaw gateway restart

El objetivo del rollback no es “rendirte”. Es volver a un estado sano para investigar con cabeza fría.

Qué hacer si algo falla

OpenClaw no arranca

1. Revisa openclaw gateway status
2. Corre openclaw doctor
3. Sigue openclaw logs --follow
4. Si el problema empezó justo después del update, compara config actual contra backup y changelog

OpenClaw arranca y muere en loop

1. Busca conflicto de puertos o servicios duplicados con openclaw gateway status --deep
2. Revisa si discovery o bind cambió entre versiones
3. Verifica si el gateway quedó con auth o guardrails más estrictos
4. No sigas tirando comandos al azar: vuelve a la escalera del Paso 11

Los modelos no responden o falta auth

1. Corre openclaw models status
2. Revisa auth-profiles.json en el agentDir correcto
3. Confirma que tus claves o tokens realmente están cargando en el runtime actual
4. Si usas compatibilidades heredadas, valida que no hayan quedado a medias después del update

Nada funciona

1. Detén el experimento
2. Restaura el backup
3. Vuelve a la última versión estable para ti
4. Relee changelog y docs antes del siguiente intento

Lista de verificación rápida

Antes de actualizar:

• Backup creado con openclaw backup create --verify
• .env respaldado si aplica
• Versión actual documentada
• Estado actual capturado con openclaw status y openclaw gateway status
• Changelog y docs revisados
• Método de actualización correcto identificado

Después de actualizar:

• Binario actualizado y versión confirmada
• openclaw doctor ejecutado
• Servicios duplicados descartados
• Auth y modelos verificados con openclaw models status
• Gateway reiniciado con openclaw gateway restart
• openclaw gateway status muestra gateway sano
• Canal principal probado
• openclaw channels status --probe sin sorpresas
• Logs observados por al menos 5 minutos
• Plan de rollback listo si algo se degrada

Reflexión final

Una actualización de software debería tomar 15 minutos, no 6 horas. La diferencia entre un update exitoso y un desastre es tener un procedimiento documentado y seguirlo. No importa cuánta experiencia tengas o qué tan buena parezca tu herramienta de IA: sin un proceso claro, cualquier update es una lotería.

Documenta tu procedimiento. Haz backup siempre. Y si algo sale mal, no entres en pánico: restaura, lee y vuelve a intentarlo con calma.

---

Por: Cesar Rosa Polanco - Basado en un caso real, con apoyo editorial de inteligencia artificial.