VMOS Edge 帮助文档

简体中文

English

简体中文

English

Appearance

VMOS Edge CLI 官方使用指南 ​

@vmosedge/cli 是 VMOS Edge Desktop 的官方命令行工具，可用于管理云机实例、查询主机与镜像状态、执行桌面自动化，以及通过 batch JSON 或 YAML 工作流批量运行任务。对于大多数首次接触 VMOS Edge CLI 的用户，官方更推荐先通过 AI Agent + 官方 Skill 接入，再逐步深入到纯 CLI、批处理和工作流编排。

推荐路线

  • 新手或希望快速接入的用户：优先使用 AI Agent + 官方 Skill
  • 需要脚本化、批处理、工作流编排或精细调试的用户：再切换到纯 CLI

推荐使用方式 ​

路线适合人群说明
AI Agent + 官方 Skill首次接触 VMOS Edge CLI、希望快速上手的用户由 Agent 按官方规则调用 CLI 能力，上手门槛更低
纯 CLI需要调试单条命令、编写 batch JSON、维护 YAML 工作流的用户灵活度更高，适合进阶使用

AI Agent + 官方 Skill 适合谁 ​

  • 第一次接触 VMOS Edge CLI 的用户
  • 想快速接入 VMOS Edge 自动化能力的用户
  • 想把 VMOS Edge 接入 Codex、Cursor、Claude Code、Gemini CLI、GitHub Copilot、OpenClaw 等 Agent 的用户
  • 不想一开始就记忆大量命令、参数和工作流格式的用户

安装官方 Skill ​

先查看官方 skills 仓库中的可用 skill：

bash
npx skills add https://github.com/vmos-dev/vmos-edge-skills --list

安装 operate-vmos-edge-cli：

bash
npx skills add https://github.com/vmos-dev/vmos-edge-skills --skill operate-vmos-edge-cli

使用前准备 ​

在安装 skill 之前，建议先确认本地环境已准备完成：

  • 已安装 Node.js 18 或更高版本
  • 系统中可正常使用 npm
  • 已安装 VMOS Edge Desktop
  • 已安装官方 CLI：@vmosedge/cli
  • 安装完成后，可通过 vmos-edge-cli schema 验证 CLI 是否可用

推荐安装顺序 ​

首次接入时，建议按下面顺序完成安装与验证。

1. 检查 Node.js 与 CLI 环境 ​

bash
node --version
vmos-edge-cli --version

2. 安装官方 CLI ​

bash
npm i -g @vmosedge/cli

3. 验证 CLI 是否可用 ​

bash
vmos-edge-cli schema

4. 安装官方 Skill ​

bash
npx skills add https://github.com/vmos-dev/vmos-edge-skills --skill operate-vmos-edge-cli

安装说明

官方推荐的标准安装方式是 npm i -g @vmosedge/cli。不建议用 node dist/main.js、pnpm build 或 pnpm link 代替正式安装。

首次使用建议 ​

第一次使用时，推荐按下面思路操作：

  1. 先安装 @vmosedge/cli
  2. 运行 vmos-edge-cli schema，确认 CLI 可用
  3. 安装 operate-vmos-edge-cli skill
  4. 在 AI Agent 中通过 skill 调用 VMOS Edge 能力
  5. 后续需要调试单条命令、编写 batch JSON 或 YAML 时，再进入纯 CLI 模式

这个顺序更符合官方推荐的使用路径：先完成环境预检，再读取状态，再执行动作，最后验证结果。

纯命令行安装与校验 ​

如果你准备直接使用 vmos-edge-cli，建议先完成一遍标准预检。

Preflight 标准流程 ​

bash
node --version
vmos-edge-cli --version
npm i -g @vmosedge/cli
vmos-edge-cli schema

这组命令对应官方建议的标准 Preflight 流程：

  • 检查 Node.js 版本
  • 检查 CLI 是否已安装
  • 如未安装则执行安装
  • 通过 schema 做最终验证

检查失败时的处理 ​

  • node 不存在：先安装 Node.js 18+
  • npm 不存在：通常表示 Node.js 未正确安装
  • vmos-edge-cli 不存在：执行安装命令后重新验证
  • schema 失败：先处理错误，不要继续后续命令

桌面客户端路径配置 ​

如果 VMOS Edge Desktop 不在默认安装路径，需要先设置 app.bin-path，再执行 app start。

常见默认路径如下：

平台默认路径
WindowsC:\Program Files\VMOS Edge 2.0\VMOS Edge 2.0.exe
macOS/Applications/VMOS Edge 2.0.app
Linux/opt/vmos-edge/vmos-edge

设置路径：

bash
vmos-edge-cli config set app.bin-path "你的实际安装路径"

查看配置：

bash
vmos-edge-cli config show

第一次跑通 ​

如果你第一次使用纯 CLI，建议按下面顺序操作一遍。

1. 启动桌面客户端 ​

bash
vmos-edge-cli app status
vmos-edge-cli app start
vmos-edge-cli app wait-ready

2. 检查主机状态 ​

bash
vmos-edge-cli host check 192.168.1.100
vmos-edge-cli host info 192.168.1.100

3. 查看镜像与设备 ​

bash
vmos-edge-cli image list --host 192.168.1.100
vmos-edge-cli device list --host 192.168.1.100

4. 创建一个云机 ​

bash
vmos-edge-cli device create --host 192.168.1.100 --image <image_id> --name demo --count 1

5. 启动设备并查看详情 ​

