OLVM AIops

OLVM AIops

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

**Oracle Linux Virtualization Manager（OLVM）**および oVirt 4.5向けの AI を活用した運用ツールです。エンジン REST API を使用し、ガバナンス機能を標準搭載しています。 MCP と CLI の両方の呼び出しを記録する監査ログ、トークン数／暴走防止の予算ガード、明確なリスクレベルを備えています。OLVM を運用するチーム（多くの場合、別のハイパーバイザープラットフォームと並行して運用）向けに構築されており、推測ではなくエンジンの証拠に基づいて、エージェントが「何に対応する必要があるか？」に答えられるようにします。pycurl ベースのエンジン SDK ではなく、httpx と MCP SDK を基盤にしています。

このリリースは読み取り専用です：インベントリ、健全性、容量、診断に対応します。 エンジンのアクションは非同期です。エンジンから complete が返されても、VM やホストが目標の状態に達するまでには時間がかかるため、各アクションの結果を確認できるようになるまで、書き込みツールは提供しません。XCP-ng には使用しないでください。xcpng-aiops を使用してください。Proxmox VE には使用しないでください。proxmox-aiops を使用してください。

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

OLVM／oVirt エンジンを正確に読み取り、すべての呼び出しを記録します。エージェントが何を変更できるかを判断することはありません。それは接続に使用するエンジンアカウントの役割です。そのアカウントに ReadOnlyAdmin などの読み取り専用ロールを付与すると、エンジン自体がその権限を適用します。

このツールが保証するのは、何も記録されずに終わる呼び出しがないことです。MCP と CLI のどちらからの呼び出しも、すべて ~/.olvm-aiops/audit.db に監査レコードとして記録されます。

より小規模なモデルやローカルモデルを実行していますか？ツールがすでに保証している内容と、その他の部分に使用できる既製のシステムプロンプトについては、 agent-guardrails.md を参照してください。

このツールが答える質問

質問	ツール	CLI
エンジン自体は正常ですか？ 証明書、バックアップ、時刻を確認します。	engine_health_rca	olvm-aiops engine health
ホストに何が起きていますか？	host_health_rca	olvm-aiops host health
ストレージが原因で、エンジンがディスクを作成できなくなりそうですか？	storage_capacity_rca	olvm-aiops storage capacity
この VM が一時停止している／応答していないのはなぜですか？	vm_health_rca	olvm-aiops vm health
最近何が起きましたか？ 前回確認してから新しい情報はありますか？	event_list	olvm-aiops event list
長時間実行された操作のうち、失敗したものはどれですか？	job_list	olvm-aiops job list --status failed
インベントリ	datacenter_list、cluster_list、host_list/host_get、storage_domain_list/storage_domain_get、vm_list/vm_get、vm_stats	datacenter、cluster、host、storage、vm

MCP ツールは17個あります。読み取りと診断が15個、さらにガバナンス機能の undo_list / undo_apply（読み取り専用リリースでは取り消す操作はありません）があります。

各診断では、重要度の高い検出事項から順に表示されます。各検出事項には、測定された signal、cause、action、明示的な rank が含まれます。一時的な状態を障害として報告することはありません。エンジンによってインストール中または再起動中のホストは「進行中」として扱われ、フェンシング用ハードウェアのないホストのアラート 9000 は参考情報として扱われ、ホスト、VM、またはデータセンターがその後復旧したイベントには、置き換え済みの印が付きます。24時間より古いイベント（events_window_hours）は検出事項ではなく履歴として扱われ、期間内の警告以上のイベントはすべて、証明書の有効期限切れやバックアップの欠落などエンジン全体に関わるアラートも含め、いずれか1つの診断に必ず含まれます。

ドキュメントではなく、稼働中のエンジンを基に構築

すべての読み取り処理は、Keycloak を有効にした実稼働の Oracle Linux Virtualization Manager 4.5.5-1.73.el9 エンジンを対象に作成し、すべてのフィクスチャはそのエンジンから取得しています。このツールでは、エンジンの次のような動作に対応しています。

• 件数、サイズ、フラグは JSON 文字列として、タイムスタンプはエポックミリ秒の数値として返されます。
• 接続されたストレージドメインには、/storagedomains にステータスがありません。ステータスは、各データセンターのストレージドメインコレクションから読み取ります。
• /jobs は search を受け付けず、ジョブを古い順に返すため、ここでジョブを並べ替えます。
• イベントに対する time 検索は使用できません（形式によってすべて返すか、何も返さないかのどちらかになります）。一方、from=<index> は正確なカーソルです。そのため、after_index とクライアント側の since_minutes を使用します。
• カーソルを新しい順に並べると、そのカーソルより後の最新イベントが返され、残りはスキップされるため、after_index では古い順に読み取ります。
• /ovirt-engine/services/health はログインなしで応答し、データセンターの古いステータスアラートは、復旧後もログに残ります。
• ログインイベントには SSO セッション ID が表示されます。イベントを返す前に、この ID を秘匿します。

クイックスタート

Claude Code プラグインとして

1 回インストールするだけで、エージェントにスキルと MCP サーバーの両方を提供します。

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

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

