企业官网建设流程全解析

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/ 下每个目录就是一块板子的引脚定义。按你的目标挑：

原理一条线就能讲完：你说话，板子上的麦克风采集音频，本地唤醒词模型判断"该我了吗"；一旦唤醒，音频用 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 是两套完整实现，私有化部署照着改。

🩹 问题速查

前三条覆盖了新手最高频的卡点，还卡住的话，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