iPhone-use

让 Codex 插上 USB 就能操控真 iPhone

开源 free 自动化工作流

访问官网 ↗ GitHub ↗ 文档 ↗

GitHub 星标 ★ 1608

维护状态活跃

是否开源是

定价模式 free

项目预览

项目数据

分类自动化工作流

开发团队zhongerxin

所属国家

官网地址

GitHubhttps://github.com/zhongerxin/iPhone-use

定价模式free

价格说明开源免费，需自行部署

访问状态

是否开源是

开源协议MIT

主要语言Python

技术栈/模型

GitHub 星标★ 1608

30天Star增速

HF 下载量

上线时间2026-10-06 00:00:00

代码更新—

仓库体积—

本站数据更新—

维护状态活跃

中文支持

访问方式

移动端支持

综合评分

收录时间2026-10-10

浏览次数0

项目介绍

iPhone-use 是一个让 Codex 通过 USB 直接操作真实 iPhone 的开源工具，解决 AI 代理难以控制物理手机、只能在模拟器里跑自动化的问题。它通过 USB 连接设备，提供引导式安装流程，让 Codex 能识别屏幕、点击、输入、启动 App，并执行 App 自动化任务。核心能力包括：实时屏幕流与截图回退机制，确保代理在画面延迟或异常时仍能获取当前状态；面向真实设备的操作通道，而非模拟器或云真机；以 Python 实现，便于二次开发和接入现有自动化工作流。项目定位在 AI 代理与移动端真实设备之间搭桥，适合需要让大模型直接操控 iPhone 完成重复操作、测试或数据采集的场景。

Star 增长趋势

本站每日记录该项目 GitHub 星标变化，观测越久曲线越完整

正在加载星标数据…

技术标签

使用教程

—

难度：高级约 60 分钟部署方式：本地安装 7 步

环境要求

macOS 系统，并安装 Codex 桌面端或 Codex CLI
完整版 Xcode（已完成首次启动配置），仅 Command Line Tools 不够
可在 Xcode 中使用的 Apple 账号与开发团队（用于签名 WDA Runner）
通过 USB 连接的真实 iPhone，需信任此 Mac、开启开发者模式并在安装期间保持解锁
Python 3.9+；Node.js 20.19+ / 22.12+ / 24+，npm 10+

安装与启动步骤

1确认环境与真机

检查本机 Codex CLI、Python、Node.js、npm、完整 Xcode，以及是否已用 USB 连接 iPhone 并信任此 Mac、开启开发者模式。
2克隆仓库

仓库当前为私有，需先具备 GitHub 访问权限；也可改用已取得的源代码包解压后操作。
```
git clone https://github.com/zhongerxin/iPhone-use.git
```
3运行安装脚本

进入目录执行安装脚本，它会校验并暂存源码、注册本地 marketplace、安装插件与技能，并把服务注册为 MCP iphone_use。
```
cd iPhone-use
sh scripts/install.sh
```
4重连 Codex 聊天

安装后当前聊天可能未加载新工具，需重连或新开一个 Codex 聊天，流程可在重连后继续。

5用提示词配置 WDA

把 README 给出的安装提示词粘贴给 Codex，让它检查现有配置、优先复用已有 WDA，并使用你自己的开发团队与 bundle ID 完成签名构建启动。

请帮我安装和配置 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 账号登录、设备信任、开发者模式
或解锁需要我操作时，告诉我明确步骤，等我完成再继续。

6手动签名启动 WDA

若不走提示词，可在 Xcode 打开 WebDriverAgent.xcodeproj，选 WebDriverAgentRunner scheme 与自己的 iPhone，在 Signing & Capabilities 配置 Team 和
7检查服务状态

首次使用先调用 pua_setup(action="status") 复用健康服务，缺少时才 start 一次；start 默认最多等 20 秒，超时按同一 job 查询，不要重复启动。

关键配置

配置项	必填	说明	示例
`IPHONE_USE_ANALYTICS`	否	设为 0 关闭匿名使用统计埋点，需重启 MCP 服务生效	`0`
`DO_NOT_TRACK`	否	设为 1 同样可关闭匿名埋点，需重启 MCP 服务生效	`1`

如何确认成功

以 pua_ready 返回 ready=true 为准，服务就绪后 Codex 侧边栏可显示手机屏幕。

常见问题

Q：仓库拉不下来或提示无权限怎么办？

A：仓库目前为私有，需要有 GitHub 访问权限，或者直接使用已取得的源代码包，解压后在包目录运行同一个安装脚本。

Q：安装完插件但 Codex 里看不到新工具？

A：当前聊天需要重连或新开一个 Codex 聊天来加载工具，之前的流程可以在重连后继续。

Q：还需要越狱或单独启动 Appium Server 吗？

A：不需要。无需越狱，也无需单独启动 Appium Server；WDA 固定使用已验证的 16.14.0 提交，下载、依赖安装、签名与构建由 setup 流程管理。

Q：只装了 Command Line Tools 可以吗？

A：不可以，必须安装完整 Xcode 并完成首次启动配置，且 Xcode 需支持手机当前的 iOS 版本。

Q：WDA 启动后 ready 一直不为 true？

A：start 默认最多等待 20 秒，超时后按同一 job 查询状态，不要重复启动；仍失败则检查设备是否解锁、WDA 服务是否在运行。

注意事项

使用前必须先在 iPhone 上用自己的 Apple 账号签名、安装并启动 WebDriverAgentRunner，已有健康的 WDA 可直接复用。
Apple 账号登录、设备信任、开发者模式开启及手机解锁需本人操作，Codex 只能提示步骤。
安装与启动期间请保持手机解锁并保持 USB 连接。
不要照搬作者的设备标识或签名信息，需使用你自己的 Apple 开发团队和可签名 bundle ID。

核心亮点

通过 USB 操作真实 iPhone，不依赖模拟器或云真机，能覆盖真机才有的行为
提供实时屏幕与截图回退双通道，代理在画面异常时仍能继续执行
Python 实现，引导安装流程降低接入门槛，便于扩展自定义自动化任务

不足之处

依赖 Codex 与 USB 连接，使用场景受限于特定代理和有线环境
项目处于成长阶段，设备兼容性与长期维护情况有待观察

适用场景

让 AI 代理在真机上自动完成 App 签到、表单填写等重复操作
移动端自动化测试时，用大模型直接操控真机执行用例
需要真机屏幕状态采集与交互的数据采集或演示流程

替代项目

Appium、Airtest

上一篇：agentic_coding_flywheel_setup

下一篇：fsearch