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 `Reasoning:` message too      },    },  },}

デフォルト

• 間隔: 30m（Claude CLI の再利用を含め、Anthropic OAuth/トークン認証が検出された認証モードの場合は 1h）。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 プロンプトはユーザーメッセージとしてそのまま送信されます。システムプロンプトには、デフォルトエージェントで Heartbeat が有効な場合にのみ「Heartbeat」セクションが含まれ、実行は内部的にフラグ付けされます。
• Heartbeat が 0m で無効化されている場合、通常の実行でもブートストラップコンテキストから HEARTBEAT.md が省略されるため、モデルは Heartbeat 専用の指示を見ません。
• アクティブ時間（heartbeat.activeHours）は、設定されたタイムゾーンで確認されます。時間枠外では、Heartbeat は時間枠内の次のティックまでスキップされます。
• Cron 作業がアクティブまたはキューに入っている間、Heartbeat は自動的に延期されます。heartbeat.skipWhenBusy: true を設定すると、そのエージェント自身のセッションキー付きサブエージェントまたはネストされたコマンドレーンでも延期されます。別のエージェントでサブエージェント作業が進行中という理由だけでは、兄弟エージェントは一時停止されなくなりました。

Heartbeat プロンプトの用途

デフォルトプロンプトは意図的に広めになっています。

• バックグラウンドタスク: 「Consider outstanding tasks」は、エージェントにフォローアップ（受信箱、カレンダー、リマインダー、キューに入った作業）を確認し、緊急のものを表面化するよう促します。
• 人間へのチェックイン: 「Checkup sometimes on your human during day time」は、ときどき軽い「必要なことはありますか？」メッセージを促しますが、設定されたローカルタイムゾーン（タイムゾーン を参照）を使うことで夜間の通知乱発を避けます。

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

Heartbeat に非常に具体的なこと（例: 「Gmail PubSub 統計を確認する」または「Gateway の健全性を検証する」）をさせたい場合は、agents.defaults.heartbeat.prompt（または agents.list[].heartbeat.prompt）をカスタム本文に設定します（そのまま送信されます）。

応答契約

• 注意を要するものがない場合は、HEARTBEAT_OK と返信します。
• ツール対応の Heartbeat 実行では、表示更新なしの場合に notify: false で heartbeat_respond を呼び出すか、アラートの場合に 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 Reasoning: 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.",        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 # Hide HEARTBEAT_OK (default)      showAlerts: true # Show alert messages (default)      useIndicator: true # Emit indicator events (default)  telegram:    heartbeat:      showOk: true # Show OK acknowledgments on Telegram  whatsapp:    accounts:      work:        heartbeat:          showAlerts: false # Suppress alert delivery for this account

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

各フラグの役割

• 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 # all Slack accounts    accounts:      ops:        heartbeat:          showAlerts: false # suppress alerts for the ops account only  telegram:    heartbeat:      showOk: true

一般的なパターン

HEARTBEAT.md（任意）

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

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

HEARTBEAT.md が存在していても実質的に空（空行と # Heading のような Markdown 見出しだけ）の場合、OpenClaw は API 呼び出しを節約するために Heartbeat 実行をスキップします。そのスキップは reason=empty-heartbeat-file として報告されます。ファイルがない場合でも Heartbeat は実行され、モデルが何をするかを決めます。

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

HEARTBEAT.md の例:

# Heartbeat checklist - Quick scan: anything urgent in inboxes?- If it's daytime, do a lightweight check-in if nothing else is pending.- If a task is blocked, write down _what is missing_ and ask Peter next time.

tasks: ブロック

HEARTBEAT.md は、Heartbeat 自体の中で interval ベースの確認を行うための小さな構造化 tasks: ブロックもサポートします。

例:

tasks: - name: inbox-triage  interval: 30m  prompt: "Check for urgent unread emails and flag anything time sensitive."- name: calendar-scan  interval: 2h  prompt: "Check for upcoming meetings that need prep or follow-up." # Additional instructions - Keep alerts short.- If nothing needs attention after all due tasks, reply HEARTBEAT_OK.

タスクモードは、1つの Heartbeat ファイルに複数の定期チェックを持たせつつ、毎 tick すべてにコストを払いたくない場合に便利です。

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

はい。依頼すれば可能です。

HEARTBEAT.md はエージェントワークスペース内の通常のファイルにすぎないため、通常のチャットでエージェントに次のように伝えられます。

• 「毎日のカレンダー確認を追加するように HEARTBEAT.md を更新して。」
• 「HEARTBEAT.md を、より短く inbox のフォローアップに集中した内容に書き直して。」

これをプロアクティブに行わせたい場合は、Heartbeat プロンプトに次のような明示的な行を含めることもできます。「チェックリストが古くなったら、よりよいものにして HEARTBEAT.md を更新してください。」

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

次のコマンドでシステムイベントをキューに入れ、即時 Heartbeat をトリガーできます。

openclaw system event --text "Check for urgent follow-ups" --mode now

複数のエージェントで heartbeat が設定されている場合、手動起動はそれらの各エージェントの Heartbeat を即座に実行します。

次のスケジュール済み tick まで待つには、--mode next-heartbeat を使用します。

推論の配信（任意）

デフォルトでは、Heartbeat は最終的な「回答」ペイロードだけを配信します。

透明性が必要な場合は、次を有効にします。

• agents.defaults.heartbeat.includeReasoning: true

有効にすると、Heartbeat は Reasoning: というプレフィックス付きの別メッセージも配信します（/reasoning on と同じ形）。これは、エージェントが複数のセッション/codex を管理していて、なぜ ping すると判断したのかを確認したい場合に役立ちます。ただし、望む以上に内部の詳細が漏れる可能性もあります。グループチャットではオフのままにすることを推奨します。

コスト意識

Heartbeat は完全なエージェントターンを実行します。短い interval はより多くのトークンを消費します。コストを下げるには:

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

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

Heartbeat によって既存のセッションが以前に小さなローカルモデル、たとえば 32k ウィンドウの Ollama モデルのままになり、次のメインセッションターンでコンテキストオーバーフローが報告された場合は、セッションのランタイムモデルを設定済みのプライマリモデルに戻してください。最後のランタイムモデルが設定済みの heartbeat.model と一致する場合、OpenClaw のリセットメッセージはこの点を明示します。

現在の Heartbeat は、実行完了後に共有セッションの既存のランタイムモデルを保持します。Heartbeat を新しいセッションで実行するために isolatedSession: true を引き続き使用できます。最小のプロンプトにするには lightContext: true と組み合わせるか、共有セッションに十分な大きさのコンテキストウィンドウを持つ Heartbeat モデルを選択してください。

関連

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