手机控制（Android 预览）

当前版本支持通过 Gateway 所在电脑的 ADB 控制 Android 模拟器和手机，也支持通过 ADB 地址与私钥接入已有阿里云手机。提供独立手机模型配置、设备管理、Agent 工具权限及有界执行。云厂商账号自动接入、远程 Runner、鸿蒙和 iOS 尚未实现。

已有阿里云手机？先阅读阿里云手机接入指南，按步骤获取 ADB 地址和私钥文件。

向云手机共享当前位置

在 Web 手机面板点击「共享当前位置」，选择大概或精确位置，再点击「同意并共享」，随后完成浏览器定位授权。即使 Gateway 部署在云端，位置仍来自打开 UI 的设备。浏览器需要 HTTPS 或其他安全上下文。首次应用位置前，先暂停正在执行的 Agent。

可选单次位置（30 秒有效）或最多五分钟的前台持续共享（每十秒重新采样）。点击「停止共享」、离开页面、撤销系统权限、来源失联、位置过期或任务结束后，会恢复云手机原来的定位。未能验证恢复时，显示「重试定位清理」，依赖定位的 Agent 操作保持阻止。原生移动端共享页面和后台持续定位尚未接入。

无影适配器复用已注册的 ADB 连接，并同时校验定位属性与 Android GPS 回读；不支持的镜像格式会拒绝写入。有定位权限的应用可能读取位置，任务模型也可能从画面获知。原始用户采样不进入聊天或长期记忆，第三方应用已保存的信息无法撤回。定位同步不会改变云手机的网络出口或账号资料。

使用本机模拟器

1. 启动 Android 模拟器。
2. 打开「设置 → 手机控制」，开启功能。
3. 选择已配置的真实手机模型并保存，配置方法见下方「配置手机模型」。
4. 刷新设备，添加模拟器。新连接默认允许所有应用，也可选「仅允许所选应用」，直接从手机应用列表中勾选；启用 phone_use 工具的 Agent 即可使用，无需额外填写 Agent ID。
5. 手动打开已授权应用，选择手机并填写一个小目标，点击「开始试运行」。

Gateway 电脑需要 Android SDK Platform Tools。浏览器打开控制台并不会让远程 Gateway 获得浏览器所在电脑的 USB 权限。ADB 可通过环境变量、常见 SDK 路径自动发现，也可在 xopc.json 配置 phone.adbPath。

无线连接手机（Android 11+）

打开「添加手机 → 无线连接 Android 手机」。手机与 Gateway 所在电脑需要处于同一局域网，仅浏览器与手机同网还不够。当前支持局域网私有 IPv4 地址，尚不包含跨公网连接器。

扫码配对：手机开启「开发者选项 → 无线调试」，选择「使用二维码配对设备」，扫描页面二维码。二维码有效期为 90 秒，页面分别显示配对与连接状态。连接成功后确认手机名称和应用访问范围，保存设备。

配对码：手机打开「使用配对码配对设备」，选择页面发现的配对地址，或手动填写手机 IP、配对端口和六位配对码。连接端口默认自动发现；mDNS 不可用时，填写无线调试首页显示的连接端口。配对端口与连接端口不同且会变化，不应默认填写 5555。「连接已配对设备」可用当前 IP 和连接端口直接连接，无需重复配对。

已保存的无线手机会在发现设备时尝试断线重连，每台手机最多每 30 秒重试一次；设备菜单也提供「重新连接」，支持手动填写变化后的地址。更新地址前会验证已认证手机的身份，保留设备名称、默认选择和应用权限，不会自动继续之前的 Agent 任务。若手机已忘记 Gateway，需先重新配对，再重连已有设备。删除 xopc 设备记录不会撤销 Android 的 ADB 信任，需在手机无线调试设置中手动忘记该电脑。

ADB 与 mDNS 均运行在 Gateway 电脑。发现失败时检查 Platform Tools、防火墙与 Wi-Fi 设备隔离，或手动填写地址。配对码和二维码凭据仅临时保存在内存，不写入日志或数据库。

配置手机模型

在「手机操作模型」选择兼容的专用手机模型或通用视觉模型并保存。页面显示所属服务商与凭据配置状态；新增服务商、API Key、模型 ID 和手机动作协议统一在「智能 → 模型」管理。手机控制页不再重复维护服务商连接。

连接 XOPC Cloud 后，尚未设置的全局手机模型会自动补为 xopc-cloud/phone，复用现有 Cloud 登录凭据，无需在客户端另填智谱 Key。已有手机模型选择和 Agent 覆盖保持不变。也可以在此页选择自己的独立模型；云端服务可用性与账户配额以 Cloud 为准。

