开源 · 真实 iPhone
给 Agent
一个身体。
让 Codex 和 Claude Code 看见并操作你的 iPhone。
读取屏幕，使用真实 App，确认操作结果。通过 Mac 上的 Swift CLI 完成。
你的 Mac，你的 iPhone，你选择的 Agent。
接入你正在使用的工具。
- Codex
- Claude Code
- macOS + iPhone
- MIT 许可证
用证据
确认任务完成。
计算 125 × 8，重新连接后，在计算器历史记录中核对保存的结果。
- 先看当前界面。发现 App，读取截图与无障碍树。
- 再选择下一步。使用当前引用点击计算器按键，并保留画面校验。
- 核对保存的结果。读取屏幕上的 1,000，重新连接并打开历史记录，确认同一笔计算。
这是一次 CLI 任务记录。下方的首个任务用于检查客户端插件的“设置”操作流程。
简单操作，串起真实 App 工作流。
- 观察
- Apple PNG 截图；可选 Runner 无障碍快照。
- observe · inspect
- 操作
- 发现并打开 App，点击、滑动、拖动和编辑文字。
- apps · open · tap · swipe · type · press
- 验证
- 区分输入已完成、被拒绝或结果不确定。观察后再决定下一步。
- completed · not_dispatched · unknown
当前支持：真实 iPhone。 选择标准截图/HID 控制或可选 XCTest Runner。当前版本通过 CLI 操作。
从安装到首个任务。
使用已有的 Codex 或 Claude Code 账号。iPhone-use 采用 MIT 许可证。
开始前：Mac、iPhone 与 Xcode
标准模式需要 Apple Silicon、macOS 27 / iOS 27 和 完整 Xcode，以及已信任、通过 USB 连接且开启开发者模式的 iPhone。仅 Runner 模式需要开发签名和 setup。
0.2.1 已通过安装包检查；此前候选真机证据覆盖 iPhone 12 Pro / iOS 27.0.1。全新 Mac 与免费 Personal Team 配置仍未验收。 查看前置条件.
-
1. 安装 CLI。
在 Mac 终端中执行：
brew install HughLee824/tap/iphone-use iphone-use --version从 AgentSoma 迁移？请先卸载旧 agentsoma formula，再安装 iphone-use。本机签名资料会保留。
希望手动下载？请阅读 手动安装指南。请保留完整的 CLI 与 Runner 发布包。
-
2. 安装客户端插件。
Codex
在终端执行，然后开始新的 Codex 任务：
codex plugin marketplace add HughLee824/iphone-use codex plugin add iphone-use@iphone-use需要客户端版本支持
codex plugin。命令已在 CLI 0.146.0 上核对。在新任务中调用$iphone-use:iphone-use。Claude Code
在终端执行，然后开始新的 Claude Code 会话：
claude plugin marketplace add HughLee824/iphone-use claude plugin install iphone-use@iphone-use调用
/iphone-use:iphone-use并开始新会话。插件提供设备操作说明；CLI 和 Xcode 需单独安装。通过项目自有 Git marketplace 分发。 安装与升级.
-
3. 准备 iPhone。
连接手机，信任 Mac，开启开发者模式并保持解锁。复制以下命令返回的设备 ID：
devices:iphone-use devices export IOS_UDID='YOUR_DEVICE_ID' iphone-use config set mode standardsetup仅用于通过自己的开发签名准备 Runner 模式。标准模式采用 Apple PNG 与原生 HID，不启动 Runner。 模式与签名指南. -
4. 交给 Agent 首个任务。
在新的客户端会话中调用技能，然后发送：
打开我的 iPhone 设置，进入“通用”，读取截图确认页面，然后断开会话。不要修改任何设置。
Agent 读取“通用”截图、确认页面并报告正常断开后，任务才算完成。单次点击成功不代表任务完成。
阅读首个任务指南