​

Heartbeat（Gateway）

Heartbeat と Cron の違いは？ 使い分けの指針については Cron vs Heartbeat を参照してください。

​

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

1. ハートビートを有効のままにします（デフォルトは 30m、Anthropic OAuth/setup-token の場合は 1h）。または独自の間隔を設定します。
2. エージェントのワークスペースに小さな HEARTBEAT.md チェックリストを作成します（任意ですが推奨）。
3. ハートビートメッセージの送信先を決定します（デフォルトは target: "last"）。
4. 任意: 透明性のためにハートビートの reasoning 配信を有効にします。
5. 任意: アクティブ時間（ローカル時間）にハートビートを制限します。

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
        // activeHours: { start: "08:00", end: "24:00" },
        // includeReasoning: true, // optional: send separate `Reasoning:` message too
      },
    },
  },
}

​

デフォルト

• Interval: 30m (または 1h Anthropic OAuth/setup-token が検出された認証モードの場合) 間隔: 30m（Anthropic OAuth/setup-token が検出された認証モードの場合は 1h）。agents.defaults.heartbeat.every またはエージェントごとの agents.list[].heartbeat.every を設定します。無効化するには 0m を使用します。 間隔: 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 と返信します。
• ハートビート実行中、OpenClaw は返信の 先頭または末尾 に現れる HEARTBEAT_OK を ack として扱います。このトークンは削除され、残りの内容が ≤ ackMaxChars（デフォルト: 300）の場合、返信は破棄されます。 トークンが削除され、残りのコンテンツが 以下の ackMaxChars (デフォルト: 300) の場合、返信は ドロップされます。
• 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)
        target: "last", // last | none | <channel id> (core or plugin, e.g. "bluebubbles")
        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 はグローバルなハートビート動作を設定します。
• 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: "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",
        activeHours: {
          start: "09:00",
          end: "22:00",
          timezone: "America/New_York", // optional; uses your userTimezone if set, otherwise host tz
        },
      },
    },
  },
}

​

マルチアカウントの例

{
  agents: {
    list: [
      {
        id: "ops",
        heartbeat: {
          every: "1h",
          target: "telegram",
          to: "12345678",
          accountId: "ops-bot",
        },
      },
    ],
  },
  channels: {
    telegram: {
      accounts: {
        "ops-bot": { botToken: "YOUR_TELEGRAM_BOT_TOKEN" },
      },
    },
  },
}

​

フィールドノート

• every: ハートビート間隔（duration 文字列。デフォルトの単位 = 分）。
• model: ハートビート実行時の任意のモデル上書き（provider/model）。
• includeReasoning: 有効にすると、利用可能な場合に別個の Reasoning: メッセージも配信します（/reasoning on と同じ形状）。
• session: ハートビート実行用の任意のセッションキー。
  • main（デフォルト）: エージェントのメインセッション。
  • 明示的なセッションキー（openclaw sessions --json または sessions CLI からコピー）。
  • セッションキー形式: Sessions および Groups を参照。
• target:
  • last（デフォルト）: 最後に使用した外部チャンネルに配信します。
  • 明示的なチャンネル: whatsapp / telegram / discord / googlechat / slack / msteams / signal / imessage。
  • none: ハートビートを実行しますが、外部には 配信しません。
• to: 任意の受信者上書き（チャンネル固有の ID。例: WhatsApp の E.164、Telegram の chat id）。
• accountId: マルチアカウントチャンネルのオプションのアカウントID。 accountId: マルチアカウントチャンネル用の任意のアカウント ID。target: "last" の場合、アカウント ID はアカウントをサポートする解決済みの最終チャンネルに適用され、それ以外は無視されます。アカウント ID が解決済みチャンネルに設定されたアカウントと一致しない場合、配信はスキップされます。 アカウントIDが解決済みチャネルの設定済みアカウントと一致しない場合、配信はスキップされます。 accountId: マルチアカウントチャンネル用の任意のアカウント ID。target: "last" の場合、アカウント ID はアカウントをサポートする解決済みの最終チャンネルに適用され、それ以外は無視されます。アカウント ID が解決済みチャンネルに設定されたアカウントと一致しない場合、配信はスキップされます。 アカウントIDが解決済みチャネルの設定済みアカウントと一致しない場合、配信はスキップされます。
• prompt: デフォルトのプロンプト本文を上書きします（マージされません）。
• ackMaxChars: HEARTBEAT_OK 以降に配信を許可する最大文字数。
• activeHours: ハートビートの実行をタイムウィンドウに制限します。 activeHours: ハートビート実行を時間ウィンドウに制限します。start（HH:MM、包含）、end（HH:MM、排他的。終日の場合は 24:00 可）、および任意の timezone を持つオブジェクト。 activeHours: ハートビート実行を時間ウィンドウに制限します。start（HH:MM、包含）、end（HH:MM、排他的。終日の場合は 24:00 可）、および任意の timezone を持つオブジェクト。
  • 省略または "user": 設定されていれば agents.defaults.userTimezone を使用し、なければホストシステムのタイムゾーンにフォールバックします。
  • "local": 常にホストシステムのタイムゾーンを使用します。
  • 任意の IANA 識別子（例: America/New_York）: 直接使用され、無効な場合は上記の "user" の挙動にフォールバックします。
  • アクティブウィンドウ外では、次にウィンドウ内に入るティックまでハートビートはスキップされます。

​

配信動作

• ハートビートは、デフォルトでエージェントのメインセッション（agent:<id>:<mainKey>）で実行されます。session.scope = "global" の場合は global になります。特定のチャンネルセッション（Discord/WhatsApp など）に上書きするには session を設定します。 sessionを 特定のチャンネルセッション（Discord/WhatsApp/etc）にオーバーライドするように設定します。 sessionを 特定のチャンネルセッション（Discord/WhatsApp/etc）にオーバーライドするように設定します。
• session は実行コンテキストのみに影響します。配信は target と to によって制御されます。
• 特定のチャンネル/受信者に配信するには、target + to を設定します。 特定のチャンネル/受信者に配信するには、target + to を設定します。 特定のチャンネル/受信者に配信するには、target + to を設定します。target: "last" を使用すると、配信はそのセッションの最後の外部チャンネルを使用します。
• メインキューがビジーな場合、ハートビートはスキップされ、後で再試行されます。
• target が外部宛先に解決されない場合でも、実行自体は行われますが、送信メッセージはありません。
• ハートビートのみの返信はセッションを維持しません。最後の updatedAt が復元され、アイドル期限は通常どおり動作します。

​

可視性コントロール

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 のステータス表示用にインジケーターイベントを発行します。

​

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

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 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.

​

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

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

​

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

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

​

Reasoning 配信（任意）

• agents.defaults.heartbeat.includeReasoning: true

​

コストに関する注意