使用 AutoGLM 时，在模型管理中配置相应服务商与 autoglm-phone，声明图像输入和 AutoGLM Phone 动作协议。专用模型须支持所选协议；通用视觉模型须同时支持图片输入与函数工具调用。模拟模型仅用于内部开发测试，不在用户模型列表中提供。

选择 AutoGLM 并保存后，「测试模型连接」只发送内置合成图片，不读取手机截图。测试分别检查动作协议与按钮定位，会产生真实模型调用，费用以平台账户为准。

通用视觉模型使用 OpenAI Chat Completions 或 Responses API、支持图片输入与函数工具调用时，会自动出现在手机模型列表中，使用 structured-tools-phone-v1，无需专门训练的手机模型或原生 computer 工具。可在 xopc 的 OpenAI 服务商中通过 ChatGPT OAuth 登录，再到手机操作设置中选择支持图片输入的 GPT 模型并保存；复用现有登录和凭据刷新，无需另填手机 Key。模型仍可用于普通聊天与看图。supportsTools: false 会排除不支持工具调用的模型；托管服务与专用电脑模型仍需显式声明手机支持。

专用手机模型需配置图片输入、OpenAI Chat Completions API 和受支持的手机协议：autoglm-phone-v1、structured-phone-v1、doubao-seed-phone-v1 或 gui-owl-phone-v1。通用函数工具协议 structured-tools-phone-v1 也可显式声明，支持 Responses。Agent 的模型设置可覆盖全局手机模型，聊天模型保持独立；当前不自动切换备用手机模型。

使用自己的云端模型 Key（BYOK）

在「智能 → 模型」添加 Volcengine Ark 或 Alibaba Bailian · Phone Use，填写自己的 Key 并保存，再到手机操作设置中选择模型。预设会自动带上图片输入和对应手机协议；已有服务商可手动新增模型。已有手机模型选择不会被替换。

服务商	Base URL	预设模型 ID	手机协议
火山方舟	https://ark.cn-beijing.volces.com/api/v3	doubao-seed-2-1-pro-260915	doubao-seed-phone-v1
百炼 Phone Use	https://dashscope.aliyuncs.com/compatible-mode/v1	gui-plus-2026-02-26	gui-owl-phone-v1

**申请豆包 Key：**登录火山方舟控制台，选择项目，在「API Key 管理」创建 Key，在「开通管理」开通对应 Seed 模型。步骤见官方快速入门。模型 ID 以账户实际可用项为准；如使用 ep-... 推理接入点，可替换模型 ID，保留手机协议。使用标准模型服务地址，不要混用 Coding Plan 地址和凭据。也可以在 Gateway 环境中配置 ARK_API_KEY 或 VOLCENGINE_API_KEY。

2026-10-27 已移除不可用的魔搭 GUI-Owl 预设与未做真机验证的 Seed Lite 预设。魔搭凭据保留供普通模型使用；手机列表仅保留已验证的豆包 Pro 和百炼 GUI-Plus 入口。

GUI-Owl 官方项目将百炼托管 API 指向 gui-plus-2026-02-26。这是厂商的 GUI-Plus 服务名，不表示某个开源 8B 权重的别名。其原生手机动作提示已通过 xopc 的截图定位与 Android 导航验证。本地 BYOK 选择 dashscope-phone/gui-plus-2026-02-26，托管服务选择 xopc-cloud/phone-gui-plus。根据官方 GUI-Plus 文档，须使用北京地域百炼 API Key，可按获取 API Key申请。手机服务与现有电脑操作服务使用独立入口，按所选能力限制控制协议。

BYOK 复用现有 Gateway 服务商凭据管理，直接请求配置的服务商，不要求连接 XOPC Cloud。保存模型不切换正在执行的会话。先使用「测试模型连接」：只发送合成图片，不操作手机。两种原生协议均只接受单个动作，拒绝批量、畸形和截断输出，继续由宿主执行应用限制和完成验证。目录中的费用占位值不代表免费；账户权限、实际费用、延迟和真实 App 成功率需用自己的 Key 验证。

原生 UI 无可读文字时，observe 会自动调用已配置的手机模型，只读识别当前截图。节点只包含部分文字时，可在 observe 提供 goal 指定读取目标；run / step 以模型结束、但未通过原生 UI 验证时，也会自动按原目标尝试一次截图读取。模型读取计入现有请求数和活跃时间预算，不执行点击或输入。

