中文 English

别再手点虚拟机了：Proxmox VE 接入 AI Agent 手把手教程，默认只读也能自动巡检

发布时间: 2026-07-11
Proxmox VE AI Agent MCP 虚拟化 API Token 自动化 运维安全

很多人第一次听到“让 AI 管 Proxmox VE”，脑子里出现的画面是：对 AI 说一句话，它就能创建虚拟机、扩容磁盘、重启服务，甚至自动修复故障。这个方向没有错，但真正安全的起点不是“把管理员密码交给 AI”，而是给 AI 一张只读、可撤销、可限制范围的门禁卡。本文会从零解释 Proxmox VE、API Token、MCP 和 AI Agent 的关系，给出人工配置与 Agent 自动配置两条路线，并提供 Windows 11、Ubuntu 26.04、macOS 26 三套一键脚本。

Proxmox VE 与 AI Agent 安全连接题图

图：本文自制题图。AI Agent 不应拿到机房“万能钥匙”，而应通过受限 Token 和 MCP 桥接访问 Proxmox VE。

先说结论

如果你只想记住最重要的内容，请记住下面几句话：

Proxmox VE 到底是什么

Proxmox Virtual Environment，通常简称 Proxmox VE 或 PVE，是一套面向服务器虚拟化的开源平台。它把几个原本需要分别维护的能力放进同一个管理平面：

可以把它想象成一所大型寄宿学校。物理服务器是教学楼，虚拟机和容器是教室，存储是仓库，网络是走廊，备份是档案室。Proxmox VE 就是总务处：它知道每间教室在哪里、用了多少电、谁正在上课，以及什么时候应该搬家或关门。

截至 2026 年 7 月，Proxmox 官方下载页面提供 Proxmox VE 9.2。版本会继续变化，部署前应以官方发布页面和当前集群兼容性为准。

Proxmox VE 9.2 数据中心仪表盘真实截图

图：Proxmox 官方 Proxmox VE 9.2 数据中心仪表盘截图，节点名称等环境信息已模糊处理。真实界面能在一个页面汇总节点健康、资源利用率和客户机状态。

为什么要让 Proxmox VE 接入 AI Agent

传统 Proxmox 运维并不难，但很碎。你可能先打开网页看节点，再逐台检查虚拟机，随后查看存储空间、备份任务和失败日志。节点少时还能手工完成，节点一多，日常巡检就像每天逐户抄水表：动作重复，容易漏项，也很难快速汇总。

接入 AI Agent 后，可以把自然语言变成结构化巡检任务。例如：

列出当前离线的虚拟机，按节点分组；检查存储使用率；只给出风险摘要，不要执行任何修改。

Agent 会把这句话拆成多个工具调用：查询节点、查询虚拟机、查询存储、整理结果。真正访问 Proxmox VE 的不是大模型本身，而是本地 MCP Server。

这像餐厅点菜：你说“我想吃清淡一点，不要花生”，服务员负责理解要求，厨房负责真正做菜。AI Agent 是服务员，MCP Server 是传菜系统，Proxmox API 是厨房窗口，API Token 则是员工卡。没有员工卡，厨房不会接受请求；员工卡权限不足，也不能进入危险区域。

MCP 是什么，为什么适合这件事

MCP 全称 Model Context Protocol。对普通用户来说，不必先钻进协议细节，只需要理解它解决了一个问题：让 AI Agent 用统一方式发现和调用外部工具。

没有 MCP 时，每个 Agent、每套 API、每个脚本都要单独粘合。使用 MCP 后，服务器可以向 Agent 声明：“我有列出节点、查询虚拟机、查看存储、创建快照等工具；每个工具需要哪些参数；返回的数据是什么格式。”Agent 再根据你的问题选择工具。

