Depura OpenClaw: Guía rápida de logs y solución de errores

¿Alguna vez has sentido que tu código se comporta como una caja negra? No hay nada más frustrante que enviar una petición y recibir un silencio absoluto por respuesta. Cuando las cosas fallan, necesitas visibilidad inmediata para no perder horas adivinando qué salió mal en el sistema.

Tener el control de los logs es fundamental para mantener la estabilidad de tus integraciones. En esta guía te muestro cómo encontrar la información que necesitas y cómo exprimir las herramientas de depuración de OpenClaw para solucionar problemas rápido.

¿Dónde guarda OpenClaw los logs?

Los logs se encuentran en $OPENCLAW_STATE_DIR/logs (por defecto es ~/.openclaw/logs).

Para un acceso rápido, puedes usar estos comandos:

# Open logs directory
openclaw logs --path

# Tail live
openclaw logs --follow

# Show last 500 lines
openclaw logs

Los logs rotan a diario y puedes generarlos en formato JSON si necesitas realizar un análisis estructurado.

¿Cómo leo los logs en tiempo real?

Si quieres ver qué está pasando justo en este momento, utiliza el flag --follow:

openclaw logs --follow

# Filter JSON logs
openclaw logs --follow --json | jq 'select(.level == "error")'

Llegó un mensaje pero no hubo respuesta. ¿Cómo debugueo?

Si el sistema recibe datos pero no responde, te recomiendo seguir estos pasos para identificar el cuello de botella:

1. Revisa los logs en vivo:

   openclaw logs --follow

2. Inicia el modo debug de forma temporal:

   openclaw gateway stop
   OPENCLAW_DEBUG=1 openclaw gateway start

3. Confirma que el canal esté activo y que el mensaje no haya sido ignorado:

   openclaw channels status

4. Verifica el estado de la sesión y de los modelos:

   openclaw status
   openclaw models status

5. Busca errores específicos de rate-limit, autenticación o fallos del modelo en los logs.

Los logs tienen demasiado ruido o no son detallados. ¿Cómo los ajusto?

Puedes cambiar el nivel de detalle modificando gateway.logLevel (el valor predeterminado es info):

• debug: muy detallado, ideal para desarrollo.
• info: nivel estándar para producción.
• warn: solo muestra advertencias y errores.
• error: solo muestra fallos críticos.

{
  gateway: { logLevel: "debug" }
}

El servicio no se reinicia tras un fallo. ¿Qué pasa?

Si OpenClaw se detiene y no vuelve a levantar, el problema suele estar en la configuración de tu gestor de servicios (launchd o systemd):

• En launchd: asegúrate de que KeepAlive esté configurado como true.
• En systemd: verifica que tengas Restart=on-failure y WantedBy=multi-user.target.

Puedes comprobar el estado del servicio con estos comandos:

# macOS
launchctl list | grep openclaw

# Linux
systemctl --user status openclaw
journalctl --user -u openclaw -n 100

¿Cómo verifico el estado del Gateway de forma programática?

Si necesitas automatizar la vigilancia del sistema, puedes consultar el endpoint de salud:

curl http://localhost:18789/health

# Or via CLI
openclaw health
openclaw health --json

Rompí algo por accidente. ¿Cómo reseteo?

A veces es mejor empezar de cero si la configuración se ha vuelto inconsistente. Tienes dos opciones:

# Full reset (wipes config, creds, sessions)
openclaw reset --scope full --yes

# Or just sessions
openclaw reset --scope sessions --yes

Después de resetear, vuelve a ejecutar el proceso de onboarding:

openclaw onboard --install-daemon

¿Cómo reporto un error?

Si encuentras un bug que no puedes solucionar, sigue estos pasos para que podamos ayudarte:

1. Reproduce el error activando el logging de debug:

   OPENCLAW_DEBUG=1 openclaw gateway restart

2. Revisa si alguien más ha reportado lo mismo en GitHub Issues.
3. Si es un problema nuevo, abre un issue incluyendo:
   • La versión de OpenClaw (openclaw --version).
   • Tu sistema operativo y versión de Node.js.
   • Fragmentos relevantes del log (asegúrate de borrar tus API keys o tokens).
   • Los pasos exactos para reproducir el fallo.

Próximos pasos

• Configuración de canales
• Gestión de modelos

AI Setup Assistant