工具结果的 facts 仍只包含原生节点文字；readings 分别标明 source: native_ui / screenshot、verification: observed / unverified / unavailable，并附带 frameId 和 capturedAt。截图识别始终为未验证，不能满足原生完成条件或提升任务的 verified 状态。无法识别、预算不足或存在密码字段时，返回不可用原因，不猜测结果。聊天 Agent 应注明截图来源和未验证状态。识别文字只在会话内返回，不写入持久操作报告，原始截图不进入聊天记录。

手机管理与试运行

每台手机可修改名称、启用状态和应用权限。新连接的本机与云手机默认「允许所有应用」；选「仅允许所选应用」后，会读取手机上的真实应用名称，支持搜索和勾选，无需填写包名。已有应用限制会保留，直到用户主动修改。限制模式至少选择一个应用。应用列表复用实时画面的固定版本 scrcpy 组件。启用 phone_use 工具的 Agent 即可使用已授权手机，无需额外配置设备 Agent ID。修改访问范围会停止现有控制。「移除连接」仅删除 xopc 注册记录，不删除模拟器或应用。支持默认手机，离线后不会自动换另一台。

真实模型试运行前先手动打开已授权应用，再填写一个小目标，可选填写完成时应显示的具体文字。支持暂停、人工接管后恢复、继续当前目标、停止和释放手机。恢复后重新观察，丢弃旧动作。空闲或暂停后可以查看临时截图。

工具入口是 phone_use。每个小目标默认最多 6 步，最多可设 12 步，单次活跃操作预算由 phone.maxOperationDurationMs 配置，默认 300,000 毫秒（5 分钟），人工接管期间不消耗预算。每个任务另有动作和模型请求限制，活跃执行时限取 maxOperationDurationMs 与 maxSessionDurationMs 的较小值；连接寿命独立管理。预算耗尽返回 operation_timeout，保留界面事实与步骤并暂停会话，等待用户检查和交还；不会误报用户取消或自动重开重试。模型说完成但缺少界面证据时仍显示未验证。

停止不能撤销已送达 Android 的输入。结果未知时先核查，不能自动重发。当前只协调同一 Gateway SQLite 状态下的设备独占，同一手机应只由一个 Gateway/Runner 管理。

截图不进入聊天历史、附件库、持久报告或普通日志；原生界面文字只短期保留，持久化报告仅记录有上限的操作元数据。真实调用时截图会发送给手机模型，返回的界面文字也可能进入主 Agent 模型。

当目标值已出现在其他可见内容中、指定输入框却尚未出现时，下一次预测会收到一条有界差异提示，避免把“内容可见”误认为“已输入查询”；不自动生成输入或增加模型请求。声明了原生完成条件时，模型说“完成”仍需最新界面证据。条件未满足会反馈具体差异，最多纠正两次；迟到的界面结果可直接进入独立确认，无需再次预测。持续提前结束则暂停为 completion_unmet，不再追加说明请求或自动生成输入，检查后再继续。

Android 观察在一次操作内复用设备端无障碍进程，每次请求读取当前 UI 树；截图与派发前的新鲜度检查仍保留。操作结束、取消或人工接管时释放观察进程。其他自动化服务可能占用唯一的 UiAutomation 所有权，xopc 不会自动停止它们。

对明确请求的字段替换，当前聚焦、可识别且非密码的原生编辑框使用短事务：校验应用、控件标识、位置和旧值，只写一次，再确认同一原生节点的结果。确认失败暂停供人工检查，不自动重放。插入模式和旧驱动集成保留原输入链路。

旧链路中，Android 7 及以上的中文和 Emoji 输入通过独立的 scrcpy 控制通道粘贴，无需安装或切换输入法；视频降级为截图也可使用。输入内容可能保留在手机剪贴板，不读取或同步原有剪贴板。收到通道应答后还会检查输入框文字，不能确认时暂停等待接管，不重复输入或自动安装 APK。手机管理可关闭自动输入，改用手机自带键盘。密码框仍禁止自动输入；不开放任意 shell、安装 APK、提取文件或云资源管理。

开发验证

慢速本地视觉模型可通过 phone.modelRequestTimeoutMs 调整单次模型响应（含读取响应体）的时限，默认 45,000 毫秒，范围 1,000–300,000 毫秒。整体任务的活跃时间预算仍然生效；单次超时明确返回 PHONE_MODEL_TIMEOUT，不会派发该次未完成预测的动作，也不会自动重试。用户取消与模型超时分别处理。

pnpm exec tsx scripts/verify-phone-use.mts

脚本使用隔离临时状态启动真实 Gateway，通过鉴权和路由懒加载执行模拟器测试。只重启模拟器的系统设置任务，不清除应用数据。默认不调用付费模型，显式测试截图和元数据保存在 /tmp/xopc-phone-use-evidence。