本文选用开源的 gilby125/mcp-proxmox Node.js MCP Server。它默认只读，只有显式设置 PROXMOX_ALLOW_ELEVATED=true 才会开放高权限工具，同时支持节点和 VMID allowlist。本文在本地执行了该项目的完整单元测试：共 61 项，全部通过；也使用 MCP stdio 请求成功列出了工具。由于测试机器无法代替读者访问各自的私有 PVE 集群，文章不会伪造真实集群查询结果。

Proxmox MCP 开源项目真实页面截图

图：本文采用的 Proxmox MCP Server 开源项目页面真实截图。安装前请再次检查仓库、许可证、最近提交和代码变更。

整体链路是怎样工作的

AI Agent、MCP、Token 与 Proxmox VE 的连接流程

一次只读查询通常经过下面这条链路：

这里最重要的设计是“分层”。Agent 不保存管理员会话，MCP 不应该默认拥有删除权限，Token 也不应该继承无限权限。任何一层出现问题，都能单独撤销或替换。

安全底线：先只读，再谈自动化

让 AI Agent 直接管理虚拟化平台，最大的风险不是“AI 不聪明”，而是权限太大、目标范围太宽、操作没有二次确认。

建议按下面的顺序逐步开放：

Proxmox AI Agent 权限分层

不要一开始就使用管理员 Token，也不要为了省事把 TLS 校验、节点范围和写权限全部放开。PROXMOX_VERIFY_TLS=false 只适合可信内网中的自签名证书过渡场景；更稳妥的做法是给 PVE 配置可信证书，然后设为 true。

在 Proxmox VE 创建只读 API Token

网页人工配置

在 Proxmox VE 管理界面中进入：

Datacenter → Permissions → Users

创建一个专用用户，例如：

User: ai-agent
Realm: Proxmox VE authentication server

然后进入：

Datacenter → Permissions → API Tokens

为该用户创建 Token，Token ID 可使用 mcp，并保持 Privilege Separation 开启。Token Secret 通常只显示一次，应立即存入密码管理器，不要发到聊天窗口，也不要提交到 Git。

最后进入：

Datacenter → Permissions

在根路径 / 为 Token 分配 PVEAuditor。如果你只希望 AI 查看某个资源池，可以把 ACL 放到对应资源池，而不是根路径。

命令行人工配置

登录 Proxmox VE Shell 后执行：

pveum user add 'ai-agent@pve' --comment 'Read-only AI Agent'
pveum user token add 'ai-agent@pve' 'mcp' --privsep 1
pveum acl modify / -token 'ai-agent@pve!mcp' -role PVEAuditor
pveum user token permissions 'ai-agent@pve' 'mcp'

第二条命令会输出 Token Secret。请立即保存并清理终端滚屏或录屏。文章不提供任何真实 Secret 示例。

如果只需要查看虚拟机，可把授权路径从 / 收窄到 /vms。如果使用资源池，还可以继续缩小范围。权限配置就像给孩子一张图书馆卡：能进阅览室，不代表能进财务室，更不代表可以把整栋楼拆掉。

Proxmox VE 官方 API Viewer 真实截图

图：Proxmox VE 官方 API Viewer 真实页面。API Viewer 可用于核对接口路径、请求方法和参数，但权限仍由用户、Token 与 ACL 决定。

人工安装 MCP Server

下面以 Node.js 20 或更高版本为例。所有组件都运行在本地，不需要把 PVE 凭据交给第三方托管服务。

git clone https://github.com/gilby125/mcp-proxmox.git
cd mcp-proxmox
npm install
npm test

先用脱敏环境变量测试工具发现，不访问真实 PVE：

printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' \
  | PROXMOX_HOST='<PVE_HOST>' \
    PROXMOX_TOKEN_VALUE='<TOKEN_SECRET>' \
    node index.js

如果输出中出现 proxmox_get_nodes、proxmox_get_vms、proxmox_get_storage 等工具，说明 MCP 进程能够启动。然后把它加入支持 MCP 的 AI Agent 配置：

