cronとheartbeat、どう使い分ける？ — OpenClawの定期実行ガイド

OpenClawを使っていると、「毎朝決まった時間にブリーフィングがほしい」「定期的にメールをチェックしてほしい」といった定期実行の仕組みがほしくなります。

OpenClawには、そうした定期実行を実現する方法が2つあります。cron jobとheartbeatです。この2つ、名前は聞いたことがあっても、どう使い分ければいいのかピンと来ない方も多いのではないでしょうか。

この記事では、cronとheartbeatの違いと使い分け方を、実例を交えながら解説します。

cronとheartbeat、何が違う？

cron job: 正確な時間に、決めたことを実行

cronは、指定した時刻に、決めたタスクを実行する仕組みです。

たとえば：

• 毎朝7時にニュースブリーフィングを配信
• 毎週月曜日の9時にX（旧Twitter）の下書きを生成
• 20分後にリマインダーを送る

こうした「○○時になったら△△する」という、時間ベースのタスクに向いています。

cronの特徴は以下の通りです：

• 時間が正確：指定した時刻ぴったりに実行されます
• 独立したタスク：メインセッションとは別に動かせます
• 一回きりも、繰り返しもOK：「一度だけ」も「毎日」も設定できます

heartbeat: 定期的にチェックして、必要なら反応

heartbeatは、一定間隔でエージェントに問いかけて、やることがあるか確認する仕組みです。

イメージとしては、エージェントに「何かある？」と定期的に声をかける感じです。エージェントは、その都度状況をチェックして：

• やることがあれば → 実行して報告
• 何もなければ → HEARTBEAT_OKと返して静かにする

たとえば：

• 30分おきにメールをチェック
• 1時間おきにカレンダーを確認して、近い予定があれば知らせる
• 定期的にTwitterのメンションを確認

こうした「定期的に状況を見て、何かあれば対応する」という、ポーリング型のタスクに向いています。

どう使い分ける？ 判断の基準

「いつ」が大事 → cron

タスクが時刻に紐づいているなら、cronを使います。

• 毎朝7時のブリーフィング
• 毎週月曜の9時にレポート生成
• 毎日23時に「そろそろ寝る時間」リマインダー
• 会議の15分前に通知

これらは「その時間になったら実行する」ことに意味があるので、cronが適しています。

「何か」を確認したい → heartbeat

タスクが状態のチェックなら、heartbeatを使います。

• 新着メールがあるか確認
• 近い予定があるか確認
• Twitterにメンションがあるか確認
• 天気が変わったか確認

これらは「定期的に見る」ことが目的で、多少タイミングがズレても問題ないので、heartbeatが適しています。

cronの設定方法

スケジュールの指定方法

cronのスケジュールは、3つの方法で指定できます。

1. at: 一度だけ、指定時刻に実行

schedule:
  type: at
  at: '2026-02-20T15:30:00+09:00'

「2026年2月20日15時30分（日本時間）に実行」という意味です。一度きりのリマインダーなどに使えます。

2. every: 一定間隔で繰り返し実行

schedule:
  type: every
  everyMs: 3600000  # 1時間（ミリ秒）

3. cron: cron式で柔軟に指定

schedule:
  type: cron
  cron: '0 7 * * *'
  timezone: 'Asia/Tokyo'

これは「毎日7時（日本時間）に実行」という意味です。

cron式は左から順に：

分 時 日 月 曜日

たとえば：

• 0 7 * * * → 毎日7時
• 0 9 * * 1 → 毎週月曜9時
• 30 18 * * 1-5 → 平日の18時30分
• 0 0 1 * * → 毎月1日の0時

heartbeatの設定方法

heartbeatは、設定ファイルで間隔を指定しておき、エージェントに「何をチェックするか」をHEARTBEAT.mdに書いておく形で使います。

間隔の設定

heartbeatの間隔は、エージェントの設定ファイルで指定します：

agent:
  heartbeat:
    enabled: true
    intervalMs: 1800000  # 30分（ミリ秒）
    quietHours:
      start: '23:00'
      end: '08:00'
      timezone: 'Asia/Tokyo'

ポイント：

• intervalMsで間隔を指定（ミリ秒）
• quietHoursで「静かにする時間帯」を設定できる

HEARTBEAT.mdでタスクを指定

HEARTBEAT.mdに、チェックしてほしいことを書いておきます：

# HEARTBEAT.md - 定期チェック項目

## チェック項目

以下を定期的に確認して、必要なら報告してください。

### メール
- 未読メールがあるか確認
- 重要そうなメール（仕事関係、請求書など）があれば通知
- 特に何もなければスキップ

### カレンダー
- 今後2時間以内の予定があるか確認
- あれば通知（予定名と開始時刻）
- なければスキップ

## 報告のルール

- すべてのチェックで何もなければ `HEARTBEAT_OK` だけ返す
- 何かあった項目だけ報告する
- 深夜（23:00-08:00）は緊急でない限り静かにする

まとめ: cronとheartbeatの使い分けチャート

最後に、判断チャートをまとめておきます。

• 時刻が大事 → cron
• チェックしたい → heartbeat
• 複数まとめたい → heartbeat
• 独立タスク → cron (isolated)

OpenClawのcronとheartbeat、最初は似たようなものに見えますが、使い分けが分かると、それぞれの良さが見えてきます。

cronは「時間通りに、決めたことをきっちり実行」するのが得意。朝のルーティンや定期レポートなど、時刻に紐づくタスクに向いています。

heartbeatは「定期的に様子を見て、何かあれば対応」するのが得意。メールチェックや予定確認など、ポーリング型のタスクに向いています。