Cron と Heartbeat

​

まずはこれで判断する

​

Heartbeat: 定期的な状況確認

​

Heartbeat が向いている場面

• 複数の定期チェック: 受信トレイ、カレンダー、天気、通知、プロジェクト状況を 5 つの別々の cron ジョブで監視する代わりに、1 つの heartbeat でまとめて処理できます。
• コンテキストを踏まえた判断: エージェントはメインセッションの完全なコンテキストを持っているため、何が急ぎで何が後回しでよいかを賢く判断できます。
• 会話の連続性: Heartbeat 実行は同じセッションを共有するため、エージェントは最近の会話を覚えており、自然にフォローアップできます。
• 低オーバーヘッドな監視: 1 つの heartbeat で、多数の小さなポーリングタスクを置き換えられます。

​

Heartbeat の利点

• 複数チェックをまとめて実行: 1 回のエージェントターンで、受信トレイ、カレンダー、通知をまとめて確認できます。
• API 呼び出しを削減: heartbeat 1 回の方が、独立した cron ジョブを 5 本動かすより安価です。
• コンテキストを考慮できる: いま何に取り組んでいるかをエージェントが理解しており、優先度を判断できます。
• 賢い抑制: 注意すべきことが何もなければ、エージェントは HEARTBEAT_OK を返し、メッセージは配信されません。
• 自然なタイミング: キューの負荷に応じて多少ずれますが、多くの監視用途では問題ありません。

​

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

# Heartbeat checklist

- 緊急のメールがないか確認する
- 今後 2 時間以内の予定をカレンダーで確認する
- バックグラウンドタスクが完了していれば結果を要約する
- 8 時間以上静かな状態が続いていれば短い確認メッセージを送る

​

Heartbeat の設定例

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

​

Cron: 正確な時刻での実行

​

Cron が向いている場面

• 正確な時刻が必要: 「毎週月曜の午前 9:00 に送る」のように、「9 時前後」でなく正確な実行時刻が必要な場合。
• 単独タスク: 会話コンテキストを必要としないタスク。
• 異なるモデル / thinking: より高性能なモデルを使う価値がある重い分析。
• ワンショットのリマインダー: --at を使った「20 分後に知らせて」。
• 頻繁でノイズが多いタスク: メインセッションの履歴を散らかしたくないタスク。
• 外部トリガー: エージェントがほかに動いているかどうかに関係なく、独立して実行されるべきタスク。

​

Cron の利点

• 正確な時刻指定: タイムゾーン対応の 5 フィールドまたは 6 フィールド（秒付き）の cron 式を使えます。
• 負荷分散を内蔵: 毎時ちょうどの繰り返しスケジュールは、デフォルトで最大 5 分ずらして実行されます。
• ジョブ単位の制御: --stagger <duration> で分散を上書きするか、--exact で厳密な時刻実行を強制できます。
• セッション分離: cron:<jobId> で実行され、メイン履歴を汚しません。
• モデルの上書き: ジョブごとに、より安価なモデルや高性能なモデルを指定できます。
• 配信制御: 独立ジョブのデフォルトは announce（要約配信）で、必要に応じて none も選べます。
• 即時配信: announce モードでは heartbeat を待たずに直接投稿されます。
• エージェントのコンテキストが不要: メインセッションがアイドル状態でも compact 済みでも実行できます。
• ワンショット対応: --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"

​

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

​

判断フローチャート

そのタスクは「正確な時刻」に実行する必要がありますか？
  YES -> cron を使う
  NO  -> 次へ

メインセッションから分離して実行する必要がありますか？
  YES -> cron（isolated）を使う
  NO  -> 次へ

そのタスクは他の定期チェックとまとめて実行できますか？
  YES -> heartbeat を使う（`HEARTBEAT.md` に追加）
  NO  -> cron を使う

ワンショットのリマインダーですか？
  YES -> `--at` 付きの cron を使う
  NO  -> 次へ

別の model や thinking level が必要ですか？
  YES -> `--model` / `--thinking` 付きの cron（isolated）を使う
  NO  -> heartbeat を使う

​

両方を組み合わせる

1. Heartbeat は、受信トレイ、カレンダー、通知などの日常的な監視を、30 分ごとに 1 回のバッチ処理で行います。
2. Cron は、毎日のレポートや週次レビューのような正確なスケジュールと、ワンショットのリマインダーを担当します。

​

例: 効率的な自動化構成

# Heartbeat checklist

- 緊急のメールがないか受信トレイを確認する
- 今後 2 時間以内の予定をカレンダーで確認する
- 保留中のタスクを見直す
- 8 時間以上静かな状態が続いていれば軽く確認する

# 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 が適している場面

• 複数ステップの自動化: 単発プロンプトではなく、ツール呼び出しの固定パイプラインが必要。
• 承認ゲート: 副作用を伴う処理を一時停止し、承認後に再開したい。
• 再開可能な実行: 以前のステップをやり直さず、一時停止したワークフローを続行したい。

​

Heartbeat / cron との関係

• Heartbeat / cron は、実行が いつ 起きるかを決めます。
• Lobster は、実行開始後に どの手順 を踏むかを定義します。

​

運用上のメモ（コードベース準拠）

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

​

メインセッションと独立セッション

​

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

• リマインダーやイベントをメインセッションのコンテキストに表示したい
• エージェントに次の heartbeat で完全なコンテキストを使って処理させたい
• 別の独立実行は不要

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

​

独立 cron を使う場面

• 事前コンテキストなしのクリーンな状態で始めたい
• 異なるモデルや thinking 設定を使いたい
• 要約をチャンネルに直接 announce したい
• メインセッションを履歴で埋めたくない

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

​

コストに関する考慮点

• トークンオーバーヘッドを抑えるため、HEARTBEAT.md は小さく保ってください。
• 似たチェックは複数の cron ジョブに分けず、heartbeat にまとめてください。
• 内部処理だけが必要なら、heartbeat で target: "none" を使ってください。
• 定常タスクには、より安価なモデルを指定した独立 cron を使ってください。

​

関連

• Heartbeat - heartbeat 設定の詳細
• Cron jobs - cron CLI / API リファレンスの詳細
• System - system event と heartbeat 制御