Proxmox AIops

Proxmox AIops

免责声明：由社区维护的开源项目。与 Proxmox Server Solutions GmbH 无关联，也未获得其认可或赞助。“Proxmox”是其所有者的商标。本项目采用 MIT 许可证。

通过 AI 驱动 Proxmox VE 虚拟机和容器生命周期操作，并内置治理机制——统一审计日志、令牌／失控预算保护、撤销令牌记录，以及清晰的风险等级标签。独立运行：除 proxmoxer 和 MCP SDK 外，无其他外部依赖。目前尚未覆盖 Proxmox 的所有操作。

验证状态：已针对真实的 Proxmox VE 8.4.19 完成三轮实测——只读功能、QEMU 写入功能，以及双节点集群（仲裁、实时迁移、move-disk 和一次实际成功的备份）。第 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 机制封装。
• 诊断／根因分析（只读）：diagnose node-pressure 根据 CPU／内存／根文件系统压力对集群节点进行排序；diagnose guest-health 扫描虚拟机／容器，查找已停止的客户机、内存饱和以及磁盘空间将满的情况。每项发现都会列出触发判断的实测数值和具体操作建议——采用透明的启发式规则，而非黑盒判断。
• 凭据：使用 proxmox-aiops init（引导向导）和 proxmox-aiops secret ... 管理加密的密钥存储——不会在 config.yaml 中保存明文密码。
• 可逆性：对于具有明确逆向操作的写入操作（启动／停止／关机／重新配置／克隆／迁移／创建快照／移动磁盘、启动／停止容器，以及恢复到空闲 VMID），系统会记录逆向操作描述符；不可逆操作（删除、回滚快照、强制恢复）则声明无逆向操作，并标记为 high 风险。磁盘扩容仅支持增大（拒绝缩小）。
• 异步任务：Proxmox 写入操作会返回任务 UPID——可使用 cluster task-status 轮询完成状态，或使用 cluster task-log 读取日志行（失控预算保护可防止轮询循环失控）。

此工具决定和不决定的事项

它能够准确、高效地执行 Proxmox VE 操作（读取和写入），并记录每一项操作。它不会决定是否允许执行写入操作。这个决定由 Agent 判断，或由你所连接的账户权限决定：使用仅获授只读权限的 Proxmox VE 用户或 API 令牌（不包含 VM./Datastore. 写入角色），这样写入操作就会在服务端失败——权限的实际归属地就在服务端。

因此，你无需配置只读开关、策略文件或审批关卡。此工具唯一能保证的是，绝不会有操作悄无声息：通过 MCP 或 CLI 发出的每次调用，都会在 ~/.proxmox-aiops/audit.db 中生成一条审计记录；对于破坏性写入，它仍会捕获操作前状态，并在存在逆向操作时记录该操作。

每个工具都会声明一个 risk_level，并将其作为描述性级别（none/confirm/review）写入审计记录——审核者可以一眼看出某条记录是否涉及高风险删除。这只是一个标签，不是关卡。

正在运行较小的模型或本地模型？请参阅 agent-guardrails.md——其中列出了此工具现在会替你执行的防护措施（这样你就不必在提示词预算中重复说明），还提供了一个现成的系统提示词，供你用于处理剩余事项。

快速开始

作为 Claude Code 插件

安装一次，Agent 就能同时获得技能和 MCP 服务：

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

MCP 服务通过 uv 获取，并固定为此插件声明的包版本，因此可以追溯审计记录对应的写入代码。凭据仍需通过 proxmox-aiops init 配置——见下文。

作为 OpenClaw 插件

同一软件包也发布在 ClawHub 上，只需安装一次，即可同时获得技能和 MCP 服务：

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

之后请重启 OpenClaw 网关，使其加载插件。MCP 服务通过 uv 获取，并固定为此确切版本，因此 uvx 必须位于 PATH 中——如果缺少 uvx，技能仍会安装，但会报告 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 审计数据库中（可通过 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。