第27回: HEARTBEAT.mdとは — 自律動作の仕組み

この回はレクチャー動画はありません。テキストのみとなります。

この回で学ぶこと

Heartbeatとは何か（定期的に自動実行されるタスクリスト）
HEARTBEAT.mdの書き方
通知先の設定方法
最初の自律タスクの設定

前回のおさらい

Part 5（第21〜26回）で秘書にチャネル連携を設定した。スマホのTelegramから秘書に話しかけ、画像やファイルを送り、複数チャネルで同時運用できるようになった。ただし、ここまでは全て「ユーザーが話しかけたら秘書が応答する」という受け身の動き。今回から、秘書が自分から動く仕組みを作る。

Heartbeatの仕組み

Heartbeatは、OpenClawの5つのパーツの中で最も重要な機能。第3回で「定時業務」と説明したパーツがこれにあたる。

ここまでの秘書は「話しかけたら答える」だけだった。Heartbeatを設定すると、秘書が自分からやることリストをチェックして、必要なときだけ報告してくれるようになる。

仕組みを順番に見ていこう：

OpenClawは一定間隔で「Heartbeat」を自動実行する（初期設定は30分ごと）
実行のたびに、HEARTBEAT.mdというファイルの中身を読みに行く
HEARTBEAT.mdには「やることリスト」がチェックリスト形式で書かれている
秘書がリストの内容を読んで、条件に合うタスクがあれば処理する
異常なし → 何もしない。問題があったときだけチャネル（Telegram等）で報告する

人間の心臓が定期的に鼓動を打つように、OpenClawも定期的にHEARTBEAT.mdをチェックする。これが「Heartbeat（心拍）」という名前の由来。

ChatGPTとの決定的な違い: ChatGPTはユーザーがプロンプトを送らない限り何もしない。OpenClawはHeartbeatにより、ユーザーが寝ていても自分からタスクを実行する。

「異常なし」のとき、秘書は内部的に HEARTBEAT_OK というサインを出す。このサインが出た場合は通知をスキップする仕組みになっている。「番犬が見回りして何もなかったから吠えなかった」というイメージ。

Heartbeatの実行間隔について

初期設定は30分ごと。ほとんどの人はこのままで十分。

変更したい場合は openclaw.json で設定する：

{
  "agents": {
    "defaults": {
      "heartbeat": {
        "every": "30m"
      }
    }
  }
}

"10m"（10分ごと）、"1h"（1時間ごと）、"2h"（2時間ごと）なども指定できる。"0m" にするとHeartbeat自体を無効化できる。

HEARTBEAT.mdの書き方

HEARTBEAT.mdはMarkdownのチェックリスト形式で書く。プログラミングの知識は不要で、日本語でやってほしいことを書くだけ。

基本構造：

# Heartbeat タスク

## 毎朝のルーティン
- [ ] 朝7:00〜8:00の間に、天気予報を調べて送る
- [ ] 1日1回だけ実行する

## 常時チェック
- [ ] ディスク使用量が90%を超えていないか確認する
- [ ] 超えていたら警告を送る

書き方のルール：

[ ] — まだやっていないタスク。秘書が毎回チェックする
[x] — 完了済みのタスク。秘書はスキップする（1回限りのタスクに使う）
## 見出し — タスクのグループ分け。見出しの名前がそのままスケジュールのヒントになる
時間・頻度・条件は日本語でそのまま書く（「朝7時」「1日1回」「毎週月曜」など）

重要な注意：時間指定の仕組み

「朝7:00〜8:00」と書いた場合、時計のアラームのように正確にその時刻に実行されるわけではない。

Heartbeatは30分ごとに動くので、7:00か7:30のタイミングで秘書がHEARTBEAT.mdを読み、「今は朝7:00〜8:00の範囲内だから、このタスクをやろう」とAIが判断する。つまり、秘書が「今何時かな？この時間帯に当てはまるかな？」と考えて決めている。

正確に「毎朝7:00ちょうど」に実行したい場合は、Heartbeatではなく「cron（クロン）」という別の仕組みを使う（この講座では扱わないが、公式ドキュメントに記載がある）。

ポイント: チェックリスト（- [ ]）以外に、普通の箇条書き（- ○○を確認する）でも秘書は指示として読み取れる。ただしチェックリスト形式のほうが「完了/未完了」が明確なので推奨。

注意: HEARTBEAT.mdの中身が空っぽ（見出ししかない等）の場合、秘書はHeartbeat自体をスキップしてAPI呼び出しを節約する。タスクを書かないとそもそも動かない。

通知先の設定 — ここを忘れると通知が来ない

HEARTBEAT.mdを書いただけでは、秘書は結果をどこにも送らない。これが最もハマりやすいポイント。

通知先は openclaw.json で明示的に設定する必要がある：

{
  "agents": {
    "defaults": {
      "heartbeat": {
        "every": "30m",
        "target": "telegram"
      }
    }
  }
}

target の設定値：

