ESP32 Agent
装好 ESP32 iPhone Agent，关键在于选对板子、用对线，再调几个 iPhone 设置
ESP32 iPhone Agent 装不上的问题，多数出在硬件：ESP32 型号买错、线只能充电，或者手机不达标。这一页讲该买什么、怎么刷、怎么连，以及出问题时先查哪里。
怎么挑板子
测过的板子是 Seeed Studio XIAO ESP32S3 标准版，8 MB 闪存、8 MB PSRAM，约 40 元。Sense 和 Plus 不是被测过的那块，买标准版。
| 板子 | 状态 |
|---|---|
| XIAO ESP32S3（标准版，8 MB 闪存、8 MB PSRAM） | 已测试并支持 |
| 其他带原生 USB、至少 8 MB 闪存和 8 MB PSRAM 的 ESP32-S3 板子 | 应该能用，未测试 |
| 用 CH340 或 CP2102 串口芯片的 ESP32-S3 板子 | 不支持 |
| ESP32-C3、ESP32-C6、ESP32-S2、初代 ESP32 | 不支持 |
手机和线材要求
- iPhone XS 或更新机型，iOS 18 或更高版本。
- 蜂窝数据。板子的热点没有外网，手机连着它的时候，模型要走蜂窝数据。
- 一根短的 USB-C 转 USB-C 数据线，约 30 厘米。只能充电的线不行，这也是「板子像坏了」最常见的原因。
- Lightning 机型要在手机和线之间加一个 Lightning 转 USB 相机转换器。
板子由手机供电，不涉及电池或单独的充电器。
安装步骤
- 刷固件。把板子接到电脑上，用 Chrome 或 Edge 打开安装页，在浏览器里刷。iPhone 刷不了板子。
- 装 App。从 TestFlight 装 ESP32 Agent App，那里是公开测试版。自己编译的话需要一台装了 Xcode 的 Mac，只需要一次，运行时不需要。
- 把板子插到 iPhone 上。用那根数据线，Lightning 机型再加上相机转换器。
- 打开「辅助触控」。板子相当于鼠标；打开之后，点击是轻点，拖动是滑动。
- 连热点。板子会开一个自己的 Wi-Fi，让 iPhone 连上去。
- 开屏幕镜像。打开控制中心，点「屏幕镜像」，选 ESP32 Agent。
- 给它一个大脑。要么在 App 里配任意兼容 OpenAI 接口的视觉模型，要么在电脑上用 npx -y esp32agent 装 Handsy CLI，从电脑上操作手机。
按症状排查
刷机时找不到板子
确认用的是电脑上的 Chrome 或 Edge，线能传数据。先换线，再查别的。确认板子是带原生 USB 的 ESP32-S3，不是 CH340 或 CP2102 的那种。
「屏幕镜像」里没有 ESP32 Agent
板子得由手机供电，手机得连着板子的热点。板子要是不上电，先怀疑线，Lightning 机型怀疑转换器。
有画面但点不动
多半是「辅助触控」没开。不开的话，iPhone 不会把鼠标点击变成轻点。
点按位置稍微偏一点
USB 指针是相对的。App 会跟踪它、把它归位到角落，精确点按之前先晃一下、在屏幕上找到它再修正偏差。小的偏差是正常的，会自动纠正。
模型连不上
连着板子热点时手机没有 Wi-Fi 外网。确认蜂窝数据开着，并且允许这个 App 使用。
跑到一半停了
板子、热点或镜像链路断了，运行会暂停，链路恢复后从同一步继续。手机锁屏也会让镜像停，解锁后继续。
某个界面对 Agent 是黑的
iOS 不镜像密码输入、Apple Pay 和 DRM 视频。这是 iOS 的规矩，不是故障。
带重音符号或 emoji 的字打不出来
键盘输入只支持 ASCII。
已知性能上限
蓝牙 LE 大约 300–500 kbps，所以镜像画面是 480×1040、最高 5 fps，每一步要几秒，大部分时间花在模型上。横屏 App 目前不支持。
查运行过程
每次运行都存在手机上，可以逐步回放。要把一次运行附到问题报告里，进「运行」，打开这次运行，点 ⋯，选「导出轨迹」。源码在 GitHub，MIT 许可，固件里的 AirPlay 接收器为 GPL-3.0。