78/xiaozhi-esp32 · 上手攻略

  • 仓库：78/xiaozhi-esp32
  • 链接：https://github.com/78/xiaozhi-esp32
  • 分类：skill
  • 作者：spark
  • 更新：2026-07-13

是什么

小智 AI 聊天机器人（XiaoZhi AI Chatbot）是 78（虾哥 / 稚晖君相关开源圈里非常活跃的一位）维护的 ESP32 端开源语音对话固件。它的定位是「一个 30–80 元硬件就能跑的、可以用 Qwen / DeepSeek 等大模型驱动的语音助手」，并且通过 MCP（Model Context Protocol）把设备本身的能力和云端能力都开放给大模型 —— 既能控制本机的扬声器、LED、舵机、GPIO，也能让模型调用云端 MCP 去搜邮件、控智能家居、查知识库。

硬件层支持 ESP32-C3、ESP32-S3、ESP32-P4 三个系列；软件层跑的是「离线唤醒（ESP-SR）→ 流式 ASR → LLM → TTS → OPUS 编解码」的标准语音链路，可以走 WebSocket 或 MQTT+UDP 与服务端通信。整个项目是 MIT 协议，硬件方案至少 70+ 款（市面上常见 LiChuang 立创 ESP32-S3、ESP-BOX3、M5Stack CoreS3 / AtomS3R+Echo Base、LilyGO T-Circle-S3、XiaGe Mini C3、SenseCAP Watcher 等都直接能用），社区里也已经衍生出 Python / Java / Go 三个服务端实现和 Android / Linux 客户端。

解决什么问题

  • 把大模型装进廉价硬件：以前要在 ESP32 上跑 LLM 对话，要么上传完整音频到云端再 TTS 回来，要么自己写整套语音流水线；这个项目把这套东西封装成开箱即用的固件。
  • 让设备成为 MCP 节点：传统的「AI 音箱」只能被云端命令控制；MCP-based 让大模型主动调用设备上的工具（开灯、转舵机、读传感器），把硬件变成 agent 的「手」。
  • 给中文母语用户低门槛体验：README 中文 / 英文 / 日文三语，支持多语言识别（中文、英文、日文），OLED/LCD 上能显示中文和 emoji，并且有国内服务器（xiaozhi.me）默认接入 Qwen Realtime 免费使用。
  • 可定制的 AI 女友 / AI 宠物范式：官方文档里直接把它放在「Handcraft your AI girlfriend」的视频标题下，强调「会说话的硬件 + 可换人格 + 可换外形」的玩法。

快速安装

先选硬件，再选路径。 README 直接给了两条路线：完全不想碰代码的「烧录预编译固件」路线，以及要改代码 / 加自定义 MCP 工具的「ESP-IDF 5.4+ 开发路线」。

A. 烧录预编译固件（推荐新手）

  1. 看 README 里的「Hardware」一节，挑你手头对应型号的固件（项目 Release / 飞书文档里都有预编译包）。
  2. 在 Windows 上下载并解压 flash_download_tool.zip（乐鑫官方烧录工具）。
  3. 按飞书《Beginner's Firmware Flashing Guide》选择对应芯片（esp32s3 / esp32c3 / esp32p4）的合并固件（merged bin）烧到 0x0 偏移。
  4. 烧录完成重启后，设备会默认连 xiaozhi.me 官方服务器；用手机注册一个账号（个人用户可用免费的 Qwen Realtime 模型），在 OLED / LCD 上扫绑定码完成设备激活。
  5. 说唤醒词（默认在固件里）就开始对话。

B. 从源码编译（要改代码、加自定义 MCP 工具）

  1. 装好 ESP-IDF 5.4.0 或更新版本（README 与官方文档 xiaozhi.dev 都明确写「5.4.0+」；5.3.x 会在 idf.py set-target 报版本错误）。建议直接下离线安装包，不要在 Windows 上从源码编译 IDF。
  2. 拉仓库、初始化子模块（如果需要）。
  3. 进项目目录：

bash # 选芯片（按你硬件选一个） idf.py set-target esp32s3 # 旧版菜单（可选） idf.py menuconfig # 编译 idf.py build # 烧录 idf.py -p /dev/ttyUSB0 flash # 看日志 idf.py -p /dev/ttyUSB0 monitor

  1. Linux 比 Windows 编译快很多，驱动也少踩坑（README 原话）。VSCode / Cursor 装 ESP-IDF 插件后可以直接在 IDE 里点。
  2. 修改服务端地址（如果用自托管）改 main/application.h 里默认的 WebSocket / MQTT endpoint。

C. 自托管服务端（可选）

官方只提供客户端固件；要彻底私有化，社区有三种实现：

  • Python 版：xinnan-tech/xiaozhi-esp32-server
  • Java 版：joey-zhou/xiaozhi-esp32-server-java
  • Go 版：AnimeAIChat/xiaozhi-server-go 或 hackers365/xiaozhi-esp32-server-golang

把固件里默认的 xiaozhi.me endpoint 换成你自己服务的地址即可，协议层（WebSocket 或 MQTT+UDP）保持一致。

核心用法

1. 默认对话流（拿到固件后就能玩）

按下设备 / 说唤醒词 → 设备通过 WebSocket 上传 OPUS 音频到服务端 → 流式 ASR 拿到文本 → 服务端调 Qwen / DeepSeek → 文本 + 流式 TTS 音频推回设备 → 扬声器播放。整个链路延迟通常在 800ms–1.5s 之间，取决于网络和模型。

