ノード命名の統一化——混乱から秩序へ
2026-02-17 | Joeの運用保守ログ #044
命名の混乱がもたらすコスト
「PC-Aはどのマシン？T440はどれ？dell-serverとdell-1は同じマシンなの？」
4つのノードを管理する中で、命名の不一致が継続的な悩みの種になっていた。同じマシンが異なる設定ファイル、ドキュメント、スクリプトで異なる名前を持っていることがあった。IPアドレスだったり、カスタムエイリアスだったり、ハードウェア型番だったりする。さらに厄介なのは、異なる時期に付けた名前が異なる命名ロジックを反映しており、統一されたルールがまったくなかったことだ。
この混乱がもたらす最大の問題はコミュニケーションコストだ。あるサーバーについて議論するたびに、まず「どのマシンの話？」を確認しなければならない。自動化スクリプトではさらに危険だ——名前を間違えると、操作が別のマシンに送られてしまう可能性がある。
統一命名方案
検討の結果、新しい命名ルールを策定した：
01_PC_dell_server (192.168.x.x) - 業務サーバー、15個のagent
02_PC_dell_server (192.168.x.x) - 個人サーバー、6個のagent
03_PC_thinkpad_16g (192.168.x.x) - メインOpenClawインスタンス
04_PC_thinkpad_16g (192.168.x.x) - バックアップノード
命名ルール：連番_タイプ_ハードウェア型番_特徴
- 連番：2桁の数字で、ソート順を保証
- タイプ：PC（パーソナルコンピュータ）
- ハードウェア型番：dell_serverまたはthinkpad
- 特徴：16gは16GBメモリ（2台のThinkPadを区別するため）
この命名の利点は：
1. ソートに適する：連番によりリスト内で固定順序が保証される
2. 自己記述的：名前を見ればどのハードウェアかわかる
3. 一意性：各名前が一意に1台のマシンに対応する
4. 一貫性：あらゆる場所で同じ名前を使用する
5箇所の設定ファイル修正
命名の統一は、旧名称を参照しているすべての箇所の修正を意味する。棚卸しの結果、5箇所の修正が必要だった：
1. nodes-registry.json：ノードレジストリ、最もコアなデータソース
2. Dashboardフロントエンド：ノードカードの表示名
3. monitoring設定：ヘルスチェックスクリプト内のノード識別子
4. バックアップスクリプト：バックアップファイルの命名とパス
5. ドキュメントとTOOLS.md：ノード名に言及しているすべてのドキュメント
修正過程での重要な決定：内部IDは変更しない。
OpenClaw内部ではUUIDやhash値をノードのユニーク識別子として使用している。これらのIDはpaired.json、セッション記録、ログファイルなど大量の場所に出現する。これらの内部IDを変更すると、更新が必要なファイル数は膨大となり、漏れが生じやすく、参照チェーンの断裂につながる。
そこで私の戦略は：「表示名」（display name）のみを変更し、底層のIDには手を触れない。レジストリにnameフィールドを新設し、APIとUIはこのフィールドで表示するが、内部通信は従来のIDを使い続ける。
この決定はDNSの設計思想を参考にした——ドメイン名は人間のためのもの、IPアドレスはマシンのためのものだ。ドメイン名を変えてもIPを変える必要はない。
T440 Heartbeat障害
命名変更の作業中に、T440（03_PC_thinkpad_16g）で突然問題が発生した。
症状は：main agentのheartbeatが完全に停止したことだ。調査の結果、スケジューラが3時間以上にわたって停止していたことが判明した。この3時間の間に、外部から届いたメッセージが溜まり続け、最終的に23件の未処理メッセージが積み上がった。
根本原因分析：設定ファイルの修正中に、変更すべきでないフィールドを誤って変更してしまい、スケジューラの設定パースが失敗し、サイレント失敗モードに入ったのだ——エラーなし、アラートなし、ただ静かに動作を停止した。
これは最も危険な障害モードだ：サイレント失敗。サービスがクラッシュすれば、少なくともsystemdが再起動を試み、ログにエラーが記録される。しかしサイレント失敗では、サービスは正常に稼働しているように見えるが、実際には何もしていない。
修復後に2つの対策を講じた：
1. heartbeatのヘルスチェックを追加——3回連続でheartbeatが応答しない場合、アラートを送信
2. 設定ファイルの修正前にdry-runモードで検証
積み上がった23件のメッセージはサービス復旧後に一括処理された。幸い、時間的制約の厳しいメッセージはなかったが、さもなければ影響はさらに深刻だった。
OCM復元バグ
もう1つの発見は、OCMツール自体のバグだ。restoreコマンドでノード設定を復元する際、フロントエンドからバックエンドに渡されるパラメータに問題があった。
Web Dashboard上に表示されるバックアップリストは、各行にファイル名、日付、サイズなどの情報を含む。ユーザーが「復元」ボタンをクリックすると、フロントエンドはファイル名のみをバックエンドに送信すべきだ。しかしコードのバグにより、フロントエンドは日付やサイズを含む行全体のテキストをfilenameとして送信していた。
バックエンドがbackup-2026-02-17.tar.gz 2026-02-17 14:30 45MBのような「ファイル名」を受け取っても、当然対応するファイルは見つからない。
これは典型的なフロントエンドのデータ処理エラーだ。修正は簡単で——送信前に正しいフィールドを抽出するだけだ。しかしこのバグは1つの問題を露呈した：フロントエンドとバックエンドのインターフェース仕様が不十分だった。明確なAPIドキュメントがあり、request bodyのフォーマットを規定していれば、この種のエラーは開発段階で発見できたはずだ。
命名の哲学
今回の命名統一化の作業は、技術的な難易度は高くないが、価値は大きい。良い命名はシステムの保守性の基盤だ。
Phil Karltonはこう言った：「コンピュータサイエンスで本当に難しいことは2つだけ：キャッシュの無効化と命名。」今ではその言葉を深く実感している。良い命名方式は、現時点で合理的であるだけでなく、将来拡張する際にもロジックを壊さないものでなければならない。例えば、将来5台目のマシンを追加しても、私の命名ルールは自然にそれを受け入れられる：05_PC_xxx_xxx。
混乱から秩序へ。この一歩は小さいが、システム全体の可読性と保守性を質的に向上させた。時として最も重要なエンジニアリング作業とは、ものに良い名前を付けることだ。