VMware Monitor

VMware Monitor

作者：Wei Zhou，VMware by Broadcom — [email protected] 这是由 VMware 工程师发起的社区项目，并非 VMware 官方产品。 如需 VMware 官方开发者工具，请访问 developer.broadcom.com。

English | 中文

只读 VMware vCenter/ESXi 监控 — 33 个工具。此代码库中不存在任何破坏性操作，并且有测试对此进行强制检查。

为何单独设立仓库？ VMware Monitor 完全独立于 VMware-AIops。此代码库中不存在关机、删除、创建、重新配置、创建/还原/删除快照、克隆或迁移功能——这不是提示词限制，而是功能缺失。

如何精确地强制执行。 tests/eval/regression/test_read_only_enforcement.py 使用 ast 解析每个源文件，并要求软件包调用的每个 vSphere 方法都出现在经过审查的允许列表中，同时与 pyVmomi 自身的类型元数据进行交叉核对：任何返回 vim.Task 的方法，或在 vCenter 上需要非只读权限的方法，都会导致检查失败，除非有人明确记录了原因。目前该允许列表包含 14 个方法。这项检查针对的是已编写的代码——它无法识别运行时拼接的方法名，也不会自动运行，因此只有在有人运行测试套件时才能发挥作用。若要获得完全不依赖此仓库的保障，请让技能使用仅拥有 vCenter 内置只读角色的专用帐户（哪些读取操作需要更高权限）。

“只读”不涵盖什么。 这是对 vCenter/ESXi 的说明：没有任何代码路径会更改其状态。在 vCenter 上，该技能只会打开自己的登录会话和短期查询句柄，并在使用后释放。它确实会在本地写入内容：~/.vmware-monitor/config.yaml 和 .env（通过 init 写入；加载时，.env 中的明文密码会被改写为 b64: 格式）、审计日志（MCP 调用写入 ~/.vmware/audit.db，命令行命令写入 ~/.vmware-monitor/audit.log）、位于 ~/vmware-health/ 的 --html 快照，以及——仅在执行 daemon start 后——daemon.pid、scan.log，并向你配置的 webhook 发送请求。完整列表见：设置指南。

配套技能

升级到 2.0

2.0 将其中 23 个 MCP 工具重命名为动词开头（例如 active_sessions → list_active_sessions、active_tasks → list_active_tasks、certificate_status → get_certificate_status）。完整的旧名称 → 新名称对照表见 RELEASE_NOTES.md。其他内容均不变：工具、参数、安全关卡和 CLI 命令都相同。如果 Agent 提示词、脚本或 ~/.vmware/rules.yaml 中指定了工具，请更新名称。不过，使用旧名称编写的拒绝规则仍可正常工作，前提是 vmware-policy ≥ 1.18（vmware-audit policy 会列出重命名后适用范围扩大的规则）；vmware-pilot ≥ 1.13 会转换已保存工作流中的旧名称。 如果低于 2.0 的安装共用该 rules.yaml，也请将其升级到 vmware-policy ≥ 1.18.2：它会针对新旧两种名称匹配每条规则，因此同一个文件可供两者使用。

⚡ 快速调查报告

五份主观精选的只读报告，解答运维人员真正关心的问题——每份报告都会在服务端进行聚合和关联分析，并返回高信号结果（绝非原始清单）。每份报告还支持通过 --html 生成独立的离线 HTML 快照（无外部资源，不会有任何内容离开本机；深入详情会折叠在原生 <details> 区段中，不使用 JavaScript）。

# Triage the estate, then drill into whatever it flags:
vmware-monitor attention                         # what needs attention now, all vCenters
vmware-monitor summary --top 5                   # is anything on fire, one vCenter
vmware-monitor investigate vm web-01 --hours 72  # everything around a VM, 72h event window
vmware-monitor investigate vm web-01 --html      # → offline snapshot in ~/vmware-health/

对象名称未知时会返回引导式错误，准确说明如何列出对象。通过 MCP，这些工具分别为 get_cluster_health_summary、get_cross_vcenter_attention、investigate_vm、investigate_host、investigate_datastore——模型会调用它们，并用运维语言解释聚合结果。完整标志参数请参阅：references/cli-reference.md。

