外观
手机控制
手机控制台只做 APKClaw 辅助桥接，不把桌面启动器伪装成手机端启动器。它负责保存设备、验证 Token 与 Lumi 签名、取截图、下发任务、录屏留证和查看节点树。
基础概念
| 名称 | 说明 |
|---|---|
| APKClaw | 安装在安卓手机上的 Agent App |
| Phone URL | 手机局域网地址，例如 http://192.168.1.100:9527 |
| Phone Token | 手机端显示的 API Token，用于基础访问 |
| Lumi Signature | OpenClaw 与手机端之间的安全签名校验 |
| 无障碍服务 | 允许手机端读取界面和执行点击输入 |
| 任务超时 | 手机 Agent 等待任务完成的最大时间 |
推荐连接流程
- 手机安装 APKClaw。
- 手机和电脑连到同一局域网。
- 打开手机端发布中转或局域网配置页。
- 在启动器“手机控制台”点击新增。
- 填入
http://手机 IP:9527和 Token。 - 点击保存并验证。
- 看到“Token 与 Lumi 安全通道已验证”再执行任务。
扫码或短码配对的建议方案
“扫码对接”可以按网络条件分为两种方案：
| 方案 | 做法 | 优点 | 代价 |
|---|---|---|---|
| 局域网二维码 | 电脑显示 URL、设备 ID、一次性 nonce，手机扫码提交 Token | 不依赖公网，体验直接 | 要处理防火墙和同网段 |
| 6 位短码中转 | 电脑生成短码，手机输入短码，服务器中转配对材料 | 不碰相机，不怕局域网隔离 | 需要可靠中转服务 |
生产建议先做 6 位短码。短码 3 分钟过期，只能用一次；配对成功后再把设备写入本地 phone-agents.json。
Invalid Lumi signature
Invalid Lumi signature 或 lumi_signature_repair_failed 表示基础 Token 可能能访问，但安全签名没有对齐。
常见原因：
- 手机端和启动器保存的 Token 不一致。
- 设备刚更新，签名算法或 nonce 状态不一致。
- 电脑端保存了旧设备配置。
- 手机时间和电脑时间差太大。
- 请求被代理或网关改写了签名相关 header。
处理顺序：
text
1. 在手机端重新复制 Token
2. 启动器删除旧设备
3. 重新新增并保存验证
4. 点击“唤醒”后再刷新截图
5. 仍失败时看手机执行日志里的签名修复结果120s 超时怎么理解
截图里看到 Task timeout (120s)，说明手机 Agent 的某个任务等待超过了 120 秒。它不是“连接一定坏了”，而是这条任务没有按预期结束。
排查：
| 检查项 | 说明 |
|---|---|
| 锁屏 | 锁屏时应返回“需要先解锁”，不能误报任务失败 |
| 无障碍 | 无障碍服务关闭时无法读节点树或点击 |
| Prompt | 任务太大时拆成观察、判断、执行三步 |
| 截图 | 先刷新截图，看手机当前在哪个页面 |
| 日志 | 看 R loop_start 后是否有实际动作 |
任务写法
好的手机任务要有边界：
text
读取当前屏幕，判断下一步可以安全执行的动作。仅返回观察结果，不执行点击、输入或打开新应用。需要执行时再升级：
text
在当前页面点击“设置”按钮；如果没有看到按钮，返回当前屏幕摘要并停止执行。定时任务与模板库
手机控制里的任务库用于保存可复用自动化模板，定时任务用于按时间触发这些模板。v2.1.8 后，内置模板会同步到后台调度器，避免 UI 里能看到模板、调度器却找不到任务定义。
推荐模板分层：
| 类型 | 用途 | 建议 |
|---|---|---|
| 观察模板 | 读取当前页面、判断是否满足条件 | 默认启用，低风险 |
| 单步模板 | 点击一个明确按钮或进入固定页面 | 必须写停止条件 |
| 流程模板 | 签到、擦亮、曝光、定时发布等多步动作 | 先单机跑通，再启用定时 |
| 广告等待模板 | 等待 30 秒广告、拒绝链式广告、领取奖励 | 必须限制最大等待时长 |
定时任务建议从低频开始，例如每 30 分钟或每小时执行一次。需要每隔几分钟发布或曝光时，应增加冷却时间、失败计数和截图留证，避免页面变化后持续误点。
广告等待任务
手机 Agent 有时间概念，可以执行“观察 30 秒广告”一类任务。稳定写法不是盲等，而是循环观察：
text
在 30 秒内观察广告页面；如果看到“领取奖励”或“关闭”按钮，按规则处理；如果进入新的链式广告或未知弹窗，停止并返回截图摘要。v2.1.8 的广告等待模板会按 maxWatchSeconds 推导任务超时，默认保留 135 秒执行窗口。这样既能覆盖广告加载和奖励领取，也能避免任务无限挂起。
多设备批量执行
多设备编队适合重复、低风险、可观察的任务。
不建议一开始就批量执行发送、发布、付款、删除、授权变更等动作。先让每台设备跑通 status 和截图，再并发。
CLI 入口
powershell
cd D:\Axiangmu\AUSTART\openclaw_ui_integration
npm run phone:agent -- run --prompt "读取当前手机屏幕并返回摘要" --mode observe --json
npm run phone:vision -- frame --out ./data/phone-frames/frame.jpg --json
npm run phone:video -- start --max-seconds 60 --filename demo.mp4 --json所有 Agent 自动化调用都尽量加 --json，让上层程序解析字段，而不是猜人类文本。