ESP32 iPhone Agent .env 配置项全解析:从 LLM_BASE_URL 到 ACTOR/PLANNER 双模型独立配置的完整指南
ESP32 iPhone Agent .env 配置项全解析:从 LLM_BASE_URL 到 ACTOR/PLANNER 双模型独立配置的完整指南
ESP32 iPhone Agent 是一个让 AI 模型"真机操作 iPhone"的开源项目:用 AirPlay 做眼睛、$7 的 ESP32-S3 做手,接任意 OpenAI 兼容的视觉模型做大脑。整个项目的"大脑"由 server/.env 配置文件驱动——从 LLM_BASE_URL 指向的模型服务,到 ACTOR/PLANNER 双模型独立配置,全部在这一个小文件里搞定。本文将逐项解析每个配置项的含义、默认值和常见坑位,帮你一次配通。
一、先搞懂架构:.env 配置的是谁
在动手改配置之前,花 30 秒理解一下项目架构,配置项的意义就清楚了:
| 角色 | 由谁承担 | 对应配置 |
|---|---|---|
| 👀 眼睛 | UxPlay 通过 AirPlay 镜像手机屏幕 | AIRPLAY_NAME |
| 🖐️ 手 | ESP32-S3 伪装成 USB 鼠标/键盘 | DEVICE_PORT |
| 🧠 大脑 | Planner(写计划)+ Actor(选动作)两个模型 | LLM_*、ACTOR_*、PLANNER_* |
.env 文件放在 server/ 目录下。首次使用先复制模板,再在启动前加载环境变量:
cd server
cp .env.example .env
# 启动前必须先加载 .env,服务才会读到这些变量
set -a && . ./.env && set +a && .venv/bin/python -m hidagent
💡 一个常见坑:直接
python -m hidagent而不先. ./.env,所有LLM_*变量都会回落到默认值,模型请求会直接失败。
二、核心配置:LLM_* 四件套
这是 .env 中最关键的部分,决定了 Agent 用什么"大脑"。完整模板见 server/.env.example。
| 变量 | 默认值 | 含义 |
|---|---|---|
LLM_BASE_URL |
http://localhost:8000/v1 |
OpenAI 兼容的 API 端点 |
LLM_MODEL |
— | 模型名称(必须支持视觉/图片输入) |
LLM_API_KEY |
— | API 密钥,本地部署可留空 |
LLM_EXTRA_BODY |
{} |
合并进每次请求的 JSON(例如关闭思考模式) |
LLM_TOKEN_PARAM |
auto |
token 上限字段名,见下文 |
2.1 LLM_BASE_URL:模型服务在哪
指向任意 OpenAI 兼容的 chat/completions 端点,末尾要带 /v1:
# 云端 API
LLM_BASE_URL=https://api.openai.com/v1
# 本地部署(vLLM / SGLang / llama.cpp / Ollama 等)
LLM_BASE_URL=http://localhost:8000/v1
2.2 LLM_EXTRA_BODY:给模型"加料"
这个字段以 JSON 形式合并进每次请求体,最典型的用途是关闭模型的思考模式,让回复更短更快:
# Qwen3.8 系列实测配置:约 1.3 秒/动作、2 秒/计划
LLM_BASE_URL=http://<dgx-spark-ip>:8888/v1
LLM_MODEL=Qwen3.8-Flash-Next
LLM_EXTRA_BODY='{"chat_template_kwargs": {"enable_thinking": false}}'
2.3 LLM_TOKEN_PARAM:token 限制字段自动检测
新版的 OpenAI 模型把 max_tokens 换成了 max_completion_tokens。默认 auto 模式下,客户端会先发 max_tokens,如果服务端返回 400 并提示新字段名,就自动切换并重试一次(实现见 server/hidagent/llm.py)。一般不用手动设置,除非你的服务端对 400 有别的语义。
三、进阶玩法:ACTOR/PLANNER 双模型独立配置
这个项目的大脑不是单一模型,而是两个角色:
- Planner(规划者):根据目标和当前屏幕写一份简短的计划,并在卡住时修复计划
- Actor(执行者):每次看一眼新截图,选出下一个动作——点击、滑动、输入、回家键或结束
两个角色默认共用同一套 LLM_* 配置。但在 server/hidagent/app.py 中,Agent 分别用 LLM.from_env("ACTOR") 和 LLM.from_env("PLANNER") 初始化,加载逻辑在 server/hidagent/llm.py:
任何
LLM_*变量都可以用ACTOR_*或PLANNER_*单独覆盖,只改一个角色的模型,另一个保持默认。
典型场景:让 Actor 用快而便宜的小模型(它每秒都要决策),Planner 用更强的大模型(计划质量决定成败):
# 共享配置
LLM_BASE_URL=http://localhost:8000/v1
LLM_MODEL=gpt-4o-mini
# 只把 Planner 换成更强模型
PLANNER_MODEL=Qwen3.8-Flash-Next
# 或者让 Actor 走另一个更快的本地端点
ACTOR_BASE_URL=http://192.168.31.100:8088/v1
ACTOR_MODEL=Qwen3.8-Flash-Next
可覆盖的字段与 LLM_* 一一对应:BASE_URL、MODEL、API_KEY、EXTRA_BODY、TOKEN_PARAM。
上图中右上角的 DESIGN/PLANNER 和 ACTION/ACTOR 面板会实时显示两个角色实际加载的模型名,是验证双模型配置是否生效的最快方式。
四、其余配置项:端口、设备与调试
| 变量 | 默认值 | 含义 |
|---|---|---|
AIRPLAY_NAME |
iPhone Agent |
手机"屏幕镜像"列表里的接收器名称 |
PORT |
8890 |
Web UI 端口 |
HOST |
0.0.0.0 |
服务监听地址 |
DEVICE_PORT |
7300 |
ESP32 板子连过来的 TCP 端口 |
HIDAGENT_DATA |
~/.hidagent |
标定数据与调试 trace 的存放目录 |
HIDAGENT_DEBUG |
0 |
设为 1 开启调试模式 |
几个实用细节:
- 改了
AIRPLAY_NAME:手机端"控制中心 → 屏幕镜像"里显示的名字会变,找不到接收器时先检查这里; - 端口冲突:
PORT被占用时改一个即可,但DEVICE_PORT要同步记录——ESP32 固件烧录时板子连的是这个端口; - 调试模式:
HIDAGENT_DEBUG=1会为每次 Agent 运行生成一个 trace 文件夹(在HIDAGENT_DATA下),保存每次模型调用的提示词、原始回复、延迟和对应截图,排查"模型为什么点这里"时极其有用。
五、两份可直接抄的配置示例
示例 A:云端 API(最简单)
LLM_BASE_URL=https://api.openai.com/v1
LLM_MODEL=gpt-4o-mini
LLM_API_KEY=sk-xxxx
LLM_EXTRA_BODY='{}'
示例 B:全本地部署(隐私优先)
LLM_BASE_URL=http://localhost:8000/v1
LLM_MODEL=Qwen3.8-Flash-Next
LLM_API_KEY=
LLM_EXTRA_BODY='{"chat_template_kwargs": {"enable_thinking": false}}'
配通之后,一句"Set an alarm for 7:00 AM that repeats every day"就能让 Agent 自主打开时钟、拨时间滚轮、勾选重复日并保存——上图中每一步的截图、推理和耗时都在 Web UI 的 Step Wall 里可见。
六、常见坑位速查
| 现象 | 大概率原因 | 处理 |
|---|---|---|
| 启动后模型请求 401/404 | LLM_API_KEY 没填或 LLM_BASE_URL 少了 /v1 |
核对 server/.env.example 注释 |
改完 .env 不生效 |
没重新执行 . ./.env 或改错了文件 |
确认在 server/ 下操作并重启服务 |
| 手机镜像列表找不到接收器 | AIRPLAY_NAME 被改过 / 跨网段 |
手机与电脑须同网段;名字以 .env 为准 |
| 动作太慢 | 模型开了思考模式 | 用 LLM_EXTRA_BODY 关闭 thinking |
| Actor 和 Planner 想分开 | — | 加 ACTOR_MODEL / PLANNER_MODEL 覆盖 |
写在最后
.env 看着只有十几行,却决定了 ESP32 iPhone Agent 的"智商"来源:LLM_* 决定接哪个大脑,ACTOR_* / PLANNER_* 决定大脑怎么分工,端口和调试项则管住硬件链路。把第二、三节的两张表存下来,绝大多数配置问题都能三分钟定位。下一步可以看看 README.md 里的硬件烧录和手机侧 AssistiveTouch 设置,配合本文的 .env 配置,整个项目就能跑起来了。


