跳到主要内容
AI教程

使用 ESP32-S3 构建 AI 驱动的 iPhone 智能代理

了解如何刷写 ESP32-S3、使用 UxPlay 镜像 iPhone、连接兼容 OpenAI 的视觉模型、校准指针控制，并在无需 Xcode、开发者账户、越狱或在手机上安装应用的情况下运行自动化任务。

AI我搜编辑部阅读约 12 分钟
使用 ESP32-S3 构建 AI 驱动的 iPhone 智能代理

ESP32 iPhone Agent 的功能

ESP32 iPhone Agent 让 AI 模型能够查看并操作真实的 iPhone。它使用 AirPlay 屏幕镜像提供视觉输入，并使用一块价格低廉的 ESP32-S3 开发板作为 USB 鼠标和键盘。由于它通过屏幕和指针进行交互，因此不需要 Xcode、Apple 开发者帐户、越狱、开发者模式，也不需要在手机上安装辅助应用。

ESP32 iPhone Agent 界面和已连接的 iPhone

计算机可以运行 macOS 或 Linux。它负责运行 UxPlay、Python 服务器、Web 界面，以及连接到兼容 OpenAI 的视觉模型。ESP32-S3 通过 Wi-Fi 连接计算机，同时以标准 USB 人机接口设备的身份连接到 iPhone。

系统工作原理

AirPlay 提供视觉输入

iPhone 会将显示画面镜像到计算机上的 UxPlay。GStreamer 管道会将该视频流转换为 JPEG 帧，供 AI 代理和基于浏览器的实时视图共同使用。

ESP32-S3 提供操作能力

连接到 iPhone 后，开发板的行为类似 USB 鼠标和键盘。启用 iOS 辅助触控后，鼠标点击会变成轻点，指针拖动会变成滑动，滚轮可以滚动界面，键盘命令则可以输入文本或按下快捷键。

固件有意保持较少的逻辑。服务器通过 TCP 发送基于行的 move、click、scroll、type 和 key 等命令。开发板会返回 ok 或错误消息。

规划器和执行器提供智能

规划器模型根据请求的目标和当前屏幕生成简短计划。执行器模型检查每张新截图，并选择下一步操作，例如轻点、滑动、绘制路径、输入文字、按键、返回主屏幕或完成任务。同一个视觉模型可以同时承担这两个角色。

闭环检查提升可靠性

指针移动采用相对坐标，因此服务器会跟踪其估计位置。轻点前，服务器可以轻微晃动指针，在镜像图像中定位指针，修正偏移并改进校准。执行操作后，代理会检查屏幕是否发生变化。因此，未成功的操作可以被发现并重试，而不会成为后续步骤的依据。

系统还可以在重复执行操作后重新规划，并从连接断开或模型返回无效结果的情况中恢复。如果 Wi-Fi 连接断开，开发板会释放鼠标按键并自动重新连接。

主要功能

  • 无需 Apple 开发环境：不需要 Xcode、开发者帐户、代码签名、开发者模式或测试运行应用。
  • 广泛的应用兼容性：代理基于像素进行操作，而不依赖辅助功能树，因此可以适用于普通应用和游戏。
  • 支持 Mac 或 Linux 主机：服务器不局限于 macOS。
  • 灵活的模型支持：任何接受图像的兼容 OpenAI 的聊天 API 都可以使用。
  • 手动和自主控制：Web 界面支持直接轻点、滑动、滚动、输入文字、主屏幕、返回以及 AI 驱动的任务。
  • 可观察的执行过程：界面会显示手机实时画面、计划、日志、截图、操作、推理和计时信息。
  • 安全控制：紧急停止功能可以暂停代理并释放指针。

所需设备和条件

  • ESP32-S3 开发板：本项目使用裸板 Seeed Studio XIAO ESP32S3 进行了测试。如果另一块 ESP32-S3 开发板的 USB-C 端口连接到芯片的原生 USB 接口，也可以使用。
  • iPhone：USB-C 机型可以直接连接。Lightning 机型需要 Lightning 转 USB 相机转接器。
  • 计算机：一台与 iPhone 位于同一网络中的 macOS 或 Linux 计算机。
  • Wi-Fi：开发板配置需要 2.4 GHz 网络名称和密码。
  • 视觉模型：接受图像输入的云端或本地兼容 OpenAI 的端点。

