Heartbeat

Heartbeat はメインセッションで定期的なエージェントターンを実行し、煩雑な通知を送ることなく、注意が必要な事項をモデルが提示できるようにします。

Heartbeat はスケジュールされたメインセッションのターンであり、バックグラウンドタスクのレコードは作成しません。タスクレコードは、切り離された作業（ACP の実行、サブエージェント、分離された cron ジョブ）用です。

内部では、Heartbeat の実行間隔は cron スケジューラによって管理されます。Gateway は、Heartbeat が有効なエージェントごとにシステム所有の cron ジョブを 1 つ維持します（openclaw cron list --all では Heartbeat (agent-id) として表示されます）。Heartbeat 設定は望ましい状態の入力として保持される一方、永続化されたモニタースケジュールが実際の実行タイミングと、その後のランナーのクールダウンを管理します。Gateway は起動時および設定の再読み込み時に設定変更を書き込みます。openclaw doctor --fix は、次回の Gateway 起動前に欠落または古くなったモニター行を具体化できます。cron ジョブではなく、agents.*.heartbeat を編集してください。

スケジュールされた Heartbeat には cron が必要です。cron.enabled が false または OPENCLAW_SKIP_CRON=1 の場合、Gateway は起動時に警告をログに記録し、スケジュールされた Heartbeat を実行しません。手動およびイベント駆動の Heartbeat のウェイクアップは引き続き利用できます。Heartbeat 専用のフォールバックタイマーはありません。

トラブルシューティング：スケジュールされたタスク

クイックスタート（初心者向け）

設定例：

