Cron vs ハートビート

ハートビートとcronジョブはどちらも、スケジュールに基づいてタスクを実行できます。このガイドは、ユースケースに適したメカニズムを選択するのに役立ちます。

クイック決定ガイド

ハートビート: 定期的な確認

ハートビートは、メインセッションで定期的な間隔（デフォルト: 30分）で実行されます。エージェントが状況を確認し、重要なことを表面化させるために設計されています。

ハートビートを使用する場合

• 複数の定期的なチェック: 受信トレイ、カレンダー、天気、通知、プロジェクトステータスをそれぞれ別々の5つのcronジョブで確認する代わりに、単一のハートビートですべてをバッチ処理できます。
• コンテキストを考慮した判断: エージェントはメインセッションのコンテキストを完全に把握しているため、何が緊急で何が待てるかをスマートに判断できます。
• 会話の連続性: ハートビートの実行は同じセッションを共有するため、エージェントは最近の会話を記憶し、自然にフォローアップできます。
• オーバーヘッドの少ない監視: 1つのハートビートが多くの小さなポーリングタスクを置き換えます。

ハートビートの利点

• 複数のチェックをバッチ処理: 1回のエージェントターンで、受信トレイ、カレンダー、通知をまとめて確認できます。
• APIコールを削減: 5つの分離したcronジョブよりも、単一のハートビートの方がコストが低くなります。
• コンテキストを考慮: エージェントはあなたが取り組んできた内容を知っており、それに応じて優先順位を付けられます。
• スマートな抑制: 注意が必要なものが何もない場合、エージェントは HEARTBEAT_OK と返答し、メッセージは配信されません。
• 自然なタイミング: キューの負荷に基づいてわずかにずれることがありますが、ほとんどの監視には問題ありません。

ハートビートの例: 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

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

ハートビートの設定

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

詳細な設定については ハートビート を参照してください。

Cron: 正確なスケジューリング

Cronジョブは正確な時刻に実行され、メインコンテキストに影響を与えずに分離されたセッションで実行できます。毎時0分に繰り返されるスケジュールは、デフォルトで0〜5分のウィンドウ内でジョブごとに決定論的なオフセットによって自動的に分散されます。

Cronを使用する場合

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

Cronの利点

• 正確なタイミング: タイムゾーンサポート付きの5フィールドまたは6フィールド（秒）のcron式。
• 組み込みの負荷分散: 繰り返される毎時0分のスケジュールは、デフォルトで最大5分間隔でずらされます。
• ジョブごとの制御: --stagger <duration> でずらしを上書き、または --exact で正確なタイミングを強制。
• セッション分離: メイン履歴を汚染することなく cron:<jobId> で実行。
• モデルの上書き: ジョブごとに安価なモデルまたはより強力なモデルを使用可能。
• 配信制御: 分離ジョブはデフォルトで announce (要約) を使用。必要に応じて none を選択。
• 即時配信: アナウンスモードはハートビートを待たずに直接投稿。
• エージェントコンテキスト不要: メインセッションがアイドル状態または圧縮されていても実行。
• ワンショットサポート: 正確な将来のタイムスタンプ用の --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 AMちょうどに実行され、品質のために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.mdに追加)
  いいえ -> Cronを使用

これはワンショットリマインダーか？
  はい -> --at 付きのCronを使用
  いいえ -> 続行...

異なるモデルまたは思考レベルが必要か？
  はい -> --model/--thinking 付きのCron (分離) を使用
  いいえ -> ハートビートを使用

両方の組み合わせ

最も効率的な設定は、両方を使用します:

1. ハートビートは、30分ごとに1回のバッチ処理されたターンで、日常的な監視（受信トレイ、カレンダー、通知）を処理します。
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ジョブ (正確なタイミング):

# Daily morning briefing at 7am
openclaw cron add --name "Morning brief" --cron "0 7 * * *" --session isolated --message "..." --announce

# Weekly project review on Mondays at 9am
openclaw cron add --name "Weekly review" --cron "0 9 * * 1" --session isolated --message "..." --model opus

# One-shot reminder
openclaw cron add --name "Call back" --at "2h" --session main --system-event "Call back the client" --wake now

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

Lobsterは、決定論的な実行と明示的な承認を必要とするマルチステップのツールパイプラインのためのワークフローランタイムです。タスクが単一のエージェントターン以上であり、人間のチェックポイントを持つ再開可能なワークフローが必要な場合に使用します。

Lobsterが適合する場合

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

ハートビートおよびcronとの連携方法

• ハートビート/cronは、実行がいつ発生するかを決定します。
• Lobsterは、実行が開始された後にどのステップが発生するかを定義します。

スケジュールされたワークフローの場合は、cronまたはハートビートを使用してLobsterを呼び出すエージェントターンをトリガーします。アドホックなワークフローの場合は、Lobsterを直接呼び出します。

運用上の注意点 (コードより)

• Lobsterはツールモードでローカルサブプロセス (lobster CLI) として実行され、JSONエンベロープを返します。
• ツールが needs_approval を返した場合、resumeToken と approve フラグを使用して再開します。
• このツールはオプショナルプラグインです。 tools.alsoAllow: ["lobster"] を介して追加的に有効化します（推奨）。
• Lobsterは、lobster CLIが PATH 上で利用可能であることを期待します。

完全な使用方法と例については Lobster を参照してください。

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

ハートビートとcronはどちらもメインセッションと対話できますが、方法が異なります:

メインセッションcronを使用する場合

--session main と --system-event を使用するのは、以下の場合です:

• リマインダー/イベントをメインセッションコンテキストに表示させたい
• エージェントに次のハートビートで完全なコンテキストを持って処理させたい
• 別の分離実行をさせたくない

openclaw cron add \
  --name "Check project" \
  --every "4h" \
  --session main \
  --system-event "Time for a project health check" \
  --wake now

分離cronを使用する場合

--session isolated を使用するのは、以下の場合です:

• 以前のコンテキストのないクリーンな状態
• 異なるモデルや思考設定
• 要約を直接チャネルにアナウンス
• メインセッションを乱雑にしない履歴

openclaw cron add \
  --name "Deep analysis" \
  --cron "0 6 * * 0" \
  --session isolated \
  --message "Weekly codebase analysis..." \
  --model opus \
  --thinking high \
  --announce

コストの考慮事項

ヒント:

• トークンオーバーヘッドを最小限に抑えるために、HEARTBEAT.md を小さく保ちます。
• 複数のcronジョブの代わりに、類似のチェックをハートビートにバッチ処理します。
• 内部処理のみを希望する場合は、ハートビートで target: "none" を使用します。
• 日常的なタスクには、安価なモデルを使用した分離cronを使用します。

関連項目

• ハートビート - 完全なハートビート設定
• Cronジョブ - 完全なcron CLIおよびAPIリファレンス
• システム - システムイベント + ハートビート制御

Cronジョブ自動化トラブルシューティング