xiaozhi-esp32 完整教程：把 AI 语音助手整条链路装进一块 ESP32-平芜编程栈

xiaozhi-esp32 完整教程：把 AI 语音助手整条链路装进一块 ESP32

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

先看见成品：烧录完成后，设备是什么样

烧录完固件接上电，对着它说一声唤醒词，扬声器里传出短促的提示音——你问一句"今天天气怎么样"，它马上接话，说到一半你插嘴，它也能停下来听你讲。这就是 xiaozhi-esp32 给你的体验：离线唤醒、流式语音识别、自然对话全部跑在一块 ESP32 小板上，大模型部分则通过 MCP 协议外挂，Qwen、DeepSeek 这些云端模型都能直接调用。

凭什么一块小板子能对话

xiaozhi-esp32 的设计有点"服务员"的意思：设备一启动，就把自己声明为一台 MCP 服务器，向云端递上菜单——调音量、改屏幕亮度、用摄像头拍张照，每一项都是 main/mcp_server.cc 里一条 AddTool 写出来的。大模型拿着这份菜单，在对话中"照单点菜"：你说"把音量调大"，模型就向设备端对应工具发起调用，硬件立刻执行。

菜单是双向的：云端那侧的能力——查天气、看新闻、控制智能家居——也挂在同一套 JSON-RPC 2.0 协议上，不必再学第二套规矩。协议全貌见 docs/mcp-protocol_zh.md。

传输层有两套现成实现，WebSocket 与 MQTT+UDP，代码在 main/protocols/；音频走 Opus 流式编解码，边收边播，硬件带 AEC 的还支持全双工实时对话——它说话时你可以随时插嘴打断。

最小可跑通配置

备料：硬件档位、代码与工具链

硬件按预算三档选，main/boards/ 下每个子目录就是一块板子的接线和引脚定义，目前已适配 171 个板级变体：

目标	推荐硬件	说明
最低成本试水	面包板 + ESP32 + 麦克风 + 小喇叭	接线参考 main/boards/bread-compact-esp32/
体验完整功能	M5Stack CoreS3	麦克风、喇叭、屏幕、按键齐全
触摸屏体验	Waveshare ESP32-S3 Touch AMOLED 系列	表情和 UI 展示效果好

拿代码、装环境：

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

主线代码基于 ESP-IDF v6.0.2，装同版本插件即可（VSCode、Cursor 都行，Linux 上编译更快）。可观测结果：工程里能看到main/、docs/、partitions/等完整目录。

一次性的配置：set-target 与 menuconfig 选板

idf.py set-target esp32 idf.py menuconfig

menuconfig 进入Xiaozhi Assistant -> Board Type，选中你的板子（面包板选"面包板 ESP32 DevKit"）。这一步只需做一次，可观测结果：选中的板名被写进当前 sdkconfig。

烧录与联网：从 build 到唤醒激活

idf.py build && idf.py flash

可观测结果：串口监视器打出启动日志。完全的新手也可以跳过编译，直接烧录官方渠道的现成固件。开机后设备开热点（或走 BluFi），手机连上热点按向导填入 Wi-Fi 密码；激活完成后喊出唤醒词，听到提示音，对话就通了。

它适合谁玩：三类玩家各取所需

纯硬件新手：从桌面学习伙伴开始

把它放桌上就是学习伙伴：随时问问题、查资料、听外语例句。固件内置 38 种界面语言，见 main/assets/locales/，练口语时直接切到目标语言。手里有自己的板子也不怕：照 docs/custom-board_zh.md 在 main/boards/ 下新建目录，config.h里定义引脚，几十行代码就能把新板子接进来。

智能家居玩家：语音入口接进 Home Assistant

设备端 MCP 只管本地硬件，重活交给云端 MCP：问天气、查新闻、控制 Home Assistant 里的灯和空调，接入方法见 docs/mcp-usage_zh.md。

二开开发者：加工具、做表情、换协议

加一个设备端工具：在 main/mcp_server.cc 里仿照self.audio_speaker.set_volume写一条 AddTool，大模型下次上线就能"看见"并调用它。
做带屏幕的表情设备：OLED/LCD 板能显示对话表情和动画，适合桌面摆件或儿童互动玩具，显示层代码在 main/display/。
换传输协议或自建后端：main/protocols/websocket_protocol.cc 与 main/protocols/mqtt_protocol.cc 是两套完整实现，私有化部署可参考社区 server 项目。

最常见的三个报错，问对问题就修好了

"我用 5.x 的老环境编译，为什么依赖组件直接报错？"

主线已经切到 ESP-IDF v6.0，v5.5 只留给个别老款板卡。解法：插件升级到 v6.0.2，再对照 docs/esp-idf-6-migration.md 查你这块板的验证状态。

"明明启用了 BluFi，设备怎么还是走热点配网？"

两者会打架：热点模式优先级更高，抢占了配网入口。解法：在 menuconfig 的WiFi Configuration Method里关掉 Hotspot 选项再重新编译，细节见 docs/blufi_zh.md。

"语音时灵时不灵，先查哪儿？"

先排除电源——用足功率的 USB 电源，别用笔记本共享口；再盯串口日志里有没有音频断流。不同场景的参数取向：

场景	调什么	怎么调
电池供电	功耗	缩短交互时间，空闲进深度睡眠
响应慢	后端链路	换 WebSocket 传输，选延迟低的模型
唤醒误触发	唤醒词	用官方工具重训一个更短的唤醒词