iPhone 会为开发板供电。如果手机需要同时充电，请使用支持电力传输的 USB-C 集线器。

安装和配置代理

1. 克隆代码仓库

git clone https://github.com/onehumanbeing/esp32-iphone-agent.git
cd esp32-iphone-agent

2. 准备并刷写 ESP32-S3

安装 arduino-cli 和 3.x 版本的 ESP32 核心库。通过 USB 将 ESP32-S3 连接到计算机，复制示例密钥文件，然后编辑新文件。

cp hardware/hid_bridge/secrets.example.h hardware/hid_bridge/secrets.h

在 hardware/hid_bridge/secrets.h 中填写 2.4 GHz Wi-Fi 网络名称、Wi-Fi 密码，以及将运行服务器的计算机 IP 地址。然后刷写开发板：

hardware/flash.sh

刷写脚本可选接受串口和 --debug 标志。调试固件会通过 USB 串口回显命令及其持续时间。

3. 安装 UxPlay

在 macOS 上，使用 Homebrew 安装 UxPlay：

brew install uxplay

在 Debian 或 Ubuntu 上，安装 UxPlay 和所需的 GStreamer 软件包：

sudo apt install uxplay gstreamer1.0-plugins-good gstreamer1.0-plugins-bad gstreamer1.0-libav

4. 创建 Python 环境

进入服务器目录，创建虚拟环境并安装项目：

cd server
python3 -m venv .venv
.venv/bin/pip install -e .

需要 Python 3.10 或更高版本。

5. 配置模型

复制环境模板：

cp .env.example .env

编辑 server/.env，至少设置兼容 OpenAI 的端点、模型名称和 API 密钥：

LLM_BASE_URL=https://your-endpoint.example/v1
LLM_MODEL=your-vision-model
LLM_API_KEY=your-api-key

所选模型必须支持图像。使用云端 API 即可；运行本地模型是可选的。

6. 启动服务器

set -a && . ./.env && set +a && .venv/bin/python -m hidagent

在浏览器中打开 http://<computer-ip>:8890。计算机 IP 必须能从电路板所连接的网络访问。

设置 iPhone

以下手机配置通常只需执行一次：

  1. 打开设置，然后依次进入辅助功能、触控和辅助触控。
  2. 开启辅助触控。
  3. 断开已刷写电路板与计算机的连接，然后将其插入 iPhone。
  4. 确认出现圆形指针，并且网页显示控制器已连接。
  5. 在 iPhone 上打开控制中心，然后选择屏幕镜像。
  6. 选择 iPhone Agent。手机实时画面应显示在网页界面中。
  7. 在网页界面中打开手动控制，然后选择校准。
  8. 在实时画面中准确点击可见指针。

如果之后更改了辅助触控的跟踪速度，请重新校准。

运行第一个任务

在网页界面中输入目标，然后按开始。例如：

Open Settings and go to Wi-Fi

规划器会创建一个简短计划，执行器则会反复检查当前截图并选择操作。任务运行期间，请查看手机实时画面和日志。

步骤墙会记录每次决策所使用的截图，还会在图像上绘制选定的点击或滑动操作，并显示模型的推理过程和耗时。选择步骤卡片可打开更大的视图。

使用手动控制

  • 点击手机实时图像，即可在相应位置点击。
  • 在图像上拖动即可执行滑动。
  • 使用滚动输入来滚动手机画面。
  • 使用提供的控件执行主屏幕、返回、文本输入和按键操作。

如果代理行为异常，请激活紧急停止或按下 Esc。这会停止运行并释放指针。界面还提供了清除执行历史的控件。

