核心用法
claw-use-android 是一套让AI Agent拥有真实Android手机操控能力的完整解决方案，由Android端APK与CLI工具（cua）组成。核心设计哲学是Agent工作流优先：通过screen→act循环实现观察-决策-执行闭环，并支持设备端Flow引擎沉淀可复用自动化脚本。
三大核心端点
1. /screen — 语义化UI感知
返回带有稳定整数refID的结构化UI树，标注zone（区域语义）与role（交互角色）。screen -c模式仅返回可交互元素，大幅压缩token消耗，是LLM决策的首选输入。
2. /snapshot — 视觉截图
返回JPEG截图的base64编码，用于需要视觉上下文（颜色、图像、复杂布局）的场景。注意截图分辨率与UI树坐标的映射关系。
3. /act — 统一动作执行
单端点覆盖所有交互：点击（by ref/text/坐标）、输入、滑动、系统导航（back/home/recents）、应用启动等。支持批量动作序列与refID的精准寻址。
Flow引擎：设备端自动化
/flow端点将多步机械操作下沉到设备执行，100ms轮询、零LLM调用。典型场景：MIUI应用安装（"继续安装"→"继续更新"→"完成"）、批量权限授予。执行失败自动回退到screen→act循环。
关键工作流原则
- 优先读`flows.md`：匹配现有flow直接执行，跳过逐步推理
- 强制沉淀新flow：任何多步操作完成后，立即抽象可复用模式写入
flows.md - 文本优先于坐标：
click "确定"比tap 540 960更可靠、跨设备兼容 - 结构化优于视觉：
screen -c比snapshot更快、更精准、更易解析
显著优点
1. 零依赖部署：无需ADB、Root、PC连接，纯HTTP通信，跨网络可用
2. 语义化交互：refID系统+文本回退，比纯坐标方案更鲁棒
3. 双模感知：结构化UI树（快、精准）+ 视觉截图（场景化）灵活组合
4. 自积累加速：Flow引擎+强制沉淀机制，Agent越用越快，token成本指数下降
5. 完整设备I/O：剪贴板、相机、音量、电池、位置、联系人、短信、文件系统全覆盖
6. 生产级可靠性：PIN解锁100%可靠、服务保活机制、OTA自更新、多设备管理
潜在缺点与局限性
1. 无障碍服务依赖：需用户手动开启，部分厂商（MIUI/HyperOS）需额外保活配置
2. 安全限制：锁屏截图返回黑图（Android安全策略）；Pattern解锁实验性不可靠
3. 厂商兼容性：MIUI平板双栏设置界面、ICP备案弹窗、Chrome下载行为等需特殊处理
4. 坐标陷阱：截图缩放后的坐标≠实际屏幕坐标，混用易出错
5. 延迟与稳定性：HTTP轮询+无障碍遍历存在固有延迟，不适合高频实时游戏场景
6. iOS缺失：iOS端（cui）仍在计划中，目前仅限Android生态
适合人群
- AI Agent开发者：需要真实手机环境执行多步任务、验证App行为
- 自动化测试工程师：批量设备管理、回归测试、兼容性验证
- RPA场景：定时任务执行、数据录入、跨App信息流转
- 设备农场运营：低成本Android设备集群的远程管控
- LLM应用研究者：探索VLM+结构化感知在手机操控中的结合
常规风险
- 无障碍服务权限：高级系统权限，需明确用户授权，存在被滥用于恶意自动化（自动点击广告、刷单等）的理论风险
- 局域网暴露：默认7333端口HTTP服务，建议配合防火墙/VLAN隔离，避免未授权访问
- PIN明文存储：设备端存储解锁PIN，虽有token保护，但物理接触设备存在提取可能
- 截屏敏感信息：
snapshot与screen可能捕获通知、短信验证码、银行App界面，需严格日志脱敏与传输加密（建议HTTPS反向代理） - OTA安全风险：LAN HTTP下载APK存在中间人替换可能，建议校验签名或改用安全通道分发