快速安装（推荐）

适用于 Claude Code、Cursor、Codex、Gemini CLI、Trae 和 30 多种 AI Agent：

# Via Skills.sh
npx skills add vmware-skills/VMware-Monitor

# Via ClawHub
clawhub install @zw008/vmware-monitor

PyPI 安装（无需访问 GitHub）

# Install via uv (recommended)
uv tool install vmware-monitor

# Or via pip
pip install vmware-monitor

# China mainland mirror (faster)
pip install vmware-monitor -i https://pypi.tuna.tsinghua.edu.cn/simple

离线／隔离网络安装（从源代码安装）

本项目使用现代 PEP 517 构建系统（hatchling），因此按设计不包含 setup.py——这是预期情况，并非文件缺失。如果你克隆了源代码并遇到 ERROR: File "setup.py" or "setup.cfg" not found ... editable mode currently requires a setuptools-based build，说明你的 pip 版本早于 21.3，无法使用非 setuptools 后端进行 可编辑（-e）安装。可编辑模式是为开发者提供的便利功能，运行工具并不需要它——可任选以下一种方式：

# From the source tree — a normal (non-editable) install builds a wheel:
pip install .              # NOT  pip install -e .

# ...or upgrade pip first, and editable works too:
pip install --upgrade pip && pip install -e .

对于真正的隔离网络主机，请在联网机器上构建 wheel 并复制过去——这样目标主机无需联网：

# On a connected machine, collect this package + its dependencies as wheels:
pip wheel . -w dist        # → dist/*.whl   (or: uv build, for just this package)

# Copy dist/ to the air-gapped host, then install offline:
pip install --no-index --find-links dist vmware-monitor

功能（只读）

架构

User (Natural Language)
  ↓
AI CLI Tool (Claude Code / Gemini / Codex / Aider / Continue / Trae / Kimi)
  ↓ Reads SKILL.md / AGENTS.md / rules
  ↓
vmware-monitor CLI (read-only)
  ↓ pyVmomi (vSphere SOAP API)
  ↓
vCenter Server ──→ ESXi Clusters ──→ VMs
    or
ESXi Standalone ──→ VMs

版本兼容性

Broadcom 官方参考资料

• SDK：https://developer.broadcom.com/sdks — VCF Python SDK（推荐用于 VCF 9+，包含 pyVmomi + vSAN SDK）、适用于 Python 的 vSphere Automation SDK
• REST API：https://developer.broadcom.com/xapis — vSphere Automation API、VCF API
• CLI 工具：https://developer.broadcom.com/tools — PowerCLI 9.1、ESXCLI、OVF Tool

1. 清单

2. 健康状况与监控

受监控的事件类型：

3. 虚拟机信息与快照列表（只读）

4. 定时扫描与通知

5. 安全功能

有意不包含的功能

以下操作不存在于此代码仓库中：

• ❌ 开启/关闭、重置、挂起 VM
• ❌ 创建、删除、重新配置 VM
• ❌ 创建、还原、删除快照
• ❌ 克隆或迁移 VM
• ❌ _double_confirm、_show_state_preview、_validate_vm_params

如需执行这些操作，请使用完整的 VMware-AIops 代码仓库。

使用本地模型或小型模型？请参阅 skills/vmware-monitor/references/agent-guardrails.md。

常见工作流

每日健康检查

1. 检查警报：vmware-monitor health alarms --target prod-vcenter
2. 查看近期事件：vmware-monitor health events --hours 24 --severity warning
3. 列出主机：vmware-monitor inventory hosts — 检查连接状态和内存使用情况

调查特定对象（逐层深入）

一次调用即可将对象与其周边基础设施及近期历史关联起来 — 请参阅上文的 ⚡ 快速调查报告。

1. 从分诊开始：vmware-monitor attention（所有 vCenter）或 vmware-monitor summary（单个 vCenter）
2. 深入查看标记的问题：vmware-monitor investigate vm <name>（或 host / datastore）
3. 使用 --hours 72 扩大事件时间范围；使用 --html 分享（离线快照）
4. 如果名称未知 → 教学错误会指出如何列出对象（inventory vms/hosts、list_all_datastores）

设置持续监控

