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

# 开始使用：Android · Playground · ChatGPT 订阅 {#get-started}

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

## 连接 Android 设备
运行 Midscene 的电脑需要通过 `adb` 连接目标 Android 设备，支持 USB 和无线 `adb` 两种连接方式。如果已安装 `adb` 并连接好设备，可直接跳至[确认设备连接](#verify-device-connection)。

### 安装 adb

- 通过 [Android Studio](https://developer.android.com/studio) 或独立的 [Android 命令行工具](https://developer.android.com/studio#command-line-tools-only)安装 `adb`。
- 在终端运行以下命令，验证 `adb` 是否安装成功：

```bash
adb --version
```

输出类似以下内容即表示安装成功：

```log
Android Debug Bridge version 1.0.41
Version 34.0.4-10411341
Installed as /usr/local/bin/adb
Running on Darwin 24.3.0 (arm64)
```

- 参考 [Android 环境变量文档](https://developer.android.com/tools/variables)配置 `ANDROID_HOME` 环境变量，并检查是否生效：

```bash
echo $ANDROID_HOME
```

输出应指向本机安装的 Android SDK 目录，例如：

```log
/Users/your_username/Library/Android/sdk
```

### 开启调试并连接设备

以下以 USB 连接为例；如果设备已通过无线 `adb` 连接，可继续使用现有连接。

1. 在手机系统设置的「开发者选项」中开启 **USB 调试**（若同时存在 **USB 调试（安全设置）**，请一并开启，以确保支持触控事件注入）。
2. 使用支持数据传输的 USB 数据线将手机连接到电脑。
3. 保持手机解锁亮屏，在手机弹出的授权窗口中勾选并允许 USB 调试。

![android usb debug](/images/android-usb-debug-en.png)

### 确认设备连接 {#verify-device-connection}

在终端运行以下命令检查连接状态：

```bash
adb devices -l
```

输出中设备状态显示为 `device` 即表示连接就绪：

```log
List of devices attached
s4ey59	device usb:34603008X product:cezanne model:M2006J device:cezan transport_id:3
```

如果同时连接了多台设备，请记录目标设备所在行第一列的设备 ID（如上例中的 `s4ey59`），以便后续在 Playground 或项目配置中指定该设备。

若未显示目标设备或状态不是 `device`，请按以下情况排查：

- **列表为空**：USB 连接请检查数据线（需支持数据传输）、USB 连接模式和 **USB 调试**开关；无线连接请检查网络及 `adb connect` 连接状态。
- **`unauthorized`**：请解锁手机屏幕，在手机弹出的授权窗口中勾选并允许 USB 调试。
- **`offline`**：请重新建立 USB 或无线 `adb` 连接，必要时重启 `adb` 服务。请确认设备状态变为 `device` 后再继续后续步骤。

## 使用 ChatGPT 订阅登录

登录命令需要 Node.js `^20.19.0 || ^22.12.0 || >=24.0.0` 和 pnpm。请确认终端中可以执行 `node -v`；如果尚未安装 pnpm，请运行 `npm install -g pnpm`。

首先，在终端运行：

```bash
pnpm dlx @midscene/cli model siwc login
```

按照终端提示，在浏览器中登录 ChatGPT 并授权使用订阅额度。授权时可以自行设置 Agent 名称；完成后，可在 ChatGPT 的使用情况页面查看已授权的 Agent。

命令会将凭据保存到 `~/.midscene/siwc.json`。首次使用前需要手动完成这一步登录。

Playground 会读取该命令保存的凭据。请先保留以下配置，后面的步骤会把它粘贴到 Playground 设置中：

```bash
MIDSCENE_MODEL_AUTH_MODE="siwc"
MIDSCENE_MODEL_NAME="gpt-6-sol"
MIDSCENE_MODEL_FAMILY="gpt-6"
```
可用模型以你的 ChatGPT 账号为准。凭据与额度说明请参阅[使用 ChatGPT 订阅](/zh/chatgpt-subscription.md#额度与凭据)。

## 启动 Playground

请确保已安装 Node.js（版本要求 `^20.19.0 || ^22.12.0 || >=24.0.0`），且终端中可正常执行 `node -v`。下方命令使用 pnpm，如果尚未安装，请运行 `npm install -g pnpm`。

1. 在终端运行以下命令启动 Android Playground：

```bash
pnpm dlx @midscene/android-playground
```

2. 在打开的 Playground 页面中，点击右上角的齿轮图标，粘贴模型配置并保存。

![](/images/android-set-env.png)

3. 若浏览器未自动打开，请手动访问终端打印的本地地址，并保持该终端进程持续运行。
4. 在左侧连接面板中选择目标 **ADB device** 并创建 Agent（若连接了多台设备，可对照 `adb devices -l` 输出的设备 ID 进行选择）。
5. 确认预览区域已正常显示当前手机屏幕画面；若画面未显示，请先排查 `adb` 连接与截屏权限。

## 执行操作并验证结果

在手机上打开系统浏览器，跳过首次启动引导，然后在地址栏中输入以下 TodoMVC 地址：

```text
https://todomvc.com/examples/react/dist/#/
```

保持手机处于解锁亮屏状态且浏览器位于前台。

1. 在 Playground 中选择 `aiAct`，输入以下指令并运行：

```text
添加一个名为“体验 Midscene”的待办事项，然后将它标记为已完成。
```

2. 待页面中出现已勾选完成的待办事项后，切换到 `aiAssert`，输入以下断言并运行：

```text
列表中存在名为“体验 Midscene”的待办事项，且它已被标记为完成。
```

3. 确认断言执行通过，并在结果面板中查看各步骤的截图与执行过程。至此，设备连接、屏幕截图、触控输入和模型调用均已验证完毕。

4. （可选）切换到 `aiQuery`，输入以下查询并运行：

```text
列表中可见的待办事项，返回 {name: string, completed: boolean}[]。
```

结果会包含待办事项名称及其完成状态。`aiQuery` 用于从当前界面提取数据，不会修改页面。

如果执行失败，请结合报错信息排查：若无画面或无法操控设备，请查看[常见问题](/zh/platforms/android.md#常见问题)；若模型请求报错，请参考[模型连接检查](/zh/model-config.md#verify-model-connectivity)。

验证结束后，请在 TodoMVC 页面中删除刚才创建的“体验 Midscene”待办事项。如果接下来要运行 Midscene Test 的 Android 示例，请切换到 **All** 视图并确认列表已完全清空（包括已完成事项），因为示例模板在运行前会校验初始列表为空，且不会主动覆盖已有数据。

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

- **编写可重复运行的用例**：使用相同的平台和模型[创建 Midscene Test 项目](/zh/get-started/android-test-chatgpt.md)。用例是 YAML 文件，可以在本地或 CI 中运行。

- **接入 Vitest**：使用相同的平台和模型，[在 Vitest 测试中调用 Midscene](/zh/get-started/android-sdk-chatgpt.md)。

- **了解 Midscene 的工作方式**：[基本概念](/zh/basics.md)介绍了基于视觉的方案，以及 `aiAct`、即时操作和洞察类 API 的适用场景。