iPhone Use：让 Codex 通过 USB 直接操作你的真实 iPhone，MCP + WebDriverAgent 是怎么把「手机自动化」做成一个插件的

最近 GitHub 上冒出一个很有意思的项目：iPhone Use。它做的事情一句话就能说清——让你本机的 Codex 通过一根 USB 线，直接操作你手边真实的 iPhone：打开 App、读页面、点击、滚动、输入中文、整理列表，还能在侧边栏实时看到手机屏幕。截至发稿，它已经拿到 1754 Star、162 Fork，用 Python 写成，采用 MIT 协议，仓库地址在 github.com/zhongerxin/iPhone-use。

它的看点不是「又一个手机自动化脚本」，而是它把一个通常很折腾的工程问题包装成了一段提示词就能装上的 Codex 插件：底层用 Appium 维护的 WebDriverAgent（WDA）跟手机通话，中间是本地 MCP 服务，上层是安装 / 使用技能和一个实时屏幕 widget。整个链路全程走本机 USB，不需要越狱，也不用单独起 Appium Server。

iPhone Use 是什么：把真机自动化塞进 Codex 的一个插件

按官方 README 的描述，iPhone Use 的核心是「用自然语言描述任务，Codex 就能操作真实 iPhone」。它由三部分组成：一个本地 MCP 服务（Python，通过本机 loopback 转发访问 WDA）、一组安装与使用技能（setup + 使用引导），以及一个实时屏幕 widget（在聊天侧边栏里显示手机画面、设备状态和点击 / 拖动提示）。

它明显是为「偷懒」优化过的：优先复用现有连接与已有构建，WDA 固定使用已验证的 16.14.0 提交；当控件定位失败时，它会引导模型去看截图、改用坐标点击，而不是死磕控件树。设计目标很清晰——少往返、少重复、失败了也有兜底。

技术底层：WebDriverAgent + 本地 MCP + USB 转发

手机端的执行服务用的是 Appium 生态里的 WebDriverAgent。WDA 是运行在 iPhone 上的一套自动化执行服务，iPhone Use 的 MCP 服务通过本机回环地址转发去访问它。作者强调：运行数据和签名构建都留在本机，默认转发端口是 18100，远程地址会被直接拒绝。

在首次使用之前，你需要先在自己的 iPhone 上安装、签名并启动 WDA Runner。这一步依然是手机自动化的老门槛：得有 macOS、完整 Xcode（首次启动配置完成，光有 Command Line Tools 不够）、一个能在 Xcode 里用的 Apple 账号和开发团队，以及一根 USB 连接、已信任此 Mac、并按要求开启开发者模式、安装期间保持解锁的真实 iPhone。区别在于，iPhone Use 把这些步骤写进了 setup 技能，可以让 Codex 协助你走完。

git clone https://github.com/zhongerxin/iPhone-use.git
cd iPhone-use
sh scripts/install.sh

脚本会校验并暂存源码，通过 Codex CLI 注册本地 marketplace、安装插件和技能，并把服务注册为标准 MCP iphone_use。插件与标准配置共用同一命名空间，避免重复注册工具。安装完成后需要重连或新开一个 Codex 聊天。

依赖	用途
macOS 与 Codex 桌面端 / CLI	安装本地插件、运行 MCP 服务与屏幕侧边栏
完整 Xcode（完成首次启动配置）	编译、签名、部署和运行 WDA
可用的 Apple 账号与开发团队	签名手机端 WDA Runner
USB 连接的真实 iPhone	信任此 Mac、开启开发者模式、安装期间保持解锁
Python 3.9+	运行 MCP 服务（Python 端只用标准库）
Node.js 20.19+ / 22.12+ / 24+，npm 10+	USB 转发与屏幕流

用一段提示词让 Codex 帮你装好

这是这个项目最讨喜的地方：官方给了一整段可以直接粘进 Codex 的提示词。大意是——「先读仓库 README 和安装脚本，检查本机 Codex CLI、Python、Node.js、npm、完整 Xcode 以及 USB 连接的 iPhone，把项目放到合适目录，运行 sh scripts/install.sh；如果当前聊天还没加载新工具就提示重连；工具可用后读取 iphone-use-setup 技能，优先复用已有 WDA；首次配置时发现我的设备，用我自己的 Apple 开发团队和可签名 bundle ID，获取固定版本 WDA、配置签名、构建并启动，直到 pua_ready 返回 ready=true，然后打开手机屏幕。」

需要注意：Apple 账号登录、设备信任、开发者模式和解锁这些涉及安全边界的操作，仍然必须由你本人在系统界面上完成，Codex 只能告诉你明确步骤。这一点作者在 README 里写得很清楚，也算是有分寸。