{
  "mcpServers": {
    "proxmox": {
      "command": "node",
      "args": ["<ABSOLUTE_PATH>/mcp-proxmox/index.js"],
      "env": {
        "PROXMOX_HOST": "<PVE_HOST>",
        "PROXMOX_USER": "ai-agent@pve",
        "PROXMOX_TOKEN_NAME": "mcp",
        "PROXMOX_TOKEN_VALUE": "<TOKEN_SECRET>",
        "PROXMOX_ALLOW_ELEVATED": "false",
        "PROXMOX_VERIFY_TLS": "false"
      }
    }
  }
}

配置文件包含 Secret，必须限制文件权限。macOS 和 Linux 可执行 chmod 600 <CONFIG_FILE>；Windows 可在文件属性的“安全”页移除其他用户权限。

三端一键全自动脚本

脚本会安装必要的本地运行环境、下载 MCP Server、安装依赖、询问 PVE 地址与 Token，并把配置写入常见的 MCP 客户端配置文件。默认始终是只读模式，不会开启高权限工具。

Windows 11

下载：install-proxmox-agent-windows11.ps1

Set-ExecutionPolicy -Scope Process Bypass
.\install-proxmox-agent-windows11.ps1

Ubuntu 26.04

下载：install-proxmox-agent-ubuntu-2604.sh

chmod +x install-proxmox-agent-ubuntu-2604.sh
./install-proxmox-agent-ubuntu-2604.sh

macOS 26

下载：install-proxmox-agent-macos.sh

chmod +x install-proxmox-agent-macos.sh
./install-proxmox-agent-macos.sh

脚本依赖 GitHub 和 npm 获取开源代码与依赖，但 MCP Server、凭据和实际 PVE API 通信都在你的设备与 PVE 之间完成，不依赖额外的托管中转服务。如果你处于完全离线环境，可提前镜像仓库和 npm 包，再把脚本中的下载步骤改成本地路径。

让 Agent 自动配置

如果你的 AI Agent 可以读写本地文件并执行终端命令，可以把下面这段提示词交给它。注意：不要把 Token Secret 直接粘贴进提示词，应该在脚本询问时手工输入。

请为我配置 Proxmox VE 的只读 MCP 接入。
要求：
- 判断当前系统是 Windows 11、Ubuntu 26.04 还是 macOS 26；
- 下载并执行本文对应的一键脚本；
- Token Secret 必须由我在终端交互输入，不得回显、记录或写入日志；
- 保持 PROXMOX_ALLOW_ELEVATED=false；
- 不修改已有的其他 MCP Server 配置；
- 完成后只验证 tools/list 与只读节点查询；
- 不执行开机、关机、快照、迁移、删除或配置修改；
- 如果遇到 401、403 或 TLS 错误，停止并告诉我具体层级，不要自行扩大权限。

这就是“Agent 自动配置”与“把权限交给 Agent”的区别：Agent 可以帮你安装和验证，但秘密由人输入，权限由人决定，写操作默认关闭。

如何验证真的接入成功

重启 AI Agent 后，不要第一句话就让它创建虚拟机。建议按下面顺序验证：

请列出你当前可用的 Proxmox 工具名称，不要调用写操作。

请只读列出 Proxmox 节点，隐藏节点完整名称，只显示状态和资源摘要。

请只读统计运行中、已停止的 QEMU 虚拟机和 LXC 容器数量，不显示完整客户机名称。

请检查存储使用率和最近失败任务，只给出风险摘要，不执行修复。

最后做一次“反向验证”：

请删除一个虚拟机。

在默认配置下，Agent 应该拒绝或报告缺少 Elevated 权限。如果它能直接删除，说明你的权限边界没有按本文配置，必须立即停用 Token 并检查 MCP 环境变量、ACL 和 Agent 配置。

常见问题与排障顺序

Proxmox AI Agent 四层排障流程

连接超时或 Connection refused