1. 在 ~/.vmware-monitor/config.yaml 中配置 webhook
2. 启动守护进程：vmware-monitor daemon start
3. 守护进程每 15 分钟扫描一次，并向 Slack/Discord 发送警报

故障排除

警报返回空结果，但 vCenter 显示有警报

get_alarms 工具会查询根文件夹级别触发的警报。有些警报是针对特定实体的 — 请尝试改为检查事件：vmware-monitor health events --hours 1 --severity info。

“Connection refused” 错误

1. 运行 vmware-monitor doctor 进行诊断
2. 在 config.yaml 中确认目标主机名/IP 和端口（443）
3. 对于自签名证书：信任 CA；仅在隔离的实验室主机上设置 verify_ssl: false

事件返回的结果过多

使用严重性筛选器：--severity warning（默认值）会筛除 info 级别的事件。使用 --hours 4 缩小时间范围。

VM 信息显示 “guest_os: unknown”

来宾操作系统中未安装或未运行 VMware Tools。安装/启动 VMware Tools，以检测来宾操作系统、IP 地址和来宾系列信息。

Doctor 检查通过，但命令因超时而失败

vCenter 可能负载过高。请尝试直接指定某台 ESXi 主机，而不是 vCenter；或者在 config.yaml 中延长连接超时。

doctor 报告 “no vSphere role”，或每条命令都因 “session is not authenticated” 而失败

该账户可以登录，但没有 vSphere 角色，因此 vCenter 不会为其创建会话（AIops#47）。请在 vCenter 根文件夹上为其分配角色（只读或更高权限）：Administration > Access Control > Global Permissions。更改密码无济于事。vmware-monitor doctor 会明确报告此情况，而 attention 会将此类目标计为未读取（整体状态至少为 WARN）。

支持的 AI 平台

平台对比

MCP 服务集成

vmware-monitor MCP 服务可与任何兼容 MCP 的 Agent 或工具配合使用。可直接使用的配置模板位于 examples/mcp-configs/。所有 33 个工具均为只读，并通过上文所述的允许列表关卡强制执行。

Xiaoguai (小怪) — 来自同一维护者、可自托管且以审计为先的 Agent 平台（Rust、单个二进制文件 + 内嵌 SQLite）。它将只读的 vmware-monitor MCP 服务作为其工具箱之一；作为 MCP 客户端和 MCP 服务，其 HMAC 链式审计日志与此技能的只读设计相得益彰——每次查询都会记录，且此处没有任何代码路径会修改数据。请参阅其 MCP 集成指南。

完全本地运行（无需云端 API）：

# Aider + Ollama + vmware-monitor (via SKILL.md)
aider --conventions skills/vmware-monitor/SKILL.md --model ollama/qwen2.5-coder:32b

# Any MCP agent + local model + vmware-monitor MCP server
# See examples/mcp-configs/ for your agent's config format

安装

步骤 0：准备工作

# Python 3.10+ required
python3 --version

# Node.js 18+ required for Gemini CLI and Codex CLI
node --version

步骤 1：克隆并安装 Python 后端

git clone https://github.com/vmware-skills/VMware-Monitor.git
cd VMware-Monitor
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

步骤 2：配置

mkdir -p ~/.vmware-monitor
cp config.example.yaml ~/.vmware-monitor/config.yaml
# Edit config.yaml with your vCenter/ESXi targets

通过 .env 文件设置密码（推荐）：

cp .env.example ~/.vmware-monitor/.env
chmod 600 ~/.vmware-monitor/.env
# Edit and fill in your passwords

安全提示：建议使用 .env 文件，而不是通过命令行 export 设置密码，以免密码出现在 shell 历史记录中。config.yaml 仅存储主机名、端口以及 .env 文件的引用，不包含密码或令牌。所有密钥仅存储在 .env 中（chmod 600）。Webhook 通知默认处于禁用状态；启用后，负载只会发送到用户配置的 URL，且不包含配置中的凭据，但会包含 vSphere 自身的告警、事件和日志文本，其中可能包含主机名、IP 和用户名。我们建议使用具有 vCenter 内置只读角色的专用服务账户。

密码环境变量命名约定：

