ハートビート（Gateway）

ハートビートとCronの使い分け Cron vs Heartbeatでそれぞれの使い分けを確認してください。

ハートビートはメインセッションで定期的なエージェントターンを実行し、スパムにならない範囲で注意が必要な事項を通知します。

トラブルシューティング：/automation/troubleshooting

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

  1. ハートビートを有効なままにします（デフォルトは30m、Anthropic OAuth/setup-tokenの場合は1h）。または独自のケーデンスを設定します。
  2. エージェントワークスペースに簡潔なHEARTBEAT.mdチェックリストを作成します（オプションですが推奨）。
  3. ハートビートメッセージの送信先を決定します（target: "none"がデフォルト。最後の連絡先にルーティングするにはtarget: "last"を設定）。
  4. オプション：透明性のためにハートビートの推論配信を有効化。
  5. オプション：ハートビート実行がHEARTBEAT.mdのみで済む場合、軽量ブートストラップコンテキストを使用。
  6. オプション：ハートビートをアクティブ時間帯（ローカル時間）に制限。

設定例：

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last", // 最後の連絡先に明示的に配信（デフォルトは"none"）
        directPolicy: "allow", // デフォルト：ダイレクト/DMターゲットを許可。"block"で抑制
        lightContext: true, // オプション：ブートストラップファイルからHEARTBEAT.mdのみ注入
        // activeHours: { start: "08:00", end: "24:00" },
        // includeReasoning: true, // オプション：別途`Reasoning:`メッセージも送信
      },
    },
  },
}

デフォルト

  • 間隔：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.activeHours）は設定されたタイムゾーンで確認されます。ウィンドウ外ではハートビートはスキップされ、ウィンドウ内の次のティックまで待機します。

ハートビートプロンプトの用途

デフォルトのプロンプトは意図的に広範です：

  • バックグラウンドタスク：「Consider outstanding tasks」はエージェントにフォローアップ（受信箱、カレンダー、リマインダー、キュー済み作業）を確認し、緊急事項を通知するよう促します。
  • 人間へのチェックイン：「Checkup sometimes on your human during day time」は軽い「何か必要ですか？」メッセージを促しますが、設定されたローカルタイムゾーンを使用して夜間のスパムを回避します（/concepts/timezoneを参照）。

非常に具体的な作業をハートビートに行わせたい場合（例：「Gmail PubSubの統計を確認」や「ゲートウェイの健全性を検証」）、agents.defaults.heartbeat.prompt（またはagents.list[].heartbeat.prompt）にカスタム本文を設定してください（そのまま送信されます）。

レスポンス契約

  • 注意が必要な事項がなければ、**HEARTBEAT_OK**と返信。
  • ハートビート実行中、OpenClawは返信の先頭または末尾にHEARTBEAT_OKが出現した場合にackとして扱います。トークンは除去され、残りのコンテンツが**ackMaxChars以下**（デフォルト：300）の場合は返信が破棄されます。
  • HEARTBEAT_OKが返信の途中に出現した場合は、特別な扱いはしません。
  • アラートの場合はHEARTBEAT_OKを含めないでください。アラートテキストのみを返してください。

ハートビート外では、メッセージの先頭/末尾の迷子のHEARTBEAT_OKは除去されログに記録されます。HEARTBEAT_OKのみのメッセージは破棄されます。

設定

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // デフォルト：30m（0mで無効化）
        model: "anthropic/claude-opus-4-6",
        includeReasoning: false, // デフォルト：false（利用可能時に別途Reasoning:メッセージを配信）
        lightContext: false, // デフォルト：false。trueにするとワークスペースブートストラップファイルからHEARTBEAT.mdのみ保持
        target: "last", // デフォルト：none | 選択肢：last | none | <チャンネルID>（コアまたはプラグイン、例："bluebubbles"）
        to: "+15551234567", // オプション：チャンネル固有のオーバーライド
        accountId: "ops-bot", // オプション：マルチアカウントチャンネル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, // HEARTBEAT_OK後に許容される最大文字数
      },
    },
  },
}

スコープと優先順位

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

エージェントごとのハートビート

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

例：2つのエージェント、2番目のエージェントのみがハートビートを実行。

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last", // 最後の連絡先に明示的に配信（デフォルトは"none"）
      },
    },
    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.",
        },
      },
    ],
  },
}

