自动化故障排查

本页用于排查调度和投递问题（cron + heartbeat）。

命令诊断阶梯

bash

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

然后运行自动化专项检查：

bash

openclaw cron status
openclaw cron list
openclaw system heartbeat last

Cron 任务不触发

bash

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。
cron: timer tick failed → 调度器 tick 崩溃；检查周边堆栈/日志上下文。
运行输出中的 reason: not-due → 手动运行时没有 --force 且任务还未到期。

Cron 触发但无投递

bash

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

正常输出的特征：

运行状态为 ok。
隔离任务已设置投递模式/目标。
渠道 probe 显示目标渠道已连接。

常见问题特征：

运行成功但投递模式为 none → 不期望有外部消息，属正常。
投递目标缺失/无效（channel/to）→ 运行可能内部成功但跳过了出站投递。
渠道鉴权错误（unauthorized、missing_scope、Forbidden）→ 投递被渠道凭证/权限阻止。

Heartbeat 被抑制或跳过

bash

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

正常输出的特征：

Heartbeat 已启用且间隔非零。
最后一次 heartbeat 结果为 ran（或跳过原因明确）。

常见问题特征：

heartbeat skipped，reason=quiet-hours → 不在 activeHours 范围内。
requests-in-flight → 主通道繁忙，heartbeat 被推迟。
empty-heartbeat-file → 间隔 heartbeat 被跳过，因为 HEARTBEAT.md 没有可操作内容且没有排队的 cron 事件。
alerts-disabled → 可见性设置抑制了 heartbeat 出站消息。

时区和 activeHours 注意事项

bash

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 表示该键未设置；heartbeat 回退到主机时区（或 activeHours.timezone，若已设置）。
没有 --tz 的 cron 任务使用 Gateway 主机时区。
Heartbeat activeHours 使用配置的时区解析（user、local 或显式 IANA tz）。
at 类型的 cron 调度：无时区的 ISO 时间戳视为 UTC，除非使用了 CLI 的 --at "<offset-less-iso>" --tz <iana>。

常见问题特征：

主机时区变更后，任务在错误的本地时间运行。
activeHours.timezone 设置错误导致 heartbeat 在你的白天一直被跳过。

自动化故障排查 ​

命令诊断阶梯 ​

Cron 任务不触发 ​

Cron 触发但无投递 ​

Heartbeat 被抑制或跳过 ​

时区和 activeHours 注意事项 ​

自动化故障排查

命令诊断阶梯

Cron 任务不触发

Cron 触发但无投递

Heartbeat 被抑制或跳过

时区和 activeHours 注意事项