ESP32 iPhone Agent .env 配置项全解析:从 LLM_BASE_URL 到 ACTOR/PLANNER 双模型独立配置的完整指南

原创2026-10-15 15:20:151,919 阅读
文章标签:人工智能AI AgentGUI 自动化MCP 服务AI 技能嵌入式物联网硬件开发移动开发原生移动CLI音视频dsh-plugin

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_* 变量都会回落到默认值,模型请求会直接失败。

ESP32 iPhone Agent 硬件与服务器运行环境:XIAO ESP32S3 插在 iPhone 上,电脑端运行 Web UI

二、核心配置: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。

ESP32 iPhone Agent Web UI 演示:右上角 DESIGN/PLANNER 与 ACTION/ACTOR 分别显示各自使用的模型名称

上图中右上角的 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}}'

ESP32 iPhone Agent 实际运行效果:AI 自动打开时钟 App 设置每日重复闹钟

配通之后,一句"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 配置,整个项目就能跑起来了。

登录后查看全文
esp32-iphone-agent