> ## Documentation Index
> Fetch the complete documentation index at: https://openclawdoc.org/llms.txt
> Use this file to discover all available pages before exploring further.

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

> このページは、スケジューラーと配信まわり（cron + heartbeat）の問題を切り分けるためのものです。確認コマンドの順番、cron が動かない、cron は動いたが配信されないを確認できます。

このページは、スケジューラーと配信まわり（`cron` + `heartbeat`）の問題を切り分けるためのものです。

## 確認コマンドの順番

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe
```

続けて、自動化まわりのチェックを実行します。

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw cron status
openclaw cron list
openclaw system heartbeat last
```

## cron が動かない

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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 theme={"theme":{"light":"min-light","dark":"min-dark"}}
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 が抑制またはスキップされる

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw system heartbeat last
openclaw logs --follow
openclaw config get agents.defaults.heartbeat
openclaw channels status --probe
```

期待する状態は次のとおりです。

* heartbeat が 0 以外の間隔で有効になっている。
* 最後の heartbeat 結果が `ran` である、またはスキップ理由を説明できる。

よくある兆候:

* `heartbeat skipped` と `reason=quiet-hours` が出る → `activeHours` の時間外です。
* `requests-in-flight` → メインレーンがビジーのため、heartbeat が延期されています。
* `empty-heartbeat-file` → `HEARTBEAT.md` に実行可能な内容がなく、タグ付き cron イベントもキューにないため、定期 heartbeat がスキップされています。
* `alerts-disabled` → 表示設定により外向きの heartbeat メッセージが抑制されています。

## タイムゾーンと activeHours の落とし穴

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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 tz）を使います。
* タイムゾーンを含まない ISO タイムスタンプは、cron の `at` スケジュールでは UTC として扱われます。

よくある兆候:

* ホストのタイムゾーン変更後に、ジョブが意図しない時刻で実行される。
* `activeHours.timezone` が誤っているため、日中なのに heartbeat が常にスキップされる。

関連ドキュメント:

* [/automation/cron-jobs](/automation/cron-jobs)
* [/gateway/heartbeat](/gateway/heartbeat)
* [/automation/cron-vs-heartbeat](/automation/cron-vs-heartbeat)
* [/concepts/timezone](/concepts/timezone)