企业官网建设流程全解析

手把手 3 步点亮 ESP32 语音机器人：MCP 协议控制全解

【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32

你在短视频里见过桌面上那种会聊天、会跳舞、还会打灯光的迷你机器人，而它背后的主控芯片只要几十块钱。xiaozhi-esp32（小智 AI 聊天机器人）就是这么一个开源项目：以 ESP32 系列芯片为语音交互入口，通过 MCP 协议控制设备——你说一句"跳舞"，底盘真的会动。

读完本文，你能带走：

• 📌 30 秒看懂固件由哪些模块组成、如何协作
• 一张表核对：手头硬件够不够拼出一台语音交互设备
• 两条路线跑通固件：免开发环境的现成固件，和可自行编译的源码路线
• MCP 协议控制的工作原理，以及给你的板子注册一个"大模型能调用的工具"的思路
• 烧录前绕开新手最常踩的 4 个坑

30 秒看懂：固件里装着哪几块拼图

把整条链路压缩成一句话：

麦克风 → 离线唤醒 → Opus 音频流 → 大模型（ASR+LLM+TTS 或 Realtime 模型）→ MCP 工具调用 → 设备执行

链路上的每一环都有对应目录：音频处理（编解码、音频引擎、唤醒词）在 main/audio/，协议层在 main/protocols/，MCP 工具注册在 main/mcp_server.cc，而所有板级硬件逻辑都在 main/boards/。这个仓库目前有 138 个板卡目录、171 个固件发布变体，覆盖立创、乐鑫、M5Stack、微雪等常见硬件，社区活跃度可想而知。

手头的硬件够不够：一张表核对

项目本身不指定唯一硬件，走的是"一套固件、多块板子"的路线。以常见的 ESP32-S3 机器人载体（如仓库内置的 ESP-SparkBot 板型）为例，核心组件是这样：

手上已有列表内的开发板或成品，可以直接跳到烧录一节；打算自己焊的，可以对着上面的面包板接线图，参考自定义开发板指南先搭个最简版本。

从零跑起来：两条路线点亮固件

路线 A：烧现成固件（最省心）

README 里写得很直接：新手第一次操作建议先不搭开发环境，直接用免开发环境烧录的固件。固件默认接入官方服务器（xiaozhi.me），个人用户注册账号可免费使用 Qwen 实时模型。路径很简单：下载发布固件 → 让 ESP32 进入下载模式 → 用烧录工具写入 → 上电配网开聊。

路线 B：自己编译（可改任意代码）

# 项目要求 ESP-IDF v6.0.1 及以上（5.x 已不支持），推荐 v6.1 git clone https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32 cd xiaozhi-esp32 idf.py set-target esp32s3 # 指定目标芯片 idf.py menuconfig # 交互菜单里选中你的板子（BOARD_TYPE） idf.py build # 编译固件 idf.py -p /dev/ttyUSB0 flash monitor # 烧录并进入串口监视

逐句说人话：set-target告诉工具链给哪颗芯片编译；menuconfig对应 main/Kconfig.projbuild 里的板型选择表，务必挑和你手上硬件一致的那一项；build产出固件；最后一行完成烧录并打开串口监视，启动日志立刻可见。

三个核心能力，逐个拆开看

喊一声就醒：离线语音唤醒

它能在断网状态下被本地唤醒词叫醒，靠的是运行在 ESP32 上的 ESP-SR 唤醒模型。代码在 main/audio/wake_words/，既有官方实现esp_wake_word，也留了custom_wake_word自定义接口；唤醒语音提示等资源文件在 main/assets/ 下，按语言分目录存放，替换资源就能换"人设"。

大模型替你动手：MCP 协议控制

这是这个项目最值得讲的部分。链路是：你说话 → 大模型理解 → 下发tools/call请求 → 设备注册的对应工具执行 → 结果返回并播报。设备端通过一行AddTool把能力"挂牌"，仓库里 ESP-SparkBot 的"跳舞"工具长这样：

// 来源：main/boards/espressif/esp-sparkbot/esp_sparkbot_board.cc mcp_server.AddTool("self.chassis.dance", "跳舞", PropertyList(), this -> ReturnValue { SendUartMessage("d1"); // 经 UART 把跳舞指令发给电机板 light_mode_ = LIGHT_MODE_MAX; return true; });

注意工具名self.chassis.dance和中文描述"跳舞"——大模型就是靠这两样决定"什么时候按这个按钮"。完整的握手、tools/list、tools/call流程在 MCP 协议交互流程文档 和 MCP 用法说明 里写得很细。

双通道，一路音频

同一台设备可以在两种后端之间二选一：WebSocket 或 MQTT + UDP，协议层已封装好。音频走 Opus 编码，既支持传统 ASR+LLM+TTS 流水线，也支持 Realtime 端到端语音模型；带 AEC（回声消除）的硬件还能实时全双工对话——你说到一半它能让位。想换成自部署的后端服务器，改连接配置即可，协议文档就是接口契约。

跑通之后：两个值得折腾的方向

如果你的板子不在 138 个目录里，自定义开发板指南 给了标准姿势：在 main/boards/ 下新建目录、写好引脚与音频编解码初始化、再到 main/Kconfig.projbuild 注册，之后menuconfig里就能选中你自己的板子。

想让大模型"会的事"更多，只需在板级文件里多加一个AddTool：比如注册一个self.light.set_rgb，声明 r/g/b 三个 0~255 的整数参数，就能用语音调灯光。参数类型（布尔、整数、字符串）、取值范围、默认值如何声明，见 main/mcp_server.h 的注释。

新手最容易踩的 4 个坑

最后一句

xiaozhi-esp32 证明了：几十块的 ESP32，照样能撑起一套完整的语音交互加 MCP 协议控制，项目以 MIT 许可证发布，可自由商用。

常走的文档入口：MCP 交互流程 · MCP 用法 · WebSocket 协议 · MQTT+UDP 协议 · 自定义开发板。遇到问题就去项目里提 Issue，或按 README 里留的 Discord、QQ 群号进群问一句。

板子在桌上，命令就上面那几行，先烧起来再说。

【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32