# Automation troubleshooting

> Command ladder and fixes for jobs that do not fire or do not deliver

- 网址：https://funcoding.ai/agents/openclaw/automation/cron-jobs/troubleshooting/
- 来源：OpenClaw 官方文档原文（英文），MIT 许可，同步于 2026-10-11
- 官方原文：https://docs.openclaw.ai/zh-CN/automation/cron-jobs/troubleshooting

---
A command ladder and the common failure shapes for scheduled jobs. Part of the [Automations](https://funcoding.ai/agents/openclaw/automation/cron-jobs/) guide.

## Troubleshooting

### Command ladder

```bash
openclaw status
openclaw gateway status
openclaw automations status
openclaw automations list
openclaw automations runs <jobId> --limit 20
openclaw system heartbeat last
openclaw logs --follow
openclaw doctor
```

<details>
<summary>Automations not firing</summary>

- Check the `cron.enabled` config setting and `OPENCLAW_SKIP_CRON` in the Gateway's launch environment. Either can disable automatic runs; clear both disable settings and restart the Gateway to enable scheduling.
- Confirm the Gateway is running continuously.
- For `cron` schedules, verify timezone (`--tz`) vs the host timezone.
- `reason: not-due` in run output means the manual run was checked with `openclaw automations run <jobId> --due` and the job was not due yet.
- If the job's execution agent cannot be resolved, automatic and manual attempts record a failed task and a skipped run-history entry with the reason. Select an agent with `openclaw automations edit <jobId> --agent <id>`.
- A run can finish `ok` after an exec call fails and the agent replies. Check `diagnostic:` in `openclaw automations show <jobId>` or `diagnostics` in run history; unresolved exec failures produce a warning without exposing command arguments.
- `handler-unavailable` means the heartbeat service was not registered or stopped during the wait. The attempt is recorded as skipped. Check Gateway startup and sidecar errors before retrying the job.
- If a capped job's stored named creator account is unavailable, the run fails before model/tool execution. Job details, run history, and warning logs name the account. Re-add it to the channel configuration, or recreate the automation from the intended account; changing the delivery `--account` does not change creator authority. Legacy jobs without account metadata keep their existing execution policy.

</details>

<details>
<summary>Job fired but no delivery</summary>

- `System event queue is full` means the session already has 20 pending events. OpenClaw keeps those accepted events and records the overflowing reminder as a failed run instead of dropping an older reminder. Let the session process its pending events, then retry the failed reminder with `openclaw automations run <jobId>`. If heartbeats were paused, enable them with `openclaw system heartbeat enable`. Pending system events are process-local, not a durable delivery receipt across Gateway restarts.
- Delivery mode `none` means no runner fallback send is expected. The agent can still send directly with the `message` tool when a chat route is available.
- Delivery target missing/invalid (`channel`/`to`) means outbound was skipped.
- For Matrix, copied or legacy jobs with lowercased `delivery.to` room IDs can fail because Matrix room IDs are case-sensitive. Edit the job to the exact `!room:server` or `room:!room:server` value from Matrix.
- Channel auth errors (`unauthorized`, `Forbidden`) mean delivery was blocked by credentials.
- When the dispatcher records intentional suppression, job state, run history, and finished events include `deliverySuppressionReason` (`empty`, `silent`, `heartbeat`, or `channel_transform`). This is separate from `lastDeliveryError` / `deliveryError`; required delivery failures also log an error when they happen.
- For text-only isolated announcements, a reply containing only `NO_REPLY` / `no_reply` or ending with a trailing silent token suppresses the entire text and the fallback queued summary. See [Silent token suppression](https://funcoding.ai/agents/openclaw/cli/cron/#silent-token-suppression) for examples and media behavior.
- If the agent should message the user itself, check that the job has a usable route (`channel: "last"` with a previous chat, or an explicit channel/target).

</details>

<details>
<summary>Automations or heartbeat appear to prevent /new-style rollover</summary>

- Daily and idle reset freshness is not based on `updatedAt`; see [Session management](https://funcoding.ai/agents/openclaw/concepts/session/#session-lifecycle).
- Automation wakeups, heartbeat runs, exec notifications, and gateway bookkeeping may update the session row for routing/status, but they do not extend `sessionStartedAt` or `lastInteractionAt`.
- For legacy rows created before those fields existed, OpenClaw can recover `sessionStartedAt` from the transcript JSONL session header when the file is still available. Legacy idle rows without `lastInteractionAt` use that recovered start time as their idle baseline.

</details>

<details>
<summary>Timezone gotchas</summary>

- Cron expressions without `--tz` use the gateway host timezone.
- `at` schedules without timezone are treated as UTC.
- Heartbeat `activeHours` uses configured timezone resolution.

</details>