先检查 Agent 所在设备能否访问 PVE 的管理端口，再检查防火墙、路由和 PROXMOX_PORT。不要一看到超时就重建 Token，因为网络层还没有到身份验证。

401 Unauthorized

重点检查四段信息是否匹配：

Token 的认证头由“用户、Token 名称、Secret”共同组成，少一个字符都可能失败。

403 Forbidden

401 表示“门卫不认识你”，403 表示“门卫认识你，但这扇门不让进”。检查 ACL 是否授给了 Token，而不只是授给用户；如果开启了 Privilege Separation，Token 需要自己的权限交集。

pveum user token permissions 'ai-agent@pve' 'mcp'

Agent 中没有出现 Proxmox 工具

检查配置文件路径、JSON 语法、node 绝对路径和 index.js 绝对路径。先在终端执行 tools/list，把“Agent 配置问题”和“MCP 进程问题”分开。

自签名证书导致 TLS 错误

长期方案是安装可信证书并设置 PROXMOX_VERIFY_TLS=true。临时关闭校验只应在受信任网络中使用，绝不能把未校验的管理接口暴露到不可信网络。

AI 报告的名称与界面不一致

让 Agent 返回 VMID、类型和所属节点的脱敏摘要，不要只依赖自然语言名称。名称可能重复，VMID 才是更稳定的定位信息。执行任何写操作前，应让 Agent 复述目标 VMID、节点、动作和回滚方案。

高权限模式应该怎样开启

只有满足下面条件时才考虑设置：

PROXMOX_ALLOW_ELEVATED=true

Proxmox VE 9.2 动态负载均衡真实截图

图：Proxmox 官方动态负载均衡界面真实截图，环境名称已模糊。AI 可以帮助解释集群状态和提出迁移建议，但自动迁移前仍要检查存储、HA、网络和业务窗口。

适合 AI Agent 的实际任务

最适合先交给 AI 的不是“删除一台虚拟机”，而是信息密集、重复、可验证的工作：

这类任务就像让助手先整理账本，而不是直接让助手签支票。Agent 的价值首先体现在“读得快、归纳快、不会漏掉重复检查项”，然后才是有限度的执行。

Q&A

一定要使用 MCP 吗

不一定。你也可以让 Agent 调用自己编写的 REST API 脚本，或通过受限 SSH 执行 pvesh。MCP 的优势是工具描述统一、参数结构明确、比较容易被不同 Agent 发现和调用。

能不能直接使用 root Token

技术上可能可以，安全上不建议。专用用户、专用 Token、最小 ACL 和可撤销设计，能在配置泄露或 Agent 判断错误时显著缩小影响范围。

Token Secret 会不会被大模型看到

如果 Secret 被写进 MCP 客户端的 env，通常由本地客户端传给 MCP 进程，不应该出现在对话正文中。但配置文件本身仍是敏感文件，应限制权限、避免云同步、避免提交 Git，并定期轮换 Token。

可以让 AI 自动修复故障吗

可以逐步实现，但不要从生产集群开始。先只读发现问题，再让 AI 输出修复计划，然后人工批准低风险操作。无人值守修复必须有明确触发条件、幂等性、超时、回滚和审计。

为什么文章不展示真实 Token、IP 和节点名

因为教程的价值是可复用的方法，而不是暴露某个环境的入口。完整 IP、内网域名、节点名、VM 名称、Token 和任务 ID 都可能帮助攻击者拼出基础设施地图，因此本文统一使用占位符或模糊截图。

最后的建议

Proxmox VE 接入 AI Agent 并不是“给机房装一个聊天框”，而是在传统 API 自动化上增加一个能理解自然语言、能选择工具、能解释结果的调度层。

真正成熟的接入方案应该让你更安心，而不是更紧张：

先让 AI 当“巡检员”，再让它当“操作员”。当每一层门禁都清楚、每一步都有验证，你才真正拥有了一个可靠的 Proxmox VE AI 助手。

参考资料