phoneuse-official/phoneuse
AI 工程在 Mac 上通过提示词、实时画面、REST 与 MCP 控制 USB 连接的 iPhone 的开源本地工具。
PhoneUse Local
PhoneUse Local 是一个实验性的开发者预览项目,用于从 Mac 控制 USB 连接的 iPhone。本地网页(localhost:3109)把提示词发给本地 Python API,API 通过 Codex CLI 决定下一步动作,再经 Appium 的 WebDriverAgent 在手机上执行。项目同时提供 REST API 和 MCP 服务器,供自己的脚本或 AI 智能体列出设备、截屏、读取屏幕元素、点击、输入以及打开和管理应用 source:1。
它面向愿意自行处理 Xcode 签名和有线连接、想在自己的硬件上试验手机操作智能体的开发者。仓库不附带托管手机、预签名 IPA 或生产基础设施;phoneuse.com 上的托管产品是另一套部署、另一套凭据 source:2。
快速使用
前提:装有完整 Xcode 的 macOS、一台被该 Xcode 支持且已解锁并信任此 Mac 的 iPhone、开发者模式、合法签名的 WebDriverAgentRunner、Python 3.13、Node.js 24+、npm、Git,以及已登录的 Codex CLI source:23。
- 在仓库目录运行
./"Install PhoneUse.command",它会创建 Python 环境、安装后端依赖并构建网页应用。 - 在 iPhone 上开启开发者模式;从 Appium 的 WebDriverAgent 仓库 获取 WDA,并按 Appium 真机配置说明 操作。在 Xcode 中选中
WebDriverAgentRunnertarget、选择签名团队、把 iPhone 设为运行目标,执行 Product → Test 并保持运行 source:26。 - 在终端运行
./platform/start-api.sh并保持窗口打开;访问http://127.0.0.1:8765/health应返回"ok":truesource:30。 - 打开第二个终端,运行
./"Start PhoneUse.command",它会带着 API key 打开http://localhost:3109/source:29。 - 在 Your iPhone 面板选择手机,等待画面持续变化。徽标显示 Ready 表示可以发送任务;View only 表示 WDA 不可达。
要使用提示词任务,先执行一次 codex login;如果 API 找不到 Codex CLI,用 PHONEUSE_CODEX_BIN="$(command -v codex)" ./platform/start-api.sh 重启 source:33。建议先用可逆提示,例如“Open Safari and describe the current screen. Do not submit anything.”。
接入代码与智能体
REST API 的交互文档在 http://127.0.0.1:8765/docs,每个请求都要带 Authorization: Bearer <key>。接入 MCP 客户端时,把启动命令设为仓库中 platform/start-mcp.sh 的绝对路径;MCP 提供手动手机控制,不依赖 Codex。Claude Code、Claude Desktop、Cursor、Codex 的现成配置和 REST 示例见 集成文档。脚本可用 create-key.py 生成限定设备的 key source:38。
使用约束与数据处理
- 仅支持 macOS;手机连接路径不支持 Windows 和 Linux。
- 需要 Xcode 签名和开发者模式,并保持 WDA 测试运行;PhoneUse 无法绕过 Apple 的签名步骤。
- 模型集成以 Codex CLI 0.154.0 验证;其结构化输出参数可能变化,模型访问受你自己的账号限制。
- 本地 API 和网页应用固定使用 8765 与 3109 端口;如果已有另一份 PhoneUse 占用这些端口,启动器会连到那份实例。
- API 能点击、输入、安装和删除应用、读取屏幕。它只监听回环地址并校验浏览器来源,非浏览器本地程序靠 bearer key 控制;key 保存在
platform/.state/admin-token,不要粘贴到 issue 或聊天中 source:36。 - 提示词任务会通过你的 Codex 登录把任务文本、屏幕文字和辅助功能数据发给模型提供方;只有勾选 Use screenshots if controls cannot be found 时才发送截图。这不是完全离线推理。
- 智能体会按明确指令行动,不是安全沙箱:它可能发消息、下单、删除数据或改设置。重要结果要在手机上核对。
- 只有图标或自绘控件的应用可能失败,因为没有可读取的文字或辅助功能标签。
- 源码采用 MIT 许可,依赖保留各自许可证 source:44。
HotRepo 点评
HotRepo 没有记录到该仓库的日榜名次或快照历史,因此无法据此讨论热度走势。材料显示的是演示背后确有实现:Python 后端、本地网页 UI、经 Codex CLI 的智能体循环、基于 WDA 的设备控制、MCP 入口,以及 CI 工作流和成体系的安装排错文档。比星数更重要的是定位是否诚实——这是需要 Xcode 签名和实时 WDA 会话的开发者预览,并明确说明智能体不是沙箱。它适合在自己的桌面上评估手机操作智能体的开发者,而不是寻找即插即用托管手机服务的用户。
本文由 AI 根据项目 README 生成,更新于 ,以项目官方文档为准。
相关推荐
- ZSeven-W/dsh-ios为编程 Agent 提供 22 个工具,在会话内启动、构建并操控 iOS 模拟器或 USB 真机,带可点拖的实时侧栏。
- JosssphZhou/poki让 Claude Code、Codex 等 MCP 客户端通过 Mac 操控真实 iPhone,无需越狱或额外硬件。
- zhongerxin/iPhone-use让 Codex、WorkBuddy 或豆包工作通过 USB 操作真实 iPhone,完成 App 自动化、屏幕预览与截图回退。
- phone-harness/mcp这是一个托管 MCP 服务,让 AI 智能体在云端操控真实 iPhone 和 Android 模拟器。
- lxe/phoneuse在 Linux 电脑上通过 AirPlay 镜像并操作未越狱的 iPhone,用蓝牙鼠标键盘或命令行控制它。