ハートビート

ハートビートと Cron の違いは？ 使い分けのガイドについては、Cron vs ハートビート を参照してください。

​

クイックスタート (初心者向け)

1. ハートビートを有効のままにする（デフォルトは 30m、Anthropic OAuth/setup-token 利用時は 1h）か、独自の頻度を設定します。
2. エージェントのワークスペースに、小さな HEARTBEAT.md チェックリストを作成します（オプションですが推奨）。
3. ハートビートメッセージの送信先を決定します（デフォルトは target: "none" です。最後に通信した相手に送る場合は target: "last" を設定します）。
4. オプション: 透明性を高めるため、ハートビート時の推論プロセス（Reasoning）の配信を有効にします。
5. オプション: ハートビートの実行に HEARTBEAT.md さえあれば十分な場合は、軽量なブートストラップコンテキストを使用します。
6. オプション: ハートビートの実行時間を、特定のアクティブな時間帯（現地時間）に制限します。

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last", // 最後に通信した相手にのみ配信 (デフォルトは "none")
        directPolicy: "allow", // デフォルト。直接の宛先への送信を許可。抑制する場合は "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) は、構成されたタイムゾーンでチェックされます。時間外の場合、ハートビートはスキップされ、時間内に入った後の最初のタイミングで実行されます。

​

ハートビートプロンプトの目的

• バックグラウンドタスク: 「未処理のタスクを検討してください」という指示により、エージェントにフォローアップ（受信トレイ、カレンダー、リマインダー、キューにある仕事）を確認させ、緊急性の高いものを報告させます。
• 人間への声掛け: 「日中、時々ユーザーの様子を確認してください」という指示により、たまに「何か手伝うことはありますか？」といった軽い声掛けを行わせます。ただし、設定されたローカルタイムゾーンに基づき、夜間の通知連打を避けます（詳細は /concepts/timezone を参照）。

​

応答に関するルール

• 特に報告すべきことがない場合、モデルは HEARTBEAT_OK と返信します。
• ハートビート実行中、返信の 先頭または末尾 に HEARTBEAT_OK が含まれている場合、OpenClaw はそれを確認（ack）として扱います。トークンは除去され、残りの内容が ackMaxChars 以下 (デフォルト 300 文字) であれば、その返信は配信されません。
• 返信の 途中 に 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 | <channel id>
        to: "+15551234567", // オプション。チャネル固有の宛先 ID
        accountId: "ops-bot", // オプション。マルチアカウント時のアカウント ID
        prompt: "...", // デフォルトプロンプトを上書き
        ackMaxChars: 300, // HEARTBEAT_OK 以外に許容される最大文字数
      },
    },
  },
}

​

適用範囲と優先順位

• agents.defaults.heartbeat: グローバルなハートビート動作を設定します。
• agents.list[].heartbeat: 上書き・マージされます。いずれかのエージェントに heartbeat ブロックがある場合、それらのエージェントのみ がハートビートを実行します。
• channels.defaults.heartbeat: すべてのチャネルにおける可視性のデフォルトを設定します。
• channels.<channel>.heartbeat: チャネルごとのデフォルトを上書きします。
• channels.<channel>.accounts.<id>.heartbeat: 特定のアカウントの設定を上書きします。

​

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

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
      },
    },
    list: [
      { id: "main", default: true },
      {
        id: "ops",
        heartbeat: {
          every: "1h",
          target: "whatsapp",
          to: "+15551234567",
          prompt: "...",
        },
      },
    ],
  },
}

​

アクティブ時間（Active Hours）の例

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
        activeHours: {
          start: "09:00",
          end: "22:00",
          timezone: "Asia/Tokyo", // オプション。userTimezone があればそれを使用、なければホスト tz
        },
      },
    },
  },
}

​

24時間 365日の設定

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

​

マルチアカウントの例

{
  agents: {
    list: [
      {
        id: "ops",
        heartbeat: {
          every: "1h",
          target: "telegram",
          to: "12345678:topic:42", // オプション。特定のトピック/スレッドへルーティング
          accountId: "ops-bot",
        },
      },
    ],
  },
  channels: {
    telegram: {
      accounts: {
        "ops-bot": { botToken: "YOUR_TOKEN" },
      },
    },
  },
}

​

フィールドに関する補足

• every: ハートビートの間隔（期間を表す文字列。デフォルトの単位は分）。
• model: ハートビート実行時に使用するモデルの上書き (provider/model)。
• includeReasoning: 有効な場合、推論プロセスがあれば個別の Reasoning: メッセージとして配信します (/reasoning on と同様の形式)。
• lightContext: true の場合、ブートストラップコンテキストから HEARTBEAT.md のみを保持し、軽量なプロンプトで実行します。
• session: ハートビート実行に使用するセッションキー。
  • main (デフォルト): エージェントのメインセッション。
  • 明示的なセッションキー（openclaw sessions --json 等からコピー）。形式の詳細は セッション を参照。
