Container Host AIops

コンテナホスト AIops

免責事項：コミュニティによって保守されているオープンソースプロジェクトです。Docker, Inc.、Portainer.io、またはいかなるコンテナプラットフォームベンダーとも提携、承認、後援の関係にありません。「Docker」、「Portainer」およびすべての製品名・商標名は、それぞれの所有者に帰属します。MIT ライセンスです。

オーケストレーターを使用しないコンテナホスト向けのガバナンス付き AI 運用です。対象は、ローカルの Unix ソケットまたは TCP ホスト経由の Docker Engine API、管理 API（Docker のプロキシも行います）を備えた Portainer、および Docker 互換 API と libpod ネイティブエンドポイントを提供する rootful/rootless サービスソケットを備えた Podman です。ガバナンスハーネスを内蔵しており、MCP と CLI の両方にわたる統合監査ログ、暴走／予算に対するセーフティガード、取り消しトークンの記録を備えています。すべての操作を記録しますが、書き込みを許可するかどうかは判断しません。それはエージェントまたはアカウントが判断します。設計段階からマルチプラットフォームに対応しています。platform をキーとするレジストリにより、ターゲットごとの platform フィールド（docker／portainer／podman）で API の形式を選択でき、将来的に別のホストファミリーを追加しても ops／CLI／MCP レイヤーに変更は不要です。稼働中の Docker Engine 27.5.1 デーモンで動作を検証済みです（doctor、overview、主要な3つの分析、監査と取り消しの記録を伴うガバナンス付きの stop_container）。Portainer と Podman の API パスはモックテストスイートでのみカバーしています。

機能

主要なシグネチャ分析3種類と、それらを支えるガード付きの読み取り・書き込み機能を備えています。

• 再起動ループの根本原因分析 — コンテナの再起動回数と終了コードを調べ、クラッシュループしているコンテナ（restartCount がしきい値を超える、再起動中または停止状態、終了コードがゼロ以外）を検出します。終了コード（137 OOM／SIGKILL、143 SIGTERM、139 セグメンテーション違反、127 不正なエントリーポイントなど）から、それぞれに考えられる原因と対処方法を紐付け、ログの末尾も表示します。各順位には根拠となる数値が含まれ、ブラックボックス的な判定にはなりません。
• リソース圧迫分析 — 実行中のコンテナごとに CPU％／メモリ％を一度だけサンプリングし、設定済みの制限と比較します。しきい値の80％以上を「近い」、しきい値を超えるものを「超過」として検出し、制限の引き上げ、未設定のメモリ制限の設定、スケールアウトなどを推奨します。
• イメージとボリュームの肥大化 — system/df から未使用のイメージ、未使用のボリューム、ビルドキャッシュを取得し、削除候補と回収可能なバイト数を合計します。

対応機能

• CLI（container-host-aiops ...）：init、overview、container、image、volume、network、system、stack、pod、analyze、manage、secret、doctor、mcp。
• MCP サーバー（container-host-aiops mcp または container-host-aiops-mcp）：38個のツール（読み取り29個、書き込み9個）。すべてに付属の @governed_tool ハーネスを適用しています。
• 接続レイヤー：Docker は Unix ソケット（httpx.HTTPTransport(uds=...)）または TCP ホスト経由で接続します。Portainer は X-API-Key トークンを使って HTTPS 経由で接続します。このトークンは、管理対象エンドポイントの Docker API へのプロキシにも使用されます。Podman は rootful/rootless サービスソケット（自動検出：まず $XDG_RUNTIME_DIR/podman/podman.sock、次に /run/podman/podman.sock）経由で接続し、Docker 互換レイヤー（パスを全面的に再利用）に加えて libpod ネイティブエンドポイントを使用します。ローカルの Docker／Podman ソケットにはシークレットは不要です。境界となるのはソケットのファイル権限です。
• 暗号化された認証情報：Portainer API トークンは、暗号化ストア ~/.container-host-aiops/secrets.enc（Fernet + scrypt）に保存され、ディスク上に平文で保存されることはありません。マスターパスワードは、CONTAINER_HOST_AIOPS_MASTER_PASSWORD（MCP／CI）から取得するか、対話形式のプロンプト（CLI）で入力して解除します。
• 可逆性：変更を伴う書き込みでは、まず実際の変更前状態を取得し、忠実な逆操作を記録します（stop↔start、update_container は以前の CPU／メモリ制限を復元します）。取り消し不能な操作（remove_container、prune_images、prune_volumes、recreate_stack）では、監査のために変更前状態を取得しますが、取り消し操作は定義しません。
• 安全性：状態を変更する CLI 操作はすべて --dry-run に対応しており、二重確認が必要です。MCP の書き込みツールはすべて dry_run プレビューを受け取ります。削除のプレビューでは、実行前に削除対象と回収可能なバイト数を一覧表示します。