OpenClaw プラグインとして

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

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

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

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

uv tool install olvm-aiops
olvm-aiops init        # wizard: engine URL, username with profile, CA file, encrypted password
olvm-aiops doctor      # verify config, encrypted store, login and engine version
olvm-aiops host health # first diagnosis

init は ~/.olvm-aiops/config.yaml（秘密情報ではない接続情報）を書き込み、パスワードを ~/.olvm-aiops/secrets.enc に暗号化して保存します。例：

targets:
  - name: engine1
    url: https://olvm-engine.example.com     # the Administration Portal origin (FQDN)
    username: admin@ovirt@internalsso        # admin@internal on engines without Keycloak
    ca_file: /etc/pki/olvm-engine-ca.pem     # engine CA; keeps verify_ssl on
    timeout: 30                              # seconds per request; raise for busy engines

ユーザー名にはプロファイルが含まれます。4.5.1 以降、engine-setup はデフォルトで Keycloak を有効にします。そのため、管理者のユーザー名は admin@ovirt@internalsso になります。Keycloak を使用しないエンジンでは admin@internal です。エンジン CA を https://<engine>/ovirt-engine/services/pki-resource?resource=ca-certificate&format=X509-PEM-CA からダウンロードし、FQDN で接続してください。エンジンの証明書は IP アドレスを対象としていません。

非対話型で使用する場合（MCP サーバー、CI、cron）は、プロンプトなしでストアのロックを解除できるよう、マスターパスワードをエクスポートしてください。

export OLVM_AIOPS_MASTER_PASSWORD='your-master-password'

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

MCP クライアントの設定

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

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

シークレットの管理

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

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

ガバナンス

すべての MCP ツールは @governed_tool を経由し、すべての CLI コマンドは同じ名前の MCP ツールを呼び出します。記録は行いますが、承認は行いません。

• 監査 — すべての呼び出し（ツール、秘密情報をマスキングしたパラメーター、結果、ステータス、所要時間、リスクティア、オペレーターが指定した承認者や根拠があればその情報）を ~/.olvm-aiops/audit.db に記録します（OLVM_AIOPS_HOME で保存先を変更できます）。
• 予算／暴走防止ガード — 安全上の最後の防護策であり、承認ゲートではありません。累積の呼び出し回数と実行時間の上限、および短時間のループを検知するサーキットブレーカーを備えています（OLVM_MAX_TOOL_CALLS、OLVM_MAX_TOOL_SECONDS、OLVM_RUNAWAY_MAX）。
• リスクティア — risk_level から導出され、監査レコードに付与される説明用のラベルです。いかなる制御にも使用されません。
• 出力の衛生管理 — エンジンから返されたすべてのテキストは、エージェントに渡す前にサニタイズされ、サイズが制限されます。ログインイベント内の SSO セッション ID はマスキングされます。

対応範囲

領域	読み取り	書き込み
エンジン	ヘルス診断（ヘルスチェック、クロック、証明書、バックアップ）	—
ホスト	一覧表示／取得／ヘルス診断	—
ストレージドメイン	一覧表示／取得（データセンター単位のステータス、容量）／容量診断	—
VM	一覧表示／取得／統計情報／ヘルス診断	—
データセンター、クラスター	一覧表示	—
イベント、ジョブ	一覧表示（重大度、ページング、after_index、since_minutes、ジョブのステータス）	—

機能が足りませんか？ 対応範囲は意図的に絞っています。 github.com/AIops-tools/OLVM-AIops で Issue または PR を作成してください。 機能リクエスト、コントリビューション、コメントを歓迎します。

対象範囲と注意事項

• 検証状況：稼働中の OLVM 4.5.5 エンジン（KVM ホスト 1 台、NFS データドメイン 1 つ、VM 1 台）に対して、すべての読み取り機能と 4 つすべての診断をエンドツーエンドで実行しました。 その後、ユーザーがホスト 8 台と FC データドメインを備えた小規模な本番環境で読み取り専用ツールを実行し、結果がエンジン独自の API と一致することを確認しています。さらに ReadOnlyAdmin アカウントでも再実行し、すべての読み取り機能と 4 つすべての診断が動作し、その数値が管理ポータルと一致しました。未検証の対象：iSCSI／Gluster ドメイン、セルフホストエンジンのデプロイ、Keycloak を使用しないエンジン、スキャン上限を超えるエンジン。 詳細は docs/VERIFICATION.md を参照してください。
• エンジンのみ：ホスト（vdsm）への直接アクセスはありません。ホスト、ストレージ、VM はエンジンから見える状態で取得されます。
• このリリースでは書き込み不可。開始／停止／移行、メンテナンス、スナップショットは、エンジンの即時応答 complete ではなく、各操作の結果をそれぞれ確認できるようになってから実装する予定です。

対象外

XCP-ng（xcpng-aiops を使用）、Proxmox VE（proxmox-aiops を使用）、その他のハイパーバイザー、NAS／ストレージアプライアンス、バックアップスイート、コンテナクラスター、ネットワークデバイス。

ライセンス

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