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 6v5.5 只留给文档明确标注的旧板子Linux 下编译明显更快也更省驱动折腾。网络条件一个能正常连 Wi-Fi 的室内环境手机随时待命——首次配网要连设备热点芯片平台覆盖 ESP32、C3、C5、C6、S3、P4S3 生态最成熟新手优先。 跟着做让它第一次跑起来从裸板到开口对话第 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_*已经写进当前 sdkconfigesp32s3 目标默认就是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.2v5.5 只保留给文档明确标注的旧板卡升级插件后按 docs/esp-idf-6-migration.md 核对你这块板子的验证状态。坑 2开了 BluFi设备却只给热点现象明明启用了 BluFi 配网设备还是走 Wi-Fi 热点。先查什么menuconfig 里WiFi Configuration Method的当前选择。怎么解决热点模式优先级更高两个配网方式会打架把 Hotspot 选项关掉再编译详见 docs/blufi_zh.md。坑 3语音时灵时不灵对话断流现象偶尔没反应、声音截断。先查什么供电换足功率的 USB 电源别用笔记本共享口再看串口日志里有没有音频断流打印。怎么解决按场景走场景调什么怎么调电池供电整机功耗缩短单次交互时长空闲让设备进深度睡眠响应慢后端链路换 WebSocket 传输并挑延迟低的模型唤醒词误触发唤醒词本身用官方工具重训一个更短、更独特的唤醒词最后一句话收个尾xiaozhi-esp32 的价值就是让一块几十块钱的 ESP32 独立扛下唤醒到对话整条链路AI 部分全靠 MCP 协议外挂想加能力不用动硬件。最短路径就五步clone 仓库装 ESP-IDF 6.0.2 插件menuconfig 选板子build 加 flash手机连热点配网卡住时按图索骥docs/ 官方文档目录自定义板卡看 docs/custom-board_zh.mdMCP 协议交互流程看 docs/mcp-protocol_zh.md传输协议细节看 docs/websocket_zh.md 和 docs/mqtt-udp_zh.md。【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考