自动化故障排除

使用此页面解决调度器和投递问题（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 在配置/环境变量中被禁用。
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 → 可视性设置抑制出站心跳消息。

时区和 activeHours 注意事项

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 的 cron 使用网关主机时区。
心跳 activeHours 使用配置的时区解析（user、local 或显式 IANA 时区）。
没有时区的 ISO 时间戳在 cron at 计划中被视为 UTC。

常见特征：

主机时区更改后任务在错误的挂钟时间运行。
您的白天期间心跳总是被跳过，因为 activeHours.timezone 错误。