"none"（デフォルト） — どこにも送らない。秘書は内部でタスクを実行するが、結果を報告しない
"telegram" / "discord" / "slack" — 指定したチャネルに通知を送る
"last" — 最後にやりとりしたチャネルに送る

target を設定しないと、HEARTBEAT.mdのタスクは実行されるが結果が通知されない。 「設定したのに何も来ない」という場合、まずここを確認すること。

さらに、通知の種類を細かく制御できる：

{
  "channels": {
    "defaults": {
      "heartbeat": {
        "showOk": false,
        "showAlerts": true
      }
    }
  }
}

showOk: false（デフォルト） — 異常なし（HEARTBEAT_OK）のときは通知しない
showAlerts: true（デフォルト） — 異常があったときだけ通知する

この設定なら「問題があったときだけTelegramに通知が来る」という動作になる。

営業時間の設定

「深夜3時に通知が来ても困る」という場合は、Heartbeatが動く時間帯を制限できる。

{
  "agents": {
    "defaults": {
      "heartbeat": {
        "every": "30m",
        "target": "telegram",
        "activeHours": {
          "start": "08:00",
          "end": "22:00"
        }
      }
    }
  }
}

この設定なら、朝8時から夜10時の間だけHeartbeatが動き、それ以外の時間はスキップされる。スマホの「おやすみモード」のような感覚。

注意: activeHours はHEARTBEAT.mdの中に書くのではなく、openclaw.json に書く。

最初のHeartbeatを設定する

まずは最もシンプルなHeartbeatを設定してみる。

手順1: HEARTBEAT.mdファイルを作成する

場所は ~/.openclaw/workspace/HEARTBEAT.md（Part 2でセットアップしたworkspaceフォルダの中）。

以下の内容を書く：

# Heartbeat タスク

## 毎朝のルーティン
- [ ] 朝7:00〜8:00の間に、「おはようございます。今日も良い1日を！」と送る
- [ ] 天気予報を調べて一緒に送る
- [ ] 上記は1日1回だけ実行する

## 常時チェック
- [ ] ディスク使用量が90%を超えていないか確認する
- [ ] 超えていたら警告メッセージを送る

手順2: openclaw.jsonに通知先と営業時間を追加する

{
  "agents": {
    "defaults": {
      "heartbeat": {
        "every": "30m",
        "target": "telegram",
        "activeHours": {
          "start": "07:00",
          "end": "22:00"
        }
      }
    }
  }
}

手順3: ゲートウェイを再起動する

openclaw gateway restart

補足: HEARTBEAT.mdの中身を後から編集した場合は、再起動は不要。次のHeartbeatのタイミング（最大30分後）で自動的に新しい内容が読み込まれる。ただし、openclaw.json の設定（every や target 等）を変更した場合は再起動が必要。

動作確認の方法

設定後すぐに動作を確認したい場合は、ログを監視する：

openclaw logs --follow

Heartbeatが動くと、ログにタスクの実行結果が記録される。実際にTelegramに通知が届くのは条件に合致したときのみ。「朝7:00〜8:00」と書いた場合、翌朝7時台のHeartbeatでTelegramに「おはようございます」が届いたら、自律動作の第一歩が成功。

知っておくべき注意点

1. PCの電源が入っていないと動かない

Heartbeatは秘書がPC内で動いているからこそ機能する。PCがスリープ中や電源オフだと、秘書も一緒に寝てしまう。Mac miniなど常時起動のPCがあると理想的（これは講座最終回で触れる）。

2. Heartbeatのたびにコストが発生する

Heartbeatが1回実行されるたびに、秘書はAIに問い合わせてタスクの内容を判断する。30分間隔で1日19時間稼働（activeHours設定）だと、1日に約38回のAPI呼び出しになる。

モデルごとの目安コスト（1日あたり）：

Haiku（軽量モデル）: 約$0.02（約3円）
Sonnet（標準モデル）: 約$1〜3（約150〜450円）
Opus（高性能モデル）: 約$5（約750円）

チェック項目を増やすとHEARTBEAT.mdの文字数が増え、1回あたりのコストも上がる。最初は3〜5項目から始めて、慣れてきたら増やすのがおすすめ。

既知の注意点: 公式ドキュメントには「Heartbeat用に軽量モデルを指定できる」と書かれているが、現時点ではこの設定が正しく動作しないバグが報告されている。メインのモデル（Sonnet等）がそのまま使われるため、コストが想定より高くなる場合がある。

3. HEARTBEAT.mdにパスワードやAPIキーを書かない

HEARTBEAT.mdの内容は毎回のAPI呼び出しに含まれる（AIに読ませるため）。パスワードやAPIキーなどの秘密情報を書くと、外部に送信されてしまう。やりたいことだけを日本語で書き、秘密情報は .env ファイルなど別の安全な場所で管理する。

ゴール状態

HEARTBEAT.mdの書き方を理解している
通知先（target）と営業時間（activeHours）を openclaw.json で設定できた
Heartbeatのコストと注意点を把握している
「秘書が自分から動く」を翌朝に体験する準備ができている