构建 Web 后加 XOPC_PHONE_BROWSER=1 可检查桌面和窄屏页面；显式加 XOPC_PHONE_REAL_MODEL=1 且进程已取得 ZHIPU_API_KEY 才会进行真实 AutoGLM 测试。

在聊天中观看和接管

主 Agent 可调用 phone_use({ op: "request_user", reason: "请在手机上完成登录" }) 请求协助；普通 pause 只暂停任务。原任务、设备和 Agent 绑定以及剩余预算保存到 SQLite，不保存截图、密码、验证码或模型动作坐标。Agent 在主 Chat 用普通文字说明需要你做什么，手机入口显示小蓝点，不自动展开手机，也不增加接管操作卡。

点击手机入口仅查看画面，成功加载后清除本端的未查看提示；这不代表任务完成。进入手机页后明确点击「接管手机」，完成后点击「完成，继续任务」，或返回 Chat 明确说「我已登录，继续」。直接操作实体手机的用户可选择「我已处理，继续」，无需远程接管。普通问题、查看消息和打开画面均不会自动继续任务。手机页只保留设备与控制状态、画面和主操作，人工接管后提供返回键和文字输入；具体任务说明留在 Chat。

授权客户端可在观看容量范围内同时查看，同一台手机只能由一个客户端操作。另一端已接管时不能抢占。返回聊天、收起手机或切后台会释放本端人工控制，任务保持暂停；失联由服务端租约超时兜底，重新连接不自动恢复控制权。视频故障可降级为截图，不自动交还 AI。其他端仍在操作时，Chat 中的完成消息也不能绕过控制权校验。

完成请求持久化去重入队，即使上一轮尚在收尾也不会丢失；后续 turn 重新观察页面，沿用原 taskId、约束与剩余预算。刷新保留协助请求和本端已查看标记。Gateway 重启后先重新连接并校验设备及 Agent；执行中的续跑若被中断，重新等待用户明确交还，不自动重放输入。

「手机」入口和工作区绑定当前 Chat。只有存在 Phone Use 会话或可恢复协助请求的 Chat 才显示对应入口；手机面板只读取该会话的手机状态，不使用全局设备选择。切换 Chat 或离开聊天页会移除上一会话的画面，包括浮窗；每个 Chat 保留自己的工作区标签。任务结束、切换聊天或收起窗口后保持连接。任务完成释放操作权，其他聊天可以复用设备；工具 close 只结束当前任务，不断开连接。

连接默认保持至手动断开或 Gateway 停止。phone.idleDisconnectMs 默认 0；手机设置也可选择闲置 15、30 或 60 分钟后断开。执行任务、人工操作和前台查看画面期间不计闲置。面板隐藏会释放视频查看和人工输入权限，保留设备连接。

操作权由后端独占分配。其他聊天或人工正在控制时，返回 HTTP 409 / PHONE_DEVICE_BUSY，包含 executionStarted: false、占用来源和 retryPolicy: user_initiated，不会自动排队、重试或抢占。人工协助和手机控制绑定来源 Chat，设备管理仍在手机设置中进行。在来源聊天入口中也可以接管或停止当前任务。停止任务和断开连接都需要明确确认。派发结果不确定时保留检查状态，不能通过重新打开或取消绕过。

• 仅查看：安装固定版本视频服务后，聊天面板使用 scrcpy H.264 视频和 WebCodecs 解码；点击画面不会发送输入。浏览器不支持或视频出错时，明确降级为截图，并可重试视频。设置页的查看屏幕弹窗仍是只读截图。
• 接管操作：服务端暂停 Agent、等待已派发输入完成后开放人工控制。支持单指持续 DOWN/MOVE/UP 的点击、跟手拖动、长按，以及返回和非密码文本提交。移动不等待模型或逐次截图。中文通过独立的 scrcpy 粘贴通道输入，无需额外输入法；输入未确认时暂停等待接管检查。
• 退出接管：停止此窗口的人工输入，任务保持暂停。
• 交还给 Agent / 继续原任务：重新检查授权和当前页面，丢弃旧坐标后继续。正在等待的工具调用直接续接；若 Agent 已结束回复，面板会提交一次幂等的续接输入，让它继续本对话原任务。
• 停止任务：确认后结束当前任务并释放操作权，手机保持连接。断开连接是独立的确认操作。收起窗口仅结束观看；接管时收起窗口或切后台会尽力退出接管，断线由控制心跳超时兜底，保持暂停。

