OpenClaw (Moltbot/Clawdbot) ハートビート機能とは？

OpenClaw (旧Moltbot/Clawdbot) は、実用的なローカル自動化（マシンの監視、ドリフトの検出、問題が山積する前の対処）に焦点を当てることで急速に人気を博しました。その約束の中心にあるのが、ハートビート機能です。

ハートビートは、定期的な健全性および状態シグナルです。OpenClawでは、稼働状況のping以上の役割を果たします。それは、階層化された意思決定パイプラインを実行します。

1. まず安価な決定論的チェック（プロセス、ファイル、キューの深さ、APIステータス）
2. 閾値とポリシーに対するルール評価
3. 曖昧さが残る場合にのみオプションのモデルエスカレーション

この「まず安価なチェック、必要な時だけモデル」というパターンは、最近のコミュニティでの議論で開発者が求めていたものと全く同じです。すなわち、より良いコスト管理、より予測可能な動作、そして不必要なLLM呼び出しの削減です。

エージェントインフラストラクチャを構築しているのであれば、これが重要な考え方です。すなわち、ハートビートは、単なる監視イベントではなく、コントロールプレーンのプリミティブであるということです。

OpenClawハートビートアーキテクチャの概要

実行時において、OpenClawのハートビートは通常、5つのステージからなるループとして実装されます。

1. スケジューラがハートビートティックをトリガーします（例：15秒/30秒/60秒ごと）。
2. プローブランナーが決定論的なプローブを実行します。
3. ポリシーエンジンが状態遷移と深刻度を計算します。
4. エスカレーションゲートがLLM/ツールプランナーが必要かどうかを決定します。
5. アクションディスパッチャがアラート、修復タスク、または何もしない操作を発行します。

実際のイベントエンベロープは以下のようになります。

{
  "agent_id": "desktop-a17",
  "heartbeat_id": "hb_01JX...",
  "ts": "2026-02-11T10:18:05Z",
  "probes": {
    "cpu_load": 0.72,
    "disk_free_gb": 21.4,
    "mail_queue_depth": 0,
    "service_api": {
      "status": 200,
      "latency_ms": 83
    }
  },
  "policy": {
    "state": "degraded",
    "reasons": [
      "disk_free_below_warn"
    ]
  },
  "escalation": {
    "llm_required": false,
    "confidence": 0.93
  }
}

主要なシステム動作は以下の通りです。

• 決定論的なプローブ結果が主要な真実です。
• ポリシーの出力は再現可能でテスト可能です。
• LLMの使用は限定的で監査可能であり、厳格なゲートによって制限されます。

実装における「まず安価なチェック」とは

OpenClawでは、安価なチェックは以下の条件を満たす必要があります。

• 低遅延（数ミリ秒から数百ミリ秒）
• 低コスト（モデルトークンの消費なし）
• 決定論的（同じ入力 => 同じ出力）
• デフォルトで副作用なし

一般的なプローブカテゴリ：

• ローカルランタイム：プロセス生存、メモリ負荷、スレッド数
• I/O健全性：ディスク空き容量、inode負荷、パーミッション変更
• 統合健全性：ターゲットAPIステータスコード、タイムアウト、p95レイテンシ
• タスク健全性：キューラグ、リトライストーム指標
• ポリシー前提条件：有効な資格情報、証明書有効期限ウィンドウ

プローブコントラクト

ダウンストリームのロジックを安定させるため、厳密なプローブスキーマを使用します。

yaml ProbeResult: name: string ok: boolean observed_at: datetime value: number|string|object|null severity_hint: info|warn|critical error: string|null ttl_ms: integer

ttl_msは重要です。データが十分に新しい場合、バースト発生時の重複チェックをスキップします。

OpenClawがモデル推論にエスカレートすべき時

モデルエスカレーションは、決定論的ロジックが安全に判断できない場合にのみ発生すべきです。

良いエスカレーションのトリガー：

• 矛盾するプローブシグナル（APIは200だがビジネスKPIが崩壊している場合）
• 既知のシグネチャに一致しない新規のエラークラスター
• 制約下での多段階修復計画
• インシデントに対する人間が読める要約の生成

悪いエスカレーションのトリガー：

• すべての警告イベント
• 既知のランブックがある静的閾値違反
• デバウンスでノイズが解決されるような高頻度のフラッピング

ステートマシン設計：アラートのフラッピングを回避する

ほとんどのハートビートの問題は、不安定な状態遷移から生じます。ヒステリシスを持つステートマシンを使用します。

• healthy
• degraded
• critical
• recovering

遷移ルールには以下を含めるべきです。

• エントリー閾値（例：ディスク空き容量 < 15% => degraded）
• 終了閾値（例：3インターバルでディスク空き容量 > 20% => healthy）
• デバウンスウィンドウ（N個の連続サンプル）
• アクションクールダウン（繰り返しの修復を避ける）

例：

yaml transitions: healthy->degraded: condition: disk_free_pct < 15 consecutive: 2 degraded->critical: condition: disk_free_pct < 8 consecutive: 1 degraded->healthy: condition: disk_free_pct > 20 consecutive: 3 critical->recovering: condition: remediation_applied == true recovering->healthy: condition: disk_free_pct > 20 consecutive: 2

これにより、ノイズの多い振動が大幅に減少します。

ハートビートの取り込みと制御のためのAPI設計

ハートビートAPIを公開する場合、可能な限り明示的かつ冪等に保ちます。

推奨されるエンドポイント：

• POST /v1/heartbeats — ハートビートイベントを取り込む
• GET /v1/agents/{id}/status — 最新の計算済み状態
• POST /v1/heartbeats/{id}/ack — オペレーターによる確認応答
• POST /v1/policies/simulate — サンプルペイロードに対するポリシーのドライラン

