ESP32 AI 语音助手完整指南从一块开发板到能对话的开源聊天机器人【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32当你说出小智讲个笑话桌面上的设备先用离线唤醒词在本地接住你的声音几秒后回以一段自然的语音回答。这就是 xiaozhi-esp32 这个 ESP32 AI 语音助手项目的最终形态设备端负责唤醒与音频流Qwen、DeepSeek 等大模型负责理解与回答两端通过 MCP 协议协同。本文按开发板选型、编译烧录、配网对话的顺序带你走完全流程并附上调优避坑要点。项目速览xiaozhi-esp32 的定位是大模型的语音交互入口。主线基于 ESP-IDF v6.0支持 ESP32、C3、C5、C6、S3、P4 六种芯片平台累计 138 个板卡目录、171 个固件发布变体覆盖面包板 DIY 到商业成品板。通信同时支持 WebSocket 与 MQTTUDP 双协议音频采用 Opus 流式传输既支持流式 ASRLLMTTS 方案也支持 Realtime 端到端语音模型。动手前的选型清单板卡选型只有两条路线想自己弄清硬件原理的选入门档面包板方案想开箱即用的选进阶档成品板两档共用同一套固件体系只在 menuconfig 中选项不同。档位配置特点入门档ESP32-S3 或 ESP32-C3 开发板、INMP441 麦克风、MAX98357 功放、面包板与杜邦线电路自己搭建成本可控适合学习硬件链路进阶档M5Stack CoreS3、微雪 ESP32-S3-Touch-AMOLED-1.8、LILYGO T-Circle-S3 等自带屏幕与音频开箱即用部分带摄像头与电池环境依赖只有一项安装 ESP-IDF 工具链官方推荐当前最新稳定版 v6.0.2v5.5.2 仅保留给旧版板卡Linux 环境编译更快且免去驱动问题。从克隆到首次对话完整搭建流程分四步有成品板的话拉完仓库即可完成固件烧录与首次配网。第一步拉取仓库git clone https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32 cd xiaozhi-esp32第二步选定芯片与板卡进入配置界面在列表里选你的板子idf.py set-target esp32s3 idf.py menuconfig第三步编译并烧录同时打开串口监视器观察输出idf.py build idf.py -p /dev/ttyUSB0 flash monitor第四步配网对话。设备启动后会开启热点或 BluFi 配网用手机连接并在配置页填入家庭 Wi-Fi登录后说唤醒词即可开始对话。面包板方案在烧录前先对照下图检查接线可以避免第一步就卡住。能力地图固件提供的核心能力集中在这张表里动手前可先核对是否与你的场景匹配。能力说明典型场景语音交互流水线ESP-SR 离线语音唤醒支持自定义唤醒词Opus 流式传输兼容流式 ASRLLMTTS 与 Realtime 端到端模型具备 AEC 的硬件可实现全双工交互桌面与客厅对话、实时打断声纹识别识别当前说话人身份区分家庭成员的不同指令MCP 协议扩展设备端 MCP 控制音量、灯光、电机、GPIO云端 MCP 扩展智能家居、PC 桌面操作、知识搜索、邮件收发智能家居控制、语音操控外设外设与显示OLED/LCD 表情与情绪呈现、电量显示与电源管理、摄像头视觉输入、38 种界面语言表情显示、便携设备、视觉扩展多网络与双协议Wi-Fi、有线以太网、USB RNDIS、ML307/NT26 等 4G部分硬件支持 Wi-Fi 与 4G 切换WebSocket 与 MQTTUDP 双协议备份无 Wi-Fi 环境、弱信号备份协议字段与交互流程的完整定义可查 docs/websocket_zh.md 与 docs/mqtt-udp_zh.md。调优与避坑实际使用中集中的问题基本是下面几类按现象对照处理即可。Wi-Fi 连不上多是路由器只开了 5GHz 或密码填错。核对 SSID 与密码是否属于 2.4GHz 频段仍失败则重置设备网络配置重新配网。唤醒识别不准多为环境噪声大或麦克风增益偏低。远离噪声源、调高麦克风增益默认唤醒词不顺口时可训练自定义唤醒词。响应明显偏慢主要耗时在网络往返与云端推理。换用信号更好的一条链路在 menuconfig 音频配置里调低 Opus 比特率减少后台任务。Flash 或 PSRAM 不足分区表与芯片实际规格不匹配。按 Flash 大小从 partitions/ 选分区表并在 menuconfig 中启用 PSRAM让音频流水线与显示缓存使用。编译失败项目主线已迁移到 ESP-IDF v6.0旧版 SDK 会编译不过部分组件。升级到最新稳定版 IDF旧板卡需停留在 v5.5.2 时查 docs/esp-idf-6-migration.md 确认兼容状态。从用到改跑通对话之后可改的空间分三层。个性化层唤醒词、字体、表情与聊天背景均可修改本地化资源含语音提示放在 main/assets/项目同时提供网页端在线修改工具改完重新打包烧录即可。二次开发层自有硬件可按 docs/custom-board_zh.md 指南在 main/boards/ 下新增板卡目录给助手加新能力只需编写 MCP 工具并通过协议暴露不用动音频流水线对接自研服务器或更换大模型时重点关注 main/protocols/ 下的协议封装。社区层docs/ 收录了 WebSocket、MQTTUDP、MCP、BluFi 与自定义板卡的完整文档多数问题能直接找到答案提交 Issue 前先翻一遍文档。项目以 MIT 许可证发布允许免费使用、修改乃至商用。想先拥有一台能对话的设备按选型清单选一块进阶档板卡走完烧录流程即可想弄懂音频链路就从面包板方案起步。首次对话跑通之后后续任何改造都会比读源码更快。【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考