Proxmox AIops

Proxmox AIops

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

ガバナンスハーネスを内蔵し、AI を活用した Proxmox VE の VM およびコンテナーのライフサイクル操作を行います。統合監査ログ、トークン／暴走予算ガード、取り消しトークンの記録、説明的なリスクレベルラベルを備えています。自己完結型で、外部依存関係は proxmoxer と MCP SDK のみです。Proxmox のすべての操作を網羅しているわけではありません。

検証状況：実際の Proxmox VE 8.4.19 で、読み取り専用の機能、QEMU の書き込み機能、2 ノードクラスター（クォーラム、ライブマイグレーション、move-disk、実際に成功したバックアップ）の 3 ラウンドにわたって実環境検証済みです。ラウンド 2 と 3 では、モックでは検出できなかった実際のバグがそれぞれ見つかりました。証明された内容と未検証の範囲については、docs/VERIFICATION.md をご覧ください。

動作する機能

• CLI（proxmox-aiops ...）：vm list/get/config/start/stop/shutdown/reboot/reconfigure/clone/delete/migrate、vm resize-disk/move-disk/agent-ping、vm snapshot-create/snapshot-delete/snapshot-list/snapshot-rollback、backup create/list/restore、ct list/start/stop、cluster nodes/status/task-status/resources/node-status/task-log/next-vmid、ha status/resources、pool list/members、firewall vm-rules/cluster-status、storage list/content、diagnose node-pressure/guest-health、undo list/apply、init、secret set/list/rm/migrate/rotate-password、doctor、mcp。
• MCP サーバー（proxmox-aiops mcp または proxmox-aiops-mcp）：43 個のツールがあり、すべてバンドルされた @governed_tool ハーネスでラップされています。
• 診断／根本原因分析（RCA）（読み取り専用）：diagnose node-pressure は、CPU／メモリ／ルートファイルシステムの負荷に基づいてクラスターのノードを順位付けします。diagnose guest-health は、停止中のゲスト、メモリ飽和、容量が逼迫したディスクがないか、VM／コンテナーをスキャンします。各検出結果には、しきい値を超えた測定値と具体的なアクションが記載されます。ブラックボックスの判定ではなく、透明性の高いヒューリスティックです。
• 認証情報：proxmox-aiops init（オンボーディングウィザード）と proxmox-aiops secret ... で、暗号化されたシークレットストアを管理します。config.yaml に平文のパスワードを保存する必要はありません。
• 可逆性：明確な逆操作がある書き込み操作（start/stop/shutdown/reconfigure/clone/migrate/snapshot-create/move-disk、コンテナーの start/stop、空き vmid への復元）では、逆操作の記述子が記録されます。不可逆な操作（delete、snapshot-rollback、強制復元）は逆操作なしと宣言され、リスクレベルは high に設定されます。ディスクのリサイズは拡張のみ可能です（縮小は拒否されます）。
• 非同期タスク：Proxmox の書き込み操作はタスク UPID を返します。cluster task-status で完了をポーリングしたり、cluster task-log で行を読み取ったりできます（暴走予算ガードにより、ポーリングループの暴走を防ぎます）。

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

このツールは Proxmox VE の操作（読み取りと書き込み）を正確かつ効率的に実行し、すべての操作を記録します。書き込みを許可するかどうかは判断しません。それはエージェントの判断、または接続に使用するアカウントの権限によります。読み取り権限のみを付与した Proxmox VE ユーザーまたは API トークン（VM./Datastore. の書き込みロールなし）を使用すれば、書き込みはサーバー側で失敗します。権限を実際に管理しているのはサーバーです。

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

各ツールは risk_level を宣言し、監査行には説明用の区分（none/confirm/review）として記録されます。これにより、レビュー担当者はリスクの高い削除操作があったことをひと目で確認できます。これはラベルであり、ゲートではありません。

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

クイックスタート

Claude Code プラグインとして

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

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

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

OpenClaw プラグインとして

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

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

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

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

uv tool install proxmox-aiops
mkdir -p ~/.proxmox-aiops
# create ~/.proxmox-aiops/config.yaml with a targets: list
# put secrets in ~/.proxmox-aiops/.env  (chmod 600)
proxmox-aiops doctor

~/.proxmox-aiops/config.yaml の設定例：

targets:
  - name: pve-lab
    host: 10.0.0.10
    user: "claude@pve!ops"    # API token: user@realm!tokenid — a dedicated,
                              # least-privilege user, NOT root@pam
    node: pve1
    auth_kind: token
    verify_ssl: false          # self-signed lab certs only

~/.proxmox-aiops/.env（chmod 600）：PROXMOX_PVE_LAB_SECRET=<token-uuid>

監査と安全性

すべての操作は、~/.proxmox-aiops/ 配下のローカル SQLite 監査 DB に記録されます（PROXMOX_AIOPS_HOME で場所を変更できます）。すべての書き込みツールは、ガバナンスハーネスを通過します。これには、トークン数／暴走実行の予算ガード、リスク区分のタグ付け、監査ログの記録が含まれます。破壊的な CLI コマンド（vm stop、vm delete、vm snapshot-delete、vm snapshot-rollback、ct stop）には二重確認が必要で、--dry-run にも対応しています（特に backup restore はリスクが high です）。API から返されたテキストには、プロンプトインジェクション対策サニタイザーが適用されます。

コントリビューションと機能リクエスト

対応範囲は意図的に絞っています。必要なデバイス、操作、機能が不足していますか？ github.com/AIops-tools/Proxmox-AIops でイシューを作成するか、プルリクエストをお送りください。機能リクエスト、コントリビューション、コメントを歓迎します。

ライセンス：MIT。