一、它到底在解决什么问题
手机上的重复劳动一直是自动化的盲区：电脑能写脚本，手机上的 App 只能靠手指点。安卓有 ADB，iPhone 过去只有两条路——要么越狱，要么装一整套 Appium Server 自己写测试代码。iPhone Use 把这件事压缩成一句话：让 Codex 直接连着数据线操作你的真机。
它同时给了三样东西，缺一不可：
| 组成部分 | 作用 |
|---|---|
| 本地 MCP 服务 | 把「点、滑、打字、读页面」这些动作包装成 Codex 能调用的工具 |
| 安装 + 使用两套技能 | 首次配置、签名、构建、启动，以及日常操作，都有现成流程可走 |
| 实时屏幕 widget | 侧边栏里显示手机画面，带点击 / 拖动光效，看得见它在做什么 |
底层用的是 WebDriverAgent（WDA）——Appium 生态里那套跑在手机上的自动化执行服务。区别是：你不需要单独启动 Appium Server，也不需要自己啃 WDA 的配置，这些都由插件的安装流程代管。
结果就是这句话能直接执行：「打开备忘录，新建一条草稿，输入下面这段中文，核对文字后保留。」 输入和提交是分开的，工具默认不帮你按发送——这是刻意的设计。
二、动手前，先看清楚门槛
这是全文最该认真读的一节。iPhone Use 的体验很好，但它要求的准备工作比一般小工具多，因为要在一台没有越狱的 iPhone 上跑起自动化服务。
| 依赖 | 为什么需要 |
|---|---|
| macOS + Codex 桌面端 / CLI | 安装本地插件、运行 MCP 服务与屏幕侧边栏 |
| 完整 Xcode（已完成首次启动配置） | 编译、签名、部署、运行 WDA。只装 Command Line Tools 不够 |
| 可用的 Apple 账号与开发团队 | 给手机端的 WDA Runner 签名 |
| USB 连接的真实 iPhone | 需「信任此 Mac」、开启开发者模式，安装期间保持解锁 |
| Python 3.9+ | 运行 MCP 服务（只用标准库） |
| Node.js 20.19+ / 22.12+ / 24+，npm 10+ | USB 转发与屏幕流 |
三个必须先说清的点：
1. 先在你自己手机上装好 WDA Runner 并让它跑起来——这是运行在手机里的执行服务，没有它后面全免谈。
2. Xcode 要能支持手机当前的 iOS 版本。不用越狱，也不用单独启动 Appium Server；WDA 固定用已验证的 16.14.0 提交版本，下载、依赖、签名、构建都由安装流程管理。
3. 免费 Apple 账号有硬限制：个人团队最多 3 个自装 App、描述文件自签发起 7 天过期，到期要重建重装。
手动装 WDA 的三步（如果你不想让 Codex 代劳）
- USB 连上 iPhone，信任这台 Mac，按系统提示开启开发者模式，并在 Xcode 里登录自己的 Apple 账号。
- 打开 WDA 源码里的
WebDriverAgent.xcodeproj，选中WebDriverAgentRunnerscheme 和自己的 iPhone；在 Runner target 的 Signing & Capabilities 里选自己的 Team 和可签名的 Bundle Identifier。 - 用 Product → Test 构建、安装并运行。运行测试会启动 WDA 服务——注意，安装完成后这个服务仍需处于运行状态。
三、装它：把这段话丢给 Codex 就行
这是这个项目最省事的地方——安装本身也是由 Codex 干的。把下面这段复制到本机 Codex：
请帮我安装和配置 iPhone Use：
https://github.com/zhongerxin/iPhone-use
先读取仓库 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 账号登录、设备信任、开发者模式
或解锁需要我操作时，告诉我明确步骤，等我完成再继续。想自己敲命令也行，两条：
git clone https://github.com/zhongerxin/iPhone-use.git
cd iPhone-use
sh scripts/install.sh安装脚本会验证并暂存源码，通过 Codex CLI 注册本地 marketplace、装好插件与技能，并把服务注册成标准 MCP iphone_use。插件和标准配置共用同一个命名空间，不会重复注册工具。
装完后当前聊天可能不会立刻出现新工具，重连或新开一个聊天即可，流程能在重连后接着走。
四、连手机：把设备配到 READY
新聊天里启用 iPhone Use，然后说一句：
用 iphone-use-setup 帮我配置通过 USB 连接的 iPhone，安装并启动 WDA，验证 READY，然后显示手机屏幕。
接下来 Codex 会依次完成：环境诊断 → 发现设备 → 配置签名 → 获取 WDA → 后台构建 → 安装启动。已经配置过的设备会复用配置和构建，日常任务不需要每次重装。
唯一需要记住的判据是：pua_ready 返回 ready=true 之后，才开始真正的手机任务。以下这些都不算就绪——Runner 图标出现了、构建显示 BUILD SUCCEEDED、端口开放了，都不代表通道可用。
卡住了怎么查
| 现象 | 先查 | 下一步 |
|---|---|---|
| 找不到真机 / device unavailable | 数据线是否支持数据、手机是否解锁并信任、Xcode 是否完成配对 | 重连后重新 discover，确认拿到的是目标真机 |
| Xcode 没完成首次启动 / 缺组件 | doctor 返回的 Xcode 版本与首次启动状态 | 装完整 Xcode 并走完系统提示；单装命令行工具不够 |
| Developer Mode disabled | 手机上的开发者模式开关 | 手动开启并重启后重新 discover |
| signing requires development team | Xcode 里的 Apple 账号与 Team | 登录并选自己的 Team 后重新 configure / build |
| 免费描述文件用满 3 个 App | Personal Team 已装的开发 App | 自己决定是否卸载不用的，不强迫升级开发者计划 |
| profile 过期 / 旧 Runner 起不来 | 构建日志里的签名有效期 | 用原配置重新 build / start，再验 READY |
| 构建成功但 HTTP 不可达 | Runner 测试是否在运行、USB 转发进程与端口 | 用 status 分开确认「运行」和「转发」，再 start 恢复 |
| 控件树没内容 / 标签定位失败 | 页面是否自绘、受保护，或树被截断 | 别换标签反复试，按截图改坐标点击 |
| 屏幕预览空白 | 是否处于认证暂停、是否刚断开换流 | 预览不可用不等于控制通道失效，别为它反复重启 |
省时间的一条：手机若开着「iPhone 镜像」（正在从 Mac 使用此 iPhone），会和控制通道抢设备，工具会返回 mirroring_conflict。遇到就先退出镜像、必要时解锁手机，再重新验 READY。
五、17 个工具，覆盖了哪些活
模型实际可用 17 个工具，另有 2 个只给屏幕 widget 用（模型不该调）。按用途分一下：
| 分类 | 工具 | 能做的事 |
|---|---|---|
| 环境与就绪 | pua_doctor pua_setup pua_ready |
诊断环境、配置设备、后台安装启动、就绪检查 |
| 观察 | pua_observe pua_find |
读控件树、截图、按条件找目标 |
| App | 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 |
最多 20 步合成一次调用、有界滚动查找、列表采集去重 |
| 预览与统计 | pua_screen pua_metrics |
开关预览、看耗时与字节数 |
可以直接抄的三条提示词：
用 iPhone Use 打开备忘录，新建一条草稿，输入下面的中文内容，核对文字后保留。
打开目标 App，搜索这个名称，读取前几项结果并整理给我。
读取这个列表，分段滚动并去重，说明已经覆盖的范围和还未确认的部分。需要把手机里的图片或文件传回 Mac，可以走 AirDrop 那条参考路径，发送后到下载目录取文件就行。
六、它比一般自动化好在哪，边界在哪
几处值得说的工程细节
- 纯本地 USB 通道。Python MCP 服务通过本机 loopback 转发访问 WDA，运行数据和签名构建都留在本机；
WDA_URL默认转发端口 18100，远程地址会被拒绝。 - 尽量不重复干活。复用 HTTP 连接、WDA session、健康服务和已有构建；首次任务确认 READY，之后沿健康通道继续。
- 观察更省 token。控件树省略重复字段，只需要截图时不生成 XML；
batch、滚动查找、列表采集都能减少工具往返。 - 安装任务是异步的。下载、构建、启动返回可查询的工作 ID，重复 setup 会优先复用正在进行的工作。
- 定位失败有兜底。元素找不到时返回截图和处理指引，图像像素乘
image.pixel_to_point换算成 iPhone 点坐标，再交给pua_tap。 - 失败语义很明确。多进程共享操作锁；动作超时或断线可能被标记为「不确定」，这时先读实际状态，不盲目重放点击、输入或提交。
- 预览不落盘。屏幕流不写文件，锁屏与主动暂停是两种不同状态，解锁后 READY 能恢复锁屏预览。
该有的心理预期
| 情况 | 说明 |
|---|---|
| 认证一定是你自己来 | 密码、验证码、Face ID / Touch ID、手机解锁，都由你在手机界面完成，工具不索取凭据，接管期间预览会暂停 |
| 默认不会替你发送 | 工具把输入和提交分开，模型需要自己核对关键页面、接收人、数量和最终结果 |
| 速度取决于三件事 | 具体 App、USB / WDA 状态、模型响应速度。这些优化主要减少重复请求与模型往返，不是让手机变快 |
| 有匿名统计 | 插件默认向独立的 PostHog 项目上报启动、工具调用、连接状态、耗时和错误类别；用随机安装标识，不上传手机画面、输入内容或设备标识。设 IPHONE_USE_ANALYTICS=0 或 DO_NOT_TRACK=1 并重启 MCP 服务即可关闭 |
| 运行数据在哪 | 默认 ~/.local/share/iphone-use/，可用 IPHONE_USE_STATE_DIR 指定；运行目录权限 700、私有配置与图像 600。升级时若新目录不存在会继续用旧配置目录，别为了改名把运行数据删了 |
日常更新就两步：
git pull --ff-only
sh scripts/install.sh然后重连聊天，加载更新后的工具、技能和屏幕资源。
最后总结一句：它把「用代码操作 iPhone」这件事的门槛，从「配一套 Appium 环境 + 写 XCUITest」降到了「装完插件，用中文说一句话」。代价是要有一台 Mac、一套完整 Xcode、一根能传数据的数据线，以及第一次配置时耐心跟着流程走完签名和设备信任。
项目仓库（MIT 协议，作者未收集个人信息）：github.com/zhongerxin/iPhone-use
站内相关
- Codex + Excalidraw 从零开始详细教程：一句话出一条手绘白板视频，不露脸、不剪辑 —— 同样是「给 Codex 一句话，它交付成品」的路子，可以对照着看
- GitHub 从零开始详细教程：看懂仓库、发布作品、版本管理与开源协作 —— 第一次 clone 别人的项目、跑安装脚本，先过一遍这篇
- muse-skills：300 条现成 AI 玩法，每条都写清了「哪一步必须你本人动手」 —— 同样强调「哪一步必须你亲手做」，思路一致
- 抖音解析捷径：iPhone 不装 App，用快捷指令就能下载视频、音乐和封面 —— 不写代码也能让 iPhone 自动干活，更轻量的替代思路
暂无评论内容