iPhone Use

iphone-use

让 AI Agent 使用你的真实 iPhone。
Claude Code、Codex 或任何 MCP 客户端都可以读取屏幕文本，并在任何应用中点击、输入和滑动，包括没有 API 的应用。

English · 简体中文

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

https://github.com/user-attachments/assets/ee298774-bf3e-4fd0-9a08-481b20904f61

_{1 分钟演示，真实 iPhone 录屏 · 中文版}

广告 · 可投放 在此投放广告 在这里展示你的产品，支持项目持续维护。 咨询广告投放 · [email protected]

付费设置与项目赞助

需要协助设置真实 iPhone、连接你的 Agent，或创建 iOS 应用测试流程？请发送邮件，说明你的环境、工作流、预期结果以及遇到的阻碍。我们会评估可行性，并在开始工作前商定范围、验收标准和报价。

咨询付费设置 · 洽谈赞助 · [email protected]

想支持项目持续维护？请发送邮件，洽谈一次性或定期捐助。

欢迎在 GitHub 上提交社区 Bug 报告和功能请求。请勿在咨询中提供凭据和私人账户数据。

为什么选择 iphone-use

• 任何应用，无需 API。 它适用于健康、银行和支付应用（包括会屏蔽屏幕捕获的应用）、聊天应用，以及你正在测试的自有应用。
• USB 或 Wi-Fi。 用线缆为手机完成一次设置；之后即可通过加密隧道使用 Wi-Fi 操控。
• 旧款 iPhone 也能用。 支持 iOS 15 及更高版本，无需更新手机。
• 速度快。 它自带的 XCTest 设备运行器约 0.1 秒即可读取屏幕。一次点击并返回稳定后的屏幕约需 1.9 秒（数据）。
• 结果可靠。 每项操作都会报告它已执行、未发送还是状态未知，以及是否可以安全重试。若元素被遮挡，点击会被拒绝，而不会被冒称为已完成。
• 流程可重放。 一次完成的任务可以变成一个流程，只需一次调用即可重放，无需模型，也不消耗令牌。
• 也可供用户远程控制。 你可以通过浏览器或另一部 iPhone 自行操控手机，无论是在局域网内还是身处任何地方：实时 H.264 屏幕画面、鼠标和键盘，以及通过二维码配对。Agent 和用户可以共用一部手机，互不干扰（详情）。
• 实时观看 Agent 操作。 手机屏幕会显示在 Agent 主机的侧边栏中（支持 MCP Apps 时）、浏览器中或 iOS 应用中。
• Mac 上的任何内容都不会移动。 它不会触碰 Mac 的屏幕、光标或焦点。

你可以提出的要求

Open Health and tell me how many steps I walked each day this week.
Find the newest message from Mom in WeChat and read it to me.
Collect every transaction on this bank statement page, all the way to the end.
Write this 2,000-word draft into a new note in Notes.
Run my app's login test on the real phone and tell me which step fails.

Agent 会按名称查找应用（launch_app {"app": "Health"}），并在一个步骤中输入长文本（最多 20,000 个字符）。它可以读取跨多页的列表，并说明是否已到末尾。

工作原理

 Claude Code / Codex / any MCP client ──MCP──┐
 scripts and other agents ─────────────HTTP──┤
                                             ▼
                          iphone-use daemon on your Mac ──USB or Wi-Fi──▶ XCTest runner on the iPhone
                                             ▲
 you, in a browser or the iOS app ───────────┘

每部手机都由 Mac 上运行的一个守护进程负责。它会将屏幕读取为辅助功能树（文本，而非像素），通过安装在手机上的小型 XCTest 运行器发送点击和输入，并在回复前确认屏幕已稳定。Agent 和用户共用同一个守护进程，且同一时间只有一方能操作手机。

安装

你需要准备

• 一台运行 macOS 15 或更高版本的 Mac，并在 Xcode 中登录 Apple ID（免费账号也可以）。
• 一部运行 iOS 15 或更高版本且已开启开发者模式的 iPhone（设置 → 隐私与安全性 → 开发者模式）。
• 首次设置时需要一根 USB 线缆。安装前先连接 iPhone 并解锁。

