Heartbeat
Heartbeat のポーリングメッセージと通知ルール。
Tutorial.alert.info
Heartbeat はメインセッションで定期的なエージェントターンを実行し、モデルが
スパムを送らずに注意が必要な内容を表示できるようにします。
クイックスタート（初心者向け）
1. Heartbeat を有効にする（Anthropic OAuth/setup-token の場合、デフォルトで ''30m'' または ''1h''）または独自の頻度を設定します。
2. エージェントワークスペースに小さな ''HEARTBEAT.md'' チェックリストを作成します（オプションですが推奨されます）。
3. Heartbeat メッセージをどこに送信するかを決定します（''target: "last"'' がデフォルトです）。
4. オプション：透明性のために Heartbeat 推論配信を有効にします。
5. オプション：Heartbeat をアクティブ時間（現地時間）に制限します。
Example config:
{
agents: {
defaults: {
heartbeat: {
every: "30m",
target: "last",
// activeHours: { start: "08:00", end: "24:00" },
// includeReasoning: true, // optional: send separate `Reasoning:` message too
},
},
},
}デフォルト値
- 間隔：''30m''（Anthropic OAuth/setup-token が検出された認証モードの場合は ''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.activeHours''）でチェックされます。
ウィンドウ外では、Heartbeat はスキップされ、ウィンドウ内の次のティックまで待機します。
Heartbeat プロンプトの目的
デフォルトのプロンプトは意図的に広範です：
- バックグラウンドタスク：「未完了のタスクを検討する」はエージェントにレビューを促します
フォローアップ（受信トレイ、カレンダー、リマインダー、キューに入った作業）と緊急事項を表示します。
- 人間によるチェックイン：「日中に時折人間とチェックインする」は
時折の軽量な「何か必要ですか？」メッセージを促進しますが、夜間のスパムを回避します
設定されたローカルタイムゾーンを使用します（''/concepts/timezone'' を参照）。
Heartbeat に非常に具体的なことをさせたい場合（例：「Gmail PubSub
stats」または「ゲートウェイの健全性を確認」）、''agents.defaults.heartbeat.prompt'' （または
''agents.list[].heartbeat.prompt''）をカスタム本文（逐語送信）に設定します。
レスポンス契約
- 注意が必要なものがない場合、''''HEARTBEAT_OK'''' と返信してください。
- Heartbeat 実行中、OpenClaw は ''HEARTBEAT_OK'' を確認として扱います
返信の先頭または末尾に現れた場合。トークンは削除され、返信は
残りの内容が ''≤ ''ackMaxChars'''' （デフォルト：300）の場合、削除されます。
- ''HEARTBEAT_OK'' が返信の''中央''に現れた場合、特別に
扱われません。
- アラートの場合、''含めないでください'' ''HEARTBEAT_OK''。アラートテキストのみを返してください。
Heartbeat 外では、メッセージの先頭/末尾にある孤立した ''HEARTBEAT_OK'' は削除され
記録されます。''HEARTBEAT_OK'' のみのメッセージは破棄されます。
Config
{
agents: {
defaults: {
heartbeat: {
every: "30m", // default: 30m (0m disables)
model: "anthropic/claude-opus-4-5",
includeReasoning: false, // default: false (deliver separate Reasoning: message when available)
target: "last", // last | none | <channel id> (core or plugin, e.g. "bluebubbles")
to: "+15551234567", // optional channel-specific override
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.'' はチャネルのデフォルトを上書きします。
- ''channels.'' （マルチアカウントチャネル）はチャネルごとの設定を上書きします。
#
エージェントごとの Heartbeat
いずれかの ''agents.list[]'' エントリに ''heartbeat'' ブロックが含まれている場合、''それらのエージェントのみ''
Heartbeat を実行します。各エージェントブロックは ''agents.defaults.heartbeat'' の上にマージされます
（したがって、共有デフォルトを一度設定し、エージェントごとに上書きできます）。
例：2 つのエージェント、2 番目のエージェントのみが Heartbeat を実行します。
{
agents: {
defaults: {
heartbeat: {
every: "30m",
target: "last",
},
},
list: [
{ id: "main", default: true },
{
id: "ops",
heartbeat: {
every: "1h",
target: "whatsapp",
to: "+15551234567",
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.",
},
},
],
},
}#
フィールドノート
- ''every''：Heartbeat 間隔（期間文字列；デフォルト単位=分）。
- ''model''：Heartbeat 実行のオプションのモデルオーバーライド（''provider/model''）。
- ''includeReasoning''：有効にすると、利用可能な場合に個別の ''Reasoning:'' メッセージも配信します（''/reasoning on'' と同じ形状）。
- ''session''：Heartbeat 実行のオプションのセッションキー。
- ''main'' （デフォルト）：エージェントのメインセッション。
- 明示的なセッションキー（''openclaw sessions --json'' または ''セッション CLI'' からコピー）。
- セッションキーの形式：''セッション'' および ''グループ'' を参照してください。
- ''target''：
- ''last'' （デフォルト）：最後に使用された外部チャネルに配信します。
- 明示的なチャネル：''whatsapp'' / ''telegram'' / ''discord'' / ''googlechat'' / ''slack'' / ''msteams'' / ''signal'' / ''imessage''。
- ''none''：Heartbeat を実行しますが''外部に配信しません''。
- ''to''：オプションの受信者オーバーライド（チャネル固有の ID、例：WhatsApp の E.164 または Telegram チャット ID）。
- ''prompt''：デフォルトのプロンプト本文を上書きします（マージしません）。
- ''ackMaxChars''：''HEARTBEAT_OK'' の後に配信前に許可される最大文字数。
Delivery behavior
- デフォルトでは、Heartbeat はエージェントのメインセッション（''agent:''）で実行されます
または ''session.scope = "global"'' の場合は ''session.scope = "global"''。''session'' を設定して
特定のチャネルセッション（Discord/WhatsApp/など）に上書きします。
- ''session'' は実行コンテキストのみに影響します。配信は ''target'' と ''to'' によって制御されます。
- 特定のチャネル/受信者に配信するには、''target'' + ''to'' を設定します。
''target: "last"'' の場合、配信はそのセッションの最後の外部チャネルを使用します。
- メインキューがビジーの場合、Heartbeat はスキップされ、後で再試行されます。
- ''target'' が外部ターゲットに解決されない場合、実行は引き続き行われますが
送信メッセージは送信されません。
- Heartbeat 返信はセッションを''維持しません''。最後の ''updatedAt''
は復元されるため、アイドル期限切れの動作は正常です。
可視性の制御
デフォルトでは、アラートコンテンツが配信されると、''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 ステータスサーフェスのインジケーターイベントを発行します。
<strong>すべて 3 つ</strong>が 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 ops account only
telegram:
heartbeat:
showOk: true#
一般的なパターン
| Goal | Config |
| - |
|デフォルトの動作（OK はサイレント、アラートオン）| _設定不要_ |
|完全にサイレント（メッセージなし、インジケーターなし）| channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: false }' |
|インジケーターのみ（メッセージなし）| channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: true }' |
|1 つのチャネルでのみ OK| channels.telegram.heartbeat: { showOk: true }' |
HEARTBEAT.md（オプション）
ワークスペースに ''HEARTBEAT.md'' ファイルが存在する場合、デフォルトのプロンプトは
エージェントに読み取るように指示します。「Heartbeat チェックリスト」として扱います。小さく、安定しており、
30 分ごとに追加しても安全です。
''HEARTBEAT.md'' が存在しますが実質的に空の場合（空白行とマークダウン
''# Heading'' のようなヘッダーのみ）、OpenClaw は API 呼び出しを節約するために Heartbeat 実行をスキップします。
ファイルが存在しない場合、Heartbeat は引き続き実行され、モデルが何をするかを決定します。
膨張を避けるために小さく（短いチェックリストまたはリマインダー）保ってください。
Example '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'HEARTBEAT.md'</code>':