アクティブ時間帯の例

特定のタイムゾーンで営業時間にハートビートを制限：

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last", // 最後の連絡先に明示的に配信（デフォルトは"none"）
        activeHours: {
          start: "09:00",
          end: "22:00",
          timezone: "America/New_York", // オプション。設定済みのuserTimezoneがあればそれを使用、なければホストTZ
        },
      },
    },
  },
}

このウィンドウ外（東部時間で午前9時前または午後10時以降）ではハートビートはスキップされます。ウィンドウ内の次のスケジュール済みティックは通常通り実行されます。

24時間365日セットアップ

ハートビートを終日実行したい場合、以下のパターンを使用してください：

  • activeHoursを完全に省略（時間帯の制限なし。デフォルトの動作）。
  • 全日ウィンドウを設定：activeHours: { start: "00:00", end: "24:00" }。

同じstartとend時間（例：08:00から08: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" },
      },
    },
  },
}

フィールドの注記

  • every：ハートビート間隔（duration文字列。デフォルト単位は分）。
  • model：ハートビート実行時のオプションのモデルオーバーライド（provider/model）。
  • includeReasoning：有効にすると、利用可能時に別途Reasoning:メッセージも配信（/reasoning onと同じ形式）。
  • lightContext：trueの場合、軽量ブートストラップコンテキストを使用し、ワークスペースブートストラップファイルからHEARTBEAT.mdのみ保持。
  • session：ハートビート実行用のオプションのセッションキー。
    • main（デフォルト）：エージェントのメインセッション。
    • 明示的セッションキー（openclaw sessions --jsonまたはsessions CLIからコピー）。
    • セッションキーフォーマット：SessionsとGroupsを参照。
  • target：
    • last：最後に使用された外部チャンネルに配信。
    • 明示的チャンネル：whatsapp / telegram / discord / googlechat / slack / msteams / signal / imessage。
    • none（デフォルト）：ハートビートは実行するが外部に配信しない。
  • directPolicy：ダイレクト/DM配信の動作を制御：
    • allow（デフォルト）：ダイレクト/DMハートビート配信を許可。
    • block：ダイレクト/DM配信を抑制（reason=dm-blocked）。
  • to：オプションの受信者オーバーライド（チャンネル固有のID、例：WhatsAppのE.164やTelegramのチャットID）。Telegramのトピック/スレッドには<chatId>:topic:<messageThreadId>を使用。
  • accountId：マルチアカウントチャンネル用のオプションのアカウントID。target: "last"の場合、解決された最後のチャンネルがアカウントをサポートしていればアカウントIDが適用され、そうでなければ無視されます。アカウントIDが解決されたチャンネルの設定済みアカウントと一致しない場合、配信はスキップされます。
  • prompt：デフォルトのプロンプト本文をオーバーライド（マージなし）。
  • ackMaxChars：HEARTBEAT_OK後に配信前に許容される最大文字数。
  • suppressToolErrorWarnings：trueの場合、ハートビート実行中のツールエラー警告ペイロードを抑制。
  • activeHours：ハートビート実行を時間帯に制限。start（HH:MM、包含。日の始まりには00:00を使用）、end（HH:MM排他。日の終わりには24:00が使用可能）、オプションのtimezoneのオブジェクト。
    • 省略または"user"：設定済みのagents.defaults.userTimezoneを使用。未設定の場合はホストシステムのタイムゾーンにフォールバック。
    • "local"：常にホストシステムのタイムゾーンを使用。
    • 任意のIANA識別子（例：America/New_York）：そのまま使用。無効な場合は上記の"user"動作にフォールバック。
    • startとendはアクティブウィンドウとして等しくしてはいけません。等しい値は幅ゼロとして扱われます（常にウィンドウ外）。
    • アクティブウィンドウ外では、ウィンドウ内の次のティックまでハートビートはスキップされます。

