把 ESP32 变成 AI 语音助手：xiaozhi-esp32 实操上手指南

把 ESP32 变成 AI 语音助手xiaozhi-esp32 实操上手指南【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32把一块普通的ESP32开发板变成 AI 语音助手xiaozhi-esp32是目前门槛最低的选择烧录固件后喊一声唤醒词就能和它流式对话、查资料、控制灯光。本文面向想用低成本开发板做语音交互的硬件新手、学生和独立开发者。核心机制速览xiaozhi-esp32的本质是一条本地语音 云端大模型 统一控制协议的链路。设备端用ESP-SR做离线唤醒词识别唤醒后麦克风采集的音频编码成Opus流上传走WebSocket或MQTT UDP两种传输之一云端可以接传统的流式 ASR 大模型 TTS也可以接 Realtime 端到端语音模型。带 AEC回声消除的硬件如ESP32-S3、ESP32-P4能边播放边听你说话做到实时全双工对话。真正让它区别于普通聊天固件的是MCPModel Context Protocol。设备端扮演 MCP 服务器通过标准 JSON-RPC 2.0 注册工具音量、灯光、GPIO、电机等云端大模型先tools/list发现能力再用tools/call直接下达控制指令——你不需要为每种硬件单独写 AI 接入逻辑。反过来云端也能通过 MCP 扩展知识搜索、邮件收发等大模型能力。硬件与环境准备最低可运行方案一块ESP32-C3加面包板配上麦克风如 I2S MEMS 麦、小喇叭和按键即可起步成本几十元。注意 C3 系列走轻量音频引擎不支持 AEC体验是说完再回做不到全双工。推荐完整方案直接买带屏带电池的成品板如ESP32-S3-BOX-3或M5Stack CoreS3开箱即有显示、电池和回声消除完整体验唤醒—对话—表情反馈闭环。项目已覆盖 138 个板卡目录、171 个固件发布变体ESP32、ESP32-C3/C5/C6/S3/P4芯片平台均支持。软件方面源码编译需要 VSCode 或 Cursor 安装ESP-IDF插件最低版本ESP-IDF v6.0.1推荐v6.1已不再支持 5.xLinux 编译更快且免去驱动问题。从零跑通分步搭建新手路径烧录现成固件最快到项目的 Release 页面找到对应板型的固件用免开发环境工具直接烧录无需搭任何环境固件默认接入 xiaozhi.me 官方服务器注册个人账号即可免费使用 Qwen 实时模型完成配网热点或 BluFi、激活设备即可开始对话源码路径自己编译固件用 VSCode 或 Cursor 装好 ESP-IDF 插件确认 SDK 版本为 v6.0.1 及以上克隆仓库git clone https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32 cd xiaozhi-esp32选板型并编译idf.py menuconfig # 选择板型与参数 idf.py build # 选完板型后编译烧录固件并首次配网设备没有已保存 Wi-Fi 时自动进入配网默认热点模式用手机热点完成也可在 menuconfig 里改用 BluFi 蓝牙配网功能验证与体验按这个顺序验证每一步都对应一条真实链路说出唤醒词→ 设备离线识别ESP-SR本地推理不依赖网络后进入对话状态无屏设备靠提示音、带屏设备有表情反馈问一个开放问题→ 语音流式回复且回复是边想边说的流式 TTS不是整段念说把音量调大一点→ 大模型通过MCP的tools/call直接调用设备端工具喇叭音量实时变化换一种语言看界面→ 提供 38 种界面语言语音提示优先使用本地化资源缺失时回退英文进阶玩法项目用McpServer::AddTool注册设备端工具你完全可以用同样的方式给板子上的 GPIO 或舵机注册一个新工具然后对语音助手说一句话就能驱动它用法详见 docs/mcp-usage_zh.md。常见卡点与排查BluFi 配网没反应→ 热点配网和 BluFi 不能同时开启热点已启动时会优先走热点模式请在 menuconfig 里只保留一种多次测试后建议清除 NVS 中存储的旧 SSID。详见 docs/blufi_zh.md唤醒词没反应或成功率低→ 先查麦克风供电与接线供电不稳时唤醒成功率会明显下降可对照 README_zh.md 的硬件章节核对连接编译失败或报版本错误→ 主线已迁移到ESP-IDF v6.0.1以上5.x 不被支持先确认插件里的 SDK 版本再重试想加一块新开发板→ 板卡选择是一条联动链config.json→ 构建脚本 →Kconfig.projbuild→CMakeLists.txt每环都要配写法参考 docs/custom-board_zh.md资源索引想理解设备端 MCP 怎么注册工具读 docs/mcp-usage_zh.md要看协议报文级细节看 docs/mcp-protocol_zh.md关心音频引擎与 AEC 的实现直接翻 main/audio/README.md工具注册的核心代码在 main/mcp_server.cc改之前先通读一遍。【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考