导语：GitHub 上的开源项目 zhongerxin/iPhone-use 近期热度上升，在云栈社区也有不少开发者讨论。它让 Codex 等 AI Agent 能够通过 USB 连接真实 iPhone，完成 App 自动化操作、实时屏幕查看与截图回退。本文整理其原理、关键依赖与安装要点，供需要做 iOS 端自动化测试或 AI 接入的读者参考。
一、项目地址与基本信息
该项目已衍生出若干社区分支，例如：
tangshunpu/iPhone-use：加入腾讯 WorkBuddy、字节豆包工作等国产 Agent 端口quanru/iPhone-use：加入可选的 Midscene 集成xiangyingchang/iPhone-use、Xiangyu-CAS/iPhone-use 等社区维护分支
二、它能做什么
按照官方 README 描述，iPhone-use 的目标是“让 Codex 通过 USB 操作真实 iPhone”，具体覆盖以下能力：
- 引导式安装：把 WebDriverAgent（WDA）的搭建过程拆成可执行的步骤，降低上手门槛
- App 自动化：通过 WDA 对 iPhone 上的应用进行点击、输入、滚动等操作
- 实时屏幕视图：右侧栏显示手机当前画面，便于 AI 与人类同步观察
- 截图回退机制：当控件定位失败时，引导模型先看截图，再尝试坐标点击
这一组合让“自然语言指令 → 真实 iPhone 操作”成为可能。例如让 Codex“打开 Safari 并搜索某关键词”、“在备忘录里写下某段文字”、“截屏当前页面”等。
三、技术架构
iPhone-use 并不重新发明轮子，而是把现有 Appium 生态组件封装成一个开箱即用的 Codex 插件：
| 组件 |
角色 |
| WebDriverAgent（WDA） |
跑在 iPhone 端的自动化执行服务 |
| appium-ios-device |
提供 USB 通信、端口转发与屏幕流能力 |
| Appium |
整体生态底座 |
| 本地 MCP 服务 |
把上述能力以MCP工具的形式暴露给Codex |
| 屏幕 widget |
在桌面上显示实时画面的 HTML 小窗 |
按照官方说明，用户无需单独运行 Appium Server，安装插件即可使用。控件查找失败时会自动切到截图分析模式，带来更稳定的鲁棒性。
四、环境要求
- macOS：WDA 需要用 Xcode 构建，依赖 macOS + Xcode
- iPhone：一台可被 Xcode 识别的 iPhone（任意系统版本需自行确认）
- USB 数据线：用于连接 Mac 与 iPhone
- Apple ID：用于签名 WDA Runner（个人免费账号即可，但证书有效期 7 天；付费开发者账号可长期签名）
- Node.js：运行 MCP 服务所需的版本
- Codex：作为前端 Agent 接收自然语言
五、安装步骤概览
按照 README 的指引，整体流程大致如下：
1. 克隆仓库
git clone https://github.com/zhongerxin/iPhone-use.git
2. 构建并安装 WebDriverAgentRunner
- 打开仓库或单独拉取的 WDA 源码中的
WebDriverAgent.xcodeproj
- 在 Xcode 左上角选择
WebDriverAgentRunner scheme，并把目标设备切换为你的 iPhone
- 在 Runner target 的 Signing & Capabilities 中选择自己的 Apple ID 与可签名的 Bundle Identifier
- 通过 Product → Test 构建、安装并运行 WDA Runner
- iPhone 端根据提示进入 设置 → 通用 → VPN与设备管理 信任证书
3. 安装插件与依赖
安装过程中通常涉及 npm install / plugin install 等步骤，具体以仓库当前 README 为准。
4. 启动 MCP 服务与 Codex
按照官方配置启用 iPhone-use 相关 skills 与 tools，重启 Codex 会话即可在右侧栏看到实时屏幕。
六、隐私与遥测
官方说明指出，默认会向一个 PostHog 项目发送匿名的使用统计，包括：
- 启动事件
- 工具调用次数
- 连接状态
- 耗时
- 错误类型
- 随机生成的安装标识（不绑定用户身份）
明确不上传：屏幕内容、用户输入、设备标识符。如不希望被统计，可在启动前设置：
export IPHONE_USE_ANALYTICS=0
# 或
export DO_NOT_TRACK=1
七、适用场景与局限
适合
- AI Agent 接入 iOS 端的实验与原型开发
- iOS UI 自动化测试
- 个人手机操作的脚本化（截图、批量填表、辅助输入等）
- 安全研究中需要把 AI 能力延伸到 iPhone 的场景（前提是合规授权）
局限
- 仅限 macOS + Xcode 环境，Windows/Linux 无法直接构建 WDA
- 个人 Apple ID 签名证书有效期 7 天，过期需重签
- App Store 上对自动化操作敏感的应用（如银行类、涉及支付密码的页面）通常会触发风控
- iOS 系统升级后，WDA 可能需要更新匹配版本
八、小结
iPhone-use 把 Appium 生态与 Codex 生态做了桥接，让“AI 操控真实 iPhone”从概念走向可落地的开源方案。对于做 iOS 自动化测试、AI Agent 接入移动端、或研究 AI 在移动设备上行为的研究者来说，这是一个值得上手的开源项目。
建议从官方 README 开始，遇到 WDA 签名、构建失败等问题时优先查看仓库的 Issues 与社区分支（如 tangshunpu/iPhone-use 中的国产 Agent 端口说明）。 | 
发表于 1 小时前
|
查看: 5|
回复: 0
