30 分钟烧录一个会说话的 AI 语音助手xiaozhi-esp32 上手指南【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32对着桌上的小开发板说一句唤醒词它接话了还能顺手把音量调大——这就是 xiaozhi-esp32 能做到的事。自己从零搭一个 AI 语音助手得接麦克风、调 Opus 音频流、再对接大模型 API随便折腾就是好几天多数人卡在第一天就放弃了。xiaozhi-esp32 把这些全包了一个基于 MCP 的 ESP32 语音助手固件离线唤醒、流式识别、自然对话全部内置你只管烧录和配网30 分钟就能听到它开口。 先看它是不是你的菜xiaozhi-esp32 已适配 171 个发布变体main/boards/ 下每个目录就是一块板子的引脚定义。按你的目标挑目标选择为什么最低成本试水面包板 ESP32 开发板 麦克风 小喇叭main/boards/bread-compact-esp32/ 引脚定义现成照着接就行完整功能体验M5Stack CoreS3麦克风、喇叭、屏幕、按键一体零接线触摸屏表情Waveshare ESP32-S3 Touch AMOLED 系列表情和 UI 显示效果好显示层由 main/display/ 驱动完全不想编译现成固件 官方服务器注册后可免费用 Qwen 实时模型跳过编译直接烧录原理一条线就能讲完你说话板子上的麦克风采集音频本地唤醒词模型判断该我了吗一旦唤醒音频用 Opus 编码成流经 WebSocket 或 MQTT UDP 发给后端两套完整实现都在 main/protocols/后端的大模型生成回复语音流回来边收边播。同时大模型还能反过来调用设备上报的工具清单——调音量、设亮度、拍照这些在 main/mcp_server.cc 里通过 AddTool 注册设备、云端走的是同一套 JSON-RPC 2.0 协议。大模型通过单一 MCP 协议同时控制本地硬件和云端服务 从零到第一次跑通第一次烧录的步骤第 1 步拿到代码主线更新快直接拉最新代码最省事。git clone https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32 cd xiaozhi-esp32✅ 此时你应该读到main/、docs/、partitions/三个目录都在。第 2 步装好 ESP-IDF 6.0.2 环境主线基于 ESP-IDF v6.0.2版本不对是新手翻车的第一大原因用 5.x 老环境编译依赖组件会直接报错。在 VSCode 或 Cursor 里装对应版本的插件即可Linux 下编译更快。这步最容易翻车装插件、配工具链折腾半小时很正常。如果不想折腾直接去官方渠道下载现成固件烧录默认连官方服务器一样能跑通。✅ 此时你应该读到IDE 状态栏显示 ESP-IDF v6.0.2。第 3 步在 menuconfig 里选板子指定芯片后进入配置菜单在 Xiaozhi Assistant → Board Type 选中你的板子面包板选 Bread Compact ESP32。板名会写进 sdkconfig决定编译时生成哪套代码。idf.py set-target esp32 idf.py menuconfig✅ 此时你应该读到sdkconfig 里已出现你选的板子名称。第 4 步编译并烧录一条命令搞定。面包板的话麦克风、扬声器、按键这样接包含麦克风、扬声器、按钮的完整语音交互系统接线idf.py build idf.py flash✅ 此时你应该读到串口监视器里出现启动日志。第 5 步配网激活说唤醒词开机后设备开启热点手机连上按向导填入 Wi-Fi 密码。激活完成后对着设备说唤醒词。✅ 此时你应该听到提示音响起随后设备开口回应你。 让它更顺手加一个设备端工具在 main/mcp_server.cc 里仿照self.audio_speaker.set_volume写一个 AddTool大模型下次上线就能看见并调用它。适配自己的硬件照着 docs/custom-board_zh.md 在 main/boards/ 下新建目录config.h里定义引脚几十行代码接一块新板子。换传输协议或自建后端main/protocols/ 里的 websocket_protocol 和 mqtt_protocol 是两套完整实现私有化部署照着改。 问题速查现象先查什么常见原因处理编译直接报组件错插件版本主线已切 IDF 6.0.25.x 不再通用升级插件对照 docs/esp-idf-6-migration.md 检查板子验证状态开了 BluFi 却不生效menuconfig 配网方式热点模式优先级更高两者打架关掉 WiFi Configuration Method 的 Hotspot 再编见 docs/blufi_zh.md语音时灵时不灵、音频断流串口日志 电源USB 口功率不足换足功率的 USB 电源别用笔记本共享口响应慢后端链路MQTT 延迟高或模型慢换 WebSocket 传输选延迟低的模型唤醒误触发唤醒词唤醒词太长用官方工具重训一个更短的唤醒词前三条覆盖了新手最高频的卡点还卡住的话docs/ 目录下按主题分好了文档基本都能查到。下一步xiaozhi-esp32 的核心卖点是让一块几十块钱的 ESP32 扛下从唤醒到对话的整条链路AI 能力全靠 MCP 协议外挂换板子、换模型、换后端都不用重写。接下来可以玩的方向给设备加一个自己的工具main/mcp_server.cc把自家硬件接进来docs/custom-board_zh.md读懂设备端 MCP 协议docs/mcp-protocol_zh.md环境版本兼容查 docs/esp-idf-6-migration.md协议细节查 docs/mcp-protocol_zh.md。【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考