XCP-ng AIops

XCP-ng AIops

免責事項：コミュニティによって保守されているオープンソースプロジェクトです。Vates、XCP-ng プロジェクト、Xen Orchestra プロジェクトとは提携、承認、後援の関係にありません。「XCP-ng」、「Xen Orchestra」、「Xen」は、それぞれの所有者の商標です。MIT ライセンスで提供されています。

Xen Orchestra の REST API を介した、AI を活用した XCP-ng の運用。組み込みのガバナンスハーネスを備え、統合監査ログ、ポリシーエンジン、トークン／暴走予算ガード、取り消しトークンの記録、説明的なリスク階層を提供します。VM の健全性、ストレージの逼迫、バックアップの失敗、パッチ適用状況を AI エージェントでトリアージしたい、ホームラボや小規模なセルフホスト可能な XCP-ng フリート向けに構築されています。すべての書き込み操作を監査・事前確認でき、（確実な場合は）元に戻せます。自己完結型で、httpx と MCP SDK 以外の依存関係はありません。

Xen Orchestra のインスタンスが必要です（ソースから構築した XO または Xen Orchestra Appliance、/rest/v0 を備えた 5.x）。XO はこのツールが通信する管理プレーンです。ホストへの XAPI 直接アクセスは v0.1 の対象外です。Proxmox VE には使用しないでください。proxmox-aiops を使用してください。

動作する機能

• CLI（xcpng-aiops ...）：init、overview、vm list/get/stats/health-rca/start/stop/reboot/migrate、host list/get/missing-patches、pool list/get/posture、sr list/get/vdis/usage-rca/rescan、snapshot list/create/delete/revert、backup jobs/logs/failure-rca、task list、secret set/list/rm/migrate/rotate-password、doctor、mcp。
• MCP サーバー（xcpng-aiops mcp または xcpng-aiops-mcp）：29 個のツール（読み取り 19 個、書き込み 8 個、取り消し 2 個）。すべて、同梱の @governed_tool ハーネスでラップされています。
• 4 つの主要 RCA 分析（原因とアクションを構造化して出力）：VM の健全性、SR 使用状況、バックアップジョブの失敗、プールのパッチ適用状況と HA の状態。
• 暗号化された認証情報：XO 認証トークンは暗号化ストア ~/.xcpng-aiops/secrets.enc（Fernet + scrypt）に保存されます。ディスク上に平文で保存されることはありません。マスターパスワードは XCPNG_AIOPS_MASTER_PASSWORD（MCP／CI）から取得するか、CLI の対話型プロンプトで入力してロックを解除します。
• 可逆性：vm_start ↔ vm_stop は互いを逆操作として記録します。vm_migrate は移行前の実際のソースホストを取得し、「元に戻す移行」を記録します。snapshot_create は XO の応答から作成されたスナップショットの実際の ID を取得し、「そのスナップショットを削除」を記録します。不可逆な操作（snapshot_delete、snapshot_revert、vm_reboot）は監査記録用に事前の状態を取得し、取り消し不可であることを正直に明示します。
• 安全性：破壊的な CLI 操作には二重の確認が必要で、--dry-run を利用できます。すべての書き込み MCP ツールは dry_run プレビューを受け付けます（書き込み呼び出しは行われず、取り消し操作も記録されません）。
• 自身のロックアウト防止ガード（部分的 — こちらをお読みください）：Xen Orchestra は、管理対象プール上の VM として動作することがよくあります。その VM を停止すると、このツールが通信する API も停止します。そのため、以降は vm_start を送信できず、復旧にはハイパーバイザーのコンソールからのアクセス（xe vm-start）が必要です。対象で xo_self_vm_uuid を設定してください（xcpng-aiops init で確認されます）。設定すると、vm_stop はその UUID と完全に一致する場合に拒否します。--dry-run でも同様です。プレビューで許可されたように見える呼び出しをツールが実際には拒否するという、誤った結果の報告を避けるためです。設定しない場合、保護機能は一切ありません。XO の REST API には自己を示すエンドポイントがなく、トークンにもクレームがないため、ツールはどの VM 上で動作しているかを特定できません。推測はせず、フェイルオープンします。dry_run プレビューでは、VM から報告された IP が設定済みの XO ホストと一致する場合、より弱いヒント selfVmHint を追加します。これは確認する価値のある偶然の一致であり、確定事項ではありません。また、ゲストエージェントがなければ何も検出できず、共有プロキシの背後にあるすべての VM で作動するため、決してブロックはしません。

機能マトリックス（29 個の MCP ツール）

ドメイン	ツール	数	読み取り／書き込み
概要	overview	1	読み取り
VM	vm_list, vm_get, vm_stats, vm_health_rca	4	読み取り
	vm_start, vm_stop, vm_reboot, vm_migrate	4	書き込み（中）
