Cron vs Heartbeat: 使い分けガイド

Heartbeat と Cron ジョブはどちらもタスクをスケジュール実行できます。このガイドでは、用途に合った仕組みの選び方を解説します。

早見表

ユースケース推奨理由
30 分ごとに受信トレイをチェックHeartbeat他のチェックと一括処理でき、コンテキストを考慮
毎朝 9 時きっかりにレポート送信Cron（分離）正確なタイミングが必要
カレンダーの予定を監視Heartbeat定期的な気づきに自然にフィット
週次の詳細分析を実行Cron（分離）独立したタスクで、別のモデルも使用可能
20 分後にリマインドCron（メイン、--at）正確なタイミングのワンショット
バックグラウンドのプロジェクトヘルスチェックHeartbeat既存のサイクルに便乗

Heartbeat: 定期的な気づき

Heartbeat は一定間隔（デフォルト: 30 分）でメインセッション内で実行されます。エージェントが状況を確認し、重要なことがあれば通知するための仕組みです。

Heartbeat が適している場面

  • 複数の定期チェック: 受信トレイ、カレンダー、天気、通知、プロジェクトステータスなどの 5 つの個別 Cron ジョブの代わりに、1 つの Heartbeat でまとめて処理。
  • コンテキストを考慮した判断: エージェントがメインセッションのコンテキストを持っているため、緊急度の判断を的確に行える。
  • 会話の連続性: Heartbeat は同じセッションで実行されるため、最近の会話を覚えており自然にフォローアップ可能。
  • 低コストの監視: 1 つの Heartbeat で多数の小さなポーリングタスクを代替。

Heartbeat の利点

  • 複数チェックの一括処理: 1 回のエージェントターンで受信トレイ、カレンダー、通知をまとめて確認。
  • API 呼び出しの削減: 5 つの分離 Cron ジョブより 1 つの Heartbeat のほうが安価。
  • コンテキスト認識: 作業中の内容を把握しているため、優先順位付けが的確。
  • スマートな抑制: 注意が必要なことがなければ HEARTBEAT_OK で応答し、メッセージは配信されない。
  • 自然なタイミング: キュー負荷に応じてわずかにずれるが、大半の監視には十分。

Heartbeat の例: HEARTBEAT.md チェックリスト

# Heartbeat checklist

- Check email for urgent messages
- Review calendar for events in next 2 hours
- If a background task finished, summarize results
- If idle for 8+ hours, send a brief check-in

エージェントは各 Heartbeat 時にこれを読み、すべての項目を 1 ターンで処理します。

Heartbeat の設定

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // 間隔
        target: "last", // 明示的なアラート配信先（デフォルトは "none"）
        activeHours: { start: "08:00", end: "22:00" }, // オプション
      },
    },
  },
}

詳細は Heartbeat を参照。

Cron: 精密なスケジューリング

Cron ジョブは正確な時刻に実行でき、メインコンテキストに影響を与えない分離セッションで実行できます。 繰り返しの正時スケジュールは、ジョブごとに決定論的なオフセットにより 0〜5 分の範囲で自動的に分散されます。

Cron が適している場面

  • 正確なタイミングが必要: 「毎週月曜 9:00 AM にこれを送信」（「9 時頃」ではなく）。
  • 独立したタスク: 会話コンテキストが不要なタスク。
  • 異なるモデル/思考レベル: より強力なモデルを必要とする重い分析。
  • ワンショットのリマインダー: --at で「20 分後にリマインド」。
  • ノイジー/高頻度のタスク: メインセッション履歴を散らかすタスク。
  • 外部トリガー: エージェントのアクティブ状態に関係なく独立して実行すべきタスク。

Cron の利点

  • 精密なタイミング: タイムゾーンサポート付きの 5 フィールドまたは 6 フィールド（秒）cron 式。
  • 組み込みの負荷分散: 繰り返しの正時スケジュールはデフォルトで最大 5 分ずらされる。
  • ジョブ単位の制御: --stagger <duration> でずらしをオーバーライドするか、--exact で正確なタイミングを強制。
  • セッション分離: cron:<jobId> で実行しメイン履歴を汚さない。
  • モデルオーバーライド: ジョブごとに安価または強力なモデルを使用。
  • 配信制御: 分離ジョブはデフォルトで announce（サマリー）。必要に応じて none を選択。
  • 即時配信: announce モードは Heartbeat を待たずに直接投稿。
  • エージェントコンテキスト不要: メインセッションがアイドルやコンパクション済みでも実行可能。
  • ワンショット対応: --at で将来の正確なタイムスタンプを指定。

Cron の例: 毎朝のブリーフィング

openclaw cron add \
  --name "Morning briefing" \
  --cron "0 7 * * *" \
  --tz "America/New_York" \
  --session isolated \
  --message "Generate today's briefing: weather, calendar, top emails, news summary." \
  --model opus \
  --announce \
  --channel whatsapp \
  --to "+15551234567"

ニューヨーク時間の午前 7:00 に正確に実行し、高品質な結果のために Opus を使用、サマリーを WhatsApp に直接通知します。

Cron の例: ワンショットのリマインダー

openclaw cron add \
  --name "Meeting reminder" \
  --at "20m" \
  --session main \
  --system-event "Reminder: standup meeting starts in 10 minutes." \
  --wake now \
  --delete-after-run

CLI の完全なリファレンスは Cron ジョブ を参照。

判断フローチャート

タスクを正確な時刻に実行する必要がある？
  はい -> Cron を使用
  いいえ -> 次へ...

