自動化疑難排解

排程與投遞問題（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

Cron 沒有觸發

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 當掉了；查看周圍的堆疊/日誌上下文。
run 輸出中出現 reason: not-due -> 手動執行時未加 --force 且排程尚未到期。

Cron 觸發了但沒有投遞

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） -> 投遞被頻道憑證/權限阻擋。

Heartbeat 被抑制或跳過

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 常見問題

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 時區）。
未帶時區的 ISO 時間戳在 cron at 排程中視為 UTC。

常見特徵：

主機時區變更後，排程在錯誤的當地時間執行。
Heartbeat 在你的白天時段總是被跳過，因為 activeHours.timezone 設定錯誤。

相關文件：