企业官网建设流程全解析

把 ESP32 变成 MCP 语音助手：xiaozhi-esp32 从 0 到 1 烧录教程

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

半小时后，你手里会有一个能对话的桌面 AI 助手：喊它名字能应答，动嘴就能调音量、控屏幕。xiaozhi-esp32 是一个基于 MCP 协议的 ESP32 固件项目，烧进去就有离线唤醒、流式语音对话，还能把设备的硬件能力做成一份工具清单交给云端大模型直接调用。下面是完整走一遍的过程。

🔍 xiaozhi-esp32 速览：它覆盖了多少硬件和协议

这是一个跑在 ESP-IDF 上的完整语音交互入口：离线唤醒用 ESP-SR 完成，语音走 Opus 流式传输，对话能力则由后台的大模型提供。它最特别的地方在于设备本身就是一台 MCP 服务器——大模型不只跟你说话，还能反过来操作设备。

⚡ 第一次烧录固件：从克隆到唤醒应答共 5 步

第 1 步：拿到代码。

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

做完这步你应该看到工程根目录下有main/、docs/、partitions/三个目录。

麦克风、扬声器、按钮的完整接线方式，引脚定义对应main/boards/bread-compact-esp32/下的config.h。

第 2 步：选定目标芯片和板子。先装好 ESP-IDF 插件（首选 v6.0.2，Linux 下编译更快），然后以面包板为例：

idf.py set-target esp32 idf.py menuconfig

在Xiaozhi Assistant -> Board Type里选中你的板子，面包板叫“面包板 ESP32 DevKit”。做完这步你应该看到选中的板子已写进当前 sdkconfig。

第 3 步：编译。

idf.py build

做完这步你应该在build/目录下看到生成的.bin文件，且没有报错。

第 4 步：烧录。

idf.py flash

做完这步串口监视器里应该出现启动日志，设备开始自检。

第 5 步：连网并激活。这步不用敲命令。设备默认开热点，手机连上后按向导填入家里的 Wi-Fi 密码；连上官方服务器完成激活后，对设备说唤醒词，听到提示音就说明整条链路通了。完全不想编译的话，也可以直接下载现成固件烧录。

🎙️ 跑起来之后能干什么

智能家居的语音入口。“把音量调大”“屏幕亮一点”这类指令，大模型会通过 MCP 直接调用设备端工具执行；问天气、控制 Home Assistant 里的灯和空调，则交给云端 MCP，接法写在docs/mcp-usage_zh.md。

口语练习搭档。固件内置 38 种界面语言，目录在main/assets/locales/，学生放桌上随时切到目标语言练对话，语音提示缺失时自动回退英文。

有表情的桌面摆件。带屏幕的板子在对话时会显示表情和动画，显示层代码在main/display/，OLED、LCD 各有实现。

想动手改的话，这三个方向最实用：

• 加一个设备端工具：在main/mcp_server.cc里仿照self.audio_speaker.set_volume写一个AddTool，大模型下次上线就能看见并调用它。
• 适配自己的硬件：照着docs/custom-board_zh.md在main/boards/下新建目录，config.h里定义引脚，几十行代码就能把一块新板子接进来。
• 自建后端：main/protocols/下的websocket_protocol.cc和mqtt_protocol.cc是两套完整实现，私有化部署可以直接参照。

🧩 把 MCP 这一个点讲透：大模型是怎么“操作”设备的

对话里你说“音量调小”，大模型并不是把这句话变成语音念出来，而是发出一条 JSON-RPC 2.0 请求，经 WebSocket 或 MQTT + UDP 传到设备。设备端McpServer解析请求、调用对应硬件、再把结果回传。整个握手也有固定顺序：设备连上后台先发 hello 消息宣告能力，大模型侧先通过tools/list拉取工具清单，确认后才用tools/call逐个调用。细节全部有文档背书，见docs/mcp-protocol_zh.md。

大模型通过同一套 MCP 协议，同时控制本地设备硬件与云端服务。

其余技术点一句话带过：音频是 Opus 流式编解码，带 AEC 的硬件可以做到边说边听的实时全双工；唤醒则完全由设备本地完成，不依赖网络。

🛠️ 排错问答：唤醒不灵先查这里

问：明明开了 BluFi，设备为什么还是走热点配网？答：两种配网方式共存时，WiFi Configuration Method里默认启用的是 Hotspot，优先级更高。进idf.py menuconfig把 Hotspot 关掉再重新编译，BluFi 才会生效，原理见docs/blufi_zh.md。

问：用老 IDF 环境编译直接报错，怎么回事？答：主线已迁移到 ESP-IDF v6.0.2，v5.5 只保留给个别标注过的旧版板卡。把插件升到 v6.0.2，再对照docs/esp-idf-6-migration.md确认你这块板的验证状态。

问：唤醒时灵时不灵，第一步查什么？答：先排除电源，用足功率的 USB 电源，别接笔记本共享口；再看串口日志里有没有音频断流。不同场景参数取向不同：

xiaozhi-esp32 的价值，在于让一块几十元的 ESP32 独立扛下从唤醒到对话的整条链路，AI 部分全部靠 MCP 协议外挂，想加什么能力就往工具清单里添什么。想完整跑一遍的话：

1. 克隆仓库
2. 安装 ESP-IDF v6.0.2 插件
3. menuconfig 里选板子
4. 执行idf.py build和idf.py flash
5. 手机连热点完成配网

更多细节看docs/目录：板子适配问题查docs/custom-board_zh.md，协议细节查docs/mcp-protocol_zh.md，迁移和兼容状态查docs/esp-idf-6-migration.md。

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