iphone-use

让 AI agent 操作你的真实 iPhone。
Claude Code、Codex 或任何 MCP 客户端都能用它把屏幕读成文字，在任意 App 里点击、输入、滑动，包括没有 API 的 App。

English · 简体中文

```bash curl -fsSL https://raw.githubusercontent.com/leeguooooo/iphone-use/main/install.sh | sh ``` https://github.com/user-attachments/assets/6192e8a6-ab2d-4dfc-b2e9-2c971f527d55 _{1 分钟演示，真机录屏 · [English](https://github.com/user-attachments/assets/ee298774-bf3e-4fd0-9a08-481b20904f61)}

**广告位 · 招租中** ### 广告位招租在这里展示你的产品，支持项目持续维护。 [**咨询广告合作**](mailto:leeguoooo@gmail.com?subject=iphone-use%20%E5%B9%BF%E5%91%8A%E5%90%88%E4%BD%9C&body=%E4%BA%A7%E5%93%81%20%2F%20%E5%85%AC%E5%8F%B8%E5%90%8D%E7%A7%B0%EF%BC%9A%0A%E4%BA%A7%E5%93%81%E9%93%BE%E6%8E%A5%EF%BC%9A%0A%E5%B8%8C%E6%9C%9B%E6%8A%95%E6%94%BE%E7%9A%84%E4%BD%8D%E7%BD%AE%EF%BC%88README%20%2F%20%E5%AE%98%E7%BD%91%20%2F%20%E4%B8%A4%E8%80%85%EF%BC%89%EF%BC%9A%0A%E6%8A%95%E6%94%BE%E6%97%B6%E9%97%B4%EF%BC%9A%0A%E9%A2%84%E7%AE%97%20%2F%20%E5%B8%81%E7%A7%8D%EF%BC%88%E5%8F%AF%E9%80%89%EF%BC%89%EF%BC%9A%0A) · leeguoooo@gmail.com