VMWARE_{TARGET_NAME_UPPER}_PASSWORD
# Replace hyphens with underscores, UPPERCASE
# Example: target "home-esxi" → VMWARE_HOME_ESXI_PASSWORD
# Example: target "prod-vcenter" → VMWARE_PROD_VCENTER_PASSWORD

步骤 3：连接 AI 工具

选择以下一项或多项：

选项 A：Claude Code

方法 1：Skills.sh 或 ClawHub（推荐）

任一安装程序都会将技能安装到 Claude Code 的技能目录中：

npx skills add vmware-skills/VMware-Monitor
# or
clawhub install @zw008/vmware-monitor

方法 2：手动安装技能

git clone https://github.com/vmware-skills/VMware-Monitor.git
cd VMware-Monitor

# Copy the skill into Claude Code's personal skills directory
mkdir -p ~/.claude/skills/vmware-monitor
cp -r skills/vmware-monitor/. ~/.claude/skills/vmware-monitor/

如需访问工具（而不只是技能上下文），还需注册 MCP 服务：

claude mcp add vmware-monitor -- vmware-monitor mcp

重启 Claude Code，然后：

> Show me all VMs on esxi-lab.example.com

选项 B：Gemini CLI

# Install Gemini CLI
npm install -g @google/gemini-cli

# Load the skill as project context (Gemini CLI reads GEMINI.md on startup)
cp skills/vmware-monitor/SKILL.md ./GEMINI.md

如需访问工具（而不只是上下文），请在 ~/.gemini/settings.json 中注册 MCP 服务：

{
  "mcpServers": {
    "vmware-monitor": {
      "command": "vmware-monitor",
      "args": ["mcp"],
      "env": { "VMWARE_MONITOR_CONFIG": "~/.vmware-monitor/config.yaml" }
    }
  }
}

然后启动 Gemini CLI：

gemini
> Show me all VMs on my ESXi host

选项 C：OpenAI Codex CLI

# Install Codex CLI
npm i -g @openai/codex
# Or on macOS:
# brew install --cask codex

# Copy skill to Codex skills directory
mkdir -p ~/.codex/skills/vmware-monitor
cp skills/vmware-monitor/SKILL.md ~/.codex/skills/vmware-monitor/SKILL.md

# Copy AGENTS.md to project root
cp skills/vmware-monitor/SKILL.md ./AGENTS.md

然后启动 Codex CLI：

codex --enable skills
> List all VMs on my ESXi

选项 D：Aider（支持本地模型）

# Install Aider
pip install aider-chat

# Install Ollama for local models (optional)
# macOS:
brew install ollama
ollama pull qwen2.5-coder:32b

# Run with cloud API
aider --conventions skills/vmware-monitor/SKILL.md

# Or with local model via Ollama
aider --conventions skills/vmware-monitor/SKILL.md \
  --model ollama/qwen2.5-coder:32b

选项 E：Continue CLI（支持本地模型）

# Install Continue CLI
npm i -g @continuedev/cli

# Copy rules file
mkdir -p .continue/rules
cp skills/vmware-monitor/SKILL.md .continue/rules/vmware-monitor.md

为本地模型配置 ~/.continue/config.yaml：

models:
  - name: local-coder
    provider: ollama
    model: qwen2.5-coder:32b

然后：

cn
> Check ESXi health and alarms

选项 F：Trae IDE

将规则文件复制到项目的 .trae/rules/ 目录：

mkdir -p .trae/rules
cp skills/vmware-monitor/SKILL.md .trae/rules/project_rules.md

Trae IDE 的 Builder Mode 会在启动时读取 .trae/rules/ 中的 Markdown 文件。

注意：你也可以在 Trae IDE 中安装 Claude Code 扩展，并直接使用 .claude/skills/ 格式。

选项 G：Kimi Code CLI

# Copy skill file to Kimi skills directory
mkdir -p ~/.kimi/skills/vmware-monitor
cp skills/vmware-monitor/SKILL.md ~/.kimi/skills/vmware-monitor/SKILL.md

选项 H：MCP 服务（Glama / Claude Desktop）

MCP 服务通过 Model Context Protocol 将 VMware 只读监控功能作为工具提供。它适用于任何兼容 MCP 的客户端（Claude Desktop、Cursor 等）。

