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（通常与另一种虚拟机监控平台并行使用）的团队打造， 帮助 Agent 根据引擎提供的证据回答“哪些地方需要关注？”，而不是凭空猜测。基于 httpx 和 MCP SDK 构建，而非基于 pycurl 的引擎 SDK。

此版本为只读版本：清点资源、检查运行状况、容量和诊断。 引擎操作是异步的——引擎很快就会返回 complete，但 VM 或主机可能还未达到目标状态——因此，在每个写入工具都能确认自身操作结果之前，我们暂不提供这些工具。切勿用于 XCP-ng——请使用 xcpng-aiops。切勿用于 Proxmox VE——请使用 proxmox-aiops。

此工具能做什么，不能决定什么

此工具会准确读取 OLVM／oVirt 引擎并记录每次调用。它不会决定 Agent 可以更改什么——这由你连接时使用的引擎账户决定。为该账户分配只读角色（例如 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

17 个 MCP 工具：15 个读取和诊断工具，另有治理机制的 undo_list / undo_apply（在只读版本中没有可撤销的操作）。

每项诊断都会按严重程度从高到低排列发现；每项发现都包含测得的 signal、cause、action 和明确的 rank。瞬时状态不会被报告为故障：引擎正在安装或重启的主机会标记为“进行中”；没有隔离硬件的主机上的警报 9000 仅作提示；主机、VM 或数据中心之后已恢复的事件会标记为已被取代。超过 24 小时的事件（events_window_hours）属于历史记录，而非发现；时间范围内每个严重程度为警告或更高的事件都会恰好归入一项诊断——包括证书即将过期、缺少备份等影响整个引擎的警报。

基于真实运行的引擎构建，而非基于文档

每项读取功能都针对真实的 Oracle Linux Virtualization Manager 4.5.5-1.73.el9 引擎编写，每个测试夹具也都从该引擎采集；该引擎已启用 Keycloak。本工具会处理该引擎的以下特性：

• 计数、大小和标志以 JSON 字符串形式返回，时间戳则是 epoch 毫秒数值；
• 在 /storagedomains 中，已附加的存储域没有状态——状态需从每个数据中心的存储域集合中读取；
• /jobs 不接受任何 search，且按最早的顺序返回作业，因此本工具会对作业排序；
• 事件上的 time 搜索无法使用（不同格式会返回全部结果或不返回任何结果），而 from=<index> 是精确游标——因此提供了 after_index 和客户端侧的 since_minutes；
• 游标按最新优先排序时，会返回游标之后的最新事件并跳过其余事件，因此 after_index 会按最早优先的顺序读取；
• /ovirt-engine/services/health 无需登录即可响应，且数据中心的旧状态警报在恢复后仍会保留在日志中；
• 登录事件会输出 SSO 会话 ID，事件返回前会对其进行脱敏。

快速开始

作为 Claude Code 插件

一次安装即可为 Agent 同时提供技能和 MCP 服务：

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

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

作为 OpenClaw 插件

同一套程序包也发布在 ClawHub，安装一次即可同时获取技能和 MCP 服务：

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

之后重启 OpenClaw 网关，使其加载插件。MCP 服务通过 uv 获取，并固定到此确切版本，因此 uvx 必须位于 PATH 中——否则技能仍会安装，但会报告 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。从 https://<engine>/ovirt-engine/services/pki-resource?resource=ca-certificate&format=X509-PEM-CA 下载引擎 CA，并使用 FQDN 连接——引擎证书不包含其 IP 地址。

对于非交互式使用（MCP 服务、CI、cron），请导出主密码，以便无需提示即可解锁存储：

export OLVM_AIOPS_MASTER_PASSWORD='your-master-password'

密码之后会存放在哪里：导出的变量可被此 shell 启动的每个进程读取，也会记录在 shell 历史记录中。在共享主机或长期运行的主机上，建议使用交互式提示，或仅在需要它的单条命令运行期间从密钥管理器注入密码。

MCP 客户端配置

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

环境变量块注意事项：MCP 客户端会以最小环境变量集启动服务——不会继承 shell 配置文件中的导出变量。请将 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 得出的审计记录描述性标签；不执行任何限制。
• 输出卫生 — 所有引擎返回的文本在传递给 Agent 前都会经过净化和长度限制；登录事件中的 SSO 会话 ID 会被脱敏。

支持范围 / 支持范围

区域	读取	写入
引擎	健康诊断（健康检查、时钟、证书、备份）	—
主机	列出 / 获取 / 健康诊断	—
存储域	列出 / 获取（按数据中心限定的状态、容量）/ 容量诊断	—
VM	列出 / 获取 / 统计信息 / 健康诊断	—
数据中心、集群	列出	—
事件、作业	列出（严重级别、分页、after_index、since_minutes；作业状态）	—

缺少功能？（缺少什么？） 覆盖范围有意聚焦。欢迎在 github.com/AIops-tools/OLVM-AIops 提交问题或 PR——功能请求、贡献和评论均受欢迎。

范围与注意事项

• 验证状态：已针对一台运行 OLVM 4.5.5 的在线引擎端到端运行所有读取操作和全部四项诊断；该引擎包含一台 KVM 主机、一个 NFS 数据域和一台 VM。此后，一位用户已在包含 8 台主机和一个 FC 数据域的小型生产引擎上运行只读工具，结果与引擎自身的 API 一致——包括使用 ReadOnlyAdmin 账户进行的第二次运行；所有读取操作和全部四项诊断均正常，且数据与管理门户中的数值一致。尚未验证：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