## 付费接入与项目赞助需要帮你配置真实 iPhone、接入 agent，或建立 iOS App 测试流程？发邮件说明设备环境、要跑通的流程和预期结果，以及目前卡在哪里。我们先评估可行性，再确认服务范围、验收方式和报价。 [**咨询付费接入**](mailto:leeguoooo@gmail.com?subject=iphone-use%20%E4%BB%98%E8%B4%B9%E6%8E%A5%E5%85%A5%E5%92%A8%E8%AF%A2&body=%E7%9B%AE%E6%A0%87%E7%BD%91%E7%AB%99%E6%88%96%20App%EF%BC%88%E4%BB%85%E5%85%AC%E5%BC%80%E4%BF%A1%E6%81%AF%EF%BC%89%EF%BC%9A%0A%E8%A6%81%E8%B7%91%E9%80%9A%E7%9A%84%E6%B5%81%E7%A8%8B%E5%92%8C%E9%A2%84%E6%9C%9F%E7%BB%93%E6%9E%9C%EF%BC%9A%0A%E7%8E%AF%E5%A2%83%EF%BC%88Mac%20%2F%20Xcode%20%2F%20iPhone%20%2F%20iOS%20%2F%20agent%20client%EF%BC%89%EF%BC%9A%0A%E7%9B%AE%E5%89%8D%E5%8D%A1%E5%9C%A8%E5%93%AA%E9%87%8C%EF%BC%9A%0A%E9%A2%84%E7%AE%97%20%2F%20%E5%B8%81%E7%A7%8D%EF%BC%88%E5%8F%AF%E9%80%89%EF%BC%89%EF%BC%9A%0A%E6%9C%9F%E6%9C%9B%E6%97%B6%E9%97%B4%EF%BC%9A%0A) · [联系赞助维护](mailto:leeguoooo@gmail.com?subject=iphone-use%20%E8%B5%9E%E5%8A%A9%E7%BB%B4%E6%8A%A4&body=%E6%88%91%E6%83%B3%E6%94%AF%E6%8C%81%E9%A1%B9%E7%9B%AE%E6%8C%81%E7%BB%AD%E7%BB%B4%E6%8A%A4%E3%80%82%0A%E8%B5%9E%E5%8A%A9%E6%96%B9%E5%BC%8F%EF%BC%88%E4%B8%80%E6%AC%A1%E6%80%A7%E6%88%96%E6%8C%89%E6%9C%88%EF%BC%89%EF%BC%9A%0A%E9%87%91%E9%A2%9D%20%2F%20%E5%B8%81%E7%A7%8D%EF%BC%9A%0A) · leeguoooo@gmail.com 想支持项目持续维护，也可以邮件联系，商量一次性或按月赞助。普通问题和功能建议仍可在 GitHub 提交。咨询时请勿附上密码、验证码或私人账号数据。 ## 为什么用 iphone-use - **任何 App 都能操作，不需要 API。** 健康、银行、支付（包括禁止截屏的）、微信这类聊天 App，以及你自己在测的 App。 - **USB 或 Wi-Fi。** 第一次用数据线配好，之后可以拔掉线，通过加密隧道走 Wi-Fi 操作。 - **老 iPhone 也行。** 支持 iOS 15 及以上，不用升级手机系统。 - **快。** 自研 XCTest 设备 runner 读一次屏约 0.1 秒，点击并带回稳定后的画面约 1.9 秒（[测速](#速度)）。 - **结果说实话。** 每个操作都会说明是已执行、没发出去，还是结果不确定，以及能不能安全重试。点到被遮住的元素会直接拒绝，不会假装成功。 - **做过的事可以一键重放。** 做过一次的任务可以存成 flow，之后一次调用重放，不经过模型，不花 token。 - **人也能远程控制。** 用浏览器或另一台 iPhone 亲手操作这台手机，局域网或外网都行：H.264 实时画面，鼠标键盘直接操作，扫码就能配对。agent 和人共用一台手机也不会互相打架（[详见](#人用的远程控制)）。 - **能实时看 agent 在做什么。** 支持 MCP Apps 的 agent 客户端能在侧边栏看到手机画面，也可以在浏览器或 iOS App 里看。 - **不打扰你的 Mac。** 不碰 Mac 的屏幕、光标和窗口焦点。 ## 可以让它做什么 ```text 打开健康，告诉我这周每天走了多少步。在微信里找到妈妈发的最新一条消息，念给我听。把这个银行流水页面的每一笔交易都抄下来，一直翻到底。把这篇 2000 字的草稿写进备忘录，新建一条。在真机上跑一遍我们 App 的登录测试，告诉我哪一步失败了。 ``` agent 可以直接按名字打开 App（`launch_app {"app": "健康"}`），一次输入最长 2 万字，跨页读完整个列表，并说明有没有读到底。 ## 工作原理 ```text Claude Code / Codex / 任何 MCP 客户端 ─MCP──┐ 脚本和其他 agent ─────────────────────HTTP──┤ ▼ Mac 上的 iphone-use 守护进程 ──USB 或 Wi-Fi──▶ iPhone 上的 XCTest runner ▲ 你，用浏览器或 iOS App ─────────────────────┘ ``` 每台手机在 Mac 上对应一个守护进程。它把屏幕读成无障碍树（文字，不是像素），通过装在手机上的小型 XCTest runner 发送点击和输入，并在画面稳定后才返回结果。agent 和人走的是同一个守护进程，同一时间只有一方在用手机。 ## 安装 **需要准备** - 一台 Mac（macOS 15 以上），装好 Xcode 并登录 Apple ID，免费账号就行。 - 一台 iOS 15 及以上的 iPhone，打开开发者模式（设置 → 隐私与安全性 → 开发者模式）。 - 第一次配置需要一根数据线。安装前把 iPhone 插上并解锁。安装脚本接着会把手机配好，让 agent 打开「设置」读一遍屏幕给你看，在 Claude Code 和 Codex 里注册好 MCP server（装了 Cursor、Claude Desktop 的话也会一并注册，设 `IPHONE_USE_NO_CLIENT_SETUP=1` 可跳过这两个），再用一次性链接在浏览器里打开控制页，不用抄密码。缺什么会直接告诉你缺什么、怎么补。 ```bash iphone-use status # 手机现在能不能给 agent 用 iphone-use doctor # 缺什么、怎么补 iphone-use setup # 重新配置手机（换了 iPhone 或 Xcode 之后） iphone-use try # 无害的检查：打开设置、读屏、回桌面 iphone-use login # 重新登录浏览器，附手机扫码用的二维码 iphone-use upgrade # 升级全部组件 ~/.iphone-use/uninstall.sh --dry-run # 看卸载会删掉什么（去掉 --dry-run 就真的卸载） ``` ### 或者让 agent 帮你装在插着 iPhone 的那台 Mac 上，把下面这段贴给 Codex 或 Claude Code： ```text 在这台 Mac 上安装 iphone-use（https://github.com/leeguooooo/iphone-use），让你能操作我的 iPhone。 1. 运行：curl -fsSL https://raw.githubusercontent.com/leeguooooo/iphone-use/main/install.sh | sh 2. 运行 `iphone-use doctor`。终端里能修的直接修；它让你运行 `iphone-use setup` 时就运行。 3. 有几步只能我自己做：在 Xcode 里登录 Apple ID、在 iPhone 上点「信任」、打开开发者模式、解锁手机。遇到这些就停下，告诉我具体怎么做，等我说做完了再继续。不要向我要密码或验证码。 4. 再跑 `iphone-use doctor`，直到什么都不缺，然后运行 `iphone-use try`。 5. 如果这个对话里还没有 phone_* 工具，告诉我新开一个对话。 ``` ### Codex 和 Claude Code 插件插件带 skill 和 MCP server，但仍需先完成上面的安装： ```bash codex plugin marketplace add leeguooooo/iphone-use && codex plugin add iphone-use@iphone-use ``` 在 Claude Code 里： ```text /plugin marketplace add leeguooooo/iphone-use /plugin install iphone-use@iphone-use ``` ## 人用的远程控制给 agent 用的同一个守护进程，也让你自己远程操作手机： - **用浏览器。** 实时画面是手机自己编码的 H.264：局域网里原生分辨率约 50 fps，网络慢时有省流模式。单击是点击，拖动是滑动，按住是长按，滚轮和触控板能滚动。点一下画面就能用你的输入法直接往手机里打字，⌘V 能粘贴。「控件」面板列出屏幕上的元素，可以按名字点；「流程」面板能把你的操作录成可重放的 flow。页面语言跟随浏览器（中文或英文），侧栏可以切换。 - **用另一台 iPhone。** iOS 原生 App（最低部署版本 iOS 15）在 Mac 网页上扫个码就配对，不用输地址和密码。用系统硬件解码播放画面，多台手机之间随时切换。 - **禁止截屏的页面也能操作。** 银行、支付类 App 会把截屏画面涂黑，这时你看到的是屏幕元素的实时线框图，而不是一片空白，照样可以点着操作。 - **在外面也能连。** 通过带鉴权的 HTTPS 反向代理或 Tailscale 这类 VPN 连到 Mac，就能在外网控制手机（[安全说明](docs/guide.zh-CN.md#安全)）。 - **不会撞车。** 一台手机同一时间只有一个使用者。你在操作时，agent 会等着，或被告知手机在谁手里；反过来也一样。整个过程不动 Mac：不抢窗口焦点，鼠标也不会被移走。 ## 接到 agent 上 Mac 上的守护进程负责操作手机，对外提供三种入口： - **MCP server**：给 Claude Code、Codex、Claude Desktop、Cursor 等 MCP 客户端用； - **HTTP 接口**：给 agent 和脚本用（`/agent/*`）； - **网页和 iOS 原生 App**：给人用（见[人用的远程控制](#人用的远程控制)）。装了 Claude Code、Codex、Cursor 或 Claude Desktop 的话，安装时会自动给它们注册 MCP server（`IPHONE_USE_NO_CLIENT_SETUP=1` 不动 Cursor 和 Claude Desktop）。其他 MCP 客户端只要填命令，在这台 Mac 上 server 会自己找到守护进程和令牌： ```json { "mcpServers": { "iphone-use": { "command": "/Users/你的用户名/Applications/iPhoneUse.app/Contents/MacOS/iphone-use-mcp" } } } ```

