自動化のトラブルシューティング

スケジューラと配信の問題（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 がクラッシュ。周囲のスタック/ログコンテキストを確認。
実行出力に 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.md にアクション可能なコンテンツがなく、タグ付き cron イベントもキューになかったため、間隔 Heartbeat がスキップ。
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 はゲートウェイホストのタイムゾーンを使用。
Heartbeat の activeHours は設定されたタイムゾーン解決（user、local、または明示的な IANA タイムゾーン）を使用。
タイムゾーンなしの ISO タイムスタンプは cron の at スケジュールでは UTC として扱われる。

よくあるパターン:

ホストのタイムゾーン変更後、ジョブが間違った壁時計時刻に実行される。
activeHours.timezone が間違っているため、日中ずっと Heartbeat がスキップされる。