ホスト	host_list, host_get	2	読み取り
プール	pool_list, pool_get, pool_patch_ha_posture	3	読み取り
SR／VDI	sr_list, sr_get, vdi_list, sr_usage_rca	4	読み取り
	sr_rescan	1	書き込み（中）
スナップショット	snapshot_list	1	読み取り
	snapshot_create（中）、snapshot_delete（高）、snapshot_revert（高）	3	書き込み
バックアップ	backup_job_list, backup_log_list, backup_failure_rca	3	読み取り
タスク	task_list	1	読み取り
取り消し	undo_list, undo_apply	2	読み取り＋再実行

主な RCA

1. vm_health_rca — 予期せず停止した VM（自動起動／HA 再起動の優先度設定あり）、一時停止／サスペンド状態の VM、ゲストツールがない稼働中の VM、RRD 統計情報に基づく CPU／メモリの負荷を特定し、各検出結果について原因と対処を提示します。
2. sr_usage_rca — SR を物理容量の使用率順に並べます（満杯に近い状態は 85% 以上、危険な状態は 95% 以上）。シンプロビジョニングの過剰割り当て（仮想割り当て量が容量を超過）、孤立した VDI（どの VM にも接続されていない）を特定し、SR ごとに再利用可能なバイト数を示します。
3. backup_failure_rca — 失敗／スキップ／中断した XO バックアップ実行を分類します。分類項目は vdi-chain（コアレスが未完了）、quiesce（ゲスト VSS）、transport（リモートに到達できない）、storage-full、不明です。ジョブごとの件数とサンプルメッセージも示します。
4. pool_patch_ha_posture — パッチが適用されていないホスト、再起動待ちのホスト、プール内のホスト間のバージョン不一致（ライブマイグレーション／ローリングアップデートに支障）、HA を有効にしていない複数ホストのプールを特定します。

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

このツールは XCP-ng の操作（読み取りと書き込み）を正確かつ効率的に実行し、そのすべてを記録します。書き込みを許可するかどうかは判断しません。それはエージェントの判断、または接続に使用するトークンを発行した Xen Orchestra アカウントの権限に委ねられます。その XO ユーザーに読み取り専用 ACL を設定するか、トークンの権限を制限すれば、書き込みは実際に権限を管理する場所である Xen Orchestra で失敗します。

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

各ツールには risk_level が宣言されています。テストによって [READ]／[WRITE] のドキュメントタグとの整合性が保たれ、説明用のリスクレベルとして監査行に記録されます。これにより、確認者はスナップショットの削除など、高リスクの操作が行われた行をひと目で確認できます。これはラベルであり、ゲートではありません。

小型モデル／ローカルモデルを実行していますか？ agent-guardrails.md をご覧ください。このツールが代わりに適用するガードレール（プロンプトのトークン数を使って繰り返し説明する必要はありません）と、残りの内容に使えるすぐに利用可能なシステムプロンプトが記載されています。

クイックスタート

Claude Code プラグインとして

一度インストールするだけで、エージェントにスキルと MCP サーバーの両方が追加されます。

/plugin marketplace add AIops-tools/marketplace
/plugin install xcpng-aiops@aiops-tools

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

OpenClaw プラグインとして

同じバンドルが ClawHub で公開されています。一度インストールするだけで、スキルと MCP サーバーの両方をまとめて利用できます。

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

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

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

uv tool install xcpng-aiops
xcpng-aiops init        # interactive wizard: XO URL + encrypted token
xcpng-aiops doctor      # verify config, encrypted store, XO reachability + pool count
xcpng-aiops overview    # one-shot fleet health summary

init は ~/.xcpng-aiops/config.yaml（機密情報ではない接続情報）を書き込み、 XO トークンを 暗号化 して ~/.xcpng-aiops/secrets.enc に保存します。生成される設定の例：

targets:
  - name: xo1
    url: https://xo.example.com   # the XO web origin (management plane)
    verify_ssl: true              # set false only for self-signed lab certs
    api_path: /rest/v0

XO UI（ユーザーメニュー → Personal tokens）または xo-cli --createToken でトークンを作成します。対話形式ではない利用（MCP サーバー、CI、cron）では、 プロンプトなしでストアのロックを解除できるよう、マスターパスワードを環境変数に設定します。

export XCPNG_AIOPS_MASTER_PASSWORD='your-master-password'

そのパスワードの保存場所について：環境変数に設定すると、このシェルが起動する すべてのプロセスから読み取り可能になり、シェルの履歴にも記録されます。共有ホストや 長期間稼働するホストでは、対話形式のプロンプトを使うか、必要なコマンドの実行中だけ シークレットマネージャーから渡すことをおすすめします。

MCP クライアントの設定

{
  "mcpServers": {
    "xcpng-aiops": {
      "command": "uvx",
      "args": ["--from", "xcpng-aiops", "xcpng-aiops-mcp"],
      "env": { "XCPNG_AIOPS_MASTER_PASSWORD": "your-master-password" }
    }
  }
}