Cursor、VS Code、Claude Desktop、Gemini CLI、opencode、Windsurf 的配置

填绝对路径（替换 `你的用户名`），把这一项合并进文件，保留里面已有的 server。 - **Cursor**：`~/.cursor/mcp.json`（或项目里的 `.cursor/mcp.json`），用上面的 `mcpServers` 写法。 - **Claude Desktop**：`~/Library/Application Support/Claude/claude_desktop_config.json`，用上面的 `mcpServers` 写法；改完退出再重开 App。 - **Gemini CLI**：`~/.gemini/settings.json`（或项目里的 `.gemini/settings.json`），用上面的 `mcpServers` 写法。 - **Windsurf / Devin Desktop**：`~/.codeium/windsurf/mcp_config.json`（新版本是 `~/.config/devin/mcp_config.json`），用上面的 `mcpServers` 写法。 - **VS Code / Copilot**：工作区里的 `.vscode/mcp.json`，或用 **MCP: Open User Configuration** 对所有工作区生效。键名是 `servers`： ```json { "servers": { "iphone-use": { "type": "stdio", "command": "/Users/你的用户名/Applications/iPhoneUse.app/Contents/MacOS/iphone-use-mcp" } } } ``` - **opencode**：`~/.config/opencode/opencode.json`（或项目里的 `opencode.json`）。键名是 `mcp`，命令写成数组： ```json { "$schema": "https://opencode.ai/config.json", "mcp": { "iphone-use": { "type": "local", "command": ["/Users/你的用户名/Applications/iPhoneUse.app/Contents/MacOS/iphone-use-mcp"], "enabled": true } } } ```

