实验名称
基于 ESP32-S3 的 ESP-Claw 入门搭建教程。
一、实验目标
本实验面向没有接触过 ESP-Claw 的初学者。完成本实验后，读者应当能够：
- 理解 ESP-Claw 是什么，以及它与传统 IoT 的区别。
- 认识 ESP32-S3 面包板形态 ESP-Claw 的基本组成。
- 学会把开发板、外设、电源和数据线正确连接起来。
- 学会使用官方在线工具完成固件烧录和基础配置。
- 完成第一次联网、对话和外设验证。
二、项目简介
ESP-Claw 是乐鑫推出的物联网 AI 智能体框架。对于初学者来说，可以把它理解成“把一个会思考、会对话、会调用外设的智能体装进 ESP32 设备里”。它不是传统意义上的定时开关控制板，而是把设备行为、联网能力、模型能力和外设控制整合到一起，让设备能够根据对话和事件做出反应。
官方文档强调它具备几个核心特点：聊天即造物、事件驱动、MCP 双向互联、本地记忆，以及尽量把关键能力保留在设备端执行。
三、实验前需要先理解的概念
1. 什么是 ESP32-S3
ESP32-S3 是乐鑫的一款带 Wi-Fi 和蓝牙功能的微控制器。它常用于物联网、语音交互、图像采集和边缘 AI 设备。ESP-Claw 目前对硬件资源有一定要求，官方建议至少具备 8MB Flash 和 8MB PSRAM。
2. 什么是 ESP-Claw
ESP-Claw 不是单独的一块硬件，而是一套运行在 ESP 芯片上的智能体框架。它把模型、规则、外设和记忆组织起来，让设备能够接收自然语言指令，并进一步调用外设或联网服务。
3. 什么是在线烧录
在线烧录指的是不在本地复杂编译，而是直接通过浏览器把固件写入设备。对于初学者来说，这比自己拉代码、编译、配置工具链更容易上手。
4. 什么是 LLM、Lua 和 MCP
- LLM：大语言模型，用来理解自然语言和生成决策。
- Lua：轻量脚本语言，用来把确认后的逻辑固化成可重复执行的规则。
- MCP：一种统一的能力接入方式，可让设备暴露自己的工具能力，也可调用外部服务。
四、实验器材
1. 必备器材
| 器材 | 作用 |
|---|---|
| ESP32-S3 开发板 | 运行 ESP-Claw 的核心控制器 |
| 面包板 | 方便组装和接线 |
| 杜邦线 | 连接各外设和开发板 |
| USB 数据线 | 连接电脑并烧录固件 |
2. 可选外设
| 外设 | 用途 |
|---|---|
| 屏幕 | 显示状态、文字或图像 |
| USB 摄像头 | 实现视觉采集能力 |
| 麦克风 / 扬声器 | 实现语音交互 |
| WS2812 灯带 / 灯环 | 实现灯效反馈 |
| 舵机 | 实现机械动作 |
3. 推荐板卡
官方文档推荐使用 ESP32-S3-DevKitC-1。若你使用的是其他开发板，需要确认它是否满足 Flash 和 PSRAM 的要求，并且是否已经被官方支持列表收录。
五、实验环境
- 操作系统：Windows、macOS 或 Linux 均可
- 浏览器：Chrome 或 Edge
- 网络：可访问互联网的 Wi-Fi
- 烧录方式：官方在线烧录工具
官方说明在线烧录暂不支持 Firefox。
六、硬件连接方法
如果你是第一次接触这类项目，建议先做“最小系统”，也就是先只连接开发板，不急着接一大堆外设。确认能烧录、能联网后，再逐步增加外设。
1. 开发板放置
将 ESP32-S3-DevKitC-1 放置在面包板中央，左右留出扩展空间，便于后续插接杜邦线。
2. 屏幕连接
屏幕供电接 3V3 引脚。若你暂时不使用屏幕，也可以先跳过这一步。
3. 摄像头连接
ESP32-S3 的 GPIO20 对应 USB D+，GPIO19 对应 USB D-。摄像头供电可从 5V 引脚引出。
4. 灯带连接
WS2812 灯带或灯环的电源接 5V，DATA IN 接 GPIO14。
5. 舵机连接
舵机电源接 5V，PWM 信号接 GPIO47。
注意：外设电流较大时，建议使用稳定的外部 5V 电源，并且与开发板共地。不要把高负载外设直接完全依赖板载供电。
七、在线烧录步骤
步骤 1：准备电脑和浏览器
先确认电脑上使用的是 Chrome 或 Edge，并准备好 USB 数据线。
步骤 2：连接开发板
将开发板连接到电脑。如果你使用的是面包板形态的 ESP-Claw，请使用标记为 UART 的 USB 口。
步骤 3：打开官方在线烧录工具
在浏览器中进入官方在线烧录页面，点击连接设备。
步骤 4：选择固件
根据你使用的开发板选择对应固件。初学者建议先使用官方默认推荐配置，不要一开始就修改太多高级参数。
步骤 5：填写 Wi-Fi 信息
输入 Wi-Fi SSID 和密码。这个步骤很重要，因为设备烧录完成后需要连接网络，才能与聊天软件和外部服务配合工作。
步骤 6：填写 LLM 配置
官方支持 GPT、Qwen、Claude 和 DeepSeek 等模型服务。初学者可以先选择一个你已经有 API Key 的服务。
如果你的目标是尽量稳定地体验“聊天造物”，建议优先使用推理能力较强的模型。
步骤 7：填写聊天软件配置
官方支持 Telegram、QQ Bot（OpenClaw）、飞书和微信 ClawBot。你可以先选择最容易配置的一种，不必一开始全都启用。
步骤 8：填写搜索引擎配置
如果你希望设备具备联网检索和天气查询能力，建议配置 Tavily。没有搜索引擎时，设备仍可做部分本地交互，但联网查询能力会受限。
步骤 9：开始烧录
确认所有参数无误后，点击烧录。烧录完成后，设备会自动重启。
八、首次启动后应检查什么
烧录完成后，不要急着直接做复杂功能，建议先按以下顺序检查：
- 串口日志中是否显示联网成功。
- 设备是否已经获得局域网 IP。
- 聊天软件是否能够收到设备回复。
- 若已接外设，外设是否有响应。
九、第一次交互测试
你可以从最简单的问题开始，比如：
- 你好，你现在能做什么？
- 请介绍一下你的外设。
- 帮我查询今天的天气。
- 请把灯光调亮一点。
- 请显示一条欢迎信息。
如果设备能够正确回答并执行操作，说明最基本的链路已经跑通：设备联网、模型可用、聊天通道可用、外设控制可用。
十、常见故障与排查
1. 烧录完成但无法联网
请检查 Wi-Fi 名称和密码是否正确，路由器是否正常工作，以及设备是否完成了真正的重启。
2. 浏览器无法连接设备
请确认你使用的是 Chrome 或 Edge，并检查 USB 线是否支持数据传输，而不是只能充电。
3. 外设没有反应
请检查电源、共地、引脚定义和接线方向。对于舵机、灯带这类外设，供电不足是最常见问题。
4. 聊天软件无响应
请检查 Bot Token、Secret、API Key、网络访问权限以及模型参数是否填写完整。
十一、术语补充说明
1. SoftAP
SoftAP 可以理解为设备自己开出来的一个临时热点。当设备无法正常联网时，官方可能会让你通过这个热点重新配置参数。
2. 事件驱动
事件驱动不是隔几秒就去检查一次，而是“有事件就立刻处理”。它更适合实时性较强的设备。
3. 本地记忆
本地记忆可以让设备记住用户偏好、使用习惯或常用操作，提升后续交互的连续性。
十二、实验结论
通过本实验，读者可以完成从“认识 ESP-Claw”到“真正搭建并运行”的完整入门过程。它的重点不是把设备简单连上网，而是让设备具备智能体能力：能理解、能决策、能调用外设、能保存记忆。
对于第一次接触这类项目的人来说，最重要的不是追求一上来就做复杂功能，而是先把硬件、烧录、联网、交互四个基础环节跑通。只有这样，后续扩展摄像头、屏幕、灯效和语音能力时才不会混乱。
十三、思考题
- ESP-Claw 与传统 IoT 设备最大的差异是什么？
- 为什么在边缘设备上使用本地记忆很重要？
- 如果你只能保留一个外设，你会优先保留屏幕、摄像头还是舵机？为什么？
- 事件驱动架构为什么更适合这类设备？