目前只允许 Gateway 管理员通过全局手机面板或聊天入口查看/控制，分享对话不包含手机画面。输入仍受设备应用白名单约束；Home 不开放，密码字段禁止自动输入。不要在普通文本输入框中输入密码或验证码，优先在设备本地完成，再返回非敏感页面交还。

首次在 Gateway 主机运行 pnpm exec tsx scripts/setup-phone-video.mts，下载并校验官方 scrcpy 3.3.3 服务。视频和人工操作不需要 AutoGLM Key。文字输入和交还仍检查原生界面；断连、隐藏窗口、几何变化与交还会释放触点，交还确认撤销后 main 才继续。人工操作不消耗 Agent 动作预算。

本机测试模拟器已启用宿主 GPU；关闭 GPU 会限制 Android 自身渲染速度。若进入未授权应用，画面会清除，可显式返回授权应用。前台应用检查是采样校验，并非设备侧按应用隔离采集。云手机媒体、输入与撤销接口已预留，尚未接入或验证云厂商 SDK。阿里云 ADB 接入已通过独立鉴权 TCP 连接复用 scrcpy 视频与持续触控，配置步骤见下方接入指南。

连接阿里云手机（ADB）

完整步骤见阿里云手机接入指南：包含控制台入口、创建和绑定密钥对、下载 adbkey、取得公网或私网 ADB 地址，以及 xopc 添加步骤和常见问题。

在「设置 → 手机控制 → 添加手机 → 阿里云手机」填写名称、IP:端口 并上传对应私钥。测试成功后检查型号、Android 版本和画面，再确认添加。无需阿里云 AccessKey；手机模型在模型管理中独立配置。

云手机使用独立 TCP ADB 连接，支持 scrcpy 实时视频与持续触控；视频不可用时降级为截图，不修改本机 ADB 服务或密钥。移除连接仅清理 xopc 注册与凭据，不销毁收费云实例或关闭云端 ADB 入口。

执行可靠性与完成证据

阿里云手机通过内置的只读无障碍采集程序获取节点，不等待全局界面空闲，避免动态设置页面导致 uiautomator dump 失败。程序通过已认证的 ADB 临时运行，采集后删除，不安装 APK；Gateway 同时检查节点和截图是否属于同一个前台应用。本地 ADB 固定使用压缩节点模式并进行有界重试。采集失败明确返回 PHONE_UI_UNAVAILABLE，不再伪装成界面变化或空节点；动作新鲜度检查仍然保留。修改 Java 源码后，使用 JDK 17、Android platform 36 和 build-tools 36.0.0，执行 node scripts/build-phone-ui.mjs <Android SDK 目录> 重建内置程序。

手机模型会收到有界的会话内动作轨迹、原生 UI 节点和执行变化反馈。AutoGLM 保留已验证的单个 JSON 用户观察消息；真实 App 对照中回退的对话重排、中心点提示及采样试验已撤回。轨迹与输入内容不保存到运行报告。格式错误最多允许每次 run 修复一次，计入模型请求预算；同一页面状态反复执行相同动作时以 no_progress 暂停，需要查看手机并显式交还后继续。

AutoGLM 的 Type / Type_Name 会替换当前聚焦的非密码字段：重新确认字段身份，在支持时选中原内容，只输入一次，并验证最终准确值。结构化 typeText 默认仍为插入，可指定 mode: "replace"。延迟验证只重新观察，不重发输入。

run / step 可传入组合完成条件，例如：

{
  "op": "run",
  "goal": "进入关于手机并查看 Android 版本",
  "completion": {
    "appPackage": "com.android.settings",
    "textAny": ["Android version", "Android 版本"],
    "textAll": ["15"],
    "requireChange": true
  },
  "maxActions": 8
}

所有已提供条件都必须满足。应选择稳定的页面身份和与目标直接相关的证据，不额外要求无关条目同时可见。textAny 支持界面语言别名，textAll 要求每条文本都出现；field: { "resourceId": "package:id/query", "value": "coffee" } 要求可编辑字段准确匹配。旧 expectText 继续兼容，与组合条件同时生效。验证检查全部已采集原生节点，不受显示事实的 60 条上限影响。requireChange 仅表示本次执行观察到了 UI 变化，不能证明具体业务结果；完成条件必须在连续两次新观察中成立，期间仍检查取消、控制权与授权变更；模型自行结束仍未验证。

复验脚本、模拟回放对比和真实模拟器证据见优化报告。

真实 App 续轮评测及未采纳方案见真实 App 优化报告。

实验性语义执行与分层规划

可在 xopc.json 顶层 phone 配置中独立启用 semanticControls: true 和 hierarchicalPlanning: true；两项默认均为 false。