エージェントハートビートのセキュリティ境界

サンドボックス化と安全なエージェント実行に関するコミュニティの関心が高まっているのは当然のことです。ハートビートはしばしばアクションをトリガーするため、セキュリティ境界は交渉の余地がありません。

最小限の制御：

• 署名付きハートビートペイロード（HMACまたはmTLS識別）
• エージェントごとのスコープトークン（最小権限）
• ポリシー/アクションの許可リスト（任意のツール呼び出しなし）
• 修復のためのサンドボックス化された実行
• すべての状態遷移とアクションに対する監査証跡

モデルが関与する場合：

• LLM出力を信頼できない計画テキストとして扱う
• スキーマとポリシーに対してツール呼び出しを検証する
• 実行前に決定論的なガードチェックを要求する

要するに、ハートビートの検出は柔軟であることができますが、ハートビートアクションは制約されなければなりません。

可観測性とデバッグ戦略

ハートビートシステムをデバッグするには、まず以下のメトリクスを計測します。

• ハートビートの取り込み率
• 遅延/欠落ハートビートの比率
• タイプごとのプローブ遅延
• ポリシー評価遅延
• エスカレーション率（%）
• エージェント/日あたりのモデルトークン消費量
• 誤検知および見逃しインシデントラベル

ApidogによるOpenClawスタイルのハートビートAPIのテスト

ハートビートシステムは、不正なペイロード、リプレイイベント、競合状態といった境界で失敗します。Apidogは、これら境界を1つのワークスペースでテストするのに役立ちます。

実用的なフロー：

1. ApidogのビジュアルデザイナーでOpenAPIを使ってハートビートエンドポイントを定義します。
2. 正常、遅延、重複、破損したハートビートイベントのテストシナリオを構築します。
3. 状態遷移とアクション出力に視覚的なアサーションを追加します。
4. ダウンストリームチャネル（Slack/Webhook/修復サービス）を動的応答でモックします。
5. CI/CDでスイートを実行し、リグレッションゲートとして機能させます。

テストケースの例

• ingest_valid_heartbeat_returns_200
• duplicate_idempotency_key_no_duplicate_action
• critical_state_triggers_single_alert_with_cooldown
• invalid_signature_returns_401
• novelty_trigger_causes_model_escalation_when_enabled

Apidogは設計、テスト、モック、ドキュメント作成を統合しているため、ハートビートロジックの進化に合わせてAPIコントラクトと動作が常に一致します。

もしあなたのチームが現在、これを複数のツールに分けて行っているなら、Apidogに統合することで、ずれをなくし、デバッグを迅速化できます。

エンジニアが見落としがちなエッジケース

クロックスキュー

• エージェントのタイムスタンプはずれる可能性があります。
• 制限されたずれを許容し、サーバーが受信した時間を別途保存します。

ネットワークパーティション

• ハートビートは再接続後にバースト的に届くことがあります。
• シーケンス番号と再順序付けウィンドウを使用します。

バックプレッシャーストーム

• ポリシーエンジンが遅くなると、キューが遅延を増幅する可能性があります。
• アドミッションコントロールを適用し、段階的に機能低下させます。

サイレントプローブ障害

• 「データなし」は「正常」ではありません。
• 不明な状態を明示的にエンコードします。

暴走する修復ループ

• アクションが同じアクションを繰り返しトリガーする状態を引き起こします。
• アクションごとのクールダウンと最大再試行予算を追加します。

エスカレーション結果におけるモデルのドリフト

• モデル支援による決定のために評価フィクスチャを保持します。
• モデル/バージョンの変更時に再検証します。

移行に関する注意：Moltbot/ClawdbotからOpenClawへの命名変更

名称変更の経緯により、パッケージ名、ドキュメント、エンドポイントのプレフィックスに混乱が生じました。統合を維持している場合：

• 非推奨期間中は後方互換性のあるエイリアスを保持します。
• イベントスキーマを明示的にバージョン管理します（event_version）。
• 移行マップ（古いトピック名 -> 新しいトピック名）を公開します。
• レガシーおよび現在のペイロードの両方に対してコントラクトテストを追加します。

これにより、コミュニティがOpenClawの命名に収束する間、エコシステムの中断が軽減されます。

推奨される本番環境のベースライン

ハートビートの展開における健全なデフォルトが必要な場合：

• 間隔：30秒
• プローブタイムアウト：各500ミリ秒、合計2秒の予算
• デバウンス：2回連続の失敗で警告
• クールダウン：アクションタイプごとに5分
• エスカレーション上限：ハートビートの最大5%がモデルを呼び出す
• 保持期間：監査用に30日間ホット、180日間コールド

その後、ワークロードごとに調整します。開発者のデスクトップエージェントとサーバーエージェントは通常、異なるポリシーを必要とします。

最終的な要点

OpenClawのハートビート機能は、エージェントの健全性をチャット優先のワークフローではなく、規律ある制御ループとして扱うため、価値があります。成功するパターンは明確です。

• まず決定論的なプローブ、
• 次に明示的なポリシー状態マシン、
• 不確実性がある場合にのみモデルエスカレーション。

この設計により、コストが低減され、予測可能性が高まり、より安全な自動化が実現されます。

ハートビートAPIを実装する際は、コントラクト、冪等性、ポリシーシミュレーション、およびテスト自動化に重点的に投資してください。Apidogは、OpenAPI仕様の設計、依存関係のモック、回帰テストの実行、ドキュメントの公開を1か所で行えるため、ここで非常に適しています。

現在OpenClawスタイルのハートビートを構築または統合している場合、まず厳密な決定論的ルールから始め、モデルのインテリジェンスは段階的に追加してください。信頼性はまず制約から生まれ、次にインテリジェンスが続きます。