Heartbeatでエージェントを自律的に動かす

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

Heartbeatを有効のままにする（デフォルトは 30m、Anthropic OAuthやsetup-tokenを使用している場合は 1h）か、独自の間隔を設定します。
エージェントのワークスペースに、小さな HEARTBEAT.md チェックリストを作成します（任意ですが推奨します）。
Heartbeatメッセージの送信先を決定します（デフォルトは target: "none" です。最後に連絡した相手にルーティングする場合は target: "last" に設定してください）。
任意：透明性を高めるために、Heartbeatの推論（reasoning）の配信を有効にします。
任意：Heartbeatの実行に HEARTBEAT.md だけが必要な場合は、軽量な bootstrap コンテキストを使用します。
任意：毎回の実行時に会話履歴をすべて送信しないよう、isolated sessions を有効にします。
任意：Heartbeatの実行をアクティブな時間帯（ローカル時間）のみに制限します。

設定例：

{
  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)
        // 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プロンプトは、ユーザーメッセージとして**そのまま（verbatim）**送信されます。System プロンプトには「Heartbeat」セクションが含まれ、その実行には内部的にフラグが立てられます。
アクティブ時間（heartbeat.activeHours）は、設定されたタイムゾーンでチェックされます。時間枠の外では、Heartbeatはスキップされ、次の時間枠内に入るまで実行されません。

Heartbeat プロンプトの目的

デフォルトのプロンプトは、意図的に幅広く設定されています。

バックグラウンドタスク: 「未完了のタスクを検討する」ことで、エージェントにフォローアップ（インボックス、カレンダー、リマインダー、キューにある作業）を確認させ、至急対応が必要なものを表面化させます。
人間への確認: 「日中に時々、人間に声をかける」ことで、たまに「何か必要なことはありますか？」といった軽いメッセージを送るよう促します。設定したローカルタイムゾーン（/concepts/timezone を参照）を使用することで、夜間のスパムを避けることができます。

Heartbeatは完了した background tasks に反応できますが、Heartbeatの実行自体がタスクレコードを作成することはありません。

特定の動作（例：「GmailのPubSub統計を確認する」や「Gatewayのヘルスチェックを行う」など）をさせたい場合は、agents.defaults.heartbeat.prompt（または agents.list[].heartbeat.prompt）にカスタムのプロンプト本体を設定してください。

レスポンスのルール（契約）

特に対応が必要なことがない場合、エージェントは HEARTBEAT_OK と返信します。
Heartbeatの実行中、OpenClawは返信の最初または最後に HEARTBEAT_OK が含まれている場合、それを承認（ack）として扱います。このトークンは削除され、残りのコンテンツが ackMaxChars（デフォルト：300）以下であれば、返信は破棄されます。
返信の途中に HEARTBEAT_OK が現れた場合は、特別な処理は行われません。
アラートを出す場合は、HEARTBEAT_OK を含めず、アラートのテキストのみを返してください。

Heartbeat以外で、メッセージの最初や最後に HEARTBEAT_OK が紛れ込んでいる場合は、削除されてログに記録されます。HEARTBEAT_OK だけのメッセージは破棄されます。

次のステップ

Cron vs Heartbeat - どちらを使うべきかのガイド
Troubleshooting - トラブルシューティング
Background tasks - バックグラウンドタスクの詳細
Timezone concepts - タイムゾーンの設定について

AI Setup Assistant

設定 (Config)

{
  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)
        target: "last", // default: none | options: 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 は、グローバルな Heartbeat の動作を設定します。
agents.list[].heartbeat はその上にマージされます。いずれかのエージェントに heartbeat ブロックがある場合、それらのエージェントのみが Heartbeat を実行します。
channels.defaults.heartbeat は、すべての Channel の表示に関するデフォルトを設定します。
channels.<channel>.heartbeat は、Channel ごとのデフォルトを上書きします。
channels.<channel>.accounts.<id>.heartbeat （マルチアカウント Channel の場合）は、アカウントごとの設定を上書きします。

エージェントごとの 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",
          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" }。

start と end に同じ時間を設定しないように注意してください（例： 08:00 から 08:00 など）。これは「幅ゼロの時間枠」とみなされ、Heartbeat が常にスキップされてしまいます。