它能做什么：从 App 导航到列表采集

工具能力可以粗略分成几类，官方给了一张对照表：

功能	示例
App 导航与操作	打开目标 App，进入搜索、详情、设置或草稿页面
页面读取	获取紧凑控件树、文字、位置和实际截图
点击与手势	按控件或坐标点击，滑动和拖动，等待页面目标出现
中文与长文本输入	一次提供完整 Unicode 文字，长文本分段输入并支持续传
连续任务	把已知的点击、输入、等待组成一次 batch，减少模型往返
列表搜索与采集	有界滚动查找、重叠读取与去重，返回覆盖边界
可见失败恢复	控件被遮挡、未聚焦或树不完整时，查看新截图并重新选择点击位置
实时手机屏幕	iPhone 外壳、设备状态、操作光效与清楚可见的点击 / 拖动提示

官方举了几个示例提示词，读起来很自然：

用 iPhone Use 打开备忘录，新建一条草稿，输入下面的中文内容，核对文字后保留。

打开目标 App，搜索这个名称，读取前几项结果并整理给我。

读取这个列表，分段滚动并去重，说明已经覆盖的范围和还未确认的部分。

工具概览：模型可用的 17 个工具

iPhone Use 一共暴露 17 个模型可用工具（另有 2 个仅供屏幕 widget 使用），命名统一带 pua_ 前缀，按职责分得很整齐：

工具	用途
pua_doctor、pua_setup、pua_ready	环境诊断、设备配置、后台安装 / 启动与就绪检查
pua_observe、pua_find	控件树、截图与目标查询
pua_apps、pua_launch_app	查询 App 标识、读取安装证据和启动 App
pua_tap、pua_swipe、pua_press_button	点击、滑动、主屏幕等操作
pua_type_text、pua_wait	Unicode 输入与有界等待
pua_batch、pua_scroll_find、pua_collect_list	组合动作、滚动查找与列表采集
pua_screen、pua_metrics	预览开关与有界耗时统计

几个值得学的工程细节

• 本地 USB 通道。MCP 服务通过本机 loopback 转发访问 WDA，运行数据和签名构建保留在本机；默认端口 18100，远程地址会被拒绝。
• 减少重复工作。复用 HTTP 连接、WDA session、健康服务与已有构建；首次任务确认 READY，之后沿健康通道继续，而不是每次推倒重来。
• 紧凑观察与组合动作。控件树省略重复字段；只需要截图时不生成 XML；batch、滚动查找和列表采集用来减少工具回合。
• 安装任务异步执行。下载、构建与启动会返回一个可查询的工作 ID，重复 setup 会优先复用正在进行的工作。
• 截图回退。元素定位失败时返回截图与处理指引；图像像素乘以 image.pixel_to_point 换算成 iPhone 点坐标，再交给 pua_tap。
• 明确失败语义。多进程共享操作锁；动作超时或断线可能被标记为「不确定」，此时先读实际状态，避免盲目重放点击、输入或提交。
• 实时预览与暂停恢复。屏幕流不落盘；区分锁屏与主动暂停，解锁后的 READY 可以恢复锁屏预览，刷新可主动重连。

数据与隐私：默认匿名统计，但可以关掉

有一处需要留意：插件默认会向独立的 PostHog 项目发送匿名使用统计，包括启动、工具调用、连接状态、耗时和错误类别。官方说明使用随机安装标识，不上传手机画面、输入内容或设备标识。如果你介意，可以设置 IPHONE_USE_ANALYTICS=0 或 DO_NOT_TRACK=1 并重启 MCP 服务关闭。此外，本机数据默认落在 ~/.local/share/iphone-use/，运行目录权限 700、私有配置和图像文件 600，明确调用的截图有保留上限，预览流不落盘。

还有一点要提前知道：仓库目前是私有的，需要有 GitHub 访问权限，或者使用已取得的源代码包。所以想试的话，先确认你能拿到代码。

小结

iPhone Use 的价值不在于发明了什么新协议，而在于它把「真机自动化」这条一向琐碎的链路——Xcode 签名、WDA 构建、USB 转发、控件定位、截图兜底——打包成了一个可以用自然语言驱动、还能实时看到手机屏幕的 Codex 插件。对于想把手头 iPhone 上的重复操作交给 AI 的人来说，它是一个完成度相当高、且思路清楚的起点。

项目地址：github.com/zhongerxin/iPhone-use（MIT 协议；注意仓库当前为私有，需有访问权限）。