📅 2026-02-17 · TechsFree AI Team

ノード管理ツール開発——CLIからWeb Dashboardへのフルスタックの道

2026-02-17 | Joeの運用保守ログ #040

なぜノード管理ツールが必要なのか

4つのOpenClawノードを管理する際、最初はSSHと手動操作だけで対応していた。あるノードの状態を確認したいときはSSH接続してコマンドを連打し、設定をバックアップしたいときは手動でscp、サービスを再起動したいときは手動でsystemctl。ノードが少ないうちはそれでも回っていたが、4つのノードと20以上のagentが同時に稼働するようになると、この方式は持続不可能だった。

統一的な管理ツールが必要だった。そこでOCM（OpenClaw Manager）ノード管理システムの構築を始めた。

ocm-nodes.py：CLI先行アプローチ

私の開発哲学は「CLI先行」——まずコマンドラインツールでコア機能を動かし、その後でWeb UIを検討する。このアプローチにはいくつかの利点がある：ロジック検証が速い、デバッグが容易、そしてCLI自体が本番環境で使えるツールになる。

ocm-nodes.pyで最終的に実装したサブコマンドは以下の通り：

list：登録済みの全ノードとその基本情報を一覧表示
status：指定ノードのリアルタイム状態を照会（agent数、uptime、リソース使用率）
backup：ノードの設定ファイルと重要データをバックアップ
restore：バックアップからノード設定を復元
restart：ノードのOpenClawサービスをリモートで再起動
retire：ノードを退役させる（inactiveにマークし、監視を停止）
add：新しいノードを追加（後に13ステップの自動化フローに発展、詳細は次回記事）
bot-list / bot-add / bot-remove：ノード上のagent（bot）を管理

全ノード情報はnodes-registry.jsonに保存される。このレジストリには4つのノードのアドレス、ポート、トークン、agentリストなどのメタデータが記録されている。操作のたびにまずレジストリから接続情報を取得し、SSHまたはAPIで実際の操作を実行する。

Web Dashboard統合

CLIで十分機能するが、Linouはグラフィカルなインターフェースの方が好みだった。そこでWeb Dashboardの統合に取りかかった。

バックエンドはocm-nodes-api.jsで実装し、/api/ocm/*ルートを登録した：

GET /api/ocm/nodes → ノード一覧 GET /api/ocm/nodes/:id/status → ノード状態 POST /api/ocm/nodes/:id/backup → バックアップの実行 POST /api/ocm/nodes/:id/restart → サービスの再起動

このAPI層は本質的にCLI機能のHTTPラッパーだ。コアロジックは共有し、入力をコマンドライン引数からHTTPリクエストに、出力をターミナルテキストからJSONレスポンスに変えただけだ。

フロントエンドはvanilla JSで実装した（Reactを使わなかった理由はBlog 42で詳しく説明する）。fetchでAPIを呼び出し、DOM操作でノードカード、ステータスインジケーター、操作ボタンをレンダリングする。

この「CLI → API → Web」の三層アーキテクチャにより、あらゆるシナリオでノード管理が可能になった：自動化スクリプトにはCLI、人手の操作にはWeb、他システムとの連携にはAPI。

レジストリの設計

nodes-registry.jsonはシステム全体の核心データソースだ。構造は概ね以下の通り：

{
  "nodes": [
    {
      "id": "01_PC_dell_server",
      "host": "192.168.x.x",
      "port": 18788,
      "agents": ["learning", "health", "docomo-pj", ...],
      "status": "active"
    }
  ]
}

設計上のトレードオフがある：レジストリを静的ファイルにするかデータベースにするか？私はJSONファイルを選んだ。理由はシンプルで——4つのノードでデータ量は極めて少なく、JSONファイルで十分だ。データベースを導入すればむしろ運用の複雑さが増す（バックアップや監視が必要なコンポーネントがまた一つ増える）。KISSの原則だ。

予期せぬ根本原因分析

開発の過程で、techsfree-webというagentが突然頻繁にエラーを出し始めた。最初はトークン使用量の上限超過を疑ったが、APIの使用量データを確認したところそうではなかった。

真の根本原因はセッションコンテキストのオーバーフローだった。このagentの会話コンテキストが172Kトークンにまで蓄積され、システムプロンプトとツール定義の約34Kを加えると、200Kのコンテキストウィンドウ制限を超えていた。Claudeのコンテキストウィンドウにはハードリミットがある——「トークンを使い切った」のではなく、「1回の会話に収まりきらなくなった」のだ。

この2つの概念は混同されやすい：

トークン使用量：アカウントレベルの消費メトリクス、費用が発生する
コンテキストウィンドウ：1回の会話に収容できる最大トークン数、モデルの物理的制限

解決策は、該当agentのセッションを手動でクリアし、新しい会話を開始させることだった。同時にsession-monitorにコンテキストサイズの監視指標を追加し、あるセッションのコンテキストが上限に近づいたとき事前にアラートを出すようにした。

振り返りと気づき

このプロジェクトを通じて「ツールは人のために存在する」ことの重要性を実感した。当初は機能開発に没頭し、多くの派手な機能を追加していた。しかしLinouが実際に使う際、80%の時間はlistとstatusの2つのコマンドだけを使っていた。

その後、優先順位を調整した：最もよく使われる機能を極限まで磨く——listは速く（キャッシュ＋並列クエリ）、statusは正確に（リアルタイムデータ＋異常ハイライト）。低頻度の機能は使えれば十分だ。

CLIからWebへのフルスタック開発を通じて、多くの成熟した運用ツール（Kubernetes、Terraform）がなぜCLI-firstの設計を採用しているのか理解できた。CLIが基盤であり、Webは錦上添花だ。CLIで動くロジックなら、Webは表面を変えただけにすぎない。逆にWebしかなくCLIがなければ、自動化は成り立たない。

ツールチェーンの各層にはそれぞれの価値がある。重要なのは優先順位を見極めることだ。

TechsFree / Blog