30 分钟，让 ESP32 开口说话：xiaozhi-esp32 ESP32 AI 语音助手上手指南-育师

30 分钟，让 ESP32 开口说话：xiaozhi-esp32 ESP32 AI 语音助手上手指南

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

想让开发板"会聊天"？单片机固件、音频驱动、大模型接口三件事压过来，多数人还没动手就放弃了。xiaozhi-esp32 把这个过程压到一次编译烧录：刷进 ESP32 后，离线唤醒、流式语音识别、自然对话全链路就绪，AI 能力通过 MCP 协议外挂。本文带你从裸板到第一次对话。

🔭 先看看它能干什么：唤醒、流式对话、控制硬件一样不少

装完固件，你能直接拿到三样东西：

离线唤醒 + 实时对话。唤醒词检测跑在板子上的 ESP-SR 引擎，语音上传后既走流式"识别 + 大模型 + 合成"链路，也支持 Realtime 端到端语音模型；带 AEC 回声消除的板子可以边说边听，全双工互不打断。
本地硬件听大模型指挥。调音量、改屏幕亮度、切换主题、拍张照片，都是大模型对话中的一句指令。固件内置 38 种界面语言（main/assets/locales/），练外语口语可以直接切目标语言。
云端能力随意扩。设备端 MCP 只管本地硬件，查天气、控智能家居、操作 PC 桌面这类重活交给云端 MCP，两边走同一套 JSON-RPC 2.0 格式。

⚙️ 它内部怎么跑起来的：把 ESP32 本身当成一台 MCP 服务器

整个项目最核心的设计选择只有一个：设备端不写"AI 逻辑"，而是把自己注册成 MCP 服务器。开机连上后端后，固件向云端上报一张"工具清单"——每一项对应板子上一个真实动作，代码在 main/mcp_server.cc 的AddTool里，比如self.audio_speaker.set_volume调音量、self.screen.set_brightness设亮度、self.camera.take_photo拍照并解释画面。

大模型拿到这张清单后，对话中"把音量调到 30"这类话就会变成一个工具调用，板子执行完把结果回传。反过来，云端也可以把自己的服务（天气、智能家居）挂成 MCP 工具，设备侧代码不用改一行。

补充三句就够：传输层有 WebSocket 和 MQTT + UDP 两套实现（main/protocols/）；音频走 Opus 流式编解码；工程基于 ESP-IDF v6.0.2。

🧰 动手之前先备齐：板子选型和工具链版本清单

硬件按预算选，三种档位：

用途	推荐型号	理由
最低成本试水	面包板 + ESP32-C3/S3 + I2S 麦克风 + 小喇叭	几十块钱跑通全链路，接线与引脚参考 main/boards/bread-compact-esp32/
完整体验	M5Stack CoreS3	麦克风、喇叭、屏幕、按键一体，到手就能用
要屏幕表情	微雪 ESP32-S3-Touch-AMOLED 系列	触摸交互，表情和 UI 呈现效果好

工具链与环境各一条：

工具链：Cursor 或 VSCode 装 ESP-IDF 插件，版本首选v6.0.2（主线已迁移到 IDF 6，v5.5 只留给文档明确标注的旧板子）；Linux 下编译明显更快，也更省驱动折腾。
网络条件：一个能正常连 Wi-Fi 的室内环境，手机随时待命——首次配网要连设备热点；芯片平台覆盖 ESP32、C3、C5、C6、S3、P4，S3 生态最成熟，新手优先。

🚀 跟着做，让它第一次跑起来：从裸板到开口对话

第 1 步：拿到代码

git clone https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32 cd xiaozhi-esp32

验收信号：目录里能看到main/（固件源码）、docs/（协议与板卡文档）、partitions/（分区表），README 中文版在README_zh.md。

第 2 步：装好编译环境

在 IDE 里安装 ESP-IDF v6.0.2 插件。验收信号：插件状态栏显示当前 IDF 版本为 6.0.2，而不是残留的 5.x。

第 3 步：menuconfig 里锁定你的板子

idf.py set-target esp32s3

然后运行idf.py menuconfig，进入Xiaozhi Assistant -> Board Type选中你的板卡；没有对应型号就选"面包板 ESP32 DevKit"这类基础项，再补上屏幕/音频的开关选项。验收信号：对应的CONFIG_BOARD_TYPE_*已经写进当前 sdkconfig（esp32s3 目标默认就是bread-compact-wifi）。

第 4 步：编译并烧录

idf.py build && idf.py flash

验收信号：build 以Project build complete收尾，flash 输出Wrote ... bytes后串口监视器立刻开始滚动启动日志。完全不想搭环境的话，也可以直接下现成固件烧录，默认接官方服务器，注册账号后免费用 Qwen 实时模型。

第 5 步：配网激活，等第一声提示音

开机后设备开启 Wi-Fi 热点（或 BluFi 模式），手机连上热点，按向导填入家里 Wi-Fi 密码。设备重启联网、完成激活后，对着它说唤醒词。验收信号：听到提示音、屏幕表情变化，随便说句话得到回答——链路全通了。

🛠️ 把它变成自己的：三个改起来最划算的方向

加一个设备端工具。打开 main/mcp_server.cc，仿照self.audio_speaker.set_volume写一个AddTool：起个名字、描述用途、定义参数、给个回调，几十行搞定。大模型下次上线就能"看见"并调用它。
适配自己的硬件。在 main/boards/ 下新建目录，按 docs/custom-board_zh.md 在config.h里把麦克风、喇叭、按键的引脚写对，再补一个config.json声明目标芯片。照着现有板卡抄，几十行定义就能把新板子接进来。
换传输协议或自建后端。main/protocols/websocket_protocol.cc 和 mqtt_protocol.cc 是两套完整实现，私有化部署时照协议文档自建服务端即可，细节见 docs/websocket_zh.md 与 docs/mcp-usage_zh.md。

🩹 出问题时自己救：三个新手最高频的坑

坑 1：编译直接报依赖错现象：装的是 5.x 老环境，依赖组件解析失败。先查什么：插件显示的 IDF 版本。怎么解决：主线需要ESP-IDF v6.0.2，v5.5 只保留给文档明确标注的旧板卡；升级插件后按 docs/esp-idf-6-migration.md 核对你这块板子的验证状态。

坑 2：开了 BluFi，设备却只给热点现象：明明启用了 BluFi 配网，设备还是走 Wi-Fi 热点。先查什么：menuconfig 里WiFi Configuration Method的当前选择。怎么解决：热点模式优先级更高，两个配网方式会打架，把 Hotspot 选项关掉再编译，详见 docs/blufi_zh.md。

坑 3：语音时灵时不灵，对话断流现象：偶尔没反应、声音截断。先查什么：供电（换足功率的 USB 电源，别用笔记本共享口）；再看串口日志里有没有音频断流打印。怎么解决按场景走：

场景	调什么	怎么调
电池供电	整机功耗	缩短单次交互时长，空闲让设备进深度睡眠
响应慢	后端链路	换 WebSocket 传输，并挑延迟低的模型
唤醒词误触发	唤醒词本身	用官方工具重训一个更短、更独特的唤醒词