マルチアカウントの例

Telegram のようなマルチアカウント対応の Channel で特定のアカウントをターゲットにするには、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" },
      },
    },
  },
}

各フィールドの解説

every: Heartbeat の実行間隔です（期間を表す文字列。デフォルトの単位は分です）。
model: Heartbeat 実行時に使用するモデルを上書きするオプションです（provider/model）。
includeReasoning: 有効にすると、利用可能な場合に個別の Reasoning: メッセージも配信します（/reasoning on と同じ形式です）。
lightContext: true の場合、Heartbeat の実行に軽量な bootstrap コンテキストを使用し、ワークスペースの bootstrap ファイルからは HEARTBEAT.md のみを保持します。
isolatedSession: true の場合、各 Heartbeat は以前の会話履歴を持たない新しいセッションで実行されます。これは cron の sessionTarget: "isolated" と同じ分離パターンを使用します。これにより、Heartbeat ごとのトークンコストを大幅に削減できます。最大限の節約には lightContext: true と組み合わせて使用してください。配信のルーティングには、引き続きメインセッションのコンテキストが使用されます。
session: Heartbeat 実行用のオプションのセッションキーです。
- main (デフォルト): エージェントのメインセッション。
- 明示的なセッションキー: openclaw sessions --json または sessions CLI からコピーしてください。
- セッションキーの形式については、Sessions と Groups を参照してください。
target:
- last: 最後に使用された外部 Channel に配信します。
- 明示的な Channel: 設定済みの Channel またはプラグイン ID（例: discord, matrix, telegram, whatsapp）。
- none (デフォルト): Heartbeat を実行しますが、外部への配信は行いません。
directPolicy: ダイレクトメッセージ（DM）の配信動作を制御します。
- allow (デフォルト): DM での Heartbeat 配信を許可します。
- block: DM への配信を抑制します (reason=dm-blocked)。
to: オプションの受信者上書き（Channel 固有の ID。例: WhatsApp の E.164 形式や Telegram のチャット ID）。Telegram のトピックやスレッドの場合は、<chatId>:topic:<messageThreadId> を使用します。
accountId: マルチアカウント対応 Channel 用のオプションのアカウント ID です。target: "last" の場合、解決された最後の Channel がアカウントをサポートしていれば、そのアカウント ID が適用されます。それ以外の場合は無視されます。解決された Channel に設定済みのアカウントと一致しない場合、配信はスキップされます。
prompt: デフォルトのプロンプト本文を上書きします（マージはされません）。
ackMaxChars: 配信前に HEARTBEAT_OK の後に許容される最大文字数です。
suppressToolErrorWarnings: true の場合、Heartbeat 実行中のツールエラー警告のペイロードを抑制します。
activeHours: Heartbeat の実行を特定の時間枠に制限します。start（HH:MM、開始時間を含む。一日の始まりには 00:00 を使用）、end（HH:MM、終了時間は含まない。一日の終わりには 24:00 を使用可能）、およびオプションの timezone を持つオブジェクトです。
- 省略または "user": agents.defaults.userTimezone が設定されていればそれを使用し、そうでなければホストシステムのタイムゾーンを使用します。
- "local": 常にホストシステムのタイムゾーンを使用します。
- IANA 識別子（例: America/New_York）: 直接使用されます。無効な場合は、上記の "user" の動作に戻ります。
- 有効な時間枠にするには、start と end が同じであってはいけません。同じ値の場合は幅ゼロの時間枠として扱われ、常に時間枠外となります。
- アクティブな時間枠の外では、時間枠内の次のスケジュールまで Heartbeat はスキップされます。

配信の動作