语义执行要求按当前观察的 frameId 和控件 ID、文字或描述精确匹配一个完整可见的非密码节点，再通过已有的新鲜度与派发检查转换为点击；标准坐标点击也可由执行器绑定到命中位置唯一、大小受限的原生控件，无需模型生成新动作格式；无法确定时保留原坐标。AutoGLM 的语义单项保持原有提示和观察输入，结构化模型则可使用显式选择器协议。分层执行从明确的完成条件编译可观察阶段，并增加执行恢复。AutoGLM 保持原有请求协议，由主机处理危险 Back 重规划、未聚焦输入和受支持的数字键盘输入；结构化模型也可收到当前阶段。Back 边界是原生 UI 启发式判断，并非 Android 返回栈证明。

输入恢复只处理模型已经请求的 Type：目标必须是已声明的唯一、完整可见非密码字段，输入值必须与目标一致；补一次聚焦点击后，须经新观察确认焦点和原值，才派发原输入。字段缺失会触发有界重规划，不猜测目标。待输入意图在取消、控制权变化时丢弃，未知派发不重试。

停止状态的 Clock 风格键盘还支持 HHh MMm SSs 规范时长。只有完整识别的直接设置命令、明确的目标包名及匹配时长、完整唯一的原生键盘同时成立，才逐键执行。解释、引用、未知附加条件等目标仍交给普通模型；完成条件本身不会授权写入。每个按键都需新观察确认显示值，再继续下一个按键；反馈不符会暂停，不会自动启动计时器。该能力不等于通用自然语言数值输入。

生成动作共享原有动作数、模型请求数与时间预算，最终任务验证独立于阶段推进。计划和待输入意图仅在一次 run 或 step 内存活，不持久化。两项功能仍默认关闭。四组真实 App 对比及独立留出任务结果见语义执行与分层规划评测报告。

多手机与对话控制

手机管理中的「查看屏幕」打开同一个全局只读组件，正在被其他聊天使用的手机也可以观看，不另建预览会话或抢占操作权。全局入口不提供点击、滑动、文字输入或任务接管；从来源聊天的手机入口打开时，才按该聊天的实际控制权提供操作。视频查看使用独立的只读客户端身份，服务端也拒绝全局查看地址上的控制请求。

每台已注册手机都有稳定的 deviceId，可同时保持多台手机连接。普通对话默认使用系统默认手机；用户明确指定其他手机时，Agent 先通过 discover 将名称匹配到唯一 deviceId，重名时询问用户。手机列表中的「对话控制手机」创建一个新对话，将目标 deviceId 保存到该对话的 customData.phoneDeviceId，作为此对话的默认手机；创建对话不会自动执行手机操作，也不会抢占正在运行的任务。不同对话可以同时操作不同手机，同一台手机的控制权仍然互斥。

执行方式与任务结果

「设置 → 手机控制 → 默认执行方式」默认选择 主 Agent 协作（phone.executionMode: "collaborative"）：主 Agent 拆解小目标、保存返回信息，并根据反馈继续规划。直接执行（"direct"）把完整的已授权手机目标交给手机模型自行规划。两者共用现有 Runtime、手机模型、权限、完成验证、接管与派发检查，不增加独立 Planner。实验开关 hierarchicalPlanning 与此独立。

来源聊天的手机面板可设置「下一任务执行方式」，偏好按聊天保存。优先级是单次任务明确选择 > 聊天偏好 > 全局默认。修改默认不影响运行中任务；Agent 应遵守用户选择，不自行切换。discover 返回有效执行方式，报告分别返回 executionMode 和 nextExecutionMode。

同一手机任务的不同小目标和续轮应复用返回的 task.taskId；每次执行有独立 feedback.segmentId。不传 taskId 表示新任务，不能为了绕过预算或暂停而新建。协作模式提交小目标，直接模式提交完整手机目标。任务契约示例：

{
  "op": "run",
  "goal": "查看当前店铺含配送费的总价，停在提交订单之前",
  "constraints": ["不提交订单，不付款，不发送消息"],
  "requestedOutputs": [{"key": "total", "description": "读取当前显示的含配送费总价"}],
  "maxActions": 6,
  "budget": {"maxActions": 24, "maxModelRequests": 30, "maxActiveDurationMs": 120000}
}

maxActions 限制本片段；budget 限制整个任务的动作数、模型请求数及活跃时间，跨片段和切换累计，只能收紧，不能提高。Runtime 配置仍是硬上限，人工介入期间暂停活跃计时。constraints 最多 12 条，同一任务续轮保留原限制；自然语言约束会交给模型，但不等于任意限制都有程序级保证。完成条件、待读取字段本身不授权写入。

