iphone-use

iphone-use 是一款开源工具，实现Computer Use能力，让AI Agent、浏览器可以识别并直接操作真实的iPhone设备。

从v0.14.0版本开始，项目替换掉传统WebDriverAgent，使用自研XCTest runner，接口仍然保持WDA兼容；整个控制链路不依赖iPhone Mirroring。AI可以读取手机屏幕内容，执行点击、滑动、文字输入；操作失败、元素遮挡、输入未生效时，会主动反馈状态，不会静默判定执行成功。

一键安装脚本：

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

环境前置准备

• Mac主机，macOS 15及以上系统，安装Xcode并登录Apple ID，免费账号即可使用
• iPhone开启开发者模式：设置 → 隐私与安全性 → 开发者模式
• USB数据线，安装前iPhone需要插上电脑并完成解锁

安装脚本会自动完成设备配置，自动打开「设置」演示读屏能力；自动在Claude Code注册MCP服务，通过一次性链接拉起浏览器控制面板，无需手动复制密钥。
内置常用命令：

• iphone-use status：检测设备是否就绪可供Agent调用
• iphone-use doctor：诊断缺失依赖，给出修复指引
• iphone-use setup：更换手机或升级Xcode后，重新配置设备
• iphone-use try：安全自检，打开设置、读屏、返回桌面，无破坏性操作
• iphone-use login：重新登录网页控制台，提供手机扫码二维码
• iphone-use upgrade：一键升级全部组件

核心能力

真机操控，不受App截屏限制

依托XCTest自研Runner，即使是禁止截屏的银行、支付类App，依然可以读取无障碍页面元素并执行操作。

Mac端守护进程在iPhone上运行设备Runner，对外提供两类接口：面向脚本与AI Agent的HTTP接口，以及包含26个工具的MCP Server，可直接对接Claude Code、Claude Desktop等MCP客户端；同时提供网页端和iOS客户端，支持人工查看实时画面、手动点击输入。

工具不会读取、操控Mac本机屏幕、光标与窗口焦点，仅针对连接的iPhone设备。

MCP接入与HTTP API调用

安装脚本会自动部署Agent所需Skill，Claude Code环境可自动注册MCP服务。其他MCP客户端只需写入配置即可接入：

{
  "mcpServers": {
    "iphone-use": {
      "command": "/Users/你的用户名/Applications/iPhoneUse.app/Contents/MacOS/iphone-use-mcp"
    }
  }
}

也可直接调用原生HTTP接口，获取页面元素快照、下发点击/输入指令，接口会返回操作状态：执行成功、指令未下发、结果不确定，同时支持安全重试判断。元素被遮挡、输入未生效会直接抛出错误。

Flow流程录制，沉淀免模型自动化脚本

支持将重复操作录制保存为Flow脚本，按App分类管理，脚本重放时不再调用大模型、不消耗Token。官方维护Flow仓库leeguooooo/iphone-use-flows。

AI会自动识别当前App，推荐可用Flow；多步任务完成后，AI会询问是否将录制草稿保存为新流程。守护进程默认自动同步官方脚本库，可通过环境变量关闭自动更新与保存提示。

配套MCP命令：同步脚本源、查看流程列表、运行指定流程、导出本地草稿。Flow还能组合成测试套件接入CI，支持cron定时自动执行任务。

自研XCTest Runner，大幅提升响应速度

新版自研Runner为AI操控场景优化：一次性获取完整无障碍快照，不再逐个查询元素属性；直接合成触摸事件，不等待App空闲，由后台守护进程校验画面稳定。

2026年10月实测性能对比（USB连接iPhone13）：

• 读屏无障碍树：0.08–0.135秒，对比agent-device约0.7秒
• 点击并等待画面稳定：1.0秒，对比agent-device 2.8–3.3秒
  iPhone17 Pro Max完整标签点击并返回画面变化约1.9秒，旧WDA版本为4.2秒；实时画面流可达27–28fps。支持多台iPhone并行操控，每台设备独立Daemon与Runner，多机运行不会互相拖慢速度。

要点小结

1. 项目定位：开源iPhone真机AI操控工具，Computer Use能力，自研XCTest Runner替代WDA，兼容原有WDA接口，无需iPhone Mirroring
2. 接入方案：MCP Server对接Claude系列Agent，同时开放HTTP接口；自带网页控制台，支持人工实时预览操作手机
3. Flow自动化：录制操作生成免Token脚本，支持定时任务、CI测试套件，AI自动推荐匹配流程
4. 性能优势：无障碍快照、点击响应速度大幅优于传统WDA方案，支持多iPhone并行操作
5. 运行前提：macOS15+、Xcode、iPhone开启开发者模式，USB有线连接，免费Apple ID即可部署