---
title: "iPhone Use 源码解读：Codex 操作 iPhone"
description: "从固定版本源码解读 iPhone Use：Codex 如何操作真实 iPhone、哪些保护由代码强制执行、屏幕和使用数据会发往哪里，以及账号风险。"
url: https://personalagentbench.com/zh-cn/phone-use/iphone-use/
last_updated: 2026-11-05
---

# iPhone Use 源码解读：Codex 能对你的手机做什么

本页由 2026-11-05 的英文版机器翻译而成，所有数字都已和原文核对。如有出入，以[英文版](https://personalagentbench.com/phone-use/iphone-use/)为准。

iPhone Use 是一款开源插件，可让 Codex 和两款中国桌面助手操作通过线缆连接到 Mac 的真实 iPhone，包括打开应用、读取屏幕、点击、滚动和输入。它于 2026年10月6日上线 GitHub，一周后获得 3504 个 star，截至 11月5日已超过 4900 个，是我们追踪的开源[手机操作智能体](https://personalagentbench.com/zh-cn/phone-use/)中增长最快的项目之一。我们没有实际运行它。我们没有愿意交给智能体操作的备用手机，也不会用自己在意的账号进行测试。本页基于一个固定提交版本阅读其源码，说明它能做什么、会在哪些环节停下来交给你处理，以及哪些数据会离开你的 Mac。

- iPhone Use 为智能体提供 18 个工具。其中 7 个只读取屏幕，其余工具可以执行操作，包括点击任意位置、输入文字、启动任意已安装应用，以及在一次调用中连续执行最多 20 个步骤。
- 代码会拒绝在密码字段中输入，并在批量操作遇到无法验证结果的提交后停止。除此之外，包括如何处理发送和付款在内的所有保护措施，都只是要求模型遵守的指令文本。
- 截图和屏幕元素树会发送给宿主助手所使用的模型。Codex 安装版本还会默认向 PostHog 发送匿名使用事件，并从 10月16日起同时发送到 Google Analytics；另外两个安装程序会关闭这两项分析。
- 代码仓库完全没有说明 WeChat 或 Alipay 等应用是否会检测这类自动化，也没有说明账号被发现后会怎样。

## iPhone Use 是什么，由谁开发

该项目位于 [zhongerxin/iPhone-use](https://github.com/zhongerxin/iPhone-use)，采用 MIT 许可证。README 将其描述为一种让 Codex、WorkBuddy 或 Doubao 的桌面工作助手通过 USB 操作真实 iPhone 的方式，助手侧边栏还会显示手机屏幕的实时画面。[README](https://github.com/zhongerxin/iPhone-use/blob/80006885df81531ce7a874b3b0df65980e25e59b/README.md#L7-L7)。

项目迭代很快。[更新日志](https://github.com/zhongerxin/iPhone-use/blob/80006885df81531ce7a874b3b0df65980e25e59b/CHANGELOG.md#L3-L59)从 10月7日的 0.2.x 一直写到 10月16日的 0.3.15，本页描述的正是这个版本；随后 0.3.16 于 10月22日发布，为下文所述的两个分析平台新增了明确的应用启动分析事件。匿名分析于 10月9日在 0.3.7 中加入，WorkBuddy 和 Doubao 适配器于 10月13日合并；第二个分析目的地 Google Analytics 于 0.3.14 加入，第 18 个工具则于 0.3.15 加入，两者都发生在 10月16日。我们于 10月13日首次阅读 0.3.12，并在 10月22日按 0.3.15 重新阅读代码。任何介绍它的页面都只是一个时间截面；我们阅读的提交是 `8000688`。

在你寻找这个项目之前，有一个小矛盾值得注意。README 仍称该代码仓库是私有的，需要 GitHub 访问权限。[README 第 50 行](https://github.com/zhongerxin/iPhone-use/blob/80006885df81531ce7a874b3b0df65980e25e59b/README.md#L50-L50)。但它实际上是公开的。另一个名称几乎相同的项目 [leeguooooo/iphone-use](https://github.com/leeguooooo/iphone-use) 是不同作者开发的独立工具，本页讨论的不是它。

## iPhone Use 如何让 Codex 连接真实 iPhone

整个系统有 3 个组成部分，全部运行在你的 Mac 和手机上。

| 组成部分 | 是什么 | 在哪里运行 |
| --- | --- | --- |
| MCP 服务器 | 仅使用标准库的单个 Python 文件，宿主助手通过 stdio 与其通信 | Mac |
| USB 转发器 | 一个监听 `127.0.0.1:18100` 并转发到手机 8100 端口的小型 Node 脚本 | Mac |
| WebDriverAgent | Appium 的开源 UI 自动化服务，固定为 16.14.0，并使用你自己的 Apple 签名构建 | iPhone |

来源：[MCP 服务器](https://github.com/zhongerxin/iPhone-use/blob/80006885df81531ce7a874b3b0df65980e25e59b/server/iphone_use.py#L1-L2)、[转发器](https://github.com/zhongerxin/iPhone-use/blob/80006885df81531ce7a874b3b0df65980e25e59b/tooling/forward.mjs#L1-L36)、[WDA 版本和构建方式](https://github.com/zhongerxin/iPhone-use/blob/80006885df81531ce7a874b3b0df65980e25e59b/server/wda_setup.py#L31-L33)。

[WebDriverAgent](https://github.com/appium/WebDriverAgent) 与应用开发者在测试中驱动自家应用时使用的是同一种测试自动化服务。iPhone Use 改变了它的用途：不再由测试脚本决定点击什么，而是交给语言模型。客户端拒绝连接任何不位于 Mac 本机的 WebDriverAgent 地址，我们在代码中也没有发现 Wi-Fi 路径，因此手机必须始终通过线缆连接。[回环地址检查](https://github.com/zhongerxin/iPhone-use/blob/80006885df81531ce7a874b3b0df65980e25e59b/server/wda_client.py#L29-L31)。

实时屏幕画面由同一个 MCP 服务器通过一个小型网页面板提供。其内容安全策略不允许任何外部连接，因此预览功能本身不会向外部服务器回传数据。[小组件资源](https://github.com/zhongerxin/iPhone-use/blob/80006885df81531ce7a874b3b0df65980e25e59b/server/iphone_use.py#L30-L35)。

## iPhone Use 工具：智能体能读取什么，又能做什么

README 列出供模型使用的 18 个工具，另有 2 个工具仅供预览面板使用。[工具列表](https://github.com/zhongerxin/iPhone-use/blob/80006885df81531ce7a874b3b0df65980e25e59b/README.md#L194-L205)。代码将每个工具标记为只读或破坏性操作，这是理解这些工具的一种实用方式。[标注](https://github.com/zhongerxin/iPhone-use/blob/80006885df81531ce7a874b3b0df65980e25e59b/server/iphone_use.py#L178-L188)。

| 读取手机 | 操作手机 |
| --- | --- |
| `pua_observe`：元素树和/或截图 | `pua_tap`：按元素或 x/y 坐标点击 |
| `pua_find`：查找元素 | `pua_type_text`：输入文字，可选择提交 |
| `pua_wait`：等待某个元素 | `pua_swipe`、`pua_scroll_find` |
| `pua_apps`：查找应用的 bundle ID | `pua_launch_app`：打开任意已安装应用 |
| `pua_doctor`、`pua_metrics`：健康状态和耗时 | `pua_press_button`：主屏幕键、音量键 |
| `pua_screen`：打开或暂停预览 | `pua_batch`：一次调用最多执行 20 个步骤 |
|   | `pua_screenshot`：将系统截图保存到 Photos |
|   | `pua_collect_list`、`pua_setup`、`pua_ready` |

其中两个工具值得仔细看。`pua_launch_app` 在打开应用前，只检查 bundle ID 的格式是否正确；系统没有列出智能体可以或不可以打开哪些应用。[启动应用](https://github.com/zhongerxin/iPhone-use/blob/80006885df81531ce7a874b3b0df65980e25e59b/server/wda_controller.py#L596-L603)。`pua_batch` 则允许模型把点击、输入、启动应用和等待串联起来，一次最多执行 20 个步骤。这既是速度的来源，也让错误假设可能产生最远的连锁影响。[批量操作上限](https://github.com/zhongerxin/iPhone-use/blob/80006885df81531ce7a874b3b0df65980e25e59b/server/iphone_use.py#L94-L95)。

最新加入的 `pua_screenshot` 与 `pua_observe` 返回的截图不同。它会触发 iPhone 自身的截图功能，由 iOS 将图片保存到手机的 Photos 图库，之后智能体就能在应用内附上这张图片。当预览为了让你登录而暂停时，该工具会拒绝执行。[系统截图](https://github.com/zhongerxin/iPhone-use/blob/80006885df81531ce7a874b3b0df65980e25e59b/server/wda_controller.py#L620-L631)。

文件锁会阻止手机同时执行两项操作；第二个调用方会收到 `device_busy`，不会发生任何操作。[操作锁](https://github.com/zhongerxin/iPhone-use/blob/80006885df81531ce7a874b3b0df65980e25e59b/server/iphone_use.py#L330-L335)。

## iPhone Use 要求你完成哪些设置，又要信任什么

它不需要越狱，也不需要单独部署 Appium 服务器，但仍然是一套面向开发者的配置。你需要 macOS、完整安装的 Xcode、Python 3.9 或更高版本，以及 Node 20.19 或更高版本。[环境要求](https://github.com/zhongerxin/iPhone-use/blob/80006885df81531ce7a874b3b0df65980e25e59b/README.md#L107-L116)。WebDriverAgent 使用你自己的 Apple 账号和开发团队进行签名。[签名](https://github.com/zhongerxin/iPhone-use/blob/80006885df81531ce7a874b3b0df65980e25e59b/README.md#L118-L128)。

安装 skill 列出了只能由你完成的步骤：登录 Xcode，点击“信任此电脑”，开启开发者模式并重启，可能还要在“设置”中启用 UI 自动化，信任开发者描述文件，并让手机保持解锁。[手动步骤](https://github.com/zhongerxin/iPhone-use/blob/80006885df81531ce7a874b3b0df65980e25e59b/skills/iphone-use-setup/SKILL.md#L36-L41)。指令要求模型绝不向你索取凭据，并且必须等到你真正回复“完成”，而不能自行假定你已经完成。[交接规则](https://github.com/zhongerxin/iPhone-use/blob/80006885df81531ce7a874b3b0df65980e25e59b/skills/iphone-use-setup/SKILL.md#L43-L43)。

简单来说，开启开发者模式并运行 WebDriverAgent，意味着只要手机保持解锁并连接，Mac 上的软件就能操控整部手机。这正是该工具的用途。在接入那部装有银行和通信应用的手机之前，你也需要理解这一点。

## iPhone Use 在哪里停下来交给你：密码、发送和付款

对于[个人智能体](https://personalagentbench.com/zh-cn/landscape/)来说，这是最重要的部分，其中的保护措施分为两类。

**由代码强制执行。** 系统会拒绝在安全文本字段中输入，也就是 iOS 用于密码的那类字段，并返回错误，要求模型改为询问你。[拒绝安全字段](https://github.com/zhongerxin/iPhone-use/blob/80006885df81531ce7a874b3b0df65980e25e59b/server/wda_controller.py#L531-L531)。输入文字后默认不会提交，只有明确要求才会提交；批量操作遇到任何无法验证结果的提交后都会停止。[提交默认设置和批量停止](https://github.com/zhongerxin/iPhone-use/blob/80006885df81531ce7a874b3b0df65980e25e59b/server/wda_controller.py#L748-L750)。分段输入的长文本会绑定到开始输入时所在的应用和字段；只要其中任何一个发生变化，其余内容就不会继续输入。[续输保护](https://github.com/zhongerxin/iPhone-use/blob/80006885df81531ce7a874b3b0df65980e25e59b/server/wda_controller.py#L758-L781)。

**要求模型遵守。** 其他所有保护措施都只是 skill 中的指令文本。密码、PIN、验证码和 Face ID 会交给你处理，同时暂停预览。[身份验证交接](https://github.com/zhongerxin/iPhone-use/blob/80006885df81531ce7a874b3b0df65980e25e59b/skills/iphone-use/SKILL.md#L26-L26)。只有在你授权发送，并核对收件人和完整草稿后，消息才会发出。[发送规则](https://github.com/zhongerxin/iPhone-use/blob/80006885df81531ce7a874b3b0df65980e25e59b/skills/iphone-use/SKILL.md#L88-L88)。如果一次输入、发送、付款或下单的结果不确定，必须检查结果，绝不能重新执行。[禁止重放](https://github.com/zhongerxin/iPhone-use/blob/80006885df81531ce7a874b3b0df65980e25e59b/skills/iphone-use/SKILL.md#L106-L106)。

我们没有在代码或 skill 中发现一条规则，要求智能体在付款前必须停下来向你确认。skill 防止的是重复付款，而不是未经询问就完成一次付款。如果应用把密码框绘制成普通文本字段，它也不受代码检查约束，只能依靠 skill 文本提供保护。[身份验证参考](https://github.com/zhongerxin/iPhone-use/blob/80006885df81531ce7a874b3b0df65980e25e59b/skills/iphone-use/references/authentication.md#L34-L34)。可以与我们拆解过的产品对比：[Pine](https://personalagentbench.com/agents/pine/) 会在每次计费操作前询问，而 [Muse](https://personalagentbench.com/zh-cn/agents/muse/) 会将审批统一交给一个把关组件。

## 使用 iPhone Use 时，哪些数据会离开你的 Mac

共有 4 类数据会向外发送。

1. **屏幕内容，发送给模型。** 元素树和截图会返回给宿主助手，宿主助手再将其发送给所使用的模型。截图会先缩小并转换成 JPEG，原图留在磁盘上。[图像处理](https://github.com/zhongerxin/iPhone-use/blob/80006885df81531ce7a874b3b0df65980e25e59b/server/wda_image.py#L1-L6)。屏幕上显示的任何内容，无论是聊天、余额还是验证码，都会出现在图片中。
2. **应用查询，发送给 Apple。** 查找应用的 bundle ID 时可能会查询 Apple 的公共搜索 API。[应用搜索](https://github.com/zhongerxin/iPhone-use/blob/80006885df81531ce7a874b3b0df65980e25e59b/server/wda_apps.py#L199-L201)。
3. **使用事件，发送给 PostHog。** Codex 插件默认发送匿名事件；WorkBuddy 和 Doubao 的安装程序则会关闭分析，除非你传入 `--analytics`。[默认设置](https://github.com/zhongerxin/iPhone-use/blob/80006885df81531ce7a874b3b0df65980e25e59b/ANALYTICS.md#L14-L14)、[WorkBuddy 安装程序](https://github.com/zhongerxin/iPhone-use/blob/80006885df81531ce7a874b3b0df65980e25e59b/workbuddy/install.py#L77-L82)。
4. **相同事件，发送给 Google。** 从 0.3.14 开始，每个事件还会通过 Measurement Protocol 直接发送到 Google Analytics 4，并将广告用途和广告个性化标记为拒绝。让插件能够向该 Google 数据流写入数据的密钥随代码仓库一同发布，文档称这是所有者的选择。[GA4 发送程序](https://github.com/zhongerxin/iPhone-use/blob/80006885df81531ce7a874b3b0df65980e25e59b/server/analytics.py#L64-L97)、[GA4 说明](https://github.com/zhongerxin/iPhone-use/blob/80006885df81531ce7a874b3b0df65980e25e59b/ANALYTICS.md#L117-L135)。

我们将分析代码与 [ANALYTICS.md](https://github.com/zhongerxin/iPhone-use/blob/80006885df81531ce7a874b3b0df65980e25e59b/ANALYTICS.md#L27-L30) 进行了对照，两者一致：在我们阅读的版本中有 2 种事件类型（0.3.13 将之前的 3 种事件并入工具事件，0.3.16 随后又加入应用启动事件），数据包括随机安装 ID、工具名称、结果、持续时间和错误代码；同时使用允许列表，丢弃所有未预先列名的字段。屏幕文字、截图、选择器、设备 ID 和签名团队都不会发送。[允许列表](https://github.com/zhongerxin/iPhone-use/blob/80006885df81531ce7a874b3b0df65980e25e59b/server/analytics.py#L21-L42)。Google 收到的字段与 PostHog 相同，都经过允许列表筛选。设置 `IPHONE_USE_ANALYTICS=0` 或 `DO_NOT_TRACK=1` 会同时停止两者，系统会在记录前和发送前检查这些设置；只要任意一个 Google 设置为空值，就只会关闭 Google。[退出分析](https://github.com/zhongerxin/iPhone-use/blob/80006885df81531ce7a874b3b0df65980e25e59b/server/analytics.py#L113-L129)。

文档遗漏了两个细节。事件会关闭 PostHog 的位置查询，但请求仍会把你的 IP 地址传到 PostHog 的服务器；代码无法告诉我们它是否会被保留。对于 Google，文档现在明确说明，Google 可能根据请求的 IP 地址推断大致位置。[IP 说明](https://github.com/zhongerxin/iPhone-use/blob/80006885df81531ce7a874b3b0df65980e25e59b/ANALYTICS.md#L22-L25)。此外，即使事件来自另外两个宿主，每个事件仍会被标记为来自 Codex 插件。[来源标签](https://github.com/zhongerxin/iPhone-use/blob/80006885df81531ce7a874b3b0df65980e25e59b/server/analytics.py#L201-L201)。

## iPhone Use 与账号封禁：代码仓库没有说明什么

X 和 Xiaohongshu 上分享的演示包括刷 WeChat 朋友圈和订外卖，这些应用背后的公司都有自己的反自动化系统。更新日志提到一项 WeChat 优化，但它只是为了更快读取很长的聊天列表，并非为了规避检测。[WeChat 说明](https://github.com/zhongerxin/iPhone-use/blob/80006885df81531ce7a874b3b0df65980e25e59b/skills/iphone-use/references/wechat.md#L1-L15)。我们没有发现随机延迟或类似人类操作的抖动：输入按固定速率执行。[输入常量](https://github.com/zhongerxin/iPhone-use/blob/80006885df81531ce7a874b3b0df65980e25e59b/server/wda_controller.py#L27-L30)。这一点很坦诚，也意味着没有任何机制掩饰自动化行为。

代码仓库没有说明平台条款、风控或账号封禁。我们不知道 WeChat、Alipay 或 Meituan 是否会检测由 WebDriverAgent 驱动的输入，也没有实际尝试。这一空白并非 iPhone Use 独有；Droidrun 背后的托管 Android 服务采取了相反做法，宣传隐蔽输入功能，我们的[手机操作智能体概览](https://personalagentbench.com/zh-cn/phone-use/)对此有所讨论。如果你尝试 iPhone Use，请使用一部即使失去也能承受的手机，以及即使丢失也能承受的账号。

## 关于 iPhone Use，我们无法核实什么

- **它是否可用，以及成功频率如何。** 我们没有运行它。项目没有公布成功率，这里的任何内容都不是测量结果。它不在我们的测试中，也没有分数。
- **宿主会保留什么。** 截图会发送给 Codex、WorkBuddy 或 Doubao 及其模型提供商。它们的数据保留方式不在该代码仓库的范围内。
- **PostHog 和 Google 对 IP 地址的保留情况。** 每个事件都会携带请求的 IP 地址抵达它们的服务器。
- **0.3.15 之后的任何情况。** 按当前的迭代速度，本页细节可能在几天内发生变化。固定版本链接准确显示了我们阅读的内容。

## FAQ

**iPhone Use 尝试起来安全吗？** 它是开源项目，分析行为也与文档一致，这已经超过许多工具的透明度。但智能体可以在解锁的手机上打开任意应用并点击任意位置，代码层面唯一的阻止机制是密码字段和无法验证结果的提交。付款确认交给模型处理。请使用备用手机，以及即使丢失也能承受的账号。

**iPhone Use 需要越狱吗？** 不需要。它使用 Appium 的 WebDriverAgent，通过你自己的 Apple 开发团队签名，同时需要开启手机的开发者模式，并在 Mac 上完整安装 Xcode。

**iPhone Use 能通过 Wi-Fi 工作吗？** 在我们阅读的版本中不能。客户端只通过 Mac 上的转发器与 WebDriverAgent 通信，我们没有发现 Wi-Fi 路径。

**iPhone Use 会发送哪些使用数据？** 共有 2 类匿名事件，包含工具名称、结果、持续时间、错误代码和随机安装 ID，会发送到 PostHog，并从 0.3.14 起发送到 Google Analytics。它不会发送屏幕内容、截图或设备 ID。Codex 安装版本默认开启，WorkBuddy 和 Doubao 安装版本默认关闭；`IPHONE_USE_ANALYTICS=0` 会同时关闭两者。

**使用它会导致 WeChat 或 Alipay 封禁账号吗？** 我们不知道，代码仓库也没有答案：它从未提及封禁或平台条款。代码中没有任何机制掩饰自动化行为。

**如何安装 iPhone Use？** 在完整安装 Xcode、Python 3.9 或更高版本以及 Node 20.19 或更高版本的 Mac 上，克隆代码仓库，然后为 Codex 插件运行 `sh scripts/install.sh`；WorkBuddy 和 Doubao 有各自的安装程序。随后，使用你自己的 Apple 团队为 WebDriverAgent 签名，并在手机上信任这台 Mac。[安装步骤](https://github.com/zhongerxin/iPhone-use/blob/80006885df81531ce7a874b3b0df65980e25e59b/README.md#L105-L137)。我们阅读了这些步骤，但没有实际运行。其他[手机操作智能体](https://personalagentbench.com/zh-cn/phone-use/)工具可在我们的概览页面中对比。

---

Published by Personal Agent Bench (https://personalagentbench.com), run by the Zentor team. Zentor builds agent software of its own, so its products are not on the scorecard and will not be added.
