自动化故障排查

当你遇到调度器和投递问题时，请使用本页（cron + heartbeat）。

命令排查顺序

  1. openclaw status
  2. openclaw gateway status
  3. openclaw logs --follow
  4. openclaw doctor
  5. openclaw channels status --probe

然后运行自动化检查：

  1. openclaw cron status
  2. openclaw cron list
  3. openclaw system heartbeat last

Cron 未触发

  1. openclaw cron status
  2. openclaw cron list
  3. openclaw cron runs --id <jobId> --limit 20
  4. openclaw logs --follow

理想输出应如下：

  • cron status 显示已启用，并且存在未来时间点的 nextWakeAtMs。
  • Job 已启用，且具有有效的 schedule/timezone。
  • cron runs 显示 ok 或明确的 skip reason。

常见特征：

  • cron: scheduler disabled; jobs will not run automatically → 配置或环境变量中禁用了 cron。
  • cron: timer tick failed → 调度器 tick 崩溃；请检查相关堆栈信息或日志上下文。
  • 在运行输出中出现 reason: not-due → 手动执行时未使用 --force，且该 job 尚未到触发时间。

Cron 已触发但没有投递

  1. openclaw cron runs --id <jobId> --limit 20
  2. openclaw cron list
  3. openclaw channels status --probe
  4. openclaw logs --follow

理想输出应如下：

  • Run status 为 ok。
  • 对于 isolated jobs，delivery mode/target 已正确设置。
  • channel probe 显示目标 channel 已连接。

常见特征：

  • Run 已成功，但 delivery mode 为 none → 不会产生任何外部消息，这是预期行为。
  • delivery target 缺失或无效（channel/to）→ run 可能在内部成功，但会跳过外发。
  • channel 鉴权错误（unauthorized、missing_scope、Forbidden）→ 投递被 channel 凭证或权限阻止。

Heartbeat 被抑制或跳过

  1. openclaw system heartbeat last
  2. openclaw logs --follow
  3. openclaw config get agents.defaults.heartbeat
  4. openclaw channels status --probe

理想输出应如下：

  • Heartbeat 已启用，且 interval 非 0。
  • 最近一次 heartbeat 结果为 ran（或者 skip reason 是可理解的）。

常见特征：

  • heartbeat skipped 且 reason=quiet-hours → 当前处于 activeHours 之外。
  • requests-in-flight → 主处理通道正忙，heartbeat 被延后。
  • empty-heartbeat-file → interval heartbeat 被跳过，因为 HEARTBEAT.md 中没有可执行内容，且没有排队中的带标签 cron event。
  • alerts-disabled → 可见性设置抑制了对外 heartbeat 消息。

Timezone 和 activeHours 的常见陷阱

  1. openclaw config get agents.defaults.heartbeat.activeHours
  2. openclaw config get agents.defaults.heartbeat.activeHours.timezone
  3. openclaw config get agents.defaults.userTimezone || echo "agents.defaults.userTimezone not set"
  4. openclaw cron list
  5. openclaw logs --follow

快速规则：

  • Config path not found: agents.defaults.userTimezone 表示该 key 未设置；heartbeat 会回退到主机时区（如果设置了 activeHours.timezone，则优先使用它）。
  • 未指定 --tz 的 Cron 使用 gateway 主机时区。
  • Heartbeat 的 activeHours 使用已配置的时区解析方式（user、local 或显式 IANA tz）。
  • 不带时区信息的 ISO 时间戳，在 cron 的 at schedule 中会被视为 UTC。

常见特征：

  • 主机时区变更后，jobs 按错误的 wall-clock time 运行。
  • 在你的白天时段，heartbeat 始终被跳过，因为 activeHours.timezone 配置错误。