• target:
  • last: 最後に使用された外部チャネルに配信。
  • 明示的なチャネル指定: whatsapp | telegram | discord | googlechat | slack | msteams | signal | imessage。
  • none (デフォルト): ハートビートは実行するが、外部への 配信は行わない。
• directPolicy: 直接/DM 宛の配信挙動を制御します:
  • allow (デフォルト): 直接宛先への配信を許可。
  • block: 直接宛先への配信を抑制 (reason=dm-blocked)。
• to: 宛先の上書き（チャネル固有の ID。WhatsApp なら E.164、Telegram ならチャット ID など）。Telegram のトピック/スレッドの場合は <chatId>:topic:<messageThreadId> を使用。
• accountId: マルチアカウントチャネルにおけるアカウント ID。target: "last" の場合、解決された最後のチャネルがアカウントに対応していれば適用されます。一致するアカウントがない場合、配信はスキップされます。
• prompt: デフォルトのプロンプト本文を上書きします（マージされません）。
• ackMaxChars: HEARTBEAT_OK が返された際、配信を許可する最大文字数。
• suppressToolErrorWarnings: true の場合、ハートビート実行中のツールエラーの警告を抑制します。
• activeHours: ハートビートを実行する時間枠を制限します。start (HH:MM, 指定時刻を含む。1日の始まりは 00:00), end (HH:MM, 指定時刻を含まない。1日の終わりは 24:00 が指定可能), およびオプションの timezone を持つオブジェクト。
  • 未設定または "user": agents.defaults.userTimezone があればそれを使用し、なければホストのタイムゾーンを使用。
  • "local": 常にホストのタイムゾーンを使用。
  • IANA タイムゾーン識別子（例: Asia/Tokyo）: 直接使用されます。無効な場合は上記の "user" の挙動にフォールバックします。
  • アクティブなウィンドウとするには、start と end が異なる必要があります。同じ値は幅ゼロ（常に時間外）とみなされます。

​

配信の挙動

• ハートビートは、デフォルトでエージェントのメインセッション (agent:<id>:<mainKey>)、あるいは session.scope = "global" の場合は global で実行されます。特定のチャネルセッション（Discord/WhatsApp など）で実行したい場合は session を設定してください。
• session は実行コンテキスト（履歴など）にのみ影響し、どこに配信するかは target と to で制御されます。
• target: "last" の場合、そのセッションで最後に使われた外部チャネルが配信先となります。
• ハートビートの配信は、デフォルトで直接/DM ターゲットを許可しています。ハートビートを実行しつつも直接ターゲットへの送信だけを控えたい場合は、directPolicy: "block" を設定してください。
• メインキューが混雑している場合、ハートビートはスキップされ、後で再試行されます。
• target が外部の宛先に解決されない場合、実行は行われますが、外部へのメッセージ送信は行われません。
• ハートビートのみの返信（OK 応答など）によって セッションが「アクティブ」に維持されることはありません。最終更新日時 (updatedAt) が復元されるため、アイドルの期限切れ判定は通常通り機能します。

​

可視性の制御

channels:
  defaults:
    heartbeat:
      showOk: false # HEARTBEAT_OK を隠す (デフォルト)
      showAlerts: true # アラート内容を表示する (デフォルト)
      useIndicator: true # UI 上のインジケーターイベントを発行する (デフォルト)
  telegram:
    heartbeat:
      showOk: true # Telegram では OK 時も通知する
  whatsapp:
    accounts:
      work:
        heartbeat:
          showAlerts: false # このアカウントではアラート配信を抑制する

​

各フラグの役割

• showOk: モデルが OK 応答のみを返した場合に、HEARTBEAT_OK の確認通知を送ります。
• showAlerts: モデルが OK 以外の応答を返した場合に、その通知内容を送ります。
• useIndicator: UI 上のステータス表示用のインジケーターイベントを発行します。

​

一般的なパターン

​

HEARTBEAT.md (オプション)

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

- クイックスキャン: 受信トレイに緊急の件はありませんか？
- 日中であれば、特に予定がなくても軽い生存確認を行ってください。
- タスクが停滞している場合は「何が足りないか」を書き留め、次回ピーターに確認してください。

​

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

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

​

手動ウェイクアップ (オンデマンド実行)

openclaw system event --text "緊急のフォローアップをチェックして" --mode now

​

推論プロセス（Reasoning）の配信 (オプション)

• agents.defaults.heartbeat.includeReasoning: true

​

コストに関する注意