このツールが判断すること、判断しないこと

コンテナホストの操作（読み取りと書き込み）を正確かつ効率的に実行し、そのすべてを記録します。書き込みを許可するかどうかは判断しません。それはエージェントの判断、または接続先アカウントの権限によります。読み取り専用でマウントした Docker ソケットを指定するか、書き込みスコープのない Portainer アカウントを使用すれば、書き込みは権限を実際に管理するサーバー側で失敗します。

そのため、読み取り専用スイッチも、ポリシーファイルも、設定する承認ゲートもありません。このツールが保証するのは、何も黙って実行されないことです。MCP 経由でも CLI 経由でも、すべての呼び出しが監査行として ~/.container-host-aiops/audit.db に記録され、破壊的な書き込みでは、変更前の状態を取得し、可能な場合は逆操作も記録します。

各ツールは risk_level を宣言します。この値はテストによって [READ]／[WRITE] のドキュメントタグと一致するよう保たれ、説明用の区分として監査行に記録されます。そのため、レビュー担当者は行が高リスクの削除を示すものかどうかを一目で確認できます。これはラベルであり、ゲートではありません。

機能マトリックス（MCP ツール 38 種）

ドメイン	ツール	数	R/W
概要	overview	1	読み取り
コンテナ	list_containers、inspect_container、container_logs、container_stats、container_top、container_restart_summary	6	読み取り
イメージ	list_images、inspect_image、dangling_images、image_disk_usage	4	読み取り
ボリューム	list_volumes、inspect_volume、dangling_volumes	3	読み取り
ネットワーク	list_networks、inspect_network	2	読み取り
システム	system_info、system_version、system_df、system_events	4	読み取り
スタック	list_endpoints、list_stacks、stack_detail（Portainer）、list_compose_stacks（docker+podman）	4	読み取り
Pod（Podman）	list_pods	1	読み取り
分析（主力機能）	restart_loop_rca、resource_pressure_analysis、image_and_volume_bloat	3	読み取り
書き込み	remove_container、prune_images、prune_volumes、recreate_stack	4	書き込み（高）
	restart_container、stop_container、start_container、update_container	4	書き込み（中）

3 つの分析機能は、オフライン分析用にデータを渡すことも、設定済みのターゲットからライブデータを取得することもできます。list_endpoints／list_stacks／stack_detail には portainer ターゲットが必要です。list_compose_stacks（com.docker.compose.project ラベルによる Compose プロジェクトの集約と、スタックごとのヘルス情報）は docker または podman で動作します。list_pods には podman ターゲットが必要です（Docker／Portainer には Pod の概念がありません）。

プラットフォーム対応マトリックス

機能	docker	portainer	podman
コンテナ／イメージ／ボリューム／ネットワーク／システムの読み取り	✅	✅（プロキシ経由）	✅（互換）
主力の分析機能（再起動ループの RCA、リソース圧迫、肥大化）	✅	✅	✅（互換）
ライフサイクルおよび prune 書き込み（stop/start/restart/remove/update/prune）	✅	✅	✅（互換）
Compose スタックの集約（list_compose_stacks）	✅	✅（プロキシ経由）	✅
Portainer エンドポイント／スタック／recreate_stack	—	✅	—
Podman Pod（list_pods、libpod）	—	—	✅

クイックスタート

Claude Code プラグインとして

1 回のインストールで、エージェントにスキルと MCP サーバーの両方を導入できます。

/plugin marketplace add AIops-tools/marketplace
/plugin install container-host-aiops@aiops-tools

MCP サーバーは uv で取得され、このプラグインが宣言するパッケージバージョンに固定されます。そのため、監査行から、それを書き込んだコードをたどることができます。認証情報は引き続き container-host-aiops init で設定します。下記をご覧ください。

OpenClaw プラグインとして

同じバンドルが ClawHub で公開されており、1 回のインストールでスキルと MCP サーバーをまとめて導入できます。