bash
vmos-edge-cli device start --host 192.168.1.100 <device_id>
vmos-edge-cli device info --host 192.168.1.100 <device_id>

使用提示

  • 大多数 device 和 image 命令都需要传入 --host <ip>
  • host 系列命令通常把 IP 作为位置参数传入
  • 应用会在命令之间保持运行，通常不需要每次都重复执行 app start

三种调用方式 ​

官方将 vmos-edge-cli 的调用方式分为 Direct、Batch、Run 三类。

Direct ​

适合执行单个动作，或者执行后需要先查看结果，再决定下一步。

bash
vmos-edge-cli device list --host 10.0.0.5

Batch ​

适合一组彼此独立、可以连续安全执行的动作。

bash
vmos-edge-cli batch '[
  {"action":"device.list","args":{"host":"10.0.0.5"}},
  {"action":"image.list","args":{"host":"10.0.0.5"}},
  {"action":"host.hardware","args":{"ip":"10.0.0.5"}}
]'

Run ​

适合把一整套操作保存成 YAML 文件，后续反复执行。

核心判断规则如下：

  • 每一步都可以不依赖前一步结果直接执行：用 Batch
  • 必须先看结果再决定下一步：用 Direct
  • 需要沉淀成可复用流程：用 Run

编写批处理与工作流前的准备 ​

在写 batch JSON 或 YAML 之前，建议先运行 schema，不要直接猜动作名和参数名。

bash
vmos-edge-cli schema
vmos-edge-cli schema device
vmos-edge-cli schema ui

编写时可重点注意下面几条：

  • device、host、image 参数通常使用 snake_case
  • ui 参数通常使用 camelCase
  • CLI 里的位置参数，在 batch / YAML 中通常会变成命名字段
  • sleep 只在 batch / run 中可用，其余动作通常都有 direct 命令形式

桌面自动化使用方式 ​

桌面自动化推荐的基本流程是：先读取页面状态，再执行交互动作，页面变化后立即重新读取状态。

1. 读取当前页面状态 ​

bash
vmos-edge-cli ui state

如果页面元素较多，只想看可交互元素：

bash
vmos-edge-cli ui state --interactive-only

2. 点击或输入 ​

bash
vmos-edge-cli ui click 3
vmos-edge-cli ui type 5 "test text"

3. 页面变化后重新读取状态 ​

执行 click、goto、back、type 之后，建议重新执行一次 ui state，不要复用旧的元素编号。

桌面自动化使用原则 ​

优先使用 ui state ​

平时做页面检查、元素定位和状态读取时，优先使用 ui state。只有在明确需要保存图像结果时，才使用 ui screenshot。

优先使用 ui click / ui type ​

交互动作优先使用 ui click、ui type、ui select、ui native-type 等官方动作，不建议用 ui eval 模拟点击或输入。

找不到元素时先判断是否离屏或被遮挡 ​

如果目标元素在视区外，可先查看 hidden_interactive，再用 ui scroll-to 滚动到可见区域；如果被弹窗遮挡，先关闭弹窗再继续操作。

中文输入建议使用 ui native-type ​

对于中文、输入法或 CJK 场景，建议先点击输入框获取焦点，再使用 ui native-type 输入内容。

命令结果与错误排查 ​

返回结构 ​

CLI 输出通常采用统一 JSON 外层结构。

成功时一般返回：

json
{"ok": true, "data": ...}

失败时一般返回：

json
{"ok": false, "error": "...", "code": "..."}

排查问题时，建议先看 code，再看 error。

常见错误 ​

错误码含义处理方式
HOST_NOT_SET缺少主机参数补充 --host <ip>
INVALID_ARGS参数结构错误先修正参数，不要盲目重试
DEVICE_NOT_FOUND设备 ID 无效重新执行 device list 获取有效 ID
IMAGE_NOT_FOUND镜像 ID 无效重新执行 image list 获取有效镜像
ELEMENT_NOT_FOUND当前页面找不到目标元素重新执行 ui state 获取新编号
APP_NOT_RUNNING桌面客户端未启动先执行 app start
HOST_UNREACHABLE主机网络不可达检查 IP 与网络连通性
CDP_NOT_READYUI 自动化通道未就绪稍等片刻后重试，必要时先执行 app start
TIMEOUT / TRANSIENT短暂超时或瞬时故障仅在场景本身会最终完成时才重试

不建议在完全不修改任何条件的前提下，反复重试下面这类错误：

  • INVALID_ARGS
  • HOST_NOT_SET
  • DEVICE_NOT_FOUND
  • IMAGE_NOT_FOUND
  • ELEMENT_NOT_FOUND
  • ASSERTION_FAILED

新手最短上手路径 ​

如果你是第一次接触 VMOS Edge CLI，推荐按下面路径开始：

  1. 安装 Node.js 18+
  2. 执行 npm i -g @vmosedge/cli
  3. 执行 vmos-edge-cli schema
  4. 执行 npx skills add https://github.com/vmos-dev/vmos-edge-skills --skill operate-vmos-edge-cli
  5. 在 AI Agent 中开始调用 VMOS Edge 能力
  6. 需要调试或编排流程时，再补充使用纯 CLI

一句话总结 ​

普通用户优先通过 AI Agent + 官方 Skill 接入，纯 CLI 更适合进阶调试与流程编排。正式使用前先完成 Preflight；做桌面自动化时，优先 ui state，页面变化后立即重新读取状态。

VMOS Edge 团队出品

© 2026 VMOS Edge