企业官网建设流程全解析

ESP32 语音助手快速上手指南：用 xiaozhi-esp32 打造支持 171 个固件变体的 MCP 聊天机器人

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

xiaozhi-esp32 是一个基于 MCP 协议的语音交互项目：ESP32 开发板负责听和说，云端大模型（Qwen、DeepSeek 等）负责思考，中间的 MCP 协议负责把两者接起来。它的定位是"硬件侧的聊天机器人固件"，不是完整的服务端。目标读者是手里有一块 ESP32 或开发板、想体验完整语音对话流程的人。上手成本分两档：直接用现成固件，半小时能烧录点亮；自己编译源码，一个晚上能跑通并改出自己想要的效果。

🏗️ 对话是怎么发生的：架构拆解

一条数据的完整路径

以一次"唤醒 → 回答"为例：麦克风采集的音频经音频 Codec 进入输入任务，交给音频引擎做唤醒词检测（基于乐鑫 ESP-SR）和 16 kHz PCM 输出，再经 Opus 编码进入发送队列，通过 WebSocket 或 MQTT+UDP 发到服务器；服务器完成识别、大模型推理、语音合成后，把 24 kHz 的 Opus 音频流发回来解码播放。整条链路和队列划分见 main/audio/README.md。

两种通信通道，同一套消息协议

设备与服务器之间支持 WebSocket 和 MQTT + UDP 两种传输。连接建立后设备先发送一条 hello 消息，声明自己支持的能力（如 MCP、AEC）和音频参数，服务器回复确认后对话通道才打开。二进制帧承载 Opus 音频，JSON 文本帧承载状态和指令，分工清晰。

MCP：设备端和云端各当一次角色

MCP 消息封装在基础协议里，遵循 JSON-RPC 2.0，流程文档在 docs/mcp-protocol.md。设备端是 MCP 服务器（main/mcp_server.cc），把音量、LED、舵机、GPIO 暴露成"工具"给大模型调用；云端是 MCP 客户端，可以反过来调用你部署的智能家居、桌面操作、知识搜索等服务。同一套协议，两端能力互相对接，这是这个项目区别于普通语音玩具的关键设计。

🔧 开发板选择与最小上手步骤

项目目前支持138 个板卡目录、171 个固件发布变体，芯片覆盖 ESP32、C3、C5、C6、S3、P4。按硬件门槛从低到高，可以这样选：

• 入门档：ESP32 + 面包板 + 麦克风 + 喇叭，成本最低，接线参考 docs/v0/
• 体验档：ESP32-S3 加一块小屏，能看表情和状态；带 AFE 的 S3 硬件还能开全双工、边播边听
• 成品档：M5Stack CoreS3、Waveshare AMOLED 系列等一体化开发板，开箱即用

步骤如下：

1. 确定开发板，确认它在 main/boards/ 里有对应目录。
2. 新手建议直接烧现成固件（免开发环境），默认接入 xiaozhi.me 官方服务器，个人用户可免费使用 Qwen 实时模型。
3. 想自己编译时，先克隆代码：

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

4. 在 VSCode（或 Cursor）里用 ESP-IDF 插件，首选 v6.0.2；Linux 环境编译更快也更少驱动问题。
5. 运行idf.py menuconfig，选定板型，然后编译烧录。
6. 上电后用热点或 BluFi 完成配网（docs/blufi.md），说唤醒词，对话开始。

🎨 玩法与定制

场景：把助手带到没有 Wi-Fi 的地方。项目支持 ML307/EC801E、NT26 等 Cat.1 4G 模组，部分硬件可在 Wi-Fi 和 4G 间切换。做法是选一块带 4G 的板型（如 main/boards/bread-compact-ml307/ 目录），配网时走蜂窝网络，出门带着用。

场景：让 AI 看到画面。带摄像头的板型（如 SenseCAP Watcher、M5 的 AtomS3R 摄像头版）支持视觉输入，拍一张给大模型看，问"这是什么"。

场景：多人共用一台设备。项目集成了 3D-Speaker 声纹识别，能识别当前说话人身份，适合家庭或宿舍共用一台语音助手。

二次开发两个高价值入口：

• 换唤醒词和外观：唤醒词、字体、表情、聊天背景都支持网页端在线编辑，资源存进 v2 分区的 assets 区（partitions/v2/README.md），可以 OTA 更新，不用重新烧录。
• 加新板型或新工具：每块板对应 main/boards/ 下一个目录，包含config.h（引脚映射）、config.json（构建配置）和板级初始化代码，照着 docs/custom-board.md 复制一个目录改就行。

⚠️ 避坑与资源

现象：烧录后没有反应，或唤醒词不灵。先查 menuconfig 里选的板型是不是你手上这块，板型选错时引脚映射全部错位；再确认供电是否稳定，面包板方案尤其容易栽在供电上。

现象：配网一直失败。确认路由器开了 2.4 GHz 频段（ESP32 系列不支持 5 GHz），配网方式二选一：热点配网或 BluFi，流程见 docs/blufi.md。

现象：说话时设备"听到自己"，出现回声。回声消除依赖硬件 AEC 能力，只有带 AFE 的 S3/P4 平台能开全双工；小芯片平台走原始单声道 PCM，建议安静环境使用。链路细节见 main/audio/README.md。

现象：自改的板子被 OTA 覆盖后变砖。自定义板型时不要直接改原有板卡的配置，必须新建板型目录、保持板型标识唯一，否则标准固件的升级通道会覆盖你的固件，警告原文写在 docs/custom-board.md 开头。

接下来建议三件事：先用现成固件把对话流程完整走一遍；再对照 docs/ 里的协议文档（WebSocket、MQTT+UDP、MCP）挑一篇细读；确认想玩二次开发后，从 main/boards/ 里挑一个和你硬件最接近的目录当模板。

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