openclaw plugins install clawhub:@zw008/container-host-aiops
openclaw skills info container-host-aiops          # expect: Visible to model: yes

その後、OpenClaw ゲートウェイを再起動して、プラグインを読み込ませてください。MCP サーバーは uv で取得され、この正確なリリースに固定されているため、uvx が PATH 上にある必要があります。ない場合でもスキルはインストールされますが、Visible to model: no と報告されます。認証情報は以下とまったく同じ方法で設定します。

CLI またはスタンドアロン MCP サーバーとして

uv tool install container-host-aiops          # or: pipx install container-host-aiops
container-host-aiops init                      # wizard: add a Docker/Podman socket or Portainer target
container-host-aiops doctor                    # verify config, secrets, connectivity
container-host-aiops overview                  # one-shot host health
container-host-aiops analyze restart-loop      # crash-looping containers + cause/action
container-host-aiops container list --running  # running containers

MCP サーバーとして実行する場合（stdio）：

export CONTAINER_HOST_AIOPS_MASTER_PASSWORD=...   # only needed for Portainer targets
container-host-aiops-mcp

そのパスワードの保存場所について：エクスポートされた変数は、このシェルが起動するすべてのプロセスから読み取り可能であり、シェル履歴にも記録されます。共有ホストや長時間稼働するホストでは、対話型プロンプトを使用するか、必要な 1 つのコマンドの実行中のみ、シークレットマネージャーから注入してください。

ガバナンス

すべての操作（MCP と CLI の両方）は、同梱の @governed_tool ハーネスを通過します。ハーネスは記録を行いますが、認可は行いません（上記を参照）。

• 監査 — すべての呼び出し（パラメーター、結果、ステータス、所要時間、リスクティア、オペレーターが指定した承認者や根拠があればその情報）は、~/.container-host-aiops/audit.db に記録されます（CONTAINER_HOST_AIOPS_HOME で保存先を変更できます）。CLI は MCP 経由の場合と同じ行を書き込むため、監査されないエントリポイントはありません。
• 暴走防止ガード — 認可ゲートではなく、安全対策です。同じ呼び出しが短い間隔で繰り返されるとサーキットブレーカーが作動し、停止したエージェントによる無制限の呼び出しや実行時間の消費を防ぎます。CONTAINER_HOST_RUNAWAY_MAX=0 で無効にできます。任意で CONTAINER_HOST_MAX_TOOL_CALLS / CONTAINER_HOST_MAX_TOOL_SECONDS による上限も設定できます。
• 取り消しの記録 — 元に戻せる書き込みでは、取得した変更前の状態に基づいて、逆操作の記述子が記録されます。
• リスクティア — risk_level から導出される、監査行に付与される説明用のラベルです。ゲートとしては機能しません。

対象範囲

これは AIops-tools ファミリー（監査・予算・取り消し機能を備えたガバナンス付き AI 運用）の container-host メンバーで、単一ホストの Docker / Portainer / Podman を対象としています。クラスターオーケストレーター、ハイパーバイザー、ストレージアプライアンス、バックアップ製品、OT / 産業用エッジ向けではありません。これらは別のツール／ラインです。

必要な機能がありませんか？

対応範囲は、Docker Engine + Portainer + Podman（libpod）API の厳選したサブセットです。必要な呼び出しがない場合や、別のコンテナホストファミリーへの対応を希望する場合は、イシューまたは PR を作成してください。コントリビューションを歓迎します。

検証状況

• Docker — 稼働中の Docker Engine 27.5.1 デーモンで実行して検証しました。doctor と overview はローカルソケット経由で接続しました。restart-loop とイメージ／ボリュームの bloat 分析は、実際にクラッシュループしているコンテナと、実際に再利用可能なデータを対象に実行しました。また、ガバナンス付きの stop_container により、監査 DB に行が書き込まれ、機能する取り消し記述子が記録されることを確認しました。
• Portainer と Podman — モックによる検証のみです。これらの API パスは各プロジェクトの公開 API の仕様に基づいてモデル化されており、稼働中のサーバーでは実行されていません。
• モックテストスイートで保証される内容、Docker の実行ですでに確認できた内容、Portainer / Podman での実行によって今後確認する必要がある内容を含む、完全なチェックリストは docs/VERIFICATION.md にあります。container-host-aiops doctor は、どのプラットフォームでも最も手早く実行できるライブチェックです。