前言
ESP-Mosaico 不仅可以运行 LVGL 界面和普通嵌入式应用，也可以安装面向物联网设备的智能体框架 ESP-Claw。
本文记录一次完整上手过程：从浏览器烧录固件、解决串口超时、完成 2.4GHz Wi-Fi 配网，到接入阿里云百炼的 qwen3.7-plus，并解释为什么更换云端模型会直接影响设备端智能体的表现。
注意：文中不展示真实 API Key、Wi-Fi 密码和设备地址。配置时也不要公开这些信息。
1. ESP-Claw 的运行架构
ESP-Claw 并不是把一个大型语言模型完整运行在 ESP 芯片中。它更像运行在设备端的 Agent Runtime，主要负责：
- 接收 Web 或即时通信消息；
- 整理系统提示词、对话和记忆；
- 向云端 LLM 发起请求；
- 根据模型返回结果选择 Capability、Lua 或 MCP 工具；
- 控制本地屏幕、音频、传感器和存储；
- 保存必要的设备配置与长期记忆。
整体链路如下：
Web／IM 消息
↓
ESP-Claw：会话、记忆、路由与工具描述
↓
云端 LLM：理解、推理与工具选择
↓
Capability／Lua／MCP
↓
ESP-Mosaico 本地硬件或网络服务
因此，ESP32-S3、ESP32-S31 等芯片都可以在已有适配和资源满足要求时运行 ESP-Claw。具体到 ESP-Mosaico，官方 esp-mosaico-claw 仓库提供了板级定义、驱动适配、UI、系统服务与整机资源。
2. 固件来源与烧录方式
官方提供两种常见路径：
- 从源码构建
esp-mosaico-claw； - 在 ESP-Mosaico Firmware Update 页面使用浏览器烧录完整镜像。
对于首次体验，浏览器烧录更直接。使用桌面版 Chrome 或 Edge，准备一根支持数据传输的 USB 线，然后：
- 断开或关闭占用串口的程序；
- 按住开发板 BOOT 键并重新上电，使其进入下载模式；
- 在浏览器页面选择开发板对应的串口；
- 选择官方完整固件；
- 开始烧录并等待全部分区写入完成；
- 重启设备。
完整固件通常不仅包含应用本身，还包括 bootloader、分区表、OTA 数据、系统资源和存储分区。首次安装时不要只写入单一应用分区。
官方源码：https://github.com/esp-mosaico/esp-mosaico-claw
浏览器烧录：https://mosaico.espressif.com/firmware-update/
3. 解决 Timed out waiting for packet header
烧录过程中，我遇到了下面的错误：
Baudrate change error: SlipReadError: Timed out waiting for packet header
UART speed-up skipped: Unable to change the baud rate
它表示烧录工具在等待芯片回应时超时，常见原因包括：
- USB 线只能充电或者传输不稳定；
- 设备没有正确进入下载模式；
- 串口被串口监视器、IDE 或另一个网页占用；
- 浏览器尝试提高波特率后连接不稳定；
- USB Hub、转接器或接口供电不稳定。
建议按以下顺序排查：
- 更换确认支持数据传输的 USB 线，并直接连接电脑；
- 关闭 ESP-IDF Monitor、Arduino 串口监视器等程序；
- 重新执行按住 BOOT 上电；
- 在浏览器里断开后重新授权正确串口；
- 如果工具允许，降低烧录波特率后重试。
如果芯片已经成功识别，但总是在波特率切换后超时，通常应优先检查连接稳定性，而不是立即怀疑固件内容。
4. Wi-Fi 配置：使用 2.4GHz
ESP-Claw 官方 Web 控制台文档说明，除 ESP32-C5 外，目前其他相关芯片主要支持 2.4GHz Wi-Fi。因此 ESP-Mosaico 无法直接连接仅开启 5GHz 的无线网络。
需要区分以下概念：
| 名称 | 含义 |
|---|---|
| 2.4GHz／2.4G Wi-Fi | 无线路由器的 2.4GHz 频段 |
| 5GHz／5G Wi-Fi | 无线路由器的 5GHz 频段 |
| 4G／5G 移动网络 | 运营商蜂窝网络制式 |
如果路由器启用了双频合一，而设备配网失败，可以暂时创建独立的 2.4GHz SSID。Wi-Fi 设置保存后需要重启。
连接成功后，电脑或手机与设备位于同一局域网时，可以访问：
http://esp-claw.local/
如果 mDNS 域名无法解析，可从串口日志或路由器 DHCP 列表中查询设备 IP，再直接访问 http://设备IP/。
5. 接入阿里云百炼
ESP-Claw 支持 OpenAI 兼容 API，因此可以接入阿里云百炼的兼容接口。
我的配置为：
Backend: openai_compatible
Base URL: https://dashscope.aliyuncs.com/compatible-mode/v1
Model: qwen3.7-plus
API Key: 在阿里云百炼控制台创建
Tool Calling: Enabled
注意以下细节：
- Base URL 保留到
/v1； - 不要在后面继续填写
/chat/completions； - URL 末尾不要额外添加
/； - API Key 与所选地域、业务空间需要匹配；
- 保存 LLM 设置后重启设备；
- 如果模型没有视觉能力，应关闭“支持视觉输入”。
阿里云也提供业务空间专属域名，实际使用时可以按照控制台给出的地域与 Workspace ID 填写对应地址。
百炼 OpenAI 兼容说明：https://help.aliyun.com/zh/model-studio/compatibility-of-openai-with-dashscope
6. 180 种模型应该怎么选
免费额度页面可能展示大量模型，但并非所有模型都适合 ESP-Claw。列表中还包含视觉、数学、语音识别、语音合成和向量模型。
在 ESP-Claw 场景中，更应该关注：
- 是否属于通用对话模型；
- 是否支持稳定的 Tool Calling；
- 上下文长度是否足够容纳系统提示词和工具描述；
- 响应时间是否能接受；
- 是否需要视觉输入。
我先用 qwen3.6-plus 验证 API 与工具链路，之后切换到 qwen3.7-plus。qwen-math-turbo、Embedding 模型、ASR／TTS 模型不适合作为 ESP-Claw 的主聊天模型；带有 thinking 的模型可能消耗更多 Token、响应更慢，也需要额外验证工具调用兼容性。
7. Token 免费额度与用量控制
我的试用账户中，qwen3.6-plus 获得了 90 天有效的 1,000,000 Token 额度。体验一段时间后剩余 969,316 Token，即已使用 30,684 Token。
Token 不能直接换算成固定对话次数。一次 ESP-Claw 请求可能包含：
- 系统提示词；
- Capability 与工具定义；
- 当前问题；
- 历史消息；
- 本地记忆；
- 模型输出和工具调用参数。
为了减少消耗，可以：
- 完成一个任务后使用
/new创建新 Session； - 关闭暂时不用的 Capability；
- 不需要视觉时关闭视觉输入；
- 控制模型输出长度；
- 在百炼控制台打开“免费额度用完即停”。
最后一项非常重要：试用额度不是永久免费。开启用完即停后，额度耗尽会停止服务，而不是继续产生额外费用。
8. 为什么更换模型后会感觉更聪明
第一次对话时，ESP-Claw 对硬件能力的描述出现了型号错误和未经确认的功能。这类问题通常不是 UI 或 ESP 芯片性能导致的，而是模型、上下文和设备说明共同作用的结果。
可以从三个方向改善：
8.1 使用能力合适的模型
更强的通用模型通常拥有更好的指令理解、事实约束和工具选择能力，但仍不能保证完全正确。
8.2 补全设备身份信息
在 ESP-Claw 的身份、灵魂或用户信息中明确写出真实板卡型号、已安装硬件和禁止猜测的要求。不要让模型只凭产品名称推断外设。
8.3 精简 Capability
工具越多不一定越聪明。无关工具会增加上下文长度，也会增加误选概率。只保留当前需要的能力，往往更稳定。
9. 安全注意事项
ESP-Claw Web 控制台默认运行在局域网中，并会保存 API Key 等敏感配置。建议：
- 不把控制台端口暴露到公网；
- 为 SoftAP 设置密码，联网后按需自动关闭；
- 不公开包含 API Key、Wi-Fi 密码或完整配置的截图；
- 不随意分享设备文件系统或 NVS 转储；
- 修改 Lua、Skill 或系统文件前保留备份。
总结
ESP-Mosaico 上的 ESP-Claw 不是“大模型在微控制器里独立运行”，而是设备本地运行时与云端模型的协作系统。
完成固件烧录、2.4GHz 配网和 LLM 配置后，ESP-Mosaico 就拥有了对话、记忆和工具调度的基础框架。真正决定使用体验的，则是模型能力、设备身份描述、工具集合和本地规则能否彼此对齐。
这次我最终跑通了阿里云百炼 qwen3.7-plus。下一步准备继续测试 ESP-Claw 的 Skill、Lua 和 MCP，让屏幕、音频、IMU 与网络能力真正进入可被对话调用的工作流。
转载自 CSDN-专业IT技术社区
原文链接：https://blog.csdn.net/weixin_46555120/article/details/164370318
