iphone-use：让 AI agent 操作真实 iPhone

我做 iphone-use，是为了让 Codex、Claude Code 和其他 agent 直接用真实 iPhone：把屏幕读成文字，点按、滑动、输入，并检查操作是否生效。

它在本地 Mac 上运行守护进程，在手机上运行自研 XCTest runner。你可以通过 CLI、HTTP API、MCP 或浏览器使用它。它不操作 Mac 的光标和窗口焦点。

安装：Mac、Xcode 和真实 iPhone

需要 macOS 15 以上、Xcode、登录了 Apple ID 的签名环境和 USB 数据线。免费 Apple ID 可以使用。手机先打开开发者模式，再连接 Mac 并解锁。

curl -fsSL https://raw.githubusercontent.com/leeguooooo/iphone-use/main/install.sh | sh
iphone-use doctor
iphone-use status
iphone-use try

try 会打开设置、读取屏幕并返回主屏幕，是验证基础操作的无害示例。以当前输出为准；安装成功不等于手机随时可操作。doctor 会列出需要补齐的条件。

让 Codex、Claude Code 或 MCP 客户端用手机

安装器会准备 agent skill，并为已安装的 Claude Code 注册 MCP。其他 MCP 客户端可以使用下列配置，替换路径中的用户名。

{
  "mcpServers": {
    "iphone-use": {
      "command": "/Users/YOUR_USERNAME/Applications/iPhoneUse.app/Contents/MacOS/iphone-use-mcp"
    }
  }
}

HTTP API 位于 /agent/*；MCP 工具覆盖设备状态、读屏、输入、快捷操作和流程。先读状态，再按当前元素快照操作。操作结果会区分已执行、未发出和不确定，不能把收到响应当作任务完成。

读屏、中文输入和截图受限的 App

runner 通过 XCTest 读取无障碍树并注入触摸和 Unicode 文本，不依赖 Mac 的拼音输入法。截图受限的 App 可以尝试无障碍读屏；能读到什么取决于该 App 暴露的元素，不能保证每个页面都可读。

做过一次的任务，存成 flow

网页面板可以录制已确认的操作。草稿经过审阅后，存成按 App 分类的 flow；重放的正常路径不调用模型。官方流程库是 iphone-use-flows，可以查看脚本和验证记录。

~/Applications/iPhoneUse.app/Contents/MacOS/iphone-use-mcp flow list
~/Applications/iPhoneUse.app/Contents/MacOS/iphone-use-mcp flow validate my-task.json

重复任务还可以组成测试套件或定时执行；账号、权限和 App 更新都可能让旧流程失效，重放失败时需要重新验证。

iphone-use 和 agent-device、Mobile MCP、Appium 怎么选？

工具	适合的场景
iphone-use	在自己的真实 iPhone 上操作现有 App，本地 Mac 托管，人工网页遥控与 agent 共用接口，录制后重放 flow。
agent-device	编码 agent 检查 App 改动，跨平台设备控制、回放、CI 和云设备工作流。
Mobile Next / Mobile MCP	通过 MCP 操作 iOS、Android，本地设备与云设备接入。
Appium	编写并维护跨平台自动化测试，用现有 WebDriver 测试生态。

这是用途比较，不能据此认定某家更快或更稳定。性能数字需要同设备、同操作、同等待条件的对照。

常见问题

需要越狱吗？

不需要。需要开发者模式和签名过的 XCTest runner。

还用 WebDriverAgent 或 iPhone Mirroring 吗？

从 v0.14.0 起，自研 XCTest runner 取代 WebDriverAgent；当前控制路径不依赖 iPhone Mirroring。旧文章中的 Mirroring 和三层输入方案是历史实现。

可以直接从 Windows 或 Linux 控制吗？

当前本地设备宿主是 Mac。远程客户端可以访问 Mac 提供的网页和接口，不能把远程访问描述成原生 Windows 设备宿主。

能操作登录后的 App 吗？

它操作手机现有 App，因此可以使用手机已有登录态。密码、验证码、身份核验和最终支付由用户处理。

部署在哪里？

设备 runner 和守护进程由你自己托管。对外接口需要鉴权；手机上的 runner 只接受用每次启动生成的令牌签名的请求；iOS 15/16 走局域网时流量签名但不加密。

当前文档和源码

官网 · 安装 · 让 agent 用手机 · GitHub / README · 完整指南 · XCTest runner · Releases · chrome-use