> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt.

# 开始使用：桌面端 · Midscene Test · 模型 API Key {#get-started}

本页是在**桌面端**上使用 **Midscene Test**、通过**模型 API Key** 接入模型的配置步骤。如需其他组合，请查看[全部配置路径](/zh/get-started.md#all-setup-paths)。

## 安装 Node.js
安装 Node.js `^20.19.0 || ^22.12.0 || >=24.0.0`，并确认终端中可以执行 `node -v`。
下文命令使用 pnpm。如果尚未安装，请运行 `npm install -g pnpm`。

## 授予桌面系统权限
- **macOS**：需要为启动 Playground 或运行脚本的终端 / IDE（如 Terminal、iTerm2、VS Code、Cursor、WebStorm 等）授予两项独立的系统权限：
  1. **辅助功能权限**（用于控制鼠标与键盘）：前往「系统设置 > 隐私与安全性 > 辅助功能」开启对应应用的开关（详见 [nut.js macOS 配置说明](https://github.com/nut-tree/nut.js#macos)）。
  2. **屏幕录制权限**（用于截取桌面画面）：前往「系统设置 > 隐私与安全性 > 屏幕录制」开启对应应用的开关。**授权后请完全退出并重启该终端或 IDE**，再启动 Playground。
- **Windows**：操作常规权限的桌面程序无需额外配置。但受 Windows 用户界面特权隔离（UIPI）机制限制，未提权的普通进程**无法**向「以管理员身份运行」的高权限窗口注入鼠标点击或按键事件（光标仍能移动到目标位置，但点击和按键会被系统静默丢弃）。建议优先以普通权限启动被测程序；若被测程序必须以管理员身份运行，请**同样以管理员身份启动运行 Midscene 的终端或 Node.js 进程**（详见下方[常见问题](/zh/platforms/desktop.md#windows点击对某些程序不生效)）。
- **Linux（图形桌面）**：需安装 [ImageMagick](https://imagemagick.org/script/download.php) 以提供截图能力。
- **Linux（无头服务器 / CI 环境）**：在没有物理显示器的 Linux 服务器（如 GitHub Actions）上运行时，需安装 Xvfb 与 ImageMagick，并开启无头（Headless）模式自动创建虚拟显示器：

```bash
# 安装依赖
sudo apt-get install -y xvfb x11-xserver-utils imagemagick
```

使用 Xvfb 时，请确保被测应用同样启动在该虚拟显示器环境中（本机带有物理显示器时无需开启此项）。
如需通过 RDP 控制远程 Windows 桌面，请参阅[桌面端环境配置](/zh/platforms/desktop.md#connect-device)。

## 创建测试项目

```bash
pnpm dlx @midscene/test create my-tests \
  --platform computer \
  --package-manager pnpm
cd my-tests
```

该命令会生成项目文件、安装依赖并生成 Node 说明书，不会运行测试。生成的文件说明请参阅[项目结构](/zh/midscene-test/use.md#project-structure)。

## 配置模型

在 `my-tests` 目录中，将 `.env.example` 复制为 `.env`：
```bash
cp .env.example .env
```

在下方选择一个模型，它的配置包含四项。点击**获取 API Key**到服务商创建 API Key，再用它替换 `MIDSCENE_MODEL_API_KEY` 中的 `......`。

下方是 Doubao-Seed-2.1 Turbo 的配置。其他推荐模型：

- [Qwen3.7 Plus](/zh/model-api-setup.md#qwen) (阿里巴巴)
- [DeepSeek V4.1 Flash](/zh/model-api-setup.md#deepseek) (深度求索)
- [Gemini 3.5 Flash](/zh/model-api-setup.md#gemini) (Google)
- [GPT-6 Sol](/zh/model-api-setup.md#gpt) (OpenAI)
- [Kimi K3](/zh/model-api-setup.md#kimi) (月之暗面)
- [MiMo V2.6 Pro](/zh/model-api-setup.md#xiaomi-mimo) (小米)
- [GLM-5V-Turbo](/zh/model-api-setup.md#glm-v) (智谱)
- [Ling-3.0-flash-VL](/zh/model-api-setup.md#ant-ling) (蚂蚁集团)

**火山引擎** ([获取 API Key](https://console.volcengine.com/ark))

```bash
MIDSCENE_MODEL_BASE_URL="https://ark.cn-beijing.volces.com/api/v3"
MIDSCENE_MODEL_API_KEY="......"
MIDSCENE_MODEL_NAME="doubao-seed-2-1-turbo-260628"
MIDSCENE_MODEL_FAMILY="doubao-seed"
```

**OpenRouter** ([获取 API Key](https://openrouter.ai/settings/keys))

```bash
MIDSCENE_MODEL_BASE_URL="https://openrouter.ai/api/v1"
MIDSCENE_MODEL_API_KEY="......"
MIDSCENE_MODEL_NAME="bytedance-seed/seed-2-1-turbo"
MIDSCENE_MODEL_FAMILY="doubao-seed"
```

其他版本与使用说明请参阅[豆包 Seed 系列](/zh/model-api-setup.md#doubao-seed-model)。

各模型的差异请参阅[模型选择指南](/zh/model-selection.md)。UI-TARS 等兼容模型请参阅[使用模型 API Key](/zh/model-api-setup.md#支持的模型)。

用这份配置填写 `.env` 中的四项 `MIDSCENE_MODEL_*` 变量。

## 验证模型并完成配置
运行以下命令，检查模型能否连通、是否与 Midscene 兼容。该命令只读取当前目录下的 `.env`，不需要浏览器或设备：
```bash
pnpm exec midscene-test model verify
```
如果验证失败，请参阅[验证模型连接](/zh/model-config.md#verify-model-connectivity)。

如需控制主显示器以外的显示器，请在 `.env` 中设置 `COMPUTER_DISPLAY_ID`。在无界面 Linux 环境中，还需设置 `MIDSCENE_COMPUTER_HEADLESS_LINUX=true`。

## 运行示例并查看报告

示例会在目标显示器的浏览器中打开 React TodoMVC，并先检查列表为空。运行期间请勿移动鼠标或操作键盘。如果列表中留有之前运行产生的待办事项，请切换到 **All** 并删除全部事项（包括已完成的事项）。

```bash
pnpm test
```
终端会输出测试结果和 `Report:` 报告路径。打开 HTML 报告，选择用例和步骤即可查看截图、输入输出和错误信息。报告默认保存在 `midscene_run/report/` 目录下。
用例通过即表示模型、运行环境和项目都已正常工作。运行参数请参阅[运行测试](/zh/midscene-test/running.md)。

## 下一步
- **查看更多案例**：[案例展示](/zh/showcases.md)收录了各平台的演示视频和完整执行报告。

- **测试自己的应用**：在被控制的显示器上打开目标应用，再用 `aiAct` 和 `aiAssert` 描述步骤。如需在用例中启动或重置应用，请[开发自定义 Node](/zh/midscene-test/extend.md)。

- **编写和组织用例**：[编写 YAML 用例](/zh/midscene-test/writing.md)介绍了输入、变量、标签和 hooks。
- **在 CI 中运行**：请参阅[在 GitHub Actions 中运行](/zh/midscene-test/running.md#在-github-actions-中运行)。