重要配置选项

  • LLM_BASE_URL：兼容 OpenAI 的端点。默认值为 http://localhost:8000/v1。
  • LLM_MODEL 和 LLM_API_KEY：模型名称和 API 凭据。
  • LLM_EXTRA_BODY：合并到每次模型请求中的 JSON，例如用于禁用模型思考模式的设置。
  • ACTOR_* 和 PLANNER_*：针对相应 LLM_* 设置的角色专属覆盖项。
  • AIRPLAY_NAME：iPhone 屏幕镜像列表中显示的接收器名称。默认值为 iPhone Agent。
  • PORT：网页界面端口，默认为 8890。
  • DEVICE_PORT：ESP32-S3 使用的端口，默认为 7300。
  • HIDAGENT_DATA：校准和跟踪目录，默认为 ~/.hidagent。
  • HIDAGENT_DEBUG：设置为 1 时启用服务器端调试日志。

高级用法与故障排除

为规划器和执行器分配不同模型

规划器和执行器可以使用同一个模型，但通过角色专属环境变量可以分别覆盖模型设置。需要使用不同端点或模型时，请使用相关 LLM_* 变量对应的 PLANNER_* 和 ACTOR_* 形式。

连接本地模型服务器

任何配备视觉模型的兼容 OpenAI 服务器都可以采用相同方式配置，包括 vLLM、SGLang、llama.cpp 和 Ollama。该项目使用两台通过张量并行提供 NVIDIA Qwen3.8-Flash-Next-NVFP4 的 NVIDIA DGX Sparks 进行开发和计时。

该配置的示例为：

LLM_BASE_URL=http://<dgx-spark-ip>:8888/v1
LLM_MODEL=Qwen3.8-Flash-Next
LLM_EXTRA_BODY='{"chat_template_kwargs": {"enable_thinking": false}}'

在禁用思考模式的情况下，报告的开发配置每次操作约需 1.3 秒，每次规划约需 2 秒。这些数据仅描述特定的硬件和模型配置，并不保证其他部署具有相同速度。

启用跟踪收集

在 server/.env 中设置以下值：

HIDAGENT_DEBUG=1

调试模式会记录每条电路板命令及其延迟，还会在 ~/.hidagent/traces/ 下为每次代理运行创建一个目录。该目录包含 steps.jsonl，其中记录模型提示词、原始回复、延迟测量值和操作，以及模型调用所看到的截图。

了解电路板协议

  • ping 执行健康检查。
  • home 将指针移至左上角，以建立已知位置。
  • move <dx> <dy> 以恒定速度相对移动指针。
  • press、release 和 click 控制鼠标左键。
  • scroll <v> <h> 发送垂直和水平滚轮输入。
  • type <text> 输入 ASCII 文本。
  • key <combo> 发送按键或组合键，例如 enter、cmd+h 或 cmd+space。

解决 Linux 上的 AirPlay 发现问题

如果计算机有多个网络接口，而 iPhone 未列出接收器，请将 Avahi mDNS 广播限制到连接手机所在网络的接口。

已知限制

  • iOS 不会镜像密码输入、Apple Pay、受 DRM 保护的视频以及其他一些受保护的屏幕，因此代理无法看到这些内容。
  • 手机锁定后，屏幕镜像会停止。代理运行期间请禁用自动锁定。
  • 键盘文本输入仅限 ASCII。
  • 更改辅助触控跟踪速度后，必须重新进行指针校准。
  • 代理依赖开发板与服务器之间可用的网络路径，以及手机与计算机之间可用的 AirPlay 流。

负责任地操作

仅自动化操作你拥有或获授权使用的设备和账户，并遵守相关应用的条款。

由于代理可以执行与人类相同类型的输入操作，请监督正在运行的任务，并确保紧急停止功能始终可用。

结语

ESP32 iPhone Agent 结合了 AirPlay 镜像、低成本 ESP32-S3 USB HID 桥接器和兼容 OpenAI 的视觉模型，无需 Apple 传统开发工具链即可自动操作实体 iPhone。配置好固件、服务器、模型端点、辅助触控、镜像和指针校准后，你可以发出自然语言目标，检查每项决策，手动介入，并收集详细跟踪记录以进行调试。