requestedOutputs 最多 8 个唯一字段，包含 key、description 和可选精确原生 selector（resourceId、text、description）。唯一、完整可见的非密码节点可以直接返回原生观察值，不额外调用模型；缺失或歧义明确返回 unavailable。没有 selector 时，每个字段使用一次有界、只读的截图识别，计入共享预算。截图值标记 unverified，不提升任务完成验证。任务文本、字段及详细反馈仅在会话中使用，不进入持久操作报告。

feedback 返回任务与片段标识、执行方式、outcome、停止原因、验证级别、Runtime 判断的进展、带来源/画面/时间的字段、观察证据、本片段用量及 nextAction。outcome 包含 running、completed、partial、blocked、needs_user、failed、cancelled。模型声称完成而无界面证据时为 partial；completed 仅证明当前片段的界面条件，不证明整个用户任务或业务交易成功。字段缺失仍明确标注，不补猜。预算耗尽不是自动重试或无限续跑的授权。

切换当前任务：先选择下一任务方式，再点击「切换当前任务 → 暂停并切换」。Runtime 暂停并等待已派发输入结束，清除旧预测和坐标，重新观察；保留 taskId、原限制与已消耗预算，等待用户在手机面板明确交还。交还后复用同一 taskId 继续剩余目标。人工接管、过期控制版本及未知派发结果不能通过切换绕过；全局只读查看入口不能修改来源聊天。

用户通过聊天明确要求切换时，可用 set_mode 指定 executionMode；默认仅修改后续任务，applyCurrent: true 执行相同的暂停切换流程。切换后的人工交还不能用工具 resume 绕过。

执行耗时诊断与模型对照

操作报告的 performance 详情包含 operationId、总耗时、各阶段计数与耗时，以及模型请求的数值元数据。日志 PhoneRuntime 的 phase=execution_timing 提供同一类记录，可区分 UI 树、截图、模型等待、动作派发、输入确认和稳定等待。阶段可能嵌套或并行，不能直接相加作为总耗时占比。普通 JSON 响应只记录首字节时间；服务提供流式 token 时才记录首 token 时间。诊断不保存屏幕文字、提示词、模型原文或凭据，也不进入主 Agent 的规划上下文。

可在 xopc.json 中分别设置以下实验项，默认值如下：

{
  "phone": {
    "autoGlmPrompt": "current",
    "autoGlmProtocol": "current",
    "autoGlmSampling": "current",
    "modelResponseMode": "json",
    "modelRepetitionGuard": false,
    "batchReadings": false
  }
}

三个 AutoGLM 项可分别改为 upstream，独立对照上游中文提示、图片优先的对话轮次和采样参数。上游提示追加 xopc 主机约束；最多八轮已确认派发的动作历史只保存在适配器内存中，被丢弃的预测不会冒充已执行动作，任务改变或人工接管会清理历史。它是有界的主机适配，并非原样运行官方 Python 执行器，权限、取消、输入确认与完成验证继续生效。

modelResponseMode: "stream" 请求 SSE 并测量首 token；未完整结束的流不会派发动作。开启 modelRepetitionGuard 可在流读取期间中止大段精确重复。流式和重复检测保持默认关闭，需对照真实完成率、错误率、费用和总耗时后决定是否采用。

云端 UI helper 按内容哈希校验复用；操作结束、接管、取消或临时预览完成后，发送显式退出指令并等待进程退出，再交接 UI 自动化连接，避免只关闭 ADB 通道后仍有观察器占用。Unicode 输入在一次操作内复用专用通道，在结束、接管或取消时释放。实验项 batchReadings 可将多个视觉输出合并为一次只读请求，默认关闭；缺失字段保持 unavailable，截图读数保持 unverified。

鸿蒙 USB 真机

在「设置 → 手机控制 → 添加手机」选择「USB 连接鸿蒙手机」。点击「一键安装缺失组件」，或在对话中请配置助手安装鸿蒙连接组件，无需安装 DevEco Studio。之后手机开启开发者模式和 USB 调试，用数据线连接并授权电脑。第一版只接入 hdc list targets -v 中的 USB 设备，暂不支持无线 HDC 和鸿蒙云手机。

默认自动查找常见 SDK 目录，也可在连接窗口填写 HDC 可执行文件路径，保存到 phone.hdcPath。环境变量 HARMONYOS_SDK_HOME、DEVECO_SDK_HOME 可指向包含 openharmony/toolchains/hdc 或 toolchains/hdc 的 SDK 根目录；同时支持自动发现 xopc 托管的 HDC，最后回退到 PATH 中的 HDC。鸿蒙连接不依赖 ADB 和 scrcpy。

