Heartbeat

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

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

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

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

設定例：

{  agents: {    defaults: {      heartbeat: {        every: "30m",        target: "last", // explicit delivery to last contact (default is "none")        directPolicy: "allow", // default: allow direct/DM targets; set "block" to suppress        lightContext: true, // optional: only inject HEARTBEAT.md from bootstrap files        isolatedSession: true, // optional: fresh session each run (no conversation history)        skipWhenBusy: true, // optional: also defer when this agent's subagent or nested lanes are busy        // activeHours: { start: "08:00", end: "24:00" },        // includeReasoning: true, // optional: send separate `Thinking` message too      },    },  },}

デフォルト

• 間隔：30m。Anthropic プロバイダーのデフォルトを適用すると、解決された認証モードが OAuth/トークン（Claude CLI の再利用を含む）の場合は 1h に引き上げられますが、これは heartbeat.every が未設定の場合に限られます。agents.defaults.heartbeat.every またはエージェントごとの agents.list[].heartbeat.every を設定してください。無効にするには 0m を使用します。
• プロンプト本文（agents.defaults.heartbeat.prompt で設定可能）：Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.
• タイムアウト：Heartbeat ターンで未設定の場合、agents.defaults.timeoutSeconds が設定されていればその値を使用します。それ以外の場合は、Heartbeat の実行間隔を使用し、上限を 600 秒とします。より長い Heartbeat 作業には、agents.defaults.heartbeat.timeoutSeconds またはエージェントごとの agents.list[].heartbeat.timeoutSeconds を設定します。
• Heartbeat プロンプトは、ユーザーメッセージとしてそのまま送信されます。システムプロンプトに「Heartbeat」セクションが含まれるのは、デフォルトエージェントで Heartbeat が有効になっており（かつ includeSystemPromptSection が false ではない）、実行に内部フラグが設定されている場合だけです。
• 0m で Heartbeat を無効にすると、通常の実行でもブートストラップコンテキストから HEARTBEAT.md が除外されるため、モデルは Heartbeat 専用の指示を参照しません。
• 稼働時間帯（heartbeat.activeHours）は、設定されたタイムゾーンで確認されます。時間帯の範囲外では、範囲内の次の実行時刻まで Heartbeat がスキップされます。
• Cron 作業が実行中またはキューに入っている間、Heartbeat は自動的に延期されます。エージェント自身のセッションキーに紐づくサブエージェントまたはネストされたコマンドレーンでも延期するには、heartbeat.skipWhenBusy: true を設定します。別のエージェントでサブエージェント作業が進行中というだけでは、兄弟エージェントは一時停止しなくなりました。

Heartbeat プロンプトの用途

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

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

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

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

応答規約

• 注意が必要な事項がない場合は、HEARTBEAT_OK と応答します。
• Heartbeat の実行では、代わりに heartbeat_respond を呼び出せます。表示される更新が不要な場合は notify: false、アラートを送信する場合は notify: true と notificationText を指定します。構造化されたツール応答が存在する場合は、テキストのフォールバックより優先されます。
• Heartbeat の実行中、OpenClaw は応答の先頭または末尾にある HEARTBEAT_OK を確認応答として扱います。このトークンは削除され、残りの内容が ackMaxChars 以下（デフォルト：300）の場合、応答は破棄されます。
• HEARTBEAT_OK が応答の途中にある場合、特別な扱いは行われません。
• アラートの場合は、HEARTBEAT_OK を含めてはいけません。アラート本文だけを返します。

Heartbeat 以外では、メッセージの先頭または末尾に意図せず含まれた HEARTBEAT_OK は削除され、ログに記録されます。HEARTBEAT_OK だけのメッセージは破棄されます。

設定

{  agents: {    defaults: {      heartbeat: {        every: "30m", // default: 30m (0m disables)        model: "anthropic/claude-opus-4-6",        includeReasoning: false, // default: false (deliver separate Thinking message when available)        lightContext: false, // default: false; true keeps only HEARTBEAT.md from workspace bootstrap files        isolatedSession: false, // default: false; true runs each heartbeat in a fresh session (no conversation history)        skipWhenBusy: false, // default: false; true also waits for this agent's subagent/nested lanes        target: "last", // default: none | options: last | none | <channel id> (core or plugin, e.g. "imessage")        to: "+15551234567", // optional channel-specific override        accountId: "ops-bot", // optional multi-account channel id        prompt: "Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.",        includeSystemPromptSection: true, // default: true; false omits the ## Heartbeats system prompt section for the default agent        ackMaxChars: 300, // max chars allowed after HEARTBEAT_OK      },    },  },}

適用範囲と優先順位

• agents.defaults.heartbeat は、Heartbeat のグローバルな動作を設定します。
• agents.list[].heartbeat は、その上にマージされます。いずれかのエージェントに heartbeat ブロックがある場合、Heartbeat を実行するのはそれらのエージェントだけです。
• channels.defaults.heartbeat は、すべてのチャンネルの表示に関するデフォルトを設定します。
• channels.<channel>.heartbeat は、チャンネルのデフォルトを上書きします。
• channels.<channel>.accounts.<id>.heartbeat（複数アカウント対応チャンネル）は、チャンネルごとの設定を上書きします。

エージェントごとの Heartbeat

いずれかの agents.list[] エントリに heartbeat ブロックが含まれる場合、Heartbeat を実行するのはそれらのエージェントだけです。エージェントごとのブロックは agents.defaults.heartbeat の上にマージされます（共有のデフォルトを一度設定し、エージェントごとに上書きできます）。

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

{  agents: {    defaults: {      heartbeat: {        every: "30m",        target: "last", // explicit delivery to last contact (default is "none")      },    },    list: [      { id: "main", default: true },      {        id: "ops",        heartbeat: {          every: "1h",          target: "whatsapp",          to: "+15551234567",          timeoutSeconds: 45,          prompt: "Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.",        },      },    ],  },}

稼働時間帯の例

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

{  agents: {    defaults: {      heartbeat: {        every: "30m",        target: "last", // explicit delivery to last contact (default is "none")        activeHours: {          start: "09:00",          end: "22:00",          timezone: "America/New_York", // optional; uses your userTimezone if set, otherwise host tz        },      },    },  },}

この時間帯の範囲外（米国東部時間の午前 9 時より前、または午後 10 時より後）では、Heartbeat がスキップされます。範囲内の次の予定時刻には、通常どおり実行されます。

24 時間 365 日の設定

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

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

複数アカウントの例

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

{  agents: {    list: [      {        id: "ops",        heartbeat: {          every: "1h",          target: "telegram",          to: "12345678:topic:42", // optional: route to a specific topic/thread          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.md（省略可能）

ワークスペースに HEARTBEAT.md ファイルが存在する場合、デフォルトのプロンプトはエージェントにそのファイルを読むよう指示します。これは「Heartbeat チェックリスト」として考えてください。30 分ごとに確認しても安全な、小さく安定した内容にします。

通常の実行では、HEARTBEAT.md はデフォルトエージェントで Heartbeat のガイダンスが有効な場合にのみ挿入されます。Heartbeat の間隔を 0m で無効にするか、includeSystemPromptSection: false を設定すると、通常のブートストラップコンテキストから省略されます。

ネイティブ Codex ハーネスでは、HEARTBEAT.md の内容は他のブートストラップファイルのようにターンへ挿入されません。ファイルが存在し、空白以外の内容がある場合、Heartbeat のコラボレーションモードに関する注記が Codex にそのファイルを示し、続行前に読むよう指示します。

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

プロンプトの肥大化を避けるため、内容はごく小さく（短いチェックリストやリマインダー）保ってください。

HEARTBEAT.md の例:

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

tasks: ブロック

HEARTBEAT.md は、Heartbeat 内で間隔ベースのチェックを行うための、小さな構造化 tasks: ブロックにも対応しています。

例:

tasks: - name: inbox-triage  interval: 30m  prompt: "緊急の未読メールを確認し、時間的制約のあるものにフラグを付ける。"- name: calendar-scan  interval: 2h  prompt: "準備やフォローアップが必要な今後の会議を確認する。" # 追加の指示 - アラートは短く保つ。- 期限を迎えたすべてのタスクを確認した後、注意が必要なものがなければ HEARTBEAT_OK と応答する。

タスクモードは、毎回すべてのチェックにコストをかけずに、1 つの Heartbeat ファイルへ複数の定期チェックをまとめたい場合に便利です。

エージェントは HEARTBEAT.md を更新できますか？

はい。更新するよう依頼すれば可能です。

HEARTBEAT.md はエージェントのワークスペースにある通常のファイルなので、通常のチャットでエージェントに次のように指示できます。

• 「HEARTBEAT.md を更新して、毎日のカレンダーチェックを追加してください。」
• 「HEARTBEAT.md を、より短く、受信トレイのフォローアップに重点を置いた内容に書き換えてください。」

これを自発的に行わせたい場合は、Heartbeat のプロンプトに「チェックリストが古くなった場合は、HEARTBEAT.md をより適切な内容に更新する。」のような明示的な一文を含めることもできます。

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

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 は最終的な「回答」ペイロードのみを配信します。

処理内容を可視化する場合は、次を有効にします。

• agents.defaults.heartbeat.includeReasoning: true

有効にすると、Heartbeat は接頭辞 Thinking が付いた別のメッセージも配信します（形式は /reasoning on と同じです）。これは、エージェントが複数のセッションや codex を管理していて、なぜ通知を送ると判断したのかを確認したい場合に役立ちます。ただし、必要以上に内部の詳細が漏れる可能性もあります。グループチャットでは無効のままにすることを推奨します。

コストへの配慮

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

• 会話履歴全体を送信しないようにするには、isolatedSession: true を使用します（実行ごとに約 100K トークンから約 2〜5K トークンまで削減）。
• ブートストラップファイルを HEARTBEAT.md のみに制限するには、lightContext: true を使用します。
• より低コストの model を設定します（例: ollama/llama3.2:1b）。
• HEARTBEAT.md を小さく保ちます。
• 内部状態の更新だけが必要な場合は、target: "none" を使用します。

Heartbeat 後のコンテキスト超過

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

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

関連項目

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