开始

安装 iphone-use

在插着 iPhone 的那台 Mac 上跑一条命令。安装脚本会把手机配好，让 agent 操作一遍给你看，在你的 agent 里注册好 MCP server，再在浏览器里打开控制页。缺什么会直接告诉你缺什么、怎么补。

需要准备

一台 macOS 15 以上的 Mac，装好完整的 Xcode.app（只有命令行工具不够），在 Xcode → 设置 → Accounts 里登录 Apple ID 并选好开发团队。免费的 Personal Team 可以用，但它的 runner 描述文件需要定期续签。也可以用 App Store Connect API key（IPU_RUNNER_ASC_KEY_PATH、IPU_RUNNER_ASC_KEY_ID、IPU_RUNNER_ASC_ISSUER_ID）签名，不用 Xcode 账号。
一台 iOS 15 及以上的 iPhone，打开开发者模式（设置 → 隐私与安全性 → 开发者模式），并通过 USB 和这台 Mac 配对、信任。
第一次配置需要一根数据线。安装前把 iPhone 插上并解锁。构建、启动和使用 runner 时手机要保持解锁和亮屏；Face ID 和锁屏密码它过不去。
不需要 Homebrew 包。只有从源码构建时才需要 Rust 工具链。

⚠️ iOS 15 和 16

这些手机不用升级系统，但从 Xcode 26 起 Xcode 看不到它们，所以 setup 会走自己的旧系统路径。这条路径需要 付费开发者账号的 App Store Connect API key；没有的话 setup 会停在 ios_too_old 并说明原因。 iOS 14 及更早的系统低于 runner 的最低要求。

安装

bash

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

安装脚本做了什么

下载最新的 GitHub Release，注册当前用户的 LaunchAgent，安装配套的 agent skill，把设备 runner 的源码放到 ~/.iphone-use/runner，并把 iphone-use 命令链接到 ~/.local/bin。
插着 iPhone 时，接着运行 iphone-use setup（构建、签名、安装并启动 runner，启动转发）和 iphone-use try（打开设置、读屏、回桌面），安装结束前你就能看到 agent 操作手机。
在 Claude Code 和 Codex 里注册 MCP server，装了 Cursor 和 Claude Desktop 的话也一并注册（IPHONE_USE_NO_CLIENT_SETUP=1 跳过这两个）。server 从 LaunchAgent 读取守护进程地址和令牌，客户端配置里不会留下密钥。
用一次性登录链接在浏览器里打开控制页，并打印一个 iPhone 相机能扫的二维码，谁都不用抄密码。

--no-setup（或 IPHONE_USE_NO_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 就真的卸载）

✅ setup 报 “No Accounts”？

打开报错里给出的 runner 工程（通常是 ~/.iphone-use/runner/IPhoneUseRunner/IPhoneUseRunner.xcodeproj），选中 IPhoneUseRunner scheme 和你的 iPhone，执行一次 Product → Build For → Testing。提示访问钥匙串时允许，让 Xcode 生成签名证书和描述文件，然后重新运行 setup。

或者让 agent 帮你装

在插着 iPhone 的那台 Mac 上，把下面这段贴给 Codex 或 Claude Code：

提示词

在这台 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，但仍需先完成上面的安装。

Codex

$ 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

其他 MCP 客户端（Cursor、VS Code、Claude Desktop、Gemini CLI、opencode、Windsurf）和 HTTP 接口见 MCP、HTTP API 与 skill。

升级

bash

$ iphone-use upgrade            # 安装最新版本（守护进程 + skill）
$ iphone-use upgrade --check    # 什么都不改，只报告

自动升级默认开启，并且只在手机空闲时进行。每天 04:30 有一个任务检查新版本，只有没人在用那台手机时才升级：没有 owner 租约、没有 hold、没有人在看实时画面，最近 15 分钟也没有 agent 请求。手机忙的话就等到第二天。升级用的是该版本自己的 install.sh，带 SHA-256 校验和回滚，所有设置都会保留。

bash

$ ~/.iphone-use/auto-update.sh disable    # 关闭，重装后也保持关闭
$ ~/.iphone-use/auto-update.sh status     # 开没开、现在会做什么、上次结果

第二台手机

一个守护进程只驱动一台手机。要同时驱动另一台 iPhone，就为它装一个命名实例，默认安装保持不动。实例有自己的一份 App、状态目录、令牌和端口。

bash

$ curl -fsSL https://raw.githubusercontent.com/leeguooooo/iphone-use/main/install.sh | sh -s -- --instance lab --udid <UDID>
$ iphone-use setup --instance lab

手边没有手机：模拟器（预览）

runner 也能跑在 iOS 模拟器上，不需要手机、Apple ID 和签名，只要装了带模拟器运行时的 Xcode。

bash

$ iphone-use simulator start "iPhone 16 Pro"
$ claude mcp add iphone-sim -e IPHONE_USE_INSTANCE=sim -- iphone-use-mcp

模拟器没有相机、App Store 应用、真实推送和 Face ID，需要这些的任务只能在真机上做。

iOS App

iOS App 不在 App Store 上架。用你自己的签名团队（就是 setup 给 runner 用的那个）构建并安装：

bash

$ iphone-use setup-app   # 第二台手机加 --instance <名字>

免费 Apple ID：遥控版 App。操作由 Mac 托管的手机，在 Mac 网页上扫码配对。
付费开发者团队：完整版 App，支持本机控制。手机自己就能提供点击、输入、读屏和 agent 接口，运行时不需要 Mac（iOS 17.4 及以上）。第一次配对仍需要插一次数据线。

下一步：可以让 agent 做什么，或者它怎么工作。