鸿蒙设备沿用 phone_use 工具、应用权限、任务预算和人工交还机制。支持启动应用、点击、双击、长按、滑动、返回、主页和等待。长按时间由设备 UiTest 决定；滑动时长转换为速度，可能受设备上下限约束。「主页」只在允许所有应用时可用。启动应用会解析已安装 bundle 的入口模块和 Ability；应用列表暂以 bundle 标识显示。

手机面板优先使用经过 Gateway 转发的原生 H.264 视频，失败时回退到截图。xopc 可在 Gateway 电脑独立安装 HDC、完整 Amazon Corretto JDK 和兼容的 HOScrcpy，健康的已有依赖直接复用。组件保存在 xopc 用户目录，不修改系统 PATH 或 JAVA_HOME。HDC 3.2.0c 和 USB 配套库来自固定的第三方 hdw2@2.3.10 分发，通过 jsDelivr 下载，unpkg 作为相同文件的备用源。按电脑平台只下载这两个文件，合计约 6 MB，逐个固定 SHA-256 和字节上限校验，不下载 SDK、npm 整包或其他平台文件，不执行 npm 安装脚本；小文件下载失败也不会自动回退完整 SDK。HOScrcpy 1.0.18-beta 来自固定的第三方 npm 分发包 @nszzj/dsh-hos-scrcpy@3.0.2，保留来源和许可声明，不称作华为官方下载。依赖文件和下载包均校验固定 SHA-256，支持下载代理、断点续传和验证过的离线包。检测与安装不会连接或操作手机。可用 phone.hdcVideo.devecoPath、javaHome、sdkJar 分别指定安装目录、JDK 根目录和完整独立的 HOScrcpy JAR。有些 DevEco 安装包中的库存在类名大小写与归档路径不一致的问题，会在启动采集前被拒绝；这种情况需指定兼容的完整库才能投屏。浏览器 WebCodecs 需 HTTPS 或 localhost 安全上下文。观察时读取焦点窗口的 UiTest 控件树并截图，检查前台窗口和旋转状态，完成后清理临时文件。优先获取 UiTest PNG；旧系统回退到 snapshot_display JPEG，再转换为 PNG。设备必须开放 UiTest、窗口和显示诊断能力；失败时会报告诊断，不会自动修改持久化系统测试模式。

文字输入仍需在手机上完成。商业鸿蒙的 UiTest 控件树可能不提供密码框标识，因此将类型不明的输入框视为敏感字段。Agent 遇到输入需求会请求协助；在手机上输入后，明确交还控制权即可继续。Agent 操作需配置真实视觉模型，不支持 Android 模拟器 mock。对话式配置已支持鸿蒙：选择 source:harmonyos，调用 install_dependency 的 kind:harmonyos 一次安装缺失的 HDC、Java 和 HOScrcpy，逐项复验；部分失败会保留已完成组件，重试时复用。USB 调试授权仍需在手机完成，电脑依赖就绪不代表真机或投屏兼容性已通过验收。

可运行 pnpm exec tsx scripts/verify-phone-hdc.mts，在隔离的内存数据库和临时状态中，通过带鉴权的真实 HTTP 路径验证 USB 发现、注册、应用列表、截图与面板能力。不调用模型、不保留截图。显式加 --actions 会打开设置、滑动、点击标题区域、返回、回到桌面，最后恢复原应用，不修改系统设置。可用 XOPC_PHONE_HDC_PATH、XOPC_PHONE_HDC_SERIAL 指定测试工具和手机。

原生视频沿用一次性票据、应用权限检查、最多四个查看者、控制权版本和显式接管/交还机制。HDC 手势在释放后执行，不会实时移动一个持续按住的原生触点。取消或撤销会丢弃未执行手势；交还会等待已派发的原生输入结束。执行前再次核对前台应用和显示几何信息；旋转或编码配置变化会使待执行手势失效。视频和输入均经过 Gateway，Java 桥不向浏览器开放端口或任意 shell 接口，不同步音频或剪贴板。切换查看/控制连接时会短暂保留编码器，无查看者后关闭。

原生视频验收：XOPC_PHONE_HDC_SDK_JAR=/path/to/compatible.jar pnpm exec tsx scripts/verify-phone-hdc-video.mts --input --browser。不设置该环境变量则测试 DevEco 自带库。脚本使用隔离临时状态，验证真实 HTTP/WebSocket 鉴权、取消手势、交还后拒绝旧控制权，以及浏览器 WebCodecs 解码。--input 会打开设置、点击标题区域并返回；--browser 需要本机 Google Chrome。不调用 LLM，不保留屏幕像素。