随后，安装程序会完成手机设置，并展示 Agent 打开“设置”并读取其中内容的过程。它会将 MCP 服务注册到 Claude Code 和 Codex；如果已安装，也会注册到 Cursor 和 Claude Desktop（IPHONE_USE_NO_CLIENT_SETUP=1 可跳过后两者），并在浏览器中打开控制页面，使用一次性登录，无需复制密码。如果有任何缺项，它会说明缺少什么以及如何解决。

iphone-use status    # is the phone ready for agents?
iphone-use doctor    # what is missing, and how to fix it
iphone-use setup     # set the phone up again (after a new iPhone or Xcode)
iphone-use try       # a harmless check: open Settings, read the screen, go Home
iphone-use login     # sign a browser in again, with a QR code for the iPhone
iphone-use upgrade   # update everything
~/.iphone-use/uninstall.sh --dry-run   # what uninstalling would remove (drop --dry-run to do it)

或者让你的 Agent 帮你安装

将以下内容粘贴到连接着 iPhone 的 Mac 上的 Codex 或 Claude Code 中：

Install iphone-use (https://github.com/leeguooooo/iphone-use) on this Mac so you can drive my iPhone.
1. Run: curl -fsSL https://raw.githubusercontent.com/leeguooooo/iphone-use/main/install.sh | sh
2. Run `iphone-use doctor`. Fix what it reports that can be fixed from the terminal, and run
   `iphone-use setup` when it tells you to.
3. Some steps only I can do: signing in to an Apple ID in Xcode, tapping Trust on the iPhone,
   turning on Developer Mode, unlocking the phone. For those, stop, tell me exactly what to do,
   and wait until I say it is done. Never ask me for a password or a code.
4. Run `iphone-use doctor` again until nothing is missing, then `iphone-use try`.
5. If the phone_* tools are not loaded in this chat yet, tell me to start a new chat.

Codex 和 Claude Code 插件

每个插件都会添加技能和 MCP 服务；仍需先完成上述安装：

codex plugin marketplace add leeguooooo/iphone-use && codex plugin add iphone-use@iphone-use

在 Claude Code 中：

/plugin marketplace add leeguooooo/iphone-use
/plugin install iphone-use@iphone-use

面向用户的远程控制

为 Agent 提供服务的同一个守护进程，也能让你亲自操控手机：

• 通过浏览器。 实时画面以 H.264 编码后从手机传输：在局域网上以原生分辨率运行，帧率约为 50 fps；网络较慢时则使用更轻量的模式。点击即可轻触，拖动即可滑动，按住即可长按，用滚轮或触控板滚动。使用你的输入法直接在手机上输入，⌘V 可粘贴。Controls 面板会列出屏幕上的元素，方便你按标签轻触；Flow 面板会将你的操作录制为可重放的工作流。页面会跟随浏览器语言（英语或中文），你也可以在侧边栏中切换。
• 通过另一部 iPhone。 原生 iOS 应用（最低部署目标为 iOS 15）通过扫描 Mac 页面上的二维码进行配对，无需输入地址或密码。它使用硬件解码器播放屏幕画面，并可在你的手机之间切换。使用 iphone-use setup-app 安装，该命令会使用你自己的团队签名；如果使用付费团队，应用还可在没有 Mac 的情况下控制其所在的手机（详情）。
• 屏幕无法录制时。 银行和支付应用会屏蔽屏幕录制；此时你看到的不是空白画面，而是屏幕元素的实时线框图，仍然可以轻触操作。
• 随时随地。 通过经过身份验证的 HTTPS 反向代理或 Tailscale 等 VPN 连接 Mac，即可从网络之外控制手机（安全说明）。
• 互不冲突。 一部手机同一时间只能由一个人控制。你操作时，Agent 会等待或收到手机当前由谁控制的通知；反过来也一样。

操作期间，Mac 上的一切都不会改变：不会有窗口获得焦点，光标也会停留在原处。

在 Agent 中使用

Mac 上的守护进程可操控手机，并以三种形式提供相同的控制能力：

• 面向 Claude Code、Codex、Claude Desktop、Cursor 和其他 MCP 客户端的 MCP 服务；
• 面向 Agent 和脚本的 HTTP API（/agent/*）；
• 面向用户的 网页和原生 iOS 应用（远程控制）。

安装程序会在检测到 Claude Code、Codex、Cursor 和 Claude Desktop 时向其注册 MCP 服务（设置 IPHONE_USE_NO_CLIENT_SETUP=1 可跳过对 Cursor 和 Claude Desktop 的配置）。其他 MCP 客户端只需要配置命令；在这台 Mac 上，服务会自行找到守护进程及其令牌：

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

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

使用绝对路径（替换 YOU），并将此条目合并到文件中；保留已有的服务器配置。

• Cursor：~/.cursor/mcp.json（或项目中的 .cursor/mcp.json），使用上面的 mcpServers 配置块。

• Claude Desktop：~/Library/Application Support/Claude/claude_desktop_config.json，使用上面的 mcpServers 配置块；退出并重新打开应用。

• 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：

  {
    "servers": {
      "iphone-use": {
        "type": "stdio",
        "command": "/Users/YOU/Applications/iPhoneUse.app/Contents/MacOS/iphone-use-mcp"
      }
    }
  }
  

• opencode：~/.config/opencode/opencode.json（或项目中的 opencode.json）。键名为 mcp，命令是一个数组：

  {
    "$schema": "https://opencode.ai/config.json",
    "mcp": {
      "iphone-use": {
        "type": "local",
        "command": ["/Users/YOU/Applications/iPhoneUse.app/Contents/MacOS/iphone-use-mcp"],
        "enabled": true
      }
    }
  }
  

也可以直接调用 HTTP API：

AUTH="Authorization: Bearer $TOKEN"; CTL="X-Phone-Control: 1"
curl -s -H "$AUTH" $HOST/agent/elements                     # the screen as text + a snapshot token
curl -s -H "$AUTH" -H "$CTL" -X POST "$HOST/agent/input?return=delta" \
  -d '{"type":"tap","element":7,"snapshot":"…"}'            # tap, then what changed (~2 s)

面向应用开发者和测试人员，同一组工具还可以读取手机日志和崩溃报告、将屏幕录制为 MP4、安装构建产物（.ipa、.app 或 https 链接）、设置模拟位置，并为每个应用保存备注，供 Agent 进入应用时读取。设置 IPHONE_USE_MCP_TOOLS=readonly 可仅开放读取类工具；使用 iphone-use-mcp --listen 127.0.0.1:PORT 可通过 HTTP 提供 MCP 服务。回环监听器只能由同一台 Mac 访问；若要让另一台机器上的客户端访问，请将其置于经过身份验证的隧道之后，或在设置 IPHONE_USE_MCP_TOKEN 的情况下监听其他地址（非回环监听时必须设置此变量）。

手边没有手机？开发期间也可以用同样的方式操控 iOS Simulator（预览功能，需要 Xcode）：iphone-use simulator start "iPhone 16 Pro" 会构建并启动所需的一切，然后用 claude mcp add iphone-sim -e IPHONE_USE_INSTANCE=sim -- iphone-use-mcp 将 Agent 指向它。请参阅 模拟器。

请参阅 MCP 工具和 Agent API 参考。

安全与隐私

• 机密信息由你掌控。 需要登录、输入密码或使用 Face ID 时，Agent 会暂停并要求你在手机上完成操作。它绝不会索要密码或验证码。
• Agent 无法绕过限制。 无论 Agent 的提示词怎么说，守护进程都会拒绝你屏蔽的应用（例如 IPHONE_USE_BLOCKED_APPS 中的 Wallet, Passwords），并限制每项任务的操作次数（IPHONE_USE_MAX_ACTIONS）（详情）。
• 操作过程一目了然。 网页会在实时屏幕上用通俗文字显示每项操作，例如 Tapped “Wi-Fi”。输入的文字不会被保留，只记录其长度。
• 默认在本地运行。 守护进程在 127.0.0.1:44321 上监听，并受密码保护；手机上的运行器只接受使用每次启动时生成的令牌签名的请求。iOS 15/16 的局域网连接未加密（安全）。
• 无遥测数据。 此版本不会发送任何使用数据（遥测 · 隐私政策）。

phone_home_layout 会读取已配对手机上持久保存的主屏幕页面、Dock、文件夹和小组件堆栈，而不会打开文件夹或截屏。 使用 page 限制响应范围。页面索引包含隐藏页面和被专注模式过滤的页面；拖动前请使用最新的 UI 元素，不要将网格位置视为屏幕坐标。

工作流：执行一次任务，无需模型即可重放

重复执行的任务会保存为工作流：经过审核、按应用划分的脚本，无需模型即可重放，因此不消耗令牌。官方注册表为 leeguooooo/iphone-use-flows。在浏览器的 Flow 面板中录制工作流，然后通过 PR 发布到该注册表。

Agent 会自行查找工作流：进入某个应用时，响应会列出该应用的工作流。如果 Agent 在一个没有工作流的应用中完成了多步骤任务，它会询问是否要将任务保存为工作流；守护进程已将这些步骤记录为草稿。守护进程会自行保持注册表为最新（IPHONE_USE_FLOWS_NO_AUTO_UPDATE=1 可关闭此功能，IPHONE_USE_FLOWS_NO_SUGGEST=1 可关闭保存建议）。

MCP=~/Applications/iPhoneUse.app/Contents/MacOS/iphone-use-mcp
$MCP flow update                            # sync the registry (sha256-checked)
$MCP flow list                              # what is available
$MCP flow run health/export-all-zh-cn       # replay one; failures say which step and why
$MCP flow draft --out my-task.json          # what you just did on the phone, as a draft flow

工作流还可用于创建可重复运行的测试套件（$MCP test suite.yaml，会生成可供 CI 使用的退出代码）和由守护进程按 cron 计划启动的定时运行（$MCP schedule add）：请参阅测试和定时运行。

速度

iphone-use 通过其专用的 XCTest 运行器控制手机（runner/）。它使用 WebDriverAgent HTTP API，并针对速度进行了优化：

• 它通过一次性读取固定属性集的无障碍快照来读取屏幕，而不是逐个遍历元素树中的属性。
• 它直接合成触摸操作，不会等到应用空闲后才执行；守护进程会在操作后检查屏幕是否已稳定。
• 它是一个内置 HTTP 服务和 MJPEG 流的小型应用；手机上无需安装额外依赖。

在同一台 iPhone 13 上通过 USB 与 agent-device 对比测得（2026 年 10 月）：

	iphone-use 运行器	agent-device
读取屏幕（无障碍树）	0.08–0.135 秒	~0.7 秒
点击后等待屏幕稳定	1.0 秒	2.8–3.3 秒

通过完整的 Agent API，按标签点击并返回稳定后的变化，在 iPhone 17 Pro Max 上约需 1.9 秒；基于 WebDriverAgent 的版本则需 4.2 秒。实时视图以 27–28 fps 的帧率传输。每部手机都有独立的守护进程和运行器，因此同时控制两部手机时，每部手机的运行速度与单独控制时一样快。

更多

• 完整指南：浏览器和 iOS 应用、流程和流程注册表、Wi-Fi 和 iOS 15/16、生命周期、配置、安全、开发。
• Agent API 参考 · MCP 工具 · 架构 · 设备设置注意事项 · 设备运行器 · 隐私
• 产品指南：安装、MCP 设置、流程及对比。
• 问题和想法：GitHub issues。

许可证

PolyForm Shield 1.0.0。本项目采用源码可用模式。根据许可证，允许非竞争性使用、修改和分发；禁止使用该软件提供具有竞争性的产品或服务，包括免费产品或服务。请参阅许可范围和第三方声明。

*-use 系列

小巧、可组合的 CLI，让 AI Agent 能够亲自操作一项真实事物。所有项目的形式都相同： 通过 curl … install.sh | sh 安装，JSON 输出到 stdout，并附带一个教会 Agent 如何操作的技能——每个仓库自己的 README 都会说明如何安装其技能，因为正确的安装方式因项目和版本而异。

仓库	为 Agent 提供
chrome-use	一个真实的浏览器——已登录的会话、表单、抓取、截图
mail-use	电子邮件——跨 Gmail / QQ / 163 / 任意 IMAP 读取、搜索、发送、分类处理
wechat-use	macOS 上的 WeChat——发送消息、查询联系人和历史记录
discord-use	Discord——消息、频道、论坛、webhook（仅 REST，Rust）
cookie-use	每个网站的多个已登录账号——捕获、切换、应用会话
profile-use	安全使用你的个人资料——填写注册 / KYC / 结账表单
bitwarden-use	Bitwarden / Vaultwarden——无头 passkey（FIDO2）登录
chatgpt-use	将你的 ChatGPT 订阅用作编码 Agent 后端——无需 API 密钥
computer-use	macOS 桌面本身
pixcake-use	只读 PixCake 探测——快照 / 差异 / SQLite 检查

作者

由 郭立 (Guo Li / leeguoo) 构建——leeguoo.com · GitHub · X · 更多工具见 *-use 系列。