一句话就有回应：xiaozhi-esp32 之 ESP32 AI语音助手完整教程-创锋一号

一句话就有回应：xiaozhi-esp32 之 ESP32 AI语音助手完整教程

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

深夜想关灯，又不想起身。你不用伸手去够遥控器，只要说一句"关灯"，摆在房间角落的那台小设备就会照办——这不是你买的智能音箱，而是用一块 ESP32 开发板自己搭出来的 xiaozhi-esp32，一个把ESP32 AI语音助手跑在你桌面上的开源项目。

一分钟认识 xiaozhi-esp32

一句话定位：它是个基于 MCP 协议的聊天机器人——ESP32 负责语音入口，云端大模型负责理解与生成，MCP 协议负责让 AI 反过来调用灯光、喇叭、GPIO 这些硬件能力。

离线语音唤醒在芯片本地运行，唤醒不依赖网络
覆盖 138 个板卡目录、171 个固件变体，从面包板接线到商业成品板都有适配
WebSocket 与 MQTT+UDP 双传输通道，Wi-Fi、4G 模块都能接

🔌 ESP32 语音助手 DIY 准备清单

名称	版本或型号	用途	是否必需
ESP32-S3 开发板	8MB Flash 以上，如 M5Stack CoreS3	主控、音频与唤醒词处理	是
麦克风 + 功放模块	INMP441、MAX98357 及杜邦线	面包板方案的语音输入输出	面包板方案必需
ESP-IDF SDK	v6.0.2（主线要求 v6.0+）	编译与烧录	自行编译时必需
VSCode 或 Cursor + ESP-IDF 插件	最新版	图形化编译与配置	自行编译时必需
官方服务器账号	xiaozhi.me 免费注册	大模型对话、OTA 升级	首次对话必需

小智 AI 聊天机器人的面包板演示：麦克风、扬声器与 ESP32 的完整连接

⏱ 五步跑通固件

第 1 步，拿到代码。

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

做完后：终端里出现项目目录，进入它再继续。

第 2 步，选定芯片目标。

idf.py set-target esp32s3

做完后：生成sdkconfig，menuconfig 里才能看到板卡选项。

第 3 步，选板卡、开唤醒词。

idf.py menuconfig

在Xiaozhi Assistant下选择你的板卡；Wake Word Type默认是 DISABLED，S3/P4 选USE_AFE_WAKE_WORD。做完后：配置写回sdkconfig。不想自己编译的话，也可以直接下载官方现成固件烧录，新手建议先走这条路。

第 4 步，编译烧录。

idf.py build && idf.py -p /dev/ttyUSB0 flash monitor

做完后：串口监视器开始滚动日志。

第 5 步，首次配网。设备会自动开热点，手机连上后在浏览器里填 Wi-Fi 账密。完成后设备进入监听状态，喊唤醒词就能开始对话。

🔊 功能深挖：最值得用的三件事

离线语音唤醒：不靠云端就能叫醒

云端唤醒需要先把语音传上去，延迟高还费流量。这个项目的唤醒词完全跑在芯片本地：S3/P4 走 AFE 的 WakeNet，C3 等轻量芯片用独立 WakeNet。想喊自己的名字？在 menuconfig 选USE_CUSTOM_WAKE_WORD，填上模型名和显示词即可，唤醒词模型存放在 assets 分区，能随 OTA 更新，不用重刷固件。

ESP32 与麦克风、扬声器、传感器的完整连接方案

MCP 协议：让大模型"碰"到硬件

大模型只会说话，不会控制设备。MCP 解决这个问题：设备连上服务器后，后台用tools/list拉取本机工具清单，需要控制时用tools/call下发调用；设备端一行McpServer::AddTool就能注册新工具。ESP-HI 机器狗就注册了self.dog.forward、self.light.set_rgb，你说"往前走走"它就真的动。音量、LED、GPIO 等设备端工具开箱可用，云端侧还能扩展到智能家居、PC 桌面操作、知识搜索。

通过 MCP 协议实现设备与云端 AI 的协同控制

双通信通道

WebSocket 和 MQTT+UDP 是两条可选传输链路：MQTT 走控制消息，UDP 承载音频并带加密与乱序防护，弱网环境多一层备选。

🛠 想改哪里，就去哪个目录

改硬件引脚、显示、按钮：main/boards/，每块板一个目录，config.h管引脚、config.json管发布配置
改唤醒词引擎：main/audio/wake_words/
改界面、字体、表情包：main/display/lvgl_display/
对接自己的服务器协议：main/protocols/
从零写新板卡，看完整指南：docs/custom-board_zh.md

⚠️ ESP32 语音助手避坑速查表

现象	可能原因	处理办法
menuconfig 里看不到目标板卡	没先选芯片目标	先执行`idf.py set-target`，再打开 menuconfig
编译报 SDK 或组件错误	IDF 版本不匹配	主线用 ESP-IDF v6.0.2；v5.5 仅兼容文档标注的旧板卡
唤醒词怎么喊都没反应	唤醒默认 DISABLED	menuconfig 里选`USE_AFE_WAKE_WORD`或`USE_CUSTOM_WAKE_WORD`
能对话但没声音	I2S 引脚或编解码芯片配置不符	对照对应板卡目录`config.h`里的引脚定义逐一核对
OTA 升级后自己的固件被覆盖	直接改了已有板卡的配置编译	在`main/boards/`新建目录并使用唯一的板卡类型
蓝牙配网搜不到设备	BluFi 与热点配网互斥	menuconfig 里只保留其中一种配网方式

更进一步

想换大模型，就在自己服务器部署一个兼容的 xiaozhi 服务端（README 列了 Python、Java、Go 等多个开源实现），设备端无需改动即可对接；想给设备加新技能，照 docs/mcp-usage_zh.md 注册 MCP 工具；想深挖音频流水线、AEC 全双工的实现，读 main/audio/README.md 里的架构图就够了。

今晚就把手头那块开发板翻出来，先刷一个现成固件走通对话。卡在哪一步，就先查上面的避坑速查表，再看对应板卡目录的说明——等你第一次听到它应声回答你的声音时，会明白这套东西值得继续折腾下去。

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

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析