也可以直接调 HTTP 接口： ```bash AUTH="Authorization: Bearer $TOKEN"; CTL="X-Phone-Control: 1" curl -s -H "$AUTH" $HOST/agent/elements # 屏幕读成文字，附一个快照令牌 curl -s -H "$AUTH" -H "$CTL" -X POST "$HOST/agent/input?return=delta" \ -d '{"type":"tap","element":7,"snapshot":"…"}' # 点击，并返回界面变化（约 2 秒） ``` 给开发和测试用的功能也在同一套工具里：读取手机日志和崩溃报告、录屏保存为 MP4、安装测试包（`.ipa`、`.app` 或 https 链接）、模拟定位，以及按 App 记录经验笔记，agent 进入该 App 时会自动读到。`IPHONE_USE_MCP_TOOLS=readonly` 只开放读取类工具；`iphone-use-mcp --listen 127.0.0.1:端口` 可以通过 HTTP 提供 MCP。监听 127.0.0.1 时只有本机能连；其他机器上的客户端要通过带认证的隧道访问，或者监听其他地址并设置 `IPHONE_USE_MCP_TOKEN`（非回环地址必须设置）。手边没有手机？开发时可以用同样的方式操作 iOS 模拟器（预览，需要 Xcode）：`iphone-use simulator start "iPhone 16 Pro"` 会编译并启动所需的一切，然后用 `claude mcp add iphone-sim -e IPHONE_USE_INSTANCE=sim -- iphone-use-mcp` 把 agent 接上去。详见[模拟器](docs/guide.zh-CN.md#模拟器预览)。详见 [MCP 工具](crates/mcp/README.md) 和 [Agent API 参考](docs/agent-api.html)。 ## 安全与隐私 - **密码只在你手里。** 遇到登录、锁屏密码、Face ID，agent 会停下来请你在手机上完成，绝不向你要密码或验证码。 - **agent 绕不过去的限制。** 守护进程会拒绝你屏蔽的 App（`IPHONE_USE_BLOCKED_APPS`，例如 `Wallet, Passwords`），并限制每个任务的操作步数（`IPHONE_USE_MAX_ACTIONS`），不管 agent 的提示词怎么写（[详情](docs/agent-reference.md#owner-limits-and-the-activity-feed)）。 - **它做了什么你看得见。** 网页会在实时画面上用大白话显示每一步，例如「点按“无线局域网”」。输入的文字不会被记录，只记字数。 - **默认只在本机。** 守护进程监听 `127.0.0.1:44321` 并要求密码；手机上的 runner 只接受用每次启动的令牌签名的请求。iOS 15/16 的局域网路径不加密（[安全说明](docs/guide.zh-CN.md#安全)）。 - **没有遥测。** 当前版本不发送任何使用数据（[遥测说明](docs/telemetry.md) · [隐私政策](docs/privacy.zh-CN.md)）。 ## Flow：做过一次的事，沉淀成脚本重复做的事存成 **flow**：按 App 分类、经过审阅的脚本，重放时不经过模型，不花 token。官方 flow 源是 **[leeguooooo/iphone-use-flows](https://github.com/leeguooooo/iphone-use-flows)**。在网页的「流程」面板里操作一遍就能录下来，再提 PR 发布到源里。 AI 不用你提醒就会找 flow：进入某个 App 时，返回结果里就列着这个 App 的 flow。在没有 flow 的 App 里做完一个多步任务后，AI 会问你要不要存成 flow，步骤守护进程已经录好了草稿。守护进程会自己保持 flow 源最新（`IPHONE_USE_FLOWS_NO_AUTO_UPDATE=1` 关闭自动更新，`IPHONE_USE_FLOWS_NO_SUGGEST=1` 关闭保存提示）。 ```bash MCP=~/Applications/iPhoneUse.app/Contents/MacOS/iphone-use-mcp $MCP flow update # 同步官方源（逐个校验 sha256） $MCP flow list # 看有哪些 flow $MCP flow run health/export-all-zh-cn # 重放一个；失败时会说卡在哪一步、为什么 $MCP flow draft --out my-task.json # 把刚才在手机上做的事导出成 flow 草稿 ``` flow 还能组成可重跑的测试套件（`$MCP test suite.yaml`，退出码可直接接 CI），也能交给守护进程按 cron 定时运行（`$MCP schedule add`）：见[测试与定时任务](docs/testing.zh-CN.md)。 ## 速度 iphone-use 用自研的 XCTest runner（[`runner/`](runner/README.md)）操作手机，接口与 WebDriverAgent 兼容。它是为速度设计的： - 读屏只做一次无障碍快照，只取固定的几个属性，不再逐个元素、逐个属性地查询。 - 直接合成触摸事件，动作前不等 App 空闲；画面是否稳定由守护进程在动作之后检查。 - 一个小 App 自带 HTTP 服务和 MJPEG 视频流，手机上不需要别的依赖。同一台 iPhone 13、USB 连接，与 [agent-device](https://github.com/callstack/agent-device) 对比（2026 年 10 月实测）： | | iphone-use runner | agent-device | |---|---|---| | 读屏（无障碍树） | 0.08–0.135 秒 | 约 0.7 秒 | | 点击并等画面稳定 | 1.0 秒 | 2.8–3.3 秒 | 走完整的 agent 接口，在 iPhone 17 Pro Max 上按标签点击并带回稳定后的变化约 1.9 秒，基于 WebDriverAgent 的版本是 4.2 秒。实时画面 27–28 fps。每台手机有独立的守护进程和 runner，两台同时操作时，每台都和单独操作一样快。 ## 更多 - [完整指南](docs/guide.zh-CN.md)：网页和 iOS App、flow 与官方 flow 源、Wi-Fi 和 iOS 15/16、生命周期、配置、安全、开发。 - [Agent API 参考](docs/agent-api.html) · [MCP 工具](crates/mcp/README.md) · [架构](docs/direct-device-architecture.html) · [设备设置常见坑](docs/runner-setup.html) · [设备 runner](runner/README.md) · [隐私](docs/privacy.zh-CN.md) - [产品指南](https://blog.leeguoo.com/zh/posts/iphone-use/)：安装、MCP 接入、flow 和选型对比。 - 问题和建议：[GitHub issues](https://github.com/leeguooooo/iphone-use/issues)。 ## 许可证 [PolyForm Shield 1.0.0](LICENSE)。本项目采用源码可见许可，允许符合条款的非竞争用途、修改和分发；禁止使用本软件提供竞争产品或服务，包括免费竞品。详见[许可范围与第三方声明](LICENSING.md)。 ## `*-use` 家族一组小而互相独立的 CLI，各自把 agent 的手伸到一个真实的东西上。装法都一样： `curl … install.sh | sh` 装命令，输出都是 JSON，并各自配一个 skill 教会 agent 使用 ——skill 怎么装以各仓库自己的 README 与对应发行版说明为准，各项目、各版本并不相同。 | 仓库 | 给 agent 的能力 | |---|---| | [chrome-use](https://github.com/leeguooooo/chrome-use) | 一个真浏览器：带登录态操作、填表、抓数据、截图 | | [mail-use](https://github.com/leeguooooo/mail-use) | 邮箱：读、搜、发、清理，Gmail / QQ / 163 / 任意 IMAP | | [wechat-use](https://github.com/leeguooooo/wechat-use) | macOS 微信：发消息、查联系人和聊天记录 | | [discord-use](https://github.com/leeguooooo/discord-use) | Discord：消息、频道、论坛、webhook（纯 REST，Rust） | | [cookie-use](https://github.com/leeguooooo/cookie-use) | 同一站点的多个登录态：抓取、切换、注入 | | [profile-use](https://github.com/leeguooooo/profile-use) | 本地个人资料：安全地填注册 / KYC / 结账表单 | | [bitwarden-use](https://github.com/leeguooooo/bitwarden-use) | Bitwarden / Vaultwarden：无头 passkey（FIDO2）登录 | | [chatgpt-use](https://github.com/leeguooooo/chatgpt-use) | 把 ChatGPT 订阅当成编码 agent 的后端，不用 API key | | [computer-use](https://github.com/leeguooooo/computer-use) | macOS 桌面本身 | | [pixcake-use](https://github.com/leeguooooo/pixcake-use) | 只读探查 PixCake：快照 / diff / SQLite 检查 | ## 作者 **郭立（Guo Li / leeguoo）** 开发 —— [leeguoo.com](https://leeguoo.com/about) · [GitHub](https://github.com/leeguooooo) · [X](https://x.com/leeguooooo) · 更多工具见 [*-use 家族](https://github.com/leeguooooo/plugins)。