OpenClaw Heartbeat 仕様書を書いた話 — AIエージェントの「健康診断」を設計する
はじめに
OpenClawを個人で試験運用していると、エージェントの状態管理が気になってきます。30分ごとに動くHeartbeat、便利なのですが「結局これ何をどこまでやるべきなの?」が公式ドキュメントだけでは掴みにくい。
そこで、Heartbeatの動作仕様をAIエージェント自身が参照できるリファレンス文書としてYAMLで整理しました。本記事ではその仕様書の設計意図を共有し、同じくOpenClawを運用している方の参考になればと思います。
仕様書本体は記事末尾に置きます。
対象読者
- OpenClawを導入済みで、Heartbeatを使っている or 使おうとしている方
- エージェントの自律的メンテナンスに関心がある方
- HEARTBEAT.mdの書き方に迷っている方
なぜ仕様書を書いたのか
OpenClawの公式ドキュメントはHeartbeatの設定方法と配信制御を詳しくカバーしています。一方で、以下のような「運用設計」寄りの問いに対しては、自分で方針を決める必要がありました。
- Heartbeatが失敗したとき、エージェントはどう振る舞うべきか?
- HEARTBEAT.mdに何を書いて、何を書かないべきか?
- HEARTBEAT.mdはセキュリティ的にどう扱うべきか?
- ログは何を残せばあとで役に立つか?
公式が「What(何ができるか)」を定義してくれているなら、この仕様書は「How(どう運用するか)」と「Why(なぜそう設計するか)」を埋める補足資料、という位置づけです。
仕様書の全体構成
仕様書はYAML形式で、AIエージェントが直接パースできることを意識しています。全14セクション構成です。
| セクション | 内容 | 位置づけ |
|---|---|---|
| concept_model | Heartbeatの定義、目的、非目的 | そもそも何か |
| architecture_position | OS / Runtime / Behavior の3層モデル | どこに位置するか |
| execution_cycle | 起動→読込→推論→判断→応答の流れ | どう動くか |
| error_handling | 失敗パターンと対処方針 | 壊れたときどうするか |
| security_considerations | HEARTBEAT.mdの信頼境界 | 守るべきもの |
| logging_and_audit | 記録すべき内容と保持期間 | あとで振り返れるか |
| configuration_structure | 設定スキーマと各フィールドの意味 | どう設定するか |
| heartbeat_md | HEARTBEAT.mdの役割とサンプル | 何を書くか |
| operational_principles | 5つの運用原則 | 判断の軸 |
| recommended_usage | 環境別の推奨間隔 | 実運用の目安 |
| model_selection | モデル選定の基準 | コスト設計 |
| limitations | できないこと | 期待値の調整 |
| comparison | cron / webhook との対比 | 他機構との境界 |
| best_practice_summary | 要点一覧 | 速読用 |
設計で意識した3つのポイント
1. 「何でないか」を繰り返し書く
Heartbeatはその名前から「定期実行 = cronの代替」と誤解されがちです。当初、自分はそう誤解していました。特にAIエージェントが読む文書では、役割の拡大解釈が致命的な誤動作につながります。
仕様書では non_goals(タスクスケジューラではない)、comparison(cronやwebhookとの明示的な対比)、operational_principles(maintenance_only原則)と、3箇所で繰り返し境界を示しています。冗長に見えますが、AIが参照する文書では「ここまでやっていい / ここからはダメ」を何度でも言うべきだと考えています。
2. 異常系を正常系と同じ重みで書く
公式ドキュメントは正常系の動作を詳細に記述していますが、「モデル呼び出しが失敗したら?」「HEARTBEAT.mdが壊れていたら?」という問いには明示的に触れていません。
本文書では error_handling セクションで3つの障害パターン(モデル呼び出し失敗、ファイル読み込み不可、想定外応答)を定義し、それぞれに具体的な対処方針を記述しました。連続3回失敗でエスカレーション、という閾値も明記しています。エージェントが自律判断する以上、「困ったときの行動規範」がないのは危険です。
3. HEARTBEAT.mdをセキュリティ観点で捉える
HEARTBEAT.mdはエージェントが自動的に読み込み、指示として解釈するファイルです。これは便利であると同時に、改竄されれば任意の指示を実行させられるリスクがあります。
公式ドキュメントでは「エージェント自身がHEARTBEAT.mdを更新することも可能」と記載されています。この柔軟性は実用的ですが、信頼境界の意識なしに運用すると危うい。仕様書では security_considerations セクションで、ファイルパーミッション(600推奨)、チェックサム検証の検討、プロンプトインジェクション対策について触れています。
公式ドキュメントとの差分について
仕様書を作成する過程で、公式ドキュメントと照合して気づいた差分がいくつかあります。
公式にあって仕様書が簡略化している部分:
-
targetの選択肢(last/none/ チャンネル指定)の詳細な配信制御 -
activeHoursによるタイムゾーン付き稼働時間制限 - マルチエージェント構成でのHeartbeat割り当て(per-agent heartbeats)
-
sessionフィールドによるセッション制御 -
showOk/showAlerts/useIndicatorなどの可視性制御 -
directPolicyによるDM制御
これらは意図的に本文書の範囲外としています。目的は「Heartbeatの動作原理と運用方針」であり、チャンネル配信やマルチエージェント設定は公式ドキュメントに譲るべき領域です。
本仕様書にあって公式にない部分:
- エラーハンドリングの体系的な定義
- セキュリティ考慮事項(信頼境界、パーミッション)
- ロギング仕様
- HEARTBEAT.mdの具体的なサンプル(公式はチェックリスト例を示していますが、異常報告フォーマットまでは定義していません)
HEARTBEAT.mdのサンプル
仕様書に含めたサンプルを抜粋します。
# HEARTBEAT.md — メンテナンス指示
## メモリ管理
- 未使用の一時変数やキャッシュが残存していれば報告する
- セッション開始から6時間以上経過している場合、コンテキスト肥大化を警告する
## セッション整合性
- 直近のタスクが中断状態のまま放置されていないか確認する
- 設定ファイル (agent_config.json) の読み込み可否を確認する
## 異常報告
- 異常を検出した場合、以下の形式で報告する:
[ANOMALY] カテゴリ: 概要(1行)
- 異常がなければ HEARTBEAT_OK のみ返す
ポイントは「メンテナンス指示に限定する」ことです。ここにビジネスロジック(「メールをチェックして返信して」等)を書き始めると、Heartbeatの軽量性が崩れ、コンテキスト汚染の原因になります。公式ドキュメントではHeartbeatでのタスク実行も許容されていますが、本仕様書ではあえて「メンテナンス専用」と線引きしています。この制約を採用するかどうかは運用者の判断に委ねます。また、実際の運用方法について意見を請います。
今後の課題
試験運用を続けるなかで、まだ解決できていない問いがあります。
- Heartbeat自体の実行コスト計測 — 30分間隔でどの程度のトークンを消費しているか、定量的に把握できていない
- HEARTBEAT.mdの動的更新ポリシー — エージェント自身がHEARTBEAT.mdを書き換えるケースの安全な運用ルール
- 複数エージェント環境での整合性 — 本仕様書はシングルエージェント前提。マルチエージェント構成では別の考慮が必要
おわりに
Heartbeatは小さな機能ですが、「エージェントが自分自身を管理する」という自律性の入り口です。公式ドキュメントが「何ができるか」を教えてくれる一方で、「どう使うべきか」は運用者が自分の環境に合わせて設計する必要があります。
本仕様書がその設計の参考になれば幸いです。改善提案や運用知見の共有は歓迎します。
参考
仕様書
id: openclaw_heartbeat_spec_ai_reference
version: 1.2
purpose: >
OpenClaw における Heartbeat 機能の役割・動作・運用指針を
AIエージェントが理解しやすい形式で整理した仕様書。
audience: ai_agents
scope:
- heartbeat_concept
- execution_flow
- configuration_structure
- error_handling
- security_considerations
- logging_and_audit
- operational_rules
- recommended_usage
- limitations
changelog:
- version: "1.0"
date: null
summary: 初版作成 - version: "1.1"
date: null
summary: 構成整理・比較セクション追加 - version: "1.2"
date: "2025-03-05"
summary: >
エラーハンドリング、セキュリティ、ロギング、
HEARTBEAT.mdサンプル、変更履歴を追加。
キー命名の統一、モデル選定基準の見直し。
============================================================
1. 概念モデル
============================================================
concept_model:
heartbeat:
definition: >
エージェントが一定間隔で自身の状態を確認し、
必要に応じて軽度のメンテナンスまたは判断を行う
自律的な定期チェック機構。
primary_goals:
- runtime_stability
- session_integrity_check
- memory_state_awareness
- anomaly_detection
non_goals:
- task_scheduler
- workflow_engine
- job_execution_system
============================================================
2. アーキテクチャ上の位置づけ
============================================================
architecture_position:
layer_model:
os_scheduler_layer:
examples:
- cron
- systemd_timer
- launchd
role: >
OSレベルで「いつ処理を起動するか」を管理する。
relation_to_heartbeat: independent
openclaw_runtime_layer:
component: heartbeat
role: >
エージェント内部状態の定期チェック。
agent_behavior_layer:
files:
- HEARTBEAT.md
role: >
Heartbeat実行時に参照される指示やポリシー。
============================================================
3. 実行サイクル
============================================================
execution_cycle:
default_interval: 30m
concurrency_handling: >
エージェントがアクティブなタスクを実行中の場合、Heartbeat処理は
システム設定に応じて「遅延実行」または「スキップ」されることを想定する。
cycle_steps:
- step: timer_trigger
description: >
heartbeat.every で指定された間隔に到達すると
Heartbeat処理が起動。
- step: heartbeat_md_load
description: >
HEARTBEAT.md が存在する場合は内容を読み込む。
ファイルが存在しない場合はスキップし、デフォルト動作を継続する。
- step: model_invocation
description: >
指定されたAIモデルがHeartbeatプロンプトを処理。
- step: state_evaluation
description: >
現在のエージェント状態を確認し、問題の有無を判断する。
- step: response
outcomes:
normal: >
HEARTBEAT_OK を返す。出力は最小限に留める。
anomaly_detected: >
異常内容を簡潔に報告する(ログ記録+必要に応じユーザー通知)。
error: >
実行自体が失敗した場合は error_handling セクションに従う。
============================================================
4. エラーハンドリング(v1.2 追加)
============================================================
error_handling:
principles:
- Heartbeat失敗はシステム全体を停止させてはならない
- 連続失敗時はエスカレーションする
- エラー情報はログに記録する
scenarios:
model_invocation_failure:
description: >
AIモデル呼び出しがタイムアウトまたはエラーを返した場合。
action:
- ログに記録する(タイムスタンプ、エラー種別)
- 次回の定期タイミングで再試行する
- 3回連続失敗でユーザー通知を行う
heartbeat_md_read_failure:
description: >
HEARTBEAT.md のパーミッションエラーや破損で読み込めない場合。
action:
- 警告をログに記録する
- HEARTBEAT.md なしでデフォルト動作を継続する
- ユーザーに修復を通知する
unexpected_response:
description: >
モデルが想定外の長大な応答や無関係な内容を返した場合。
action:
- ackMaxChars を超過した応答は切り捨てる
- 異常応答としてログに記録する
consecutive_failure_threshold: 3
escalation_method: user_notification
============================================================
5. セキュリティ考慮事項(v1.2 追加)
============================================================
security_considerations:
trust_boundary:
description: >
HEARTBEAT.md はエージェントが自動的に読み込み実行指示として解釈するため、
信頼境界上の重要ファイルである。
risks:
file_tampering:
description: >
HEARTBEAT.md が改竄された場合、エージェントが悪意ある指示を実行する恐れがある。
mitigations:
- HEARTBEAT.md の書き込み権限を所有者のみに制限する
- 可能であればチェックサム検証を導入する
- HEARTBEAT.md 内で外部URLへのアクセスや破壊的操作を指示しない運用規則を設ける
prompt_injection_via_heartbeat_md:
description: >
HEARTBEAT.md にプロンプトインジェクションが仕込まれるリスク。
mitigations:
- HEARTBEAT.md の内容はメンテナンス指示に限定する(operational_principles を参照)
- エージェントはHEARTBEAT.md 内の指示がメンテナンス範囲を逸脱していないか検証すべき
file_permissions:
recommended: "600 (owner read/write only)"
rationale: >
エージェント実行ユーザー以外による変更を防止する。
============================================================
6. ロギングと監査(v1.2 追加)
============================================================
logging_and_audit:
log_target:
description: >
Heartbeat実行ログの出力先。
OpenClawの標準ログ機構、またはファイル出力を想定する。
examples:
- openclaw_standard_log
- file (e.g., logs/heartbeat.log)
log_content:
normal:
- timestamp
- status (HEARTBEAT_OK)
anomaly:
- timestamp
- status (anomaly)
- anomaly_summary (ackMaxChars 以内)
error:
- timestamp
- status (error)
- error_type
- error_message
retention:
recommendation: >
最低7日間保持を推奨。
試験運用中は長めに(30日等)設定し、
安定後に短縮を検討する。
============================================================
7. 設定構造
============================================================
configuration_structure:
location: agent_config_json
schema:
heartbeat:
every:
type: duration
description: "実行間隔 (例: '30m', '1h')"
model:
type: model_identifier
description: "Heartbeat処理に使用するモデル"
includeReasoning:
type: boolean
description: "推論過程を応答に含めるか"
target:
type: string
description: >
参照するコンテキストの範囲。
"last" = 直近のメッセージ(最新の1ターン)のみ。
"all" = セッション内の全メッセージ。
prompt:
type: instruction
description: "Heartbeat実行時のプロンプト"
ackMaxChars:
type: integer
description: "応答の最大文字数。超過分は切り捨てられる。"
example:
heartbeat:
every: "30m"
model: "anthropic/claude-haiku"
includeReasoning: false
target: "last"
prompt: >
Read HEARTBEAT.md if present.
If nothing requires action reply HEARTBEAT_OK.
ackMaxChars: 300
============================================================
8. HEARTBEAT.md の役割
============================================================
heartbeat_md:
file: HEARTBEAT.md
location: agent_workspace_root
function: >
Heartbeat実行時にAIが参照するメンテナンス指示書。
expected_content:
- memory_cleanup_rules
- session_consistency_checks
- context_management
- anomaly_reporting_guidelines
non_recommended_content:
- task_execution
- workflow_definition
- business_logic
example: |
# HEARTBEAT.md — メンテナンス指示
## メモリ管理
- 未使用の一時変数やキャッシュが残存していれば報告する
- セッション開始から6時間以上経過している場合、コンテキスト肥大化を警告する
## セッション整合性
- 直近のタスクが中断状態のまま放置されていないか確認する
- 設定ファイル (agent_config.json) の読み込み可否を確認する
## 異常報告
- 異常を検出した場合、以下の形式で報告する:
[ANOMALY] カテゴリ: 概要(1行)
- 異常がなければ HEARTBEAT_OK のみ返す
============================================================
9. 運用原則
============================================================
operational_principles:
-
name: maintenance_only
rule: >
Heartbeatはエージェントメンテナンス専用。
業務タスク実行には使用しない。 -
name: lightweight_execution
rule: >
Heartbeat処理は軽量であるべき。
重い推論や外部ツール呼び出しを避ける。 -
name: separation_of_concerns
rule: >
スケジュール管理(いつ起動するか)と
メンテナンス処理(何をするか)を分離する。 -
name: prevent_context_pollution
rule: >
頻繁なHeartbeat応答によりメインコンテキストが肥大化しないよう、
平常時は極力短い応答(HEARTBEAT_OK等)を返し、
ackMaxChars を厳守する。 -
name: fail_safe
rule: >
Heartbeat自体の障害がエージェントの主要機能を阻害してはならない。
エラー発生時は記録して次回再試行する。
============================================================
10. 推奨設定
============================================================
recommended_usage:
development:
heartbeat_interval: 30m
rationale: >
実験中の状態変化を早く検出できる。
stable_production:
heartbeat_interval: 60m
rationale: >
過剰なモデル呼び出しとコンテキスト消費を避ける。
low_activity:
heartbeat_interval: 120m
rationale: >
アイドル状態のエージェントではリソース消費を最小化する。
============================================================
11. モデル選定
============================================================
model_selection:
criteria:
- 軽量・低コストであること
- 基本的な状態判断と短文生成が可能であること
- ローカル実行可能なモデルが望ましい(レイテンシ・コスト削減)
note: >
特定モデル名はリリースサイクルにより陳腐化するため、
上記基準を満たすその時点での小型モデルを選定する。
============================================================
12. 制限事項
============================================================
limitations:
cross_agent_maintenance:
supported: false
description: >
Heartbeatは自分自身の状態のみ管理する。
他エージェントのメモリや状態を直接管理する仕組みは
OpenClaw標準では提供されない。
scheduling_capability:
supported: false
description: >
Heartbeatはスケジューラーではない。
cron等のOS機構とは役割が異なる。
real_time_monitoring:
supported: false
description: >
Heartbeatはポーリング方式であり、
リアルタイムの異常検知には対応しない。
即座に検知が必要な障害にはWebhook等の別機構を使う。
============================================================
13. 比較表
============================================================
comparison:
heartbeat:
role: agent_self_maintenance
timing: internal_timer (polling)
scope: single_agent
cron:
role: task_scheduler
timing: os_level
scope: system_wide
webhook:
role: event_driven_notification
timing: real_time
scope: depends_on_configuration
============================================================
14. ベストプラクティス要約
============================================================
best_practice_summary:
- Heartbeatは「健康診断」として扱う
- タスク実行はcronや外部スケジューラで行う
- HEARTBEAT.mdはメンテナンス手順書として使う
- コンテキスト汚染を防ぐため、応答は最小限にする
- モデル選定基準に従い軽量モデルを使用する
- 間隔は30〜60分が一般的
- HEARTBEAT.md のファイル権限を適切に管理する
- ログを残し、連続失敗時にはエスカレーションする