Soluciona errores de OpenClaw: Guía de diagnóstico rápido

¿Hay algo más frustrante que configurar una automatización y que simplemente no pase nada? Todos hemos pasado por ese momento de revisar logs buscando por qué un proceso no arrancó cuando debía. Si estás lidiando con problemas en el scheduler o en la entrega (cron + heartbeat), esta guía te ayudará a encontrar el fallo rápido.

Usa esta página para resolver problemas de ejecución y envío en tus automatizaciones.

Escalera de comandos

Primero, verifica el estado general de tu instancia para descartar problemas de conexión o del Gateway:

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

Luego, ejecuta las comprobaciones específicas de automatización:

openclaw cron status
openclaw cron list
openclaw system heartbeat last

El Cron no se ejecuta

Si tus tareas programadas no arrancan, empieza por aquí:

openclaw cron status
openclaw cron list
openclaw cron runs --id <jobId> --limit 20
openclaw logs --follow

Un buen output se ve así:

cron status reporta que está habilitado y muestra un nextWakeAtMs futuro.
El job está habilitado y tiene un schedule o timezone válido.
cron runs muestra ok o una razón explícita de por qué se saltó.

Firmas comunes de errores:

cron: scheduler disabled; jobs will not run automatically → El cron está deshabilitado en tu configuración o variables de entorno.
cron: timer tick failed → El tick del scheduler falló; revisa el contexto del stack y los logs cercanos.
reason: not-due en el output de ejecución → Se llamó a una ejecución manual sin usar --force y al job aún no le toca ejecutarse.

El Cron se ejecutó pero no hubo entrega

A veces el proceso arranca, pero el mensaje nunca llega a su destino. Revisa estos puntos:

openclaw cron runs --id <jobId> --limit 20
openclaw cron list
openclaw channels status --probe
openclaw logs --follow

Un buen output se ve así:

El estado de la ejecución (run status) es ok.
El modo de entrega y el target están configurados correctamente para jobs aislados.
El probe del canal reporta que el canal de destino está conectado.

Firmas comunes de errores:

La ejecución fue exitosa pero el modo de entrega es none → No se espera ningún mensaje externo.
Falta el target de entrega o es inválido (channel/to) → La ejecución puede ser exitosa internamente pero se salta el envío al exterior.
Errores de autenticación en el canal (unauthorized, missing_scope, Forbidden) → La entrega está bloqueada por credenciales o permisos del canal.

Heartbeat suprimido o saltado

Si el heartbeat no está enviando señales de vida, verifica la configuración de actividad:

openclaw system heartbeat last
openclaw logs --follow
openclaw config get agents.defaults.heartbeat
openclaw channels status --probe

Un buen output se ve así:

Heartbeat habilitado con un intervalo que no sea cero.
El último resultado del heartbeat es ran (o la razón de por qué se saltó es clara).

Firmas comunes de errores:

heartbeat skipped con reason=quiet-hours → Estás fuera del horario definido en activeHours.
requests-in-flight → El carril principal está ocupado y el heartbeat se ha pospuesto.
empty-heartbeat-file → El archivo HEARTBEAT.md existe pero no tiene contenido que procesar.
alerts-disabled → La configuración de visibilidad está suprimiendo los mensajes de heartbeat salientes.

Problemas comunes con Timezone y activeHours

Las zonas horarias suelen ser la causa principal de que algo se ejecute a la hora que no es. Revisa tu configuración:

openclaw config get agents.defaults.heartbeat.activeHours
openclaw config get agents.defaults.heartbeat.activeHours.timezone
openclaw config get agents.defaults.userTimezone || echo "agents.defaults.userTimezone not set"
openclaw cron list
openclaw logs --follow

Reglas rápidas que debes recordar:

Si ves Config path not found: agents.defaults.userTimezone, la clave no está definida; el heartbeat usará la zona horaria del host (o activeHours.timezone si la configuraste).
Los cron jobs que no incluyen --tz usan la zona horaria del host donde corre el Gateway.
El activeHours del heartbeat usa la resolución de zona horaria configurada (ya sea user, local o una zona IANA explícita).
Los timestamps ISO que no incluyen zona horaria se tratan siempre como UTC para los schedules at de cron.

Firmas comunes de errores:

Los jobs se ejecutan a una hora de reloj incorrecta después de cambiar la zona horaria del host.
El heartbeat siempre se salta durante tu horario laboral porque activeHours.timezone es incorrecta.

Siguientes pasos

AI Setup Assistant

OpenClaw Expert

Sigues atascado?

Si esta pagina no resolvio tu caso, pregunta a OpenClaw Expert para pasos concretos.