文档总览
从零搭建你的 iPhone Agent
从准备开发板到发出第一条指令，按顺序完成搭建。
ESP32 iPhone Agent 通过一块 ESP32-S3，让视觉模型操作真实的 iPhone。当前版本的 Agent 运行在手机 App 中，执行任务时不需要电脑；首次安装仍需要 Mac 和 Xcode。
开始前准备什么
- 带 PSRAM 和原生 USB 的 ESP32-S3。项目实际测试的是普通版 Seeed Studio XIAO ESP32S3，配备 8 MB PSRAM。
- 运行 iOS 18 或更新版本的 iPhone，并能使用蜂窝数据。Lightning 机型还需要 Lightning 转 USB 相机转换器。
- 装有 Xcode 的 Mac，以及用于给 App 签名的 Apple ID。
- 支持图片输入的模型接口，兼容 OpenAI 风格的 Chat API。
手机的 Wi-Fi 会用于连接板子热点、传输投屏，模型请求则走蜂窝数据。购买硬件前，先核对设备要求。
1. 获取项目代码
克隆仓库并进入项目目录。除非另有说明，后面的命令都在该目录执行。
git clone https://github.com/onehumanbeing/esp32-iphone-agent.git
cd esp32-iphone-agent本文针对当前的「iPhone App + ESP32-S3」架构。legacy 分支和 v0.1.0 标签使用电脑端服务，不能混用两套安装步骤。
2. 刷写开发板
准备 arduino-cli、ESP32 3.3.x 开发板支持包和 NimBLE-Arduino 2.5.1，用数据线将板子连接到 Mac，再执行项目提供的脚本：
arduino-cli lib install "[email protected]"
hardware/flash.sh支持包安装、串口选择和恢复方法见固件刷写指南。请使用 hardware/flash.sh，它会带上视频传输所需的蓝牙缓冲区设置。
3. 安装 iPhone App
复制本地配置文件，在新文件中填写你的签名团队和独立的 Bundle ID：
cp ios/Config/Local.xcconfig.example ios/Config/Local.xcconfig
open ios/IPhoneAgent.xcodeproj在 Xcode 中选择 IPhoneAgent scheme 和已连接的 iPhone，然后编译运行。免费 Apple ID 可以签名，但每七天需要重新签名。免费账号的可选权限配置也需要处理，完整步骤见安装 iOS App。
4. 完成 App 的四项设置
把板子从 Mac 拔下，接到 iPhone，打开 ESP32 Agent。首次设置会依次检查：
- Plug Me In：发现板子并完成蓝牙配对。
- Let Me See the Screen：加入板子热点，在「控制中心 → 屏幕镜像」中选择 ESP32 Agent。
- Let Me Use the Pointer：开启辅助触控，让 App 自动校准指针。
- Give Me a Brain：填写模型地址、API key 和支持图片输入的模型名称。
每一步的操作见连接设备与投屏，模型设置见配置视觉模型。App 的具体文字可能随版本和界面语言变化，这里保留英文步骤名方便对照。
5. 发出一个容易验证的任务
先试试「打开设置，进入无线局域网」。如果模型或手机的英文界面识别更稳定，也可以用 “Open Settings and go to Wi-Fi”。点 Start，保持手机解锁并观察操作。需要停止时，可使用支持设备上的灵动岛入口，或回到 App 停止。
先选不需要输入中文的任务。目前键盘只支持 ASCII，能用中文描述任务不代表可以直接在其他 App 中输入中文。
确认是否真的完成
打开 Runs 回放每一步，并亲自检查最后的页面。模型说「完成」不等于任务已经成功。需要分析错误时，可以导出运行记录。
如果卡在某个设置步骤，按排障指南检查相应连接，不必每次都重新刷板或重装 App。