OpenClaw 自动化故障排查指南：定时任务与心跳调度、投递问题的排查步骤与常见问题

当你遇到调度与投递问题（cron 定时任务 + heartbeat 心跳）时，可以使用本页面进行排查。

命令阶梯

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

然后运行自动化检查：

openclaw cron status
openclaw cron list
openclaw system heartbeat last

定时任务未触发

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

正常的输出应该是：

• cron status 报告已启用，且有一个未来的 nextWakeAtMs。
• 任务已启用，且拥有有效的调度 / 时区。
• cron runs 显示 ok 或明确的跳过原因。

常见的错误标识：

• cron: scheduler disabled; jobs will not run automatically → 定时任务在配置 / 环境变量中被禁用。
• cron: timer tick failed → 调度器 tick 崩溃；请检查周围的堆栈 / 日志上下文。
• 运行输出中的 reason: not-due → 手动运行时没有使用 --force，且任务尚未到执行时间。

定时任务已触发但未投递

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

正常的输出应该是：

• 运行状态为 ok。
• 独立任务已设置投递模式 / 目标。
• 通道探测报告目标通道已连接。

常见的错误标识：

• 运行成功但投递模式为 none → 不需要发送外部消息。
• 投递目标缺失 / 无效（channel/to）→ 内部运行可能成功，但跳过了外部投递。
• 通道鉴权错误（unauthorized、missing_scope、Forbidden）→ 投递被通道凭证 / 权限阻止。

心跳被抑制或跳过

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

正常的输出应该是：

• 心跳已启用，且间隔非零。
• 上次心跳结果为 ran（或跳过原因可理解）。

常见的错误标识：

• heartbeat skipped 且 reason=quiet-hours → 超出了 activeHours（活跃时段）。
• requests-in-flight → 主处理通道繁忙；心跳被推迟。
• empty-heartbeat-file → 间隔心跳被跳过，因为 HEARTBEAT.md 没有可执行内容，且没有标记的定时任务排队。
• alerts-disabled → 可见性设置抑制了外部心跳消息。

时区与活跃时段的常见问题

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

快速规则：

• Config path not found: agents.defaults.userTimezone 表示该键未设置；心跳会回退到主机时区（如果设置了 activeHours.timezone 则使用该时区）。
• 没有指定 --tz 的定时任务会使用网关主机的时区。
• 心跳的 activeHours 使用配置的时区解析（user、local，或显式的 IANA 时区）。
• 没有时区的 ISO 时间戳，在定时任务的 at 调度中会被视为 UTC。

常见的错误标识：

• 主机时区变更后，任务在错误的时钟时间运行。
• 心跳在你的白天总是被跳过，因为 activeHours.timezone 配置错误。

相关文档：

• 定时任务
• 心跳
• 定时任务与心跳对比
• 时区概念