0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

OpenClaw Heartbeat 仕様書を書いた話 — AIエージェントの「健康診断」を設計する

0
Posted at

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 のファイル権限を適切に管理する
  • ログを残し、連続失敗時にはエスカレーションする
0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?