README

iPhone Use

中文 · English

!iPhone Use 在 Codex 中操作真实 iPhone 并实时展示手机屏幕

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

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

插件默认向独立的 PostHog 项目及 GA4 属性发送匿名使用统计，包括实际使用开始、工具调用、连接状态、耗时、错误类别，以及显式启动的 App 标识和公开目录名称（含 batch 中已完成的启动）。使用随机安装标识，不上传手机画面、输入内容、设备标识或已安装 App 清单。设置 IPHONE_USE_ANALYTICS=0 或 DO_NOT_TRACK=1 并重启 MCP 服务可关闭。详见 埋点与分析说明。

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

 最近更新

2026-10-09 至 2026-10-13，完整记录见 更新记录。

- 预览直接操作：支持点击画面、鼠标拖动和触控板双指滚动。
- 微信点击优化：已知导航目标直接看图点击，通讯录和会话列表按需轻量读取。
- AirDrop 文件传输：使用技能新增传输指引，将手机图片、视频和文档传回 Mac。
- 页面读取优化：精简控件树，默认最多返回 200 个节点，支持按需限制快照。
- 连接恢复改进：完善超时与断线指引，自动恢复临时快照设置。
- 长文本续传保护：续传绑定原输入框，切换 App 或焦点后停止，避免误写。

 用一段提示词让 Codex 安装

将下面这段话复制到本机 Codex：

text
请帮我安装和配置 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 访问权限，或者使用已取得的源代码包。

 在 WorkBuddy 和豆包工作中安装

两者都支持通过 USB 操作真实 iPhone，并在侧边栏显示实时画面；共用本机的设备配置、WDA 构建和操作锁，已配置过的手机优先复用。依赖仍是 macOS、完整 Xcode、Python、Node.js / npm 和 USB iPhone，安装这两个适配版无需 Codex CLI。适配版默认关闭匿名使用统计。

| 宿主 | 在源码目录运行 | 安装后的接入 |
| --- | --- | --- |
| WorkBuddy | python3 workbuddy/install.py | 在「连接器管理」信任 iphone_use，新开会话 |
| 豆包工作 | python3 doubao/install.py | 按安装器输出新建 STDIO 连接器，上传两个技能，新开「本地电脑」任务 |

将对应提示词发给本机的 WorkBuddy 或豆包工作。助手可执行本地安装；宿主界面的接入步骤若无法自动操作，会说明需要你完成的具体步骤。首次签名仍使用你自己的 Apple 账号和开发团队。

 发给 WorkBuddy 的提示词

text
请在这台 Mac 上安装 iPhone Use，让 WorkBuddy 通过 USB 操作我的真实 iPhone：
https://github.com/zhongerxin/iPhone-use

先读取 README.md、workbuddy/README.md 和安装脚本，检查 Python、Node.js、npm、
完整 Xcode 和 USB iPhone。克隆或复用本地源码，保留已有改动，
在源码目录运行 python3 workbuddy/install.py；不要运行 Codex 安装脚本。
在 WorkBuddy「连接器管理」里信任并启用 iphone_use，然后新开会话加载工具和技能。
如果这些界面步骤需要我操作，给出具体位置，等我完成后继续。

工具可用后读取 iphone-use-setup，先查询 setup status，复用已有配置、健康 WDA
或正在运行的启动任务；首次配置使用我自己的设备和 Apple 开发团队完成签名与启动。
确认 pua_ready 返回 ready=true 后调用一次 pua_screen()，在侧边栏显示实时手机画面，
再在 iPhone 计算器中验证 12×34=408。Apple 登录、信任、开发者模式或解锁
需要我接管时，说明具体步骤并等我完成；不要照搬作者的设备标识或签名信息。


 发给豆包工作的提示词

text
请在这台 Mac 上安装 iPhone Use，让豆包工作通过 USB 操作我的真实 iPhone：
https://github.com/zhongerxin/iPhone-use

在「本地电脑」任务中先读取 README.md、doubao/README.md 和安装脚本，
检查 Python、Node.js、npm、完整 Xcode 和 USB iPhone。克隆或复用本地源码，
保留已有改动，在源码目录运行 python3 doubao/install.py；不要运行 Codex 安装脚本。
按安装器输出，在「插件 · 技能 · 伙伴」中新建名为 iphone_use 的 STDIO 连接器，
命令和参数使用输出的绝对路径，并分别上传安装目录下的 iphone-use、iphone-use-setup
两个技能文件夹。启用连接器和技能，再新开「本地电脑」任务；已有连接器更

Top issues

Latest release

新增 App 启动分布统计，查看用户通过 iPhone Use 显式启动了哪些 App，以及各 App 的启动次数、匿名安装数、占比和每日趋势。

- 新增 iphone_use_app_launched 事件，同时发送到 PostHog 和 GA4。记录校验后的 bundle ID、公开目录名称、单次 / batch 来源及前台核验状态；batch 仅统计已成功返回的启动子步骤。
- PostHog 增加启动次数、使用安装数、占比、每日趋势四个图表；GA4 发布「App 使用分布」报表，包含名称和 bundle ID 数据表及四张分布 / 趋势图。
- 仅采集显式启动目标，继续排除设备上的 App 清单、画面和内容；支持通过 IPHONE_USE_ANALYTICS=0 或 DO_NOT_TRACK=1 统一关闭统计。插件与 widget 版本同步为 0.3.16。

升级插件并重新连接聊天 / 重启 MCP 后开始采集新事件，不回填历史 App 数据。GA4 新维度通常需要 24–48 小时才能出现在报表中。默认启动结果可能未核验前台状态，可通过报表的核验状态维度区分。

验证：477 项 Python 回归、57 项 widget 测试、36 项 WorkBuddy 和 15 项豆包适配测试、TypeScript 构建和发布包检查通过。

GitHub CI