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

# HarmonyOS 环境配置

Midscene 通过 HarmonyOS Device Connector（HDC）连接并控制 HarmonyOS NEXT 设备，支持对原生应用、元服务及系统界面进行自动化操作。

本文介绍如何准备 HarmonyOS 环境：安装 HDC 并连接设备。Playground、Midscene Test 和 JavaScript SDK 都使用同样的连接。

## 通过 HDC 连接设备 {#connect-device}

运行 Midscene 的电脑需要通过 `hdc` 连接目标 HarmonyOS NEXT 设备。如果已安装 `hdc` 并连接好设备，可直接跳至[确认设备连接](#verify-device-connection)。

### 安装 HDC

HDC（HarmonyOS Device Connector）是 HarmonyOS 官方提供的设备连接命令行工具，可通过以下任一方式安装：

- 通过 [DevEco Studio](https://developer.huawei.com/consumer/cn/deveco-studio/) 安装（推荐）
- 下载 [HarmonyOS 命令行工具（Command Line Tools）](https://developer.huawei.com/consumer/cn/download/)独立安装

在终端运行以下命令，验证 `hdc` 是否安装成功：

```bash
hdc version
```

终端输出版本号即表示安装成功。

:::info 配置 HDC 路径

如果 `hdc` 未加入系统 `PATH`，可以通过设置 `HDC_HOME` 环境变量指向 `hdc` 所在的目录：

```bash
export HDC_HOME=/path/to/hdc/directory
```

:::

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

1. 在 HarmonyOS 设备的系统设置中进入「系统 > 开发者选项」，开启 **USB 调试**。
2. 使用支持数据传输的 USB 数据线将设备连接到电脑。
3. 保持设备解锁亮屏，并在设备弹窗中允许 USB 调试授权。

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

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

```bash
hdc list targets
```

终端输出设备序列号（Device ID）即表示连接就绪：

```log
0123456789ABCDEF
```

如果同时连接了多台设备，请记录目标设备的序列号，以便后续在 Playground 或项目配置中指定该设备。若输出为空或显示 `[Empty]`，请检查 USB 数据线、连接模式、**USB 调试**开关及手机端的调试授权弹窗。

## 验证 {#verify}

`hdc list targets` 输出目标设备 ID 后，在 Playground 中验证环境。打开[开始使用](/zh/get-started.md?platform=harmonyos\&scene=playground)，页面已为你选好 HarmonyOS 和 Playground，选择模型接入方式后，按步骤执行一次 `aiAct` 操作和一次 `aiAssert` 断言。断言通过即表示 HDC 连接、屏幕截图、触控输入和模型调用都正常。

## 常见问题

### 输入文本后键盘未收起，或页面意外返回

请参阅 [HarmonyOS JavaScript SDK](/zh/sdk/harmonyos.md#输入文本后键盘未收起或页面意外返回)。

### 如何指定自定义的 HDC 路径？

可以通过 `HDC_HOME` 环境变量指定 `hdc` 所在的目录：

```bash
export HDC_HOME=/path/to/hdc/directory
```

通过代码参数传入的方式请参阅 [HarmonyOS JavaScript SDK](/zh/sdk/harmonyos.md#如何指定自定义的-hdc-路径)。