将阿里云手机接入 xopc
本文适用于已经购买、正在运行的阿里云 Android 云手机。你需要在阿里云控制台准备两样东西，然后在 xopc 上传配置：
| xopc 配置项 | 去哪里获取 | 填写示例 |
|---|---|---|
| 手机名称 | 自己命名，方便在 xopc 中区分 | 阿里云测试手机 |
| ADB 地址 | 云手机控制台的「ADB 连接方式」或连接命令 | 203.0.113.10:10001 |
| 私钥文件 | 创建 ADB 密钥对时浏览器下载的 adbkey | 选择下载目录中的 adbkey 文件 |
以上 IP 仅为格式示例，不能直接连接。不需要阿里云 AccessKey、阿里云账号密码或 SSH 密钥。 手机模型的 API Key 在「智能 → 模型」配置，与这里的 ADB 私钥分开管理。
1. 找到云手机和 ADB 入口
如果你购买的是 Agentic Mobile，可打开 Agentic Mobile 节点控制台，找到目标手机，打开它的 ADB 连接面板。本文后续以包含「绑定密钥对」「创建 ADB 连接」的面板为例；控制台版本不同，按钮位置可能有所变化。
如果你使用标准无影云手机控制台，可从 无影云手机控制台 的实例列表进入连接操作。该版本的密钥管理入口通常是「网络与安全 → 密钥」，实例连接入口可能标为「一键 ADB」。详细入口以阿里云官方 ADB 连接指引为准。
确认选中的是你准备交给 xopc 使用的手机，并且实例处于运行状态。
2. 创建密钥对，取得私钥文件
在目标手机的 ADB 连接 → 绑定密钥对中，打开 密钥对管理：
- 点击「创建」，输入名称，例如
xopc-phone，确认创建。 - 浏览器会下载名为
adbkey的文件。打开浏览器下载列表，找到这个文件，并保存好。 - 回到密钥对列表，确认刚创建的密钥对已出现。
标准无影云手机控制台也可以通过「网络与安全 → 密钥 → 创建密钥对」完成此步骤。创建时下载私钥、文件丢失后需要重新创建的规则见阿里云官方密钥管理说明。
要选哪个文件？
| 文件或内容 | 用途 | 是否上传到 xopc |
|---|---|---|
adbkey | ADB 私钥；通常没有扩展名 | 是 |
adbkey.pub | ADB 公钥；用于将已有公钥导入云控制台 | 否 |
密钥对名称、kp-... ID | 控制台中的密钥对标识 | 否 |
| 阿里云 AccessKey、AutoGLM API Key | 云账号或模型服务凭据 | 否 |
下载文件通常位于浏览器设置的下载目录，例如 macOS 的 ~/Downloads/adbkey，或 Windows 的「下载」文件夹。浏览器可能给重复下载的文件增加后缀，请选择这次创建、且对应目标手机绑定密钥对的私钥；不要按名称猜测其他同名文件。
已有密钥对且私钥仍在时可以直接使用。若当初是通过「导入」添加公钥，需要找到生成该公钥时对应的原始私钥。若私钥丢失，应创建新密钥对并重新绑定，不能用公钥或密钥对 ID 替代。
xopc 当前支持未加密的 RSA 2048 私钥。优先使用阿里云控制台直接创建并下载的 adbkey。不需要把私钥内容粘贴进聊天，也不需要复制到 ~/.android/adbkey 或重启本机 ADB 服务。
3. 将密钥对绑定到手机
创建密钥对不等于已经绑定手机。在目标手机的「绑定密钥对」中选择刚创建的密钥对，确认绑定；如需保存或下一步，按面板提示完成。
在标准无影云手机控制台，也可从密钥列表选择「绑定密钥对」，将目标实例加入绑定列表。
绑定完成后，再进行下一步创建 ADB 连接。上传到 xopc 的私钥必须与此处绑定的密钥对一致。
4. 创建 ADB 连接，取得地址
在目标手机的 创建 ADB 连接页完成创建，等待控制台显示成功，然后展开 ADB 连接方式。
假设控制台给出的示例命令是：
adb connect 203.0.113.10:10001那么 xopc 的「ADB 地址」只填写：
203.0.113.10:10001不要粘贴 adb connect、http://、控制台网页地址或实例 ID。端口必须与控制台显示一致，不能把公网映射端口自行改成 5555。
公网和私网怎么选？
连接由 Gateway 所在机器发起：
| 使用方式 | 地址选择 |
|---|---|
| Electron 内置 Gateway 在自己电脑上运行 | 通常使用云控制台提供的公网 IP 和公网端口 |
| Gateway 在另一台服务器上运行 | 使用那台服务器可以访问的公网地址，或已经打通的私网地址 |
| Gateway 与云手机处于互通的私网 | 可以使用控制台提供的私网 IP 和私网端口 |
例如控制台同时显示私网 192.168.1.120:5555 和公网 203.0.113.10:10001，家庭电脑通常应填写公网这一组。不能混用公网 IP 与私网端口。
能在阿里云网页里打开手机画面，并不代表 Gateway 到 ADB 地址的网络已经通。若控制台提示需要配置公网连接、网络访问或安全组，请按该产品的官方说明完成，仅允许所需来源地址访问。不同产品、网络类型的端口和配置方式可能不同，以当前控制台为准；xopc 不会自动创建云端网络规则。参见官方 ADB 连接与网络前提。
5. 在 xopc 测试并添加
- 打开 设置 → 手机控制，启用手机控制。
- 点击 添加手机 → 阿里云手机。
- 填写手机名称和上一步的 ADB 地址。
- 在「私钥文件（adbkey）」中选择下载好的私钥文件。浏览器会将文件提交给当前连接的 Gateway，填写文件路径不能代替选择文件。
- 点击 测试连接。成功后应看到手机型号、Android 版本和当前画面；这一步不调用 AutoGLM，也不需要模型 API Key。
- 确认设备正确后，点击 添加手机，按需勾选「设为默认手机」。测试结果有效期为 10 分钟，修改地址或文件后需要重新测试。
- 添加后在设备「管理」里确认应用范围。初始只允许系统设置
com.android.settings；预览或操作其他应用前，需要明确加入相应包名。
手机连上后，要让 Agent 执行任务，还需在「智能 → 模型」配置真实手机模型，再在手机控制页选择并保存。模拟模型只支持本地模拟器，不能用于云手机。更多说明见手机模型配置。
可以先交给 Agent 一个简单的只读任务：
使用 phone_use 操作默认手机，打开系统设置，查看 Android 版本，不修改任何设置，完成后关闭手机会话。
在 Gateway 所在电脑安装固定版本视频服务（pnpm exec tsx scripts/setup-phone-video.mts）后，阿里云手机可直接复用聊天面板的 scrcpy 实时视频、持续触控、接管操作和交还 Agent。Gateway 使用已保存的 ADB 私钥上传校验过的视频服务，通过独立连接传输视频和输入，浏览器不会收到私钥。视频出错或浏览器不支持 WebCodecs 时明确降级为截图。连接测试预览和设置页查看屏幕弹窗仍使用截图。
常见问题
| 现象 | 处理方式 |
|---|---|
没有下载到 adbkey | 查看浏览器下载列表、默认下载目录及下载拦截提示。若文件已经丢失，创建新密钥对并绑定，不要上传公钥。 |
| 提示私钥格式不正确 | 选择私钥文件而非 .pub、文本截图或密钥对 ID；使用未加密的 RSA 2048 私钥。 |
| 连接失败、鉴权失败 | 核对实例是否运行、绑定的密钥对是否对应上传的私钥，以及 ADB 连接是否创建成功。 |
| 连接超时 | 核对公网/私网地址与端口组合，确认 Gateway 主机的网络可达，并检查云端访问规则。不要只检查浏览器所在电脑。 |
| 测试成功，但没有出现在手机列表 | 测试不等于添加，还需点击「添加手机」。超时或 Gateway 重启后重新测试。 |
| 测试成功，但查看屏幕提示应用未授权 | 测试预览用于核对设备；正式查看受应用范围限制。手动进入已授权应用，或在「管理」中授权所需包名。 |
| 模拟模型无法操作云手机 | 改用配置好的真实手机模型，模拟模型仅允许本地模拟器。 |
| 地址或私钥已更换 | 从 xopc 移除旧连接，再用新地址和私钥重新测试、添加。 |
私钥保存和移除连接
测试阶段的私钥只临时保存在 Gateway 内存中。添加后，私钥写入 Gateway 凭据目录下的 phone-adb/，设备记录只保存引用。默认状态目录下通常为 ~/.xopc/credentials/phone-adb/；自定义状态或凭据目录时随之变化。目录权限为 0700，文件权限为 0600（支持 POSIX 权限的系统）。
Electron 使用其 Gateway 所在电脑的凭据目录；远程 Gateway 保存到服务器。上传文件不是上传到模型服务，也不是上传到阿里云账号管理接口。
xopc「移除连接」删除设备注册和保存的私钥，不会销毁或停机收费实例，也不会关闭阿里云侧的 ADB 连接。需要停用云端入口时，应另外到阿里云控制台处理。
阿里云通用文档中覆盖 ~/.android/adbkey 和重启 ADB 的步骤针对传统命令行客户端。使用本文的 xopc 云手机配置时，无需执行这些步骤：xopc 直接连接云手机，不修改电脑已有的 ADB 服务和密钥。