README

ESP32 iPhone Agent


  你的 AI 看着 iPhone 屏幕，替你点、滑、打字；
  靠的是一块插在手机上、约 40 多元的 ESP32 小板子。不需要电脑，也不用改动 iOS 系统。



  在 TestFlight 上试用 ·
  在浏览器里烧录固件 ·
  不是开发者？ ·
  看演示 ·
  文档 ·
  更新记录



  
  
  
  
  


媒体报道 Hackaday · Digital Trends · 阮一峰《科技爱好者周刊》415 · Seeed Studio 官方推荐

English · 简体中文

关注更新：X @iamhenryyuan · 小红书 袁老板讲黑客松（Henry） · YouTube 演示 · DeepSeek Harness 演示 · handsy.tech


  
  一台真 iPhone 自己做完一节多邻国课程，8 倍速，全程没人碰屏幕。


基于本项目开发？请保留 LICENSE，并在你的 README 和帖子中注明 ESP32 iPhone Agent by Henry Yuan。详见 NOTICE。

 最近更新



- 能听到手机的声音。 板子转发 AirPlay 音频，iPhone 本机转成文字，听力题、语音提示都能处理。原理。
- 免费的 Jev 线路。 简单的步骤 Jev 不到一秒就做完，其余交给大模型；Agent loop 也重做了，每步只调一次模型。
- 长任务。 不再 40 步就停，停下的任务可以接着跑；每次运行都能在手机上逐步回放。

在 TestFlight 安装（App Store 版本审核中）。需要板子固件 v0.2.4。完整更新记录。

 为什么用一块板子

大多数 iPhone Agent 都跑在电脑上：第一次用之前要装 Xcode、打开开发者模式、用数据线配对手机、在终端里敲命令；之后每次运行，电脑都得开着、连着。开发者能忍，普通人基本卡在第一步。这里由板子替代电脑，有手机就够了。

| | ESP32 iPhone Agent | 依赖电脑的方案WebDriverAgent、CoreDevice、idevice |
|---|---|---|
| 需要什么 | 一台 iPhone + 一块 7 美元的板子 | 一台 Mac（通常要较新的 macOS）、完整的 Xcode、开发工具链 |
| 怎么装 | 浏览器里烧录固件，TestFlight 装 App，App 里跟着四步走 | 终端里克隆、编译、装依赖、给辅助 App 签名 |
| iPhone 上要改什么 | 打开辅助触控（App 会一步步带你开） | 开发者模式、USB 信任和配对 |
| 运行时 | 只要手机，带到哪都能用 | 电脑要一直开着、连着 |
| 能用哪些 App | 人能用的都能用：它看屏幕、移动指针 | 调试接口和无障碍接口能拿到的部分 |
| 能听到手机的声音 | 能（App 1.0.2） | 通常不能 |

实话说代价也有：要买一块 7 美元的板子；每一步要几秒，大部分时间花在模型上；运行时手机的 Wi-Fi 被板子热点占用，要用蜂窝数据。

 不是开发者？从这里开始

1. 买板子。 Seeed XIAO ESP32S3，约 40 多元：买什么。
2. 在 Chrome 或 Edge 里烧录固件。 不用装任何工具：handsy.tech/zh/install。
3. 安装 App，跟着四步设置走。 TestFlight ·
   带图的设置指南。

遇到问题？看常见问题排查，或发邮件到 [email protected]。

 [!NOTE]
 免费线路繁忙或报错？ 免费模型线路是大家共用的，有时会繁忙或暂时报错（HTTP 503），任务可能卡住、或每一步都失败。
 这时可以在「设置 › 模型」里换成你自己的 API key 继续用，也欢迎在 X 上告诉作者：@iamhenryyuan。

 工作原理

第一次接触？先看让 AI 操控 iPhone，再看 Handsy 工作原理。


iPhone ──屏幕镜像（Wi-Fi）──▶ ESP32-S3：AirPlay 接收端 ──Wi-Fi TCP :7201──▶ ESP32 Agent App（同一台 iPhone）
   ▲                           自带热点，H.264 原样转发                    解码 → 视觉模型 → 动作
   └──────── USB HID 鼠标 + 键盘 ◀──────────── 蓝牙命令 ◀────────────────────┘


- 眼睛：AirPlay 投到板子上。 板子开自己的 Wi-Fi 热点，在手机的「屏幕镜像」里显示为 ESP32 Agent。它不解码，只把 H.264 码流经 Wi-Fi（TCP，端口 7201）转给 App。蓝牙传命令和状态。手机连着板子热点时，调用模型走蜂窝数据。
- 手：USB HID。 板子是标准 USB 鼠标和键盘。打开辅助触控（AssistiveTouch）后，鼠标控制屏幕上的指针，点击就是轻点，拖动就是滑动。
- 大脑：App。 App 解码画面，把截图发给任意兼容 OpenAI 接口的视觉模型，由规划器和执行器决定动作：点、滑、画、输入、按键、回主屏、结束。工作时 App 在后台运行，灵动岛显示它在做什么。
- 闭环。 指针是相对移动的，App 记录位置并定期回角落归零；精细点击前晃一下指针、在画面里找到它并修正偏差。每个动作后等画面稳定，再告诉模型画面有没有变化。板子、热点或镜像断开时暂停，恢复后从同一步继续。
- 复盘。 每次运行都存在手机上，可以逐步回放，点按和滑动画在截图上。



左：真机；右：Agent 通过板子的 AirPlay 镜像看到的画面。第二张是指针校准。

最初的版本（v0.1.0）用 Mac/Linux 电脑跑 UxPlay + Python 服务端，保留在 tag v0.1.0
和分支 legacy，见 docs/legacy.md。

 硬件

支持的板子和硬件细节见硬件指南。选板子、线材和转接头，或者设置时卡住了，见安装设置指南。

| 部件 | 说明 |
|---|---|
| ESP32-S3 板子 | 测试用的是 Seeed Studio XIAO ESP32S3（普通版，8 MB PSRAM；不是 Sense，也不是 Plus），淘宝搜 "XIAO ESP32S3"，约 40-50 元；海外可在 Amazon\ 购买。USB-C 口接 S3 原生 USB、带 PSRAM 的 ESP32-S3 板子都应该可以。 |
| USB-C 线 | 短的 USB-C 对 USB-C 线，例如 Anker 60W，1 英尺，2 条装\。 |
| iPhone | iOS 18 及以上，需要蜂窝数据（Wi-Fi 被板子热点占用）。USB-C 机型直接插；Lightning 机型需要 Lightning 转 USB 相机转换器。板子由手机供电。 |
| 视觉模型 | 任何支持图片输入

Top issues

Latest release

esp32agent CLI 0.1.4. Install: see cli/README.md.