配信動作

  • ハートビートはデフォルトでエージェントのメインセッション（agent:<id>:<mainKey>）で実行されます。session.scope = "global"の場合はglobalで実行。sessionで特定のチャンネルセッション（Discord/WhatsAppなど）にオーバーライド可能。
  • sessionは実行コンテキストにのみ影響します。配信はtargetとtoで制御されます。
  • 特定のチャンネル/受信者に配信するには、target + toを設定。target: "last"では、そのセッションの最後の外部チャンネルに配信します。
  • ハートビート配信はデフォルトでダイレクト/DMターゲットを許可します。directPolicy: "block"を設定すると、ハートビートターンは実行しつつダイレクトターゲットへの送信を抑制します。
  • メインキューがビジーの場合、ハートビートはスキップされ後でリトライされます。
  • targetが外部送信先に解決されない場合、実行は行われますがアウトバウンドメッセージは送信されません。
  • ハートビートのみの返信はセッションを生存状態にしません。最後のupdatedAtが復元されるため、アイドル期限は正常に動作します。

表示制御

デフォルトではHEARTBEAT_OKのackは抑制され、アラートコンテンツは配信されます。チャンネルまたはアカウントごとに調整できます：

channels:
  defaults:
    heartbeat:
      showOk: false # HEARTBEAT_OKを非表示（デフォルト）
      showAlerts: true # アラートメッセージを表示（デフォルト）
      useIndicator: true # インジケーターイベントを発行（デフォルト）
  telegram:
    heartbeat:
      showOk: true # TelegramではOKのackを表示
  whatsapp:
    accounts:
      work:
        heartbeat:
          showAlerts: false # このアカウントのアラート配信を抑制

優先順位：アカウントごと → チャンネルごと → チャンネルデフォルト → ビルトインデフォルト。

各フラグの動作

  • showOk：モデルがOKのみの返信を返した場合にHEARTBEAT_OKのackを送信。
  • showAlerts：モデルが非OKの返信を返した場合にアラートコンテンツを送信。
  • useIndicator：UIステータスサーフェス用のインジケーターイベントを発行。

3つすべてがfalseの場合、OpenClawはハートビート実行自体をスキップします（モデル呼び出しなし）。

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

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

よくあるパターン

目的設定
デフォルト動作（サイレント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ファイルが存在する場合、デフォルトのプロンプトがエージェントにそれを読むよう指示します。「ハートビートチェックリスト」として考えてください：小さく、安定していて、30分ごとに含めても安全です。

HEARTBEAT.mdが存在するが実質的に空（空行とマークダウンヘッダー# Headingのみ）の場合、OpenClawはAPI呼び出しを節約するためハートビート実行をスキップします。ファイルが存在しない場合でもハートビートは実行され、モデルが何をすべきか判断します。

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

HEARTBEAT.mdの例：

# ハートビートチェックリスト

- クイックスキャン：受信箱に緊急案件はあるか？
- 日中であれば、他に保留がなければ軽いチェックインを行う。
- タスクがブロックされている場合、_不足しているもの_を書き留め、次回Peterに確認する。

エージェントがHEARTBEAT.mdを更新できるか？

はい — 指示すれば可能です。

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

  • 「HEARTBEAT.mdを更新して、毎日のカレンダーチェックを追加して。」
  • 「HEARTBEAT.mdを書き直して、受信箱のフォローアップに焦点を絞って短くして。」

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

セキュリティ上の注意：HEARTBEAT.mdにシークレット（APIキー、電話番号、プライベートトークン）を入れないでください。プロンプトコンテキストの一部になります。

手動ウェイク（オンデマンド）

システムイベントをキューに入れて即時ハートビートをトリガーできます：

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

複数のエージェントにheartbeatが設定されている場合、手動ウェイクはそれらのエージェントのハートビートすべてを即座に実行します。

次のスケジュール済みティックまで待つには--mode next-heartbeatを使用。

推論配信（オプション）

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

透明性が必要な場合は有効化してください：

  • agents.defaults.heartbeat.includeReasoning: true

有効にすると、ハートビートはReasoning:プレフィックス付きの別メッセージも配信します（/reasoning onと同じ形式）。エージェントが複数のセッション/コーデックスを管理している場合に、なぜ通知したかを確認するのに有用です。ただし、グループチャットでは必要以上の内部情報が漏れる可能性があるため、オフにしておくことを推奨します。

コスト意識

ハートビートは完全なエージェントターンを実行します。間隔が短いほどトークン消費が増えます。HEARTBEAT.mdを小さく保ち、内部状態の更新のみが必要な場合は、より安価なmodelの使用やtarget: "none"の設定を検討してください。

arrow_back
前へ
Health
次へ
Doctor
arrow_forward