2. 自定义唤醒词 / 字体 / 表情 / 聊天背景

仓库里直接给了一个配套项目 78/xiaozhi-assets-generator，跑起来是个 Web 工具，编辑完生成一份资源包覆盖到固件里 assets/ 对应目录再重新烧录即可。

3. 加自定义 MCP 工具（让模型能控制硬件）

按 docs/mcp-usage.md 的范式，定义一个继承自 MCP 基类的工具，例如控制一个 GPIO LED：

// pseudocode, 实际基类与注册名以 docs/mcp-protocol.md 为准
class LedTool : public McpTool {
 public:
  const char* name() const override { return "self.set_led"; }
  const char* description() const override {
    return "Turn the on-board LED on or off.";
  }
  void invoke(const json& args) override {
    bool on = args.value("on", false);
    gpio_set_level(GPIO_NUM_2, on ? 1 : 0);
    emit_result({{"ok", true}});
  }
};
// 在 application.cpp 里 register_tool(std::make_shared<LedTool>());

注册完之后，模型看到「把灯打开」就会通过 MCP 调到这个工具。

4. 接云端 MCP（搜邮件 / 控智能家居 / 查知识库）

服务端支持挂第三方 MCP Server（stdio 或 SSE）。在自托管服务里把 MCP server 的配置写进 mcp_config.json（位置见你所用服务端的 README），重启后大模型就能用「查天气」「发邮件」之类的能力 —— 这也是 README 强调的「设备端 MCP + 云端 MCP」的双层架构。

5. 通信协议切换

默认走 WebSocket；如果想走 MQTT+UDP 混合（更适合网络抖动场景）改 docs/mqtt-udp.md 的配置；纯 WebSocket 协议见 docs/websocket.md。

典型适用场景

  • 极客玩家 + AI 硬件 DIY：花 30–80 元做一台能对话的「AI 玩具」，再上 3D 打印外壳。
  • AI Agent 教学 / 演示：演示大模型如何通过 MCP 协议控制真实硬件（灯、舵机、机器人）。
  • 企业 demo / 智能硬件原型：做「智能音箱」「陪伴机器人」「桌面助手」的产品快速验证。
  • 嵌入式 + LLM 课程项目：学生用 ESP32 + Qwen Realtime 跑完一个完整链路。
  • MCP 协议在 IoT 上的应用样本：是少数能直接跑在端侧设备上的 MCP 实现。

不太适合：需要本地离线跑大模型（设备算力只够做唤醒 + 编解码，必须联网）、对低延迟（< 200ms）有苛刻要求的工业控制。

坑与注意

  • v1 → v2 不能 OTA，必须手动烧录：README 明确写 v2 分区表不兼容 v1。v1 最后一个稳定版是 1.9.2，git checkout v1 切到旧分支继续维护到 2026 年 2 月。
  • ESP-IDF 版本严苛：必须 5.4.0 或更高，5.3.x 在 idf.py set-target 步骤直接报错（不是警告，是中断）。
  • 首次跑官方 xiaozhi.me 走 Qwen Realtime 模型 是免费的，但有速率 / 时长限制；想用自己模型得自托管服务端。
  • 官方服务器在中国大陆访问更稳定；海外用户更建议自托管或选区域友好的服务端实现。
  • 要 4G 联网选 ML307 Cat.1 模组：README 列了 Wi-Fi 与 ML307 4G 两种联网方式，没 Wi-Fi 信号的环境走 4G 模组即可。
  • 音频编解码是 OPUS，不是 PCM/MP3；如果你要从麦克风直接拉裸流做二次处理，记得在固件里把它关掉再走自己的 ASR。
  • OLED/LCD 显示支持 emoji：在 xiaozhi-assets-generator 里能编辑，但 LCD 屏大小有限，复杂表情可能显示不全。
  • 常见故障（飞书文档里也有）：烧错固件 → 屏幕无显示、扬声器无声音；先确认 chip 型号、merged bin 偏移、波特率。

与同类对比

  • OpenAI Realtime API / GPT-4o voice demo —— 走云端 API，硬件无关；xiao Zhi 是把整套跑在 ESP32 上、可以自托管。
  • Home Assistant Voice / ESPHome 语音组件 —— Home Assistant 偏整套智能家居中控，语音只是一部分；xiao Zhi 偏「独立对话设备 + MCP」。
  • M5Stack UIFlow / MicroPython 语音 demo —— 偏图形化快速原型，能力受限；xiao Zhi 是正经可生产的 C++ 固件。
  • 聆思 / 云知声等国内模组方案 —— 商业 SDK，闭源，按出货收费；xiao Zhi 完全开源 MIT，但模型和 TTS 还是依赖云端。
  • HeyHi / AIAEC 等其他 ESP32 语音项目 —— 多半只到「ASR + 关键词」程度，没有把 MCP 协议 + 大模型 + 设备控制串成完整链路。

一句话推荐结论

把大模型 + MCP 协议装进 30 元的 ESP32，开箱即玩也能硬核改源码，是目前中文社区里把「AI 硬件 + MCP 协议」串得最完整、可玩性最高的开源项目；想从零做一台会说话的 AI 玩具 / 智能硬件原型，就从这里开始。