環境変数ブロックに関する注意：MCP クライアントは最小限の環境でサーバーを起動するため、 シェルのプロファイルで設定した環境変数は 引き継がれません。上記の env ブロックに XCPNG_AIOPS_MASTER_PASSWORD（および使用している場合は XCPNG_AIOPS_HOME／ XCPNG_AIOPS_CONFIG／XCPNG_AUDIT_APPROVED_BY）を設定してください。設定しないと 暗号化されたストアのロックを解除できず、すべてのツールが説明用エラーを返します。

シークレットの管理

xcpng-aiops secret set xo1              # prompts hidden for the XO token
xcpng-aiops secret list                 # names only, values never shown
xcpng-aiops secret rm xo1
xcpng-aiops secret rotate-password      # re-encrypt under a new master password
xcpng-aiops secret migrate              # import a legacy plaintext .env, then retires it

従来の平文環境変数 XCPNG_<TARGET_NAME_UPPER>_TOKEN も、非推奨の警告とともに フォールバックとして引き続き利用できます（xcpng-aiops secret migrate で移行してください）。

ガバナンス

すべての MCP ツールと、同じガバナンス対象の関数を経由する CLI の書き込み操作は、 @governed_tool を通ります。これは記録を行いますが、承認は行いません（上記を参照）。

• 監査 — すべての呼び出し（ツール、シークレットをマスキングしたパラメーター、結果、ステータス、所要時間、リスクティア、オペレーターが指定した承認者／理由があればその情報）を ~/.xcpng-aiops/audit.db に記録します（保存先は XCPNG_AIOPS_HOME で変更できます）。CLI は MCP と同じ行を記録するため、監査を経由しない入り口はありません。
• 予算／暴走防止 — 承認ゲートではなく、安全対策の最後の砦です。累積呼び出し数と実行時間の上限、および短時間に繰り返す呼び出しを遮断するサーキットブレーカー（XCPNG_MAX_TOOL_CALLS、XCPNG_MAX_TOOL_SECONDS、XCPNG_RUNAWAY_MAX）により、停止しないエージェントが無制限に呼び出しや時間を消費するのを防ぎます。
• 取り消し情報の記録 — 元に戻せる書き込みでは、再実行可能な逆操作の記述子を ~/.xcpng-aiops/undo.db に記録し、_undo_id を返します。元に戻せない書き込みでは、以前の状態のみを記録します。
• リスクティア — risk_level に基づいて監査行に付与される説明用ラベルであり、何も制限しません。
• 出力のサニタイズ — XO から返されたすべてのテキストは、エージェントに渡される前にサニタイズされ、サイズが制限されます。

サポート範囲

領域	読み取り	書き込み（ガバナンス対象）
VM	一覧／取得／RRD 統計／健全性の根本原因分析	起動、停止（正常／強制）、再起動（正常／強制）、移行
ホスト	一覧／取得／不足しているパッチ	—
プール	一覧／取得／パッチと HA 状態の根本原因分析	—
SR／VDI	一覧／取得／VDI 一覧（孤立フィルター）／使用状況の根本原因分析	再スキャン
スナップショット	一覧	作成、削除、復元
バックアップ	ジョブ／ログ／失敗の根本原因分析	—
タスク	一覧	—

機能が不足していますか？ 対応範囲は意図的に絞っています。課題、PR、機能リクエスト、貢献、コメントは、すべて歓迎します。 github.com/AIops-tools/XCPng-AIops にお寄せください。

対象範囲と注意事項

• 検証状況：すべての動作はモックされた REST レスポンスに対して検証済みですが、実際に稼働する Xen Orchestra インスタンスを使ったエンドツーエンドの実行記録はまだありません。実環境での確認には xcpng-aiops doctor が最も手早い方法です。完全なチェックリストについては、docs/VERIFICATION.md をご覧ください。
• エンドポイントのパス（例：/vms/<id>/actions/snapshot、/vm-snapshots/<id>、/srs/<id>/actions/rescan、/hosts/<id>/missing_patches、/backup/logs）は、文書化されている XO REST /rest/v0 API に基づいて設計されていますが、実環境での検証が必要です。アクション名は XO のリリースによって異なる場合があります。
• 管理プレーンのみ：すべての操作は XO を経由します。ホストごとの XAPI、XO サーバーの管理（サーバーやユーザーの追加）、バックアップジョブの実行（実行／復元）は、v0.1 の対象範囲外です。
• 設計上の対象範囲外：大量のデータを破壊する操作（VM／VDI の削除など）。状態を破棄するのは snapshot_delete／snapshot_revert のみで、どちらもリスクは high であり、二重確認が必要です。

対象外

他のハイパーバイザーや VM プラットフォーム（それぞれの運用ツールを使用してください。例：Proxmox VE → proxmox-aiops）、NAS／ストレージアプライアンス、バックアップソフトウェアスイート、コンテナクラスター、ネットワークデバイスは、このツールの対象範囲外です。

ライセンス

MIT — github.com/AIops-tools/XCPng-AIops