Troubleshoot OpenClaw Automation: Fix Cron and Delivery

Ever set up a cron job and then… nothing happens? We’ve all been there, staring at a silent terminal wondering if the scheduler is asleep or if the config just vanished. Troubleshooting automation can feel like chasing ghosts, but it doesn’t have to be a guessing game.

If your cron or heartbeat tasks are acting up, you can usually find the culprit by following a few logical steps. Here is how you can get your automation back on track.

Command ladder

When things feel off, you need a clear path to find the root cause. Start with these commands to check the health of your gateway and basic services.

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

Then run automation checks:

openclaw cron status
openclaw cron list
openclaw system heartbeat last

Cron not firing

If your jobs aren’t starting at all, you need to look at the scheduler state. Use these commands to see if the job is even on the radar.

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

Good output looks like:

cron status reports enabled and a future nextWakeAtMs.
Job is enabled and has a valid schedule/timezone.
cron runs shows ok or explicit skip reason.

Common signatures:

cron: scheduler disabled; jobs will not run automatically → cron disabled in config/env.
cron: timer tick failed → scheduler tick crashed; inspect surrounding stack/log context.
reason: not-due in run output → manual run called without --force and job not due yet.

Cron fired but no delivery

Sometimes the job runs, but the message never arrives. This usually means the internal logic worked, but the handoff to the channel failed.

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

Good output looks like:

Run status is ok.
Delivery mode/target are set for isolated jobs.
Channel probe reports target channel connected.

Common signatures:

Run succeeded but delivery mode is none → no external message is expected.
Delivery target missing/invalid (channel/to) → run may succeed internally but skip outbound.
Channel auth errors (unauthorized, missing_scope, Forbidden) → delivery blocked by channel credentials/permissions.

Heartbeat suppressed or skipped

Heartbeats are great for keeping things alive, but they have their own set of rules. If they aren’t showing up, check your intervals and active hours.

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

Good output looks like:

Heartbeat enabled with non-zero interval.
Last heartbeat result is ran (or skip reason is understood).

Common signatures:

heartbeat skipped with reason=quiet-hours → outside activeHours.
requests-in-flight → main lane busy; heartbeat deferred.
empty-heartbeat-file → HEARTBEAT.md exists but has no actionable content.
alerts-disabled → visibility settings suppress outbound heartbeat messages.

Timezone and activeHours gotchas

Timezones are the classic automation trap. If your jobs are running at 3 AM instead of 3 PM, check how the system resolves your local time.

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

Quick rules:

Config path not found: agents.defaults.userTimezone means the key is unset; heartbeat falls back to host timezone (or activeHours.timezone if set).
Cron without --tz uses gateway host timezone.
Heartbeat activeHours uses configured timezone resolution (user, local, or explicit IANA tz).
ISO timestamps without timezone are treated as UTC for cron at schedules.

Common signatures:

Jobs run at the wrong wall-clock time after host timezone changes.
Heartbeat always skipped during your daytime because activeHours.timezone is wrong.

Need more help? Check out the AI Setup Assistant.

下一步

OpenClaw Expert

Still stuck?

If this page didn't answer your case, ask OpenClaw Expert for step-by-step guidance.