78/xiaozhi-esp32
GitHub: 78/xiaozhi-esp32
一个运行在 ESP32 上的开源 AI 语音助手固件，通过 MCP 协议连接大模型并控制多种外设。
Stars: 24335 | Forks: 5220
# 基于 MCP 的聊天机器人
(English | [中文](README_zh.md) | [日本語](README_ja.md))
## 简介
👉 [人类：给 AI 一只眼睛 vs AI：立刻发现主人三天没洗头【bilibili】](https://www.bilibili.com/video/BV1bpjgzKEhd/)
👉 [手把手教你 DIY AI 女友，入门教程【bilibili】](https://www.bilibili.com/video/BV1XnmFYLEJN/)
作为语音交互入口，小智 AI 聊天机器人利用 Qwen / DeepSeek 等大模型的 AI 能力，并通过 MCP 协议实现多终端控制。
## 版本说明
当前的 v2 版本与 v1 分区表不兼容，因此无法通过 OTA 从 v1 升级到 v2。有关分区表的详细信息，请参阅 [partitions/v2/README.md](partitions/v2/README.md)。
所有运行 v1 的硬件均可通过手动刷入固件升级至 v2。
v1 的稳定版本为 1.9.2。你可以通过运行 `git checkout v1` 切换到 v1。v1 分支将维护至 2026 年 2 月。
### 已实现功能
- Wi-Fi / ML307 Cat.1 4G
- 离线语音唤醒 [ESP-SR](https://github.com/espressif/esp-sr)
- 支持两种通信协议 ([Websocket](docs/websocket.md) 或 MQTT+UDP)
- 使用 OPUS 音频编解码
- 基于流式 ASR + LLM + TTS 架构的语音交互
- 说话人识别，识别当前说话人 [3D Speaker](https://github.com/modelscope/3D-Speaker)
- OLED / LCD 显示屏，支持 emoji 显示
- 电池显示与电源管理
- 多语言支持（中文、英文、日文）
- 支持 ESP32-C3、ESP32-S3、ESP32-P4 芯片平台
- 设备端 MCP 用于设备控制（扬声器、LED、舵机、GPIO 等）
- 云端 MCP 以扩展大模型能力（智能家居控制、PC 桌面操作、知识搜索、邮件等）
- 支持在线网页编辑自定义唤醒词、字体、emoji 和聊天背景 ([自定义素材生成器](https://github.com/78/xiaozhi-assets-generator))
## 硬件
### 面包板 DIY 实践
请参阅飞书文档教程：
👉 ["小智 AI 聊天机器人百科全书"](https://ccnphfhqs21z.feishu.cn/wiki/F5krwD16viZoF0kKkvDcrZNYnhb?from=from_copylink)
面包板演示：
### 支持 70+ 种开源硬件（部分列表）
- 立创 ESP32-S3 开发板
- Espressif ESP32-S3-BOX3
- M5Stack CoreS3
- M5Stack AtomS3R + Echo Base
- Magic Button 2.4
- Waveshare ESP32-S3-Touch-AMOLED-1.8
- LILYGO T-Circle-S3
- XiaGe Mini C3
- 璀璨 AI 吊坠
- WMnologo-Xingzhi-1.54TFT
- SenseCAP Watcher
- ESP-HI 低成本机器狗
## 软件
### 固件烧录
对于初学者，建议使用无需搭建开发环境即可烧录的固件。
该固件默认连接到官方 [xiaozhi.me](https://xiaozhi.me) 服务器。个人用户注册账号后可免费使用 Qwen 实时模型。
👉 [小白固件烧录指南](https://ccnphfhqs21z.feishu.cn/wiki/Zpz4wXBtdimBrLk25WdcXzxcnNS)
### 开发环境
- Cursor 或 VSCode
- 安装 ESP-IDF 插件，选择 SDK 版本 5.4 或更高
- Linux 优于 Windows，编译更快且驱动问题更少
- 本项目使用 Google C++ 代码风格，提交代码时请确保遵守
### 开发者文档
- [自定义开发板指南](docs/custom-board.md) - 了解如何为小智 AI 创建自定义开发板
- [MCP 协议 IoT 控制使用](docs/mcp-usage.md) - 了解如何通过 MCP 协议控制 IoT 设备
- [MCP 协议交互流程](docs/mcp-protocol.md) - 设备端 MCP 协议实现
- [MQTT + UDP 混合通信协议文档](docs/mqtt-udp.md)
- [详细的 WebSocket 通信协议文档](docs/websocket.md)
## 大模型配置
如果你已经拥有小智 AI 聊天机器人设备并连接到官方服务器，可以登录 [xiaozhi.me](https://xiaozhi.me) 控制台进行配置。
👉 [后台操作视频教程（旧版界面）](https://www.bilibili.com/video/BV1jUCUY2EKM/)
## 相关开源项目
关于在个人电脑上进行服务器部署，请参考以下开源项目：
- [xinnan-tech/xiaozhi-esp32-server](https://github.com/xinnan-tech/xiaozhi-esp32-server) Python 服务器
- [joey-zhou/xiaozhi-esp32-server-java](https://github.com/joey-zhou/xiaozhi-esp32-server-java) Java 服务器
- [AnimeAIChat/xiaozhi-server-go](https://github.com/AnimeAIChat/xiaozhi-server-go) Golang 服务器
- [hackers365/xiaozhi-esp32-server-golang](https://github.com/hackers365/xiaozhi-esp32-server-golang) Golang 服务器
其他使用小智通信协议的客户端项目：
- [huangjunsen0406/py-xiaozhi](https://github.com/huangjunsen0406/py-xiaozhi) Python 客户端
- [TOM88812/xiaozhi-android-client](https://github.com/TOM88812/xiaozhi-android-client) Android 客户端
- [100askTeam/xiaozhi-linux](http://github.com/100askTeam/xiaozhi-linux) 100ask 出品的 Linux 客户端
- [78/xiaozhi-sf32](https://github.com/78/xiaozhi-sf32) 四川蓝牙芯片固件
- [QuecPython/solution-xiaozhiAI](https://github.com/QuecPython/solution-xiaozhiAI) 移远 QuecPython 固件
自定义素材工具：
- [78/xiaozhi-assets-generator](https://github.com/78/xiaozhi-assets-generator) 自定义素材生成器（唤醒词、字体、emoji、背景）
## 关于本项目
这是一个开源的 ESP32 项目，基于 MIT 协议发布，允许任何人免费使用，包括商业用途。
我们希望这个项目能帮助大家了解 AI 硬件开发，并将快速演进的大语言模型应用到实际的硬件设备中。
如果你有任何想法或建议，欢迎提出 Issues 或加入我们的 [Discord](https://discord.gg/bXqgAfRm) 或 QQ 群：994694848
## Star 历史
## 版本说明
当前的 v2 版本与 v1 分区表不兼容，因此无法通过 OTA 从 v1 升级到 v2。有关分区表的详细信息，请参阅 [partitions/v2/README.md](partitions/v2/README.md)。
所有运行 v1 的硬件均可通过手动刷入固件升级至 v2。
v1 的稳定版本为 1.9.2。你可以通过运行 `git checkout v1` 切换到 v1。v1 分支将维护至 2026 年 2 月。
### 已实现功能
- Wi-Fi / ML307 Cat.1 4G
- 离线语音唤醒 [ESP-SR](https://github.com/espressif/esp-sr)
- 支持两种通信协议 ([Websocket](docs/websocket.md) 或 MQTT+UDP)
- 使用 OPUS 音频编解码
- 基于流式 ASR + LLM + TTS 架构的语音交互
- 说话人识别，识别当前说话人 [3D Speaker](https://github.com/modelscope/3D-Speaker)
- OLED / LCD 显示屏，支持 emoji 显示
- 电池显示与电源管理
- 多语言支持（中文、英文、日文）
- 支持 ESP32-C3、ESP32-S3、ESP32-P4 芯片平台
- 设备端 MCP 用于设备控制（扬声器、LED、舵机、GPIO 等）
- 云端 MCP 以扩展大模型能力（智能家居控制、PC 桌面操作、知识搜索、邮件等）
- 支持在线网页编辑自定义唤醒词、字体、emoji 和聊天背景 ([自定义素材生成器](https://github.com/78/xiaozhi-assets-generator))
## 硬件
### 面包板 DIY 实践
请参阅飞书文档教程：
👉 ["小智 AI 聊天机器人百科全书"](https://ccnphfhqs21z.feishu.cn/wiki/F5krwD16viZoF0kKkvDcrZNYnhb?from=from_copylink)
面包板演示：
### 支持 70+ 种开源硬件（部分列表）
- 立创 ESP32-S3 开发板
- Espressif ESP32-S3-BOX3
- M5Stack CoreS3
- M5Stack AtomS3R + Echo Base
- Magic Button 2.4
- Waveshare ESP32-S3-Touch-AMOLED-1.8
- LILYGO T-Circle-S3
- XiaGe Mini C3
- 璀璨 AI 吊坠
- WMnologo-Xingzhi-1.54TFT
- SenseCAP Watcher
- ESP-HI 低成本机器狗
标签：AI硬件, ASR, C/C++, ChatGPT, DeepSeek, DIY, DNS解析, ESP32, ESP32-C3, ESP32-S3, ESP-IDF, Firmware, Gemini, GPIO控制, HMI, IoT, IPv6支持, LLM, Maker, MCP, OPUS, Promptflow, Python, RAG, Siri, TTS, UML, Unmanaged PE, Websocket, 事务性I/O, 二次开发, 人工智能, 人机交互, 分布式搜索, 创客, 固件, 多模态, 多语言支持, 大模型, 安全测试框架, 对话系统, 嵌入式AI, 嵌入式开发, 开源硬件, 开源项目, 无后门, 智能家居, 智能终端, 智能音箱, 机器人, 流式语音处理, 熵值分析, 物联网, 用户模式Hook绕过, 硬件控制, 离线语音识别, 语音交互, 语音助手, 语音唤醒, 边缘计算, 通义千问, 音频编解码