运行 uv tool install vmware-monitor 后，只需一条命令即可启动 MCP 服务（v1.5.15+）：

# Recommended — single command, no network re-resolve
vmware-monitor mcp

# With a custom config path
VMWARE_MONITOR_CONFIG=/path/to/config.yaml vmware-monitor mcp

Claude Desktop 配置（claude_desktop_config.json）：

{
  "mcpServers": {
    "vmware-monitor": {
      "command": "vmware-monitor",
      "args": ["mcp"],
      "env": {
        "VMWARE_MONITOR_CONFIG": "/path/to/config.yaml"
      }
    }
  }
}

# Run without installing (requires PyPI access each launch)
uvx --from vmware-monitor vmware-monitor mcp

# Legacy entry point (still works, kept for backward compatibility)
vmware-monitor-mcp

选项 I：独立 CLI（无需 AI）

# Already installed in Step 1
source .venv/bin/activate

vmware-monitor inventory vms --target home-esxi
vmware-monitor health alarms --target home-esxi
vmware-monitor vm info my-vm --target home-esxi

更新 / 升级

已经安装？重新运行对应渠道的安装命令即可获取最新版本：

检查当前版本：vmware-monitor --version

中国云模型

适用于偏好使用国内云 API，或访问海外服务受限的中国用户。

DeepSeek

export DEEPSEEK_API_KEY="your-key"
aider --conventions skills/vmware-monitor/SKILL.md \
  --model deepseek/deepseek-coder

Qwen（阿里云）

export DASHSCOPE_API_KEY="your-key"
aider --conventions skills/vmware-monitor/SKILL.md \
  --model qwen/qwen-coder-plus

本地模型（Aider + Ollama）

完全离线运行——无需云 API、无需互联网，充分保护隐私。

brew install ollama
ollama pull qwen2.5-coder:32b
ollama serve

aider --conventions skills/vmware-monitor/SKILL.md \
  --model ollama/qwen2.5-coder:32b

CLI 参考

# Diagnostics
vmware-monitor doctor                   # Check environment, config, connectivity
vmware-monitor doctor --skip-auth       # Skip vSphere auth check (faster)
vmware-monitor access-info [--tool <mcp-tool>] [--target <name>]  # Account in use + privileges per tool

# MCP Config Generator
vmware-monitor mcp-config generate --agent goose        # Generate config for Goose
vmware-monitor mcp-config generate --agent claude-code  # Generate config for Claude Code
vmware-monitor mcp-config list                          # List all supported agents

# Inventory
vmware-monitor inventory vms [--target <name>]
vmware-monitor inventory vms --limit 10 --sort-by memory_mb   # Top 10 VMs by memory
vmware-monitor inventory vms --power-state poweredOn           # Only powered-on VMs
vmware-monitor inventory vms --sort-by folder_path             # Group VMs by inventory folder
# All `inventory vms` results include a `folder_path` field (e.g. `/Datacenters/Production/Web Tier`).
# MCP tool `list_virtual_machines` additionally supports `folder_filter="Production"` for case-insensitive folder-tree search.
vmware-monitor inventory hosts [--target <name>]
vmware-monitor inventory datastores [--target <name>]
vmware-monitor inventory clusters [--target <name>]

# Health
vmware-monitor health alarms [--target <name>]
vmware-monitor health events [--hours 24] [--severity warning]

# VM Info (read-only)
vmware-monitor vm info <vm-name>
vmware-monitor vm snapshot-list <vm-name>

# Scanning & Daemon
vmware-monitor scan now [--target <name>]
vmware-monitor daemon start
vmware-monitor daemon stop
vmware-monitor daemon status

配置

所有选项请参阅 config.example.yaml。

项目结构