{  agents: {    defaults: {      heartbeat: {        every: "30m",        target: "last", // 最後の連絡先に明示的に配信（デフォルトは "none"）        directPolicy: "allow", // デフォルト：ダイレクト／DM ターゲットを許可。抑止するには "block" を設定        lightContext: true, // 任意：Heartbeat 実行時にワークスペースのブートストラップファイルをスキップ        isolatedSession: true, // 任意：実行ごとに新しいセッションを使用（会話履歴なし）        // activeHours: { start: "08:00", end: "24:00" },      },    },  },}

デフォルト

• 間隔：30m。解決された認証モードが OAuth／トークン（Claude CLI の再利用を含む）の場合、Anthropic プロバイダーのデフォルトを適用すると 1h に引き上げられますが、これは heartbeat.every が未設定の場合に限られます。agents.defaults.heartbeat.every またはエージェントごとの agents.entries.*.heartbeat.every を設定します。無効にするには 0m を使用します。
• プロンプト本文（agents.defaults.heartbeat.prompt で設定可能）：Follow the heartbeat monitor scratch context when provided. Recurring tasks are cron jobs; create or change their schedules with cron tools or the openclaw cron CLI, not heartbeat scratch. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.
• タイムアウト：Heartbeat ターンにタイムアウトが設定されていない場合、agents.defaults.timeoutSeconds が設定されていればそれを使用します。それ以外の場合は、最大 600 秒に制限された Heartbeat の実行間隔を使用します。より長い Heartbeat 作業には、agents.defaults.heartbeat.timeoutSeconds またはエージェントごとの agents.entries.*.heartbeat.timeoutSeconds を設定します。
• Heartbeat プロンプトは、ユーザーメッセージとしてそのまま送信されます。デフォルトエージェントで Heartbeat が有効な場合、システムプロンプトには「Heartbeats」セクションが含まれ、実行には内部的にフラグが設定されます。
• 0m で Heartbeat を無効にしても、モニターの cron ジョブは残りますが無効化され、そのスクラッチは実行間隔を再度有効にしたときのために保持されます。
• cron 自体が無効な場合、Heartbeat の実行間隔が有効なままでも、スケジュールされた Heartbeat は実行されません。
• アクティブ時間帯（heartbeat.activeHours）は、設定されたタイムゾーンで判定されます。時間帯の範囲外では、範囲内の次の実行タイミングまで Heartbeat はスキップされます。
• cron の作業が実行中またはキューにある場合、あるいはそのエージェントのセッションキーに紐づくサブエージェントまたはネストされたコマンドレーンがビジー状態の場合、Heartbeat は自動的に延期されます。兄弟エージェント同士は互いを一時停止しません。

Heartbeat プロンプトの用途

デフォルトのプロンプトは、意図的に幅広い内容になっています。

• バックグラウンドタスク：「未処理のタスクを検討する」という指示により、エージェントはフォローアップ（受信トレイ、カレンダー、リマインダー、キュー内の作業）を確認し、緊急の事項を提示するよう促されます。
• 利用者への確認：「日中は時々利用者の様子を確認する」という指示により、ときどき簡単な「何か必要ですか？」というメッセージを送るよう促されます。ただし、設定された現地タイムゾーンを使用することで夜間の煩雑な通知を避けます（タイムゾーンを参照）。

Heartbeat は完了したバックグラウンドタスクに反応できますが、Heartbeat の実行自体はタスクレコードを作成しません。

Heartbeat に非常に具体的な処理（例：「Gmail PubSub の統計情報を確認する」または「Gateway の正常性を検証する」）を実行させるには、agents.defaults.heartbeat.prompt（または agents.entries.*.heartbeat.prompt）をカスタム本文（そのまま送信されます）に設定します。

応答規約

• 注意が必要な事項がない場合は、HEARTBEAT_OK と応答します。
• Heartbeat の実行では、表示する更新がない場合は notify: false を指定して heartbeat_respond を呼び出し、アラートの場合は notificationText を指定して notify: true を呼び出すこともできます。構造化されたツール応答が存在する場合は、テキストによるフォールバックよりも優先されます。
• notify: false を伴う意味のある heartbeat_respond の結果は表示されませんが、そのセッションの次のユーザーターンに向けた限定的な内部コンテキストとして記憶されます。no_change の確認応答と表示される通知は、この方法では保存されません。
• Heartbeat の実行中、OpenClaw は HEARTBEAT_OK が応答の先頭または末尾にある場合、それを確認応答として扱います。トークンは削除され、残りの内容が 300 文字以下であれば応答は破棄されます。
• HEARTBEAT_OK が応答の途中にある場合、特別な処理は行われません。
• アラートでは HEARTBEAT_OK を含めないでください。アラートのテキストのみを返します。

Heartbeat 以外では、メッセージの先頭／末尾にある不要な HEARTBEAT_OK は削除され、ログに記録されます。HEARTBEAT_OK のみで構成されるメッセージは破棄されます。

設定

{  agents: {    defaults: {      heartbeat: {        every: "30m", // デフォルト：30m（0m で無効化）        model: "anthropic/claude-opus-4-6",        lightContext: false, // デフォルト：false。true の場合、Heartbeat 実行時にワークスペースのブートストラップファイルをスキップ        isolatedSession: false, // デフォルト：false。true の場合、Heartbeat ごとに新しいセッションで実行（会話履歴なし）        target: "last", // デフォルト：none | 選択肢：last | none | <channel id>（コアまたは Plugin、例："imessage"）        to: "+15551234567", // 任意のチャンネル固有オーバーライド        accountId: "ops-bot", // 任意のマルチアカウントチャンネル ID        prompt: "Heartbeat モニターのスクラッチコンテキストが提供されている場合は、それに従ってください。定期タスクは cron ジョブです。そのスケジュールの作成または変更には、Heartbeat のスクラッチではなく、cron ツールまたは openclaw cron CLI を使用してください。以前のチャットから古いタスクを推測したり繰り返したりしないでください。注意が必要な事項がない場合は、HEARTBEAT_OK と応答してください。",      },    },  },}

適用範囲と優先順位

• agents.defaults.heartbeat はグローバルな Heartbeat の動作を設定します。
• agents.entries.*.heartbeat はその上にマージされます。いずれかのエージェントに heartbeat ブロックがある場合、それらのエージェントのみが Heartbeat を実行します。
• channels.defaults.heartbeatVisibility はすべてのチャンネルの表示設定のデフォルトを設定します。
• channels.<channel>.heartbeatVisibility はチャンネルのデフォルトをオーバーライドします。
• channels.<channel>.accounts.<id>.heartbeatVisibility（マルチアカウントチャンネル）は、チャンネルごとの設定をオーバーライドします。

エージェントごとの Heartbeat

いずれかの agents.entries.* エントリに heartbeat ブロックが含まれている場合、それらのエージェントのみが Heartbeat を実行します。エージェントごとのブロックは agents.defaults.heartbeat の上にマージされます（共有デフォルトを一度設定し、エージェントごとにオーバーライドできます）。

例：2 つのエージェントのうち、2 番目のエージェントのみが Heartbeat を実行します。

{  agents: {    defaults: {      heartbeat: {        every: "30m",        target: "last", // 最後の連絡先に明示的に配信（デフォルトは "none"）      },    },    list: [      { id: "main", default: true },      {        id: "ops",        heartbeat: {          every: "1h",          target: "whatsapp",          to: "+15551234567",          timeoutSeconds: 45,          prompt: "Heartbeat モニターのスクラッチコンテキストが提供されている場合は、それに従ってください。定期タスクは cron ジョブです。そのスケジュールの作成または変更には、Heartbeat のスクラッチではなく、cron ツールまたは openclaw cron CLI を使用してください。以前のチャットから古いタスクを推測したり繰り返したりしないでください。注意が必要な事項がない場合は、HEARTBEAT_OK と応答してください。",        },      },    ],  },}

アクティブ時間帯の例

特定のタイムゾーンの営業時間内に Heartbeat を制限します。

{  agents: {    defaults: {      heartbeat: {        every: "30m",        target: "last", // 最後の連絡先に明示的に配信（デフォルトは "none"）        activeHours: {          start: "09:00",          end: "22:00",          timezone: "America/New_York", // 任意。設定されている場合は userTimezone を使用し、それ以外の場合はホストのタイムゾーンを使用        },      },    },  },}

この時間帯の範囲外（東部時間の午前 9 時より前、または午後 10 時より後）では、Heartbeat はスキップされます。範囲内の次のスケジュールされた実行タイミングでは、通常どおり実行されます。

24/7 の設定

Heartbeat を終日実行するには、次のいずれかのパターンを使用します。

• activeHours を完全に省略します（時間帯による制限なし。これがデフォルトの動作です）。
• 終日の時間帯を設定します：activeHours: { start: "00:00", end: "24:00" }。

マルチアカウントの例

Telegram などのマルチアカウントチャンネルで特定のアカウントを対象にするには、accountId を使用します。

{  agents: {    list: [      {        id: "ops",        heartbeat: {          every: "1h",          target: "telegram",          to: "12345678:topic:42", // 任意：特定のトピック／スレッドにルーティング          accountId: "ops-bot",        },      },    ],  },  channels: {    telegram: {      accounts: {        "ops-bot": { botToken: "YOUR_TELEGRAM_BOT_TOKEN" },      },    },  },}

フィールドの注記

配信動作

表示制御

デフォルトでは、アラート内容が配信される一方で、HEARTBEAT_OK の確認応答は抑止されます。これはチャネルごと、またはアカウントごとに調整できます。

channels:  defaults:    heartbeat:      showOk: false # HEARTBEAT_OK を非表示（デフォルト）      showAlerts: true # アラートメッセージを表示（デフォルト）      useIndicator: true # インジケーターイベントを生成（デフォルト）  telegram:    heartbeat:      showOk: true # Telegram で OK の確認応答を表示  whatsapp:    accounts:      work:        heartbeat:          showAlerts: false # このアカウントへのアラート配信を抑止

優先順位: アカウントごと → チャネルごと → チャネルのデフォルト → 組み込みのデフォルト。

各フラグの動作

• showOk: モデルが OK のみの応答を返したとき、HEARTBEAT_OK の確認応答を送信します。
• showAlerts: モデルが OK 以外の応答を返したとき、アラート内容を送信します。
• useIndicator: UI のステータス表示用にインジケーターイベントを生成します。

3 つすべてが false の場合、OpenClaw は Heartbeat の実行を完全にスキップします（モデルの呼び出しもありません）。

チャネルごととアカウントごとの例

channels:  defaults:    heartbeat:      showOk: false      showAlerts: true      useIndicator: true  slack:    heartbeat:      showOk: true # すべての Slack アカウント    accounts:      ops:        heartbeat:          showAlerts: false # ops アカウントのアラートのみを抑止  telegram:    heartbeat:      showOk: true

一般的なパターン

モニターのスクラッチ（任意）

各 Heartbeat モニターの Cron ジョブは、共有状態データベースに保存される非公開のスクラッチ文書を所有します。これは「Heartbeat チェックリスト」と考えてください。小さく安定しており、30 分ごとに確認しても安全な内容にします。スクラッチが存在する場合、その内容が Heartbeat のプロンプトに追加されます。

Cron CLI で管理します（ジョブ ID は openclaw cron list --all から取得します）。

openclaw cron scratch <jobId>                 # 現在のスクラッチを表示openclaw cron scratch <jobId> --set "..."     # 正確なテキストで置き換えopenclaw cron scratch <jobId> --file notes.md # ファイルから置き換え（標準入力には -）openclaw cron scratch <jobId> --unset         # 削除

書き込みは compare-and-swap で保護されています。同時編集を上書きせず失敗させるには、--expected-revision <n> を渡します。スクラッチの上限は 256 KiB で、cron list/cron runs の出力には表示されません。

エージェントは自身のスクラッチも更新できます。Heartbeat ターン中、heartbeat_respond は任意の scratch 文字列を受け取り、以降の Heartbeat で使用するモニターのスクラッチを完全に置き換えます。

スクラッチが存在しても実質的に空の場合（空行、Markdown/HTML コメント、# Heading のような Markdown 見出し、フェンスマーカー、または空のチェックリストのひな形のみ）、OpenClaw は API 呼び出しを節約するため Heartbeat の実行をスキップします。このスキップは reason=empty-heartbeat-file として報告されます。スクラッチが存在しない場合でも Heartbeat は実行され、何を行うかはモデルが判断します。

プロンプトの肥大化を避けるため、短いチェックリストやリマインダーだけにしておきます。

スクラッチの例:

# Heartbeat チェックリスト - 簡単に確認: 受信トレイに緊急のものはあるか？- 日中で、ほかに保留中のものがなければ、簡単な状況確認を行う。- タスクがブロックされている場合は、_不足しているもの_を書き留め、次回 Peter に尋ねる。

Cron で定期チェックをスケジュールする

Heartbeat のスクラッチはプロンプトのコンテキストであり、スケジューラーではありません。各定期チェックを Cron ジョブとして作成すると、独自の実行間隔、有効/無効状態、実行履歴を持たせることができます。通常の会話コンテキストを使用する必要があるチェックでは、Cron ジョブの対象を引き続きメインセッションにできます。

古いスクラッチには、構造化された tasks: ブロックが含まれている場合があります。アップグレード後に openclaw doctor --fix を 1 回実行してください。Doctor は有効な各エントリを個別にスケジュールされた Cron ジョブへ変換し、その間隔と以前の最終実行時刻を保持し、周囲のスクラッチ本文を残したまま廃止されたブロックを削除します。実行時の Heartbeat ターンは、tasks: のテキストをスケジュールとして解析しません。

Doctor が作成した Heartbeat タスクジョブでは、Heartbeat の有効時間帯、クールダウン、過剰実行防止、ビジー状態のガードが維持されます。同時に期限を迎えたジョブは、1 回の Heartbeat ターンにまとめられる場合があります。有効時間帯の範囲外にある実行回はスキップされ、次の Cron 実行時に再試行されます。

エージェントはスクラッチを更新できますか？

はい。Heartbeat ターン中、エージェントは heartbeat_respond に scratch の値を渡し、以降の Heartbeat で使用するモニター本文を完全に置き換えることができます。通常のチャットで openclaw cron scratch <jobId> --set ... を実行するよう依頼するか、同じコマンドを使用して自身でスクラッチを編集することもできます。スクラッチにスケジューラー構文を書くのではなく、定期スケジュールは Cron で管理してください。

手動起動（オンデマンド）

openclaw system event を使用してシステムイベントをキューに追加し、必要に応じて Heartbeat を即座にトリガーします。

openclaw system event --text "緊急のフォローアップを確認" --mode now

--session-key が指定されておらず、複数のエージェントに heartbeat が設定されている場合、--mode now はそれらの各エージェントの Heartbeat を即座に実行します。

同じ CLI グループ内の関連する Heartbeat 制御：

openclaw system heartbeat last     # 最後の Heartbeat イベントを表示openclaw system heartbeat enable   # Heartbeat を有効化openclaw system heartbeat disable  # Heartbeat を無効化

コストへの配慮

Heartbeat はエージェントの完全なターンを実行します。間隔を短くすると、より多くのトークンを消費します。コストを削減するには：

• 会話履歴全体の送信を避けるため、isolatedSession: true を使用します（実行ごとに約 100K トークンから約 2～5K トークンに削減）。
• Heartbeat の実行時にワークスペースのブートストラップファイルを省略するには、lightContext: true を使用します。
• より安価な model を設定します（例：ollama/llama3.2:1b）。
• モニターのスクラッチ領域を小さく保ちます。
• 内部状態の更新のみが必要な場合は、target: "none" を使用します。

Heartbeat 後のコンテキストオーバーフロー

Heartbeat の実行完了後も、共有セッションの既存のランタイムモデルは維持されます。そのため、Heartbeat によってセッションがより小さなローカルモデル（たとえば、32k ウィンドウの Ollama モデル）に切り替わると、次のメインセッションのターンでもそのモデルが使用される場合があります。その次のターンでコンテキストオーバーフローが報告され、セッションの最後のランタイムモデルが設定済みの heartbeat.model と一致する場合、OpenClaw の復旧メッセージは Heartbeat モデルの持ち越しが原因である可能性を示し、修正方法を提案します。

これを回避するには、isolatedSession: true を使用して新しいセッションで Heartbeat を実行するか（最小のプロンプトにするため、必要に応じて lightContext: true と組み合わせます）、共有セッションに十分な大きさのコンテキストウィンドウを持つ Heartbeat モデルを選択します。

関連項目

• 自動化 - すべての自動化メカニズムの概要
• バックグラウンドタスク - 分離された処理を追跡する方法
• タイムゾーン - タイムゾーンが Heartbeat のスケジュールに与える影響
• トラブルシューティング - 自動化に関する問題のデバッグ方法