メインセッションからの分離が必要？
  はい -> Cron（分離）を使用
  いいえ -> 次へ...

他の定期チェックと一括処理できる？
  はい -> Heartbeat を使用（HEARTBEAT.md に追加）
  いいえ -> Cron を使用

ワンショットのリマインダー？
  はい -> Cron の --at を使用
  いいえ -> 次へ...

異なるモデルや思考レベルが必要？
  はい -> Cron（分離）の --model/--thinking を使用
  いいえ -> Heartbeat を使用

両方の併用

最も効率的な構成は両方を使うことです:

  1. Heartbeat が定期的な監視（受信トレイ、カレンダー、通知）を 30 分ごとに一括処理。
  2. Cron が正確なスケジュール（日次レポート、週次レビュー）とワンショットのリマインダーを担当。

例: 効率的な自動化構成

HEARTBEAT.md（30 分ごとにチェック）:

# Heartbeat checklist

- Scan inbox for urgent emails
- Check calendar for events in next 2h
- Review any pending tasks
- Light check-in if quiet for 8+ hours

Cron ジョブ（精密なタイミング）:

# 毎朝 7 時のブリーフィング
openclaw cron add --name "Morning brief" --cron "0 7 * * *" --session isolated --message "..." --announce

# 毎週月曜 9 時のプロジェクトレビュー
openclaw cron add --name "Weekly review" --cron "0 9 * * 1" --session isolated --message "..." --model opus

# ワンショットのリマインダー
openclaw cron add --name "Call back" --at "2h" --session main --system-event "Call back the client" --wake now

Lobster: 承認付きの決定論的ワークフロー

Lobster は、決定論的な実行と明示的な承認を必要とするマルチステップのツールパイプライン向けのワークフローランタイムです。 タスクが 1 回のエージェントターンを超え、人間によるチェックポイント付きの再開可能なワークフローが必要な場合に使用してください。

Lobster が適している場面

  • マルチステップの自動化: 単発のプロンプトではなく、固定されたツールコールのパイプラインが必要な場合。
  • 承認ゲート: 副作用のある処理を承認まで一時停止し、承認後に再開したい場合。
  • 再開可能な実行: 以前のステップを再実行せずに、一時停止したワークフローを続行したい場合。

Heartbeat や Cron との組み合わせ

  • Heartbeat/Cron は実行の_タイミング_を決定。
  • Lobster は実行開始後の_ステップ_を定義。

スケジュールされたワークフローには、Cron や Heartbeat で Lobster を呼び出すエージェントターンをトリガーします。 アドホックなワークフローでは Lobster を直接呼び出してください。

運用メモ（コードより）

  • Lobster はローカルサブプロセス（lobster CLI）としてツールモードで実行され、JSON エンベロープを返します。
  • ツールが needs_approval を返した場合、resumeToken と approve フラグで再開します。
  • このツールはオプションのプラグインです。tools.alsoAllow: ["lobster"] で有効化してください（推奨）。
  • Lobster は lobster CLI が PATH 上にあることを前提としています。

詳細は Lobster を参照。

メインセッション vs 分離セッション

Heartbeat と Cron のどちらもメインセッションとやり取りできますが、方法が異なります:

HeartbeatCron（メイン）Cron（分離）
セッションメインメイン（システムイベント経由）cron:<jobId>
履歴共有共有毎回新規
コンテキストフルフルなし（クリーンスタート）
モデルメインセッションのモデルメインセッションのモデルオーバーライド可能
出力HEARTBEAT_OK 以外は配信Heartbeat プロンプト＋イベントannounce サマリー（デフォルト）

メインセッション Cron を使う場面

--session main と --system-event は以下の場合に使用:

  • リマインダー/イベントをメインセッションのコンテキストに表示したい
  • エージェントがフルコンテキストで次の Heartbeat 時に処理してほしい
  • 個別の分離実行が不要
openclaw cron add \
  --name "Check project" \
  --every "4h" \
  --session main \
  --system-event "Time for a project health check" \
  --wake now

分離 Cron を使う場面

--session isolated は以下の場合に使用:

  • 過去のコンテキストなしのクリーンな状態で実行したい
  • 異なるモデルや思考レベルの設定が必要
  • チャネルに announce サマリーを直接配信したい
  • メインセッションの履歴を散らかしたくない
openclaw cron add \
  --name "Deep analysis" \
  --cron "0 6 * * 0" \
  --session isolated \
  --message "Weekly codebase analysis..." \
  --model opus \
  --thinking high \
  --announce

コストの考慮

仕組みコスト特性
HeartbeatN 分ごとに 1 ターン。HEARTBEAT.md のサイズに比例
Cron（メイン）次の Heartbeat にイベントを追加（分離ターンなし）
Cron（分離）ジョブごとにフルエージェントターン。安価なモデルも使用可能

ヒント:

  • HEARTBEAT.md を小さく保ち、トークンオーバーヘッドを最小化。
  • 類似のチェックは複数の Cron ジョブではなく Heartbeat にまとめる。
  • 内部処理のみが必要な場合は Heartbeat で target: "none" を使用。
  • 定型タスクには安価なモデルで分離 Cron を使用。

関連ドキュメント

  • Heartbeat - Heartbeat の完全な設定
  • Cron ジョブ - Cron CLI と API の完全なリファレンス
  • System - システムイベントと Heartbeat の制御
arrow_back
前へ
Cron Jobs
次へ
Troubleshooting
arrow_forward