Awesome, an open-source project for AI controlling iPhone is here I’ve always felt that Codex controlling the iPhone emulator on Mac was too slow, but now this open-source project has directly solved the problem Open-source address: https://github.com/zhongerxin/iPhone-use…

zhongerxin/iPhone-use

Source: https://github.com/zhongerxin/iPhone-use

iPhone Use

中文 · English

让 Codex 通过 USB 操作你的真实 iPhone。用自然语言描述任务，Codex 就能打开 App、读取页面、点击、滚动、输入文字、整理列表，并在侧边栏展示手机屏幕。

iPhone Use 使用 WebDriverAgent（WDA）与 iPhone 通信，包含本地 MCP 服务、安装与使用技能，以及实时屏幕 widget。它优先复用现有连接与构建；控件定位失败时，指导模型查看截图并尝试坐标点击。

插件默认向独立的 PostHog 项目发送匿名使用统计，包括启动、工具调用、连接状态、耗时和错误类别。使用随机安装标识，不上传手机画面、输入内容或设备标识。设置 IPHONE_USE_ANALYTICS=0 或 DO_NOT_TRACK=1 并重启 MCP 服务可关闭。详见 埋点与分析说明。

使用前，需要先在你自己的 iPhone 上安装、签名并启动 WDA Runner。 WDA 是运行在手机上的执行服务；下面的提示词和 setup 流程可以让 Codex 协助完成首次安装，已有健康的 WDA 可直接复用。

用一段提示词让 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 账号登录、设备信任、开发者模式
或解锁需要我操作时，告诉我明确步骤，等我完成再继续。

安装插件后，当前聊天可能需要重新连接才能加载工具，流程可在重连后继续。Apple 账号登录、设备信任、开发者模式及手机解锁仍需本人在系统界面完成。

仓库目前为私有，需要有 GitHub 访问权限，或者使用已取得的源代码包。

安装依赖

Xcode 需要支持手机当前的 iOS 版本。无需越狱，也无需单独启动 Appium Server。WDA 固定使用已验证的 16.14.0 提交，下载、依赖安装、签名和构建由 setup 流程管理。

先在自己的 iPhone 上安装并启动 WDA

手机端使用 Appium 维护的 WebDriverAgent。首次使用时，须通过 Xcode 用你自己的 Apple 账号与开发团队签名、安装并启动 WebDriverAgentRunner。

推荐使用上面的安装提示词和下面的 iphone-use-setup 流程：Codex 获取本项目固定版本的 WDA，配置你的设备和签名，再完成构建、部署与启动；需要你完成 Apple 登录、设备信任、开发者模式或解锁时，会提示具体步骤。

如需在 Xcode 手动处理：

1. 用 USB 连接自己的 iPhone，信任这台 Mac，按系统要求开启开发者模式，并在 Xcode 中配置自己的 Apple 账号。
2. 打开获取的 WDA 源码中的 WebDriverAgent.xcodeproj，选择 WebDriverAgentRunner scheme 和自己的 iPhone；在 Runner target 的 Signing & Capabilities 中选择自己的 Team 与可签名的 Bundle Identifier。
3. 使用 Product → Test 构建、安装并运行 WDA Runner，按手机上的实际提示完成信任。运行测试会启动 WDA 服务；安装后仍需要该服务处于运行状态。

本对话首次使用先调用 pua_setup(action="status")，复用健康服务或活动工作；缺少服务才 start 一次。start 默认最多等待 20 秒，超时后按同一 job 查询，不重复启动。服务就绪后，以 pua_ready 返回 ready=true 为准，再开始手机任务。设备与签名要求可参考 Appium 真机准备说明。

安装插件

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

脚本验证并暂存源码，通过 Codex CLI 注册本地 marketplace、安装插件和技能，并将安装缓存中的服务注册为标准 MCP iphone_use。插件与标准配置使用同一命名空间，避免重复工具注册。

源代码包解压后，也可以在包目录运行同一个安装脚本。安装完成后重连或新开 Codex 聊天。

连接自己的 iPhone

在新聊天中启用 iPhone Use，输入：

用 iphone-use-setup 帮我配置通过 USB 连接的 iPhone，安装并启动 WDA，验证 READY，然后显示手机屏幕。

技能引导 Codex 完成诊断、设备发现、签名配置、获取 WDA、后台构建与启动。已配置过的设备会复用配置和构建，正常任务不需要每次重装。pua_ready 返回 ready=true 后才开始手机任务。

可以做什么

示例提示词：

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

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

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

输入与提交分开，工具默认不提交文字。模型需要核对关键页面、接收人、数量和最终结果。密码、验证码、Face ID 等认证交给用户完成，接管期间可以暂停预览。

屏幕预览在同一聊天中复用已有 widget。底部提供刷新、主屏幕和截图按钮；无图像时保留黑色屏幕的 iPhone 外壳，屏幕内仅显示对应状态图标，顶部显示连接或暂停状态。预览供用户观看，模型定位仍以工具返回的实际图像或控件为依据。

技术亮点

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

这些优化主要减少重复请求与模型往返，完整任务速度仍取决于 App、USB / WDA 状态和模型响应。工程回归与真机验收分别记录在本地开发资料中。

工具概览

模型可用 17 个工具，另有 2 个仅供屏幕 widget 使用的工具。

界面异常时先返回截图，再由模型判断下一步：滚动查找一次最多滑一次，仍找不到可点击目标就暂停；遮挡、滚动无进展、输入不符或预期页面未出现也走截图兜底。已有截图直接复用，不自动继续盲滑或重放操作。

本机数据与升级

新安装默认使用 ~/.local/share/iphone-use/，可通过 IPHONE_USE_STATE_DIR 指定外部目录；原 WDA_STATE_DIR 仍兼容。升级时若新目录不存在，会继续使用检测到的旧配置目录，保留设备、签名和构建。不要为了改名删除运行数据。

运行目录权限为 700，私有配置和图像文件为 600。明确调用的截图有保留上限，预览流不落盘。签名材料、设备数据、运行日志与依赖目录均不进入源代码发布包。WDA_URL 可指定本机地址，默认转发端口为 18100，远程地址会被拒绝。

更新已克隆的仓库：

git pull --ff-only
sh scripts/install.sh

重新连接聊天以加载更新后的工具、技能和屏幕资源。若手机连接失败，先检查 USB、设备解锁、开发者模式、Xcode 签名与 setup 返回的具体错误；已有启动工作应继续查询，避免反复重启。

开发与文档

npm ci --prefix ui --no-audit --no-fund
npm run build --prefix ui
sh scripts/check.sh
python3 scripts/package.py

构建结果是自包含屏幕 HTML，源代码包位于 dist/iphone-use-<版本>-source.zip。安装和普通使用不需要重新构建 UI。安装后的插件仍完整保留 widget 的源码、样式、构建脚本、配置、依赖锁文件和测试，便于本地维护。

• 屏幕预览与恢复
• App 标识参考
• 安装与连接故障排查
• 更新记录

依赖与致谢

本项目依赖 Appium 生态与 WebDriverAgent：WDA 提供手机端的自动化执行服务，appium-ios-device 提供 USB 设备通信、端口转发与屏幕流连接能力。iPhone Use 在这些基础上提供 Codex 插件、MCP 工具、安装引导与屏幕 widget，无需单独运行 Appium Server。

感谢 Appium、WebDriverAgent 及相关项目的维护者和贡献者，让真实 iPhone 的自动化操作成为可能。

MIT License。第三方组件说明见 THIRD_PARTY_NOTICES.md。