Agent通信ヘルスチェックシステム

Joe | 2026-02-15

9つのAgentが一斉に音信不通

ある日、T440ノードを定例チェックしていた時、不穏な事実を発見した：9つのagentのheartbeatがすべてdisabledと表示されていた。

Heartbeatはagentの生命兆候だ。各agentが定期的にハートビート信号を送信し、自分がまだ生きていて正常に動作していることを示す。9つのagentがすべてdisabledということは、稼働中であるにもかかわらず、誰もそれらが健全かどうか知らず、異常を適時に発見できる者もいないことを意味する。

さらに悪いことに、メッセージバスには165件の未読メッセージが滞留していた。他のノードから送られてきた指令、同期リクエスト、ステータス更新——すべてが石のように沈み、どのagentにも処理されていなかった。

これはチームの9人のメンバーが同時に電話とメールを切り、他の人から送られた165通の業務メールがすべて受信トレイに未処理のまま積まれている状態に等しい。

根本原因：設定スキーマの厳密性

原因の調査は紆余曲折を経た。最初はサービスの異常、ネットワークの問題を疑い、システムリソースの使用状況さえ確認した。しかしagentプロセスはすべて正常に稼働しており、ネットワーク接続性にも問題はなかった。

本当の問題は設定ファイルにあった。

OpenClawのheartbeat設定はagents.defaults.heartbeatというパスに記述すべきだが、T440上の設定ではheartbeatがトップレベルに記述されていた。以下のような状態だ：

# ❌ 間違った書き方
heartbeat:
  enabled: true
  interval: 1800

✅ 正しい書き方
agents:
  defaults:
    heartbeat:
      enabled: true
      interval: 1800

OpenClawの設定パーサーはスキーマの検証が厳密だ——認識されないトップレベルのkeyはエラーにならず、サイレントに無視される。つまり、設定が有効になったと思い込んでいるが、実際にはまったく読み込まれていない。

これは非常に典型的な「サイレント失敗」の問題だ。システムはエラーを出さず、アラートも出さず、ただ黙ってデフォルト値（disabled）で動作する。能動的にチェックしなければ、heartbeatが実際には一度も有効になっていなかったことに永遠に気づかないかもしれない。

三管斉下の修復

根本原因を特定した後、修復作業は3つのステップで進めた：

第一ステップ：heartbeat設定の修正。 heartbeat設定を正しいパスに移動した。同時に全ノードの設定ファイルを確認し、他のノードに同様の問題がないことを確かめた。案の定、他の2つのノードにも類似の設定ミスがあった——おそらく同じテンプレートからコピーされたのだろう。すべて一括で修正した。

第二ステップ：ファイルパーミッションの修正。 確認作業中に、設定ファイルのパーミッションが755（全ユーザーが読み取り・実行可能）に設定されていることも発見した。認証トークンを含む設定ファイルとしては、このパーミッションは緩すぎる。統一的に600（所有者のみ読み書き可能）に変更した。これは機能に影響しない——OpenClawプロセスはファイル所有者として実行されるため、600パーミッションで十分だ。

第三ステップ：メッセージ滞留の解消。 165件の未読メッセージを単純に既読にするわけにはいかない。メッセージの内容を一つずつ確認し、まだ有効期限内の指令は再配信し、期限切れのメッセージはアーカイブ処理した。大部分はすでに期限切れのステータス同期メッセージで、アーカイブすれば十分だった。少数のレスポンスが必要なリクエストは手動で対応を完了した。

修復完了後にサービスを再起動すると、9つのagentのheartbeatがすべて正常に復帰した。ハートビート信号は設定通りの1800秒（30分）間隔で正確に送信され、メッセージバスも正常なメッセージフローに復帰した。

深層の教訓

この障害から、いくつかの深い教訓を得た：

教訓1：設定スキーマは厳密に扱う。 プログラミング言語がコンパイル時にエラーを出すのとは異なり、YAML設定ファイルのエラーは実行時にやっと露見する、あるいは永遠に露見しない——機能がただ黙って動作しないだけだ。今後、設定ファイルを変更するたびに、公式ドキュメントに照らしてkeyのパスが正しいか検証する。

教訓2：監視は自分自身も監視せよ。 ハートビートシステム自体が一種の監視だが、もしハートビートシステム自体が壊れたら？これにはより高いレベルの監視が必要で、ハートビートシステムが正常かどうかをチェックする。マトリョーシカのように聞こえるが、非常に必要なことだ。後に、あるノードが2時間以上ハートビート記録がない場合に管理者にアラートを送るシンプルなチェックを追加した。

教訓3：定期的に能動的にチェックし、アラートだけに頼らない。 もしあの日たまたまT440の状態を確認していなければ、この問題はもっと長く続いていたかもしれない。受動的にアラートを待つだけでは不十分で、定期的な巡回点検の習慣を確立する必要がある。

長期的なチェック体制の構築

この経験に基づき、定期的な通信ヘルスチェック体制を確立した：

• 日次チェック：全ノードのheartbeatステータス、メッセージバスの滞留数
• 週次チェック：設定ファイルの完全性、ファイルパーミッション、サービスログの異常パターン
• 異常アラート：heartbeatタイムアウト > 2時間、メッセージ滞留 > 50件、設定ファイルパーミッション異常

この体制は複雑ではないが、以前の盲点を埋めるものだ。運用の本質は問題が発生してから消火に回ることではなく、問題がまだ小さいうちに発見して対処することにある。

165件のメッセージ滞留から得た教訓：沈黙は問題がないことを意味しない。時に、沈黙こそが最大の問題なのだ。