Heartbeat はデフォルトでエージェントのメインセッション（agent:<id>:<mainKey>）で実行されます。session.scope = "global" の場合は global で実行されます。特定の Channel セッション（Discord/WhatsApp など）で上書きするには session を設定してください。
session は実行コンテキストにのみ影響します。配信は target と to によって制御されます。
特定の Channel や受信者に配信するには、target と to を設定します。target: "last" を使用すると、そのセッションで最後に使用された外部 Channel が配信に使用されます。
Heartbeat の配信は、デフォルトで DM を宛先にすることを許可しています。Heartbeat の実行自体は行いつつ、DM への送信だけを抑制したい場合は directPolicy: "block" を設定してください。
メインのキューがビジー状態の場合、Heartbeat はスキップされ、後で再試行されます。
target が外部の宛先に解決されない場合、実行自体は行われますが、外部メッセージは送信されません。
Heartbeat のみの返信は、セッションをアクティブな状態に保ちません。最後の updatedAt が復元されるため、アイドルの期限切れは通常通り動作します。
切り離された background tasks は、システムイベントをエンキューして、メインセッションがすぐに何かに気づくべき時に Heartbeat をウェイクさせることができます。このウェイクによって Heartbeat がバックグラウンドタスクを実行することはありません。

表示のコントロール

デフォルトでは、アラート内容の送信中、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 はハートビートの実行自体をスキップします（モデルの呼び出しも行われません）。

チャンネルごと・アカウントごとの設定例

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

よく使われるパターン

目的	設定
デフォルトの動作（OKは非表示、アラートは通知）	（設定不要）
完全にサイレント（メッセージもインジケーターもなし）	`channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: false }`
インジケーターのみ（メッセージはなし）	`channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: true }`
特定のチャンネルのみ OK を表示	`channels.telegram.heartbeat: { showOk: true }`

HEARTBEAT.md (オプション)

ワークスペース内に HEARTBEAT.md ファイルが存在する場合、デフォルトのプロンプトによってエージェントはその内容を読み取ります。これは「ハートビート用チェックリスト」だと考えてください。30分ごとに読み込んでも問題ないような、小さくて安定した内容にするのがおすすめです。

もし HEARTBEAT.md が存在していても、中身が実質的に空（空行や # Heading のような見出しのみ）である場合、OpenClaw は API コールの消費を抑えるためにハートビートの実行をスキップします。ファイル自体が存在しない場合は、通常通りハートビートが実行され、モデルがどう動くかを判断します。

プロンプトが肥大化するのを防ぐため、内容は最小限（短いチェックリストやリマインダーなど）に留めておきましょう。

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 を更新して、毎日のカレンダーチェックを追加して。」
「HEARTBEAT.md を、受信トレイのフォローアップに集中した短い内容に書き換えて。」

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

セキュリティ上の注意：HEARTBEAT.md はプロンプトのコンテキストの一部になります。秘密情報（API キー、電話番号、プライベートなトークンなど）は絶対に書き込まないでください。

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

システムイベントをキューに入れ、すぐに heartbeat をトリガーしたいときは、次のコマンドを使います。

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

複数の agent で heartbeat が設定されている場合、手動での起動を実行すると、それぞれの agent の heartbeat が即座に実行されます。

次のスケジュールされたタイミングまで待ちたい場合は、--mode next-heartbeat を使ってください。

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

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

透明性を高めたい場合は、次の設定を有効にしましょう。

agents.defaults.heartbeat.includeReasoning: true

これを有効にすると、heartbeat は Reasoning: という接頭辞が付いた別のメッセージも配信するようになります（/reasoning on と同じ形式です）。agent が複数のセッションや codex を管理していて、なぜ通知を送ってきたのか理由を知りたい場合に便利です。ただし、必要以上に内部の詳細が漏れてしまう可能性もあります。グループチャットではオフのままにしておくのがおすすめです。

コストの最適化

Heartbeatは、実行されるたびにエージェントのターンを完全に1回分実行します。そのため、実行間隔を短く設定しすぎると、トークンの消費量が急激に増えてしまう点に注意が必要です。コストを賢く抑えるために、以下の設定を試してみてください。

isolatedSession: true を使用しましょう。会話履歴をすべて送信するのを防ぐことで、1回あたりの消費量を約100Kトークンから2〜5Kトークン程度まで大幅に削減できます。
lightContext: true を設定して、読み込むコンテキストを HEARTBEAT.md だけに制限してください。
より安価な model （例：ollama/llama3.2:1b）を指定するのがおすすめです。
HEARTBEAT.md ファイル自体を小さく保つようにしましょう。
内部状態の更新だけが目的であれば、target: "none" を使用するのがベストです。

まだ解決しませんか？

このページで解決しない場合は、OpenClaw Expertに直接質問してください。