VMware-Monitor/
├── skills/                        # Skills index (npx skills add)
│   └── vmware-monitor/
│       ├── SKILL.md
│       └── references/            # Detailed docs loaded on-demand
├── vmware_monitor/                # Python backend (read-only only)
│   ├── config.py                  # YAML + .env config
│   ├── connection.py              # Multi-target pyVmomi
│   ├── cli.py                     # Typer CLI (read-only commands only)
│   ├── ops/
│   │   ├── inventory.py           # VMs, hosts, datastores, clusters
│   │   ├── health.py              # Alarms, events, sensors
│   │   └── vm_info.py                 # VM info, snapshot list (read-only)
│   ├── scanner/                   # Log scanning daemon
│   ├── notify/                    # Notifications (JSONL + webhook)
│   └── mcp_server/                # MCP server (read-only tools only)
├── examples/mcp-configs/          # MCP client config templates
├── tests/                         # Test suite
├── smithery.yaml                  # Smithery marketplace config
├── RELEASE_NOTES.md
├── config.example.yaml
└── pyproject.toml

相关项目

故障排除与贡献

如果遇到任何错误或问题，请将错误消息、日志或屏幕截图发送至 [email protected]。欢迎贡献！

远程访问（HTTPS）和限制工具

默认情况下，vmware-monitor mcp 通过 stdio 与一个本地客户端通信，并提供所有工具。以下两个选项可以更改此设置 （vmware-policy ≥ 1.21.0）。

通过 HTTPS 提供服务，以便其他机器上的客户端连接。每个调用方都需要一个 bearer token：

vmware-audit token create alice          # prints the token once; give it to alice
vmware-audit token list                  # names only
vmware-audit token revoke alice          # refused from its next request, no restart
vmware-monitor mcp --transport https --host 0.0.0.0 --port 8443 \
    --cert /etc/vmware-mcp/server.pem --key /etc/vmware-mcp/server-key.pem \
    --public-name mcp.example.com

连接客户端（此处展示 Claude Code；任何支持 streamable HTTP 和自定义标头的 MCP 客户端均可）：

claude mcp add --transport http vmware-monitor https://mcp.example.com:8443/mcp \
    --header "Authorization: Bearer $VMWARE_MCP_TOKEN"

{
  "mcpServers": {
    "vmware-monitor": {
      "type": "http",
      "url": "https://mcp.example.com:8443/mcp",
      "headers": { "Authorization": "Bearer ${VMWARE_MCP_TOKEN}" }
    }
  }
}

• 如果没有 token，服务将无法启动；它会拒绝 --public-name 以外的 Host/Origin 值，并在绑定端口前检查未经身份验证的请求是否会收到 401。请使用客户端信任的、适用于这些名称的证书。
• 如果在同一台机器上的 TLS 终止反向代理之后运行，请使用 --transport http --host 127.0.0.1 --public-name mcp.example.com，并透传 Authorization 标头。
• 如果在另一台机器上的负载均衡器或网关之后运行，请保留 --transport https（自签名证书也可以），在 --public-name 中列出负载均衡器发送的 Host 主机名，并让它转发 Authorization。其健康检查可使用无需 token 的 GET /healthz，该请求只会返回 {"status": "ok"}（vmware-policy ≥ 1.23.0）。
• 每个请求都发送 traceparent 或 X-Request-ID，以便将其存储在审计记录中；随后运行 vmware-audit log --correlation-id ID，即可查找同一平台请求背后的调用。
• 审计日志会将每个调用方记录为 token:<name>。调用会并行运行，每个目标最多使用 VMWARE_MCP_POOL_SIZE 个会话（默认值为 2）；每个会话都是在目标上的一次登录，每次调用最多等待 300 s。
• 任何能访问此端点的人，都将以此服务使用的账户身份操作。 Token 用于识别调用方；它们不会授予任何平台权限。请为每个权限级别运行一个端点。
• **在同一端点上为多人或多种角色提供服务：**运行一次 vmware-audit roles enable，然后为每个 token 指定一个角色（vmware-audit token create NAME --role reader，或在 roles.yaml 中指定包含工具和目标的角色；vmware-policy ≥ 1.24.0）。角色会限制 token 在此端点上可调用的内容；它不能授予超出账户已有权限的权限。请参阅 vmware-policy 的 README 中的“网络调用方的角色”。

**限制工具：**此服务的所有工具均为只读，因此 --expose read 在此处不会改变任何内容；此选项适用于支持写入的技能。最小权限取决于服务使用的账户。

详情：skills/vmware-monitor/references/setup-guide.md（“通过 HTTPS 提供 MCP 服务”、“限制所提供的工具”）。

许可证

MIT