外观
小智 AI 聊天机器人
小智 AI 是目前中文社区里最火的 ESP32 项目之一：一块带麦克风和喇叭的 ESP32 板子，刷上开源固件 xiaozhi-esp32，就能用语音和 Qwen、DeepSeek、豆包这类大模型对话，还能通过 MCP 协议控制灯、舵机、智能家居甚至电脑。它由作者「虾哥」(GitHub 用户名 78) 发起，固件开源，同时有官方云平台 xiaozhi.me 提供免配置的后端，对新手极其友好。
这篇是本手册对小智的完整介绍：固件、云平台、自建服务器、硬件、协议和生态都会讲到。
项目概况
| 项目 | 内容 |
|---|---|
| 固件仓库 | github.com/78/xiaozhi-esp32，仓库描述为「An MCP-based chatbot」 |
| 官方平台 | xiaozhi.me（控制台、设备绑定、智能体配置、MCP 接入点） |
| 作者 / 组织 | 虾哥 (78) 及社区贡献者 |
| 开源协议 | MIT（已核对 README 与仓库元数据），允许商用 |
| 支持芯片 | ESP32、ESP32-C3、ESP32-C5、ESP32-C6、ESP32-S3、ESP32-P4；仓库中另有 ESP32-S31 的构建配置 |
| 开发环境 | ESP-IDF v6.0.1 及以上，推荐 v6.1；README 明确写明不再支持 ESP-IDF 5.x |
| 首次发布 | 仓库创建于 2024 年 8 月 31 日；GitHub 上最早的 release 为 v0.2.0（2024 年 9 月 11 日） |
| 最新版本 | v2.5.2（2026 年 10 月 11 日） |
| 热度 | GitHub 约 3.1 万星（2026 年 10 月） |
它是怎么工作的
小智的核心思路是「设备端只管收音、播音、显示和执行动作，聪明的部分放在云端」。ESP32 本身跑不动大模型，所以整个对话链路是：
- 设备端用 ESP-SR 做离线唤醒词检测，可以自定义唤醒词。也可以靠按键触发。
- 唤醒后麦克风音频用 Opus 编码，通过网络实时上传。
- 服务端完成流式语音识别 (ASR)、大语言模型推理 (LLM)、语音合成 (TTS)，再把 Opus 音频流回设备播放。README 同时提到了接入端到端的实时语音模型 (Realtime) 的方式。
- 如果硬件带回声消除 (AEC)，可以做实时的全双工对话，说话时也能打断。
通信协议
固件提供两种传输方式，协议文档都在仓库 docs/ 下：
| 方式 | 特点 |
|---|---|
| WebSocket | 一条连接同时传二进制 Opus 音频帧和 JSON 控制消息。设备连接后先发 hello 消息，声明版本、是否支持 MCP / AEC、音频参数（文档示例为 Opus、16 kHz、单声道、60 ms 帧），服务端回 hello 后开始会话。实现最简单，自建服务器多数用它 |
| MQTT + UDP | MQTT 通道传控制消息，UDP 通道传加密的实时音频（文档中为 AES-CTR，带序列号防重放）。控制与数据分离，适合需要服务端下发指令的场景 |
网络方面，固件支持 Wi-Fi、有线以太网、USB RNDIS，以及 ML307 / EC801E / NT26 等 Cat.1 4G 模组；部分板子可以在 Wi-Fi 与 4G 之间切换。配网可以走热点或 BluFi（蓝牙配网）。
设备激活与绑定
使用官方服务时，设备要先绑定到你的 xiaozhi.me 账号。第三方资料描述的流程是：设备联网后显示一个验证码，你在 xiaozhi.me 控制台里添加设备并输入验证码，完成激活。未绑定的设备，官方服务端不会响应 hello，表现为一直「连接中」。这部分来自社区教程，细节以控制台页面为准。
MCP：小智的「手脚」
MCP (Model Context Protocol) 是让大模型调用外部工具的协议，基于 JSON-RPC 2.0。小智在两端都用到了它：
- 设备端 MCP：固件里通过
McpServer注册工具，例如self.light.set_rgb、self.dog.forward。大模型听懂「把灯调成红色」后，服务端通过tools/list发现工具，再用tools/call调用。设备端还有「仅用户可用」的工具（如重启、升级），不会被模型自主调用。 - 云端 MCP：在 xiaozhi.me 控制台的智能体配置里可以拿到一个 MCP 接入点（社区教程中给出的格式是
wss://api.xiaozhi.me/mcp/?token=...），把自己的 MCP 服务连上去，就能让小智查知识库、发邮件、操作电脑、控制智能家居。
接入点里带 token，等同于密码，别贴到公开的地方。
其他功能
README 列出的能力还有：用 3D Speaker 做声纹识别、OLED / LCD 上的表情动画、支持板子的摄像头视觉输入、电量显示与电源管理、39 种界面语言、通过在线工具自定义唤醒词、字体、表情和聊天背景（xiaozhi-assets-generator）。
需要的硬件
最低要求是：一颗 ESP32 系列芯片 + I2S 麦克风 + I2S 功放喇叭。支持列表里以 ESP32-S3 板子居多，它有 PSRAM 和向量指令，唤醒词和显示更从容；ESP32-C3 等低成本芯片也有对应板型，但功能会受限。
README 称仓库支持 138 个板型目录、171 个发布变体，列出的部分有：
| 类型 | 举例 |
|---|---|
| 开发板 | 立创实战派 ESP32-S3、乐鑫 ESP32-S3-BOX-3、M5Stack CoreS3、M5Stack AtomS3R + Echo Base、Waveshare ESP32-S3-Touch-AMOLED-1.8、LILYGO T-Circle-S3 |
| 现成小玩意 | 虾哥 Mini C3、Magic Button 2.4、璀璨 AI 挂件、SenseCAP Watcher |
| 机器人 | ESP-HI 低成本机器狗 |
| DIY | 面包板：ESP32-S3 开发板 + INMP441 麦克风 + MAX98357A 功放 + 小屏幕，仓库有接线图，另有飞书教程《小智 AI 聊天机器人百科全书》 |
买现成成品最省事，价格变化大，请自行查询。想 DIY 的话，选一块带 PSRAM 的 ESP32-S3 板，对着仓库的 docs/custom-board.md 和 main/boards/ 下已有板型改引脚定义即可。
上手路径
路线 A：直接刷现成固件，连官方平台
- 买一块支持列表里的板子，或买成品。
- 按作者的《小智 AI 固件烧录指南》刷入预编译固件。README 说明这个方式不用搭开发环境，烧录工具的基础知识见 烧录工具。
- 给设备配网，拿到验证码，到 xiaozhi.me 控制台绑定。
- 在控制台的智能体页面配置角色（人设提示词）、大模型、音色等。
路线 B：自己编译固件
- 按 README 安装 VS Code / Cursor + ESP-IDF 插件，SDK 至少 v6.0.1。作者建议用 Linux 编译，速度快、驱动问题少。
- 克隆仓库，
idf.py menuconfig选择板型，编译烧录。代码风格遵循 Google C++ 规范。 - 如需新板型，参考
docs/custom-board.md。
编译环境的基础知识见 ESP-IDF。
路线 C：自建服务器
不想依赖官方服务，可以部署社区服务端，然后在固件里把 OTA / WebSocket 地址改成自己的。见下一节。
xiaozhi.me 平台
官网 xiaozhi.me 的页面内容由前端渲染，本次抓取只拿到标题「XiaoZhi AI」。以下内容来自固件 README 和社区资料，官方控制台的实际功能请以登录后的页面为准：
| 项目 | 已知信息 |
|---|---|
| 默认后端 | 固件默认连接 xiaozhi.me 官方服务 |
| 免费政策 | 固件 README 称个人用户注册后可免费使用通义千问 (Qwen) 实时模型；一份硬件厂商文档提醒，免费不代表永远免费 |
| 控制台能力 | 设备管理（绑定、激活）、智能体（配置角色）、大模型与音色选择、MCP 接入点 |
| 模型 | README 写的是 Qwen / DeepSeek 等大模型；社区资料提到可选豆包 (Doubao)。具体可选清单随时变化，官方没有固定列表 |
| 价格 | 官方未在 README 中公布收费标准，未找到明确的付费档位说明 |
使用官方平台意味着你的语音数据会经过第三方服务器。有隐私顾虑的话，优先选择自建。
自建服务器与社区实现
README 的「相关开源项目」列出了几套服务端：
| 项目 | 语言 | 说明 |
|---|---|---|
| xinnan-tech/xiaozhi-esp32-server | Python + Java + Vue | 最成熟的社区后端，MIT 协议，约 1.1 万星（2026 年 10 月）。README 称由华南理工大学刘思源教授团队主导研发 |
| joey-zhou/xiaozhi-esp32-server-java | Java | Java 版服务端 |
| AnimeAIChat/xiaozhi-server-go | Go | Go 版服务端 |
| hackers365/xiaozhi-esp32-server-golang | Go | Go 版服务端 |
xinnan-tech 的服务端支持 WebSocket、MQTT+UDP 网关、MCP 接入点、声纹识别、RAGFlow 知识库、记忆系统，并带有 Web 智控台（用户、设备、智能体管理）。部署分两档：
- 最简化安装：Docker 或源码，只跑对话服务，配置存在文件里，无需数据库。
- 全模块安装：带数据库和智控台，多用户、多智能体。
它给出两套推荐配置：
| 模块 | 入门全免费 | 流式配置 |
|---|---|---|
| ASR | FunASR（本地） | 讯飞流式 ASR |
| LLM | glm-4-flash（智谱） | qwen-flash（阿里百炼） |
| TTS | EdgeTTS | 火山流式 TTS |
LLM 方面，任何兼容 OpenAI 接口的模型都能接入，也支持 Ollama、Dify、Coze、FastGPT、Home Assistant 等。TTS 支持 EdgeTTS、讯飞、火山、腾讯云、阿里云以及本地的 FishSpeech、GPT-SoVITS 等。
这个仓库的当前版本为 v0.9.7（2026 年 9 月 29 日）。
除了服务端，生态里还有使用同一协议的客户端：py-xiaozhi（Python 桌面端）、xiaozhi-android-client、100ask 的 xiaozhi-linux，以及面向其他芯片的移植（如思澈 SF32 蓝牙芯片版、移远 QuecPython 版）。
版本演进
| 阶段 | 时间 | 要点 |
|---|---|---|
| 0.x | 2024 年 9 月起 | 早期原型，release 从 v0.2.0 开始 |
| 1.0 | 2025 年 1 月 | v1.0.1（2025-01-23），随后 v1.1.0（2025-02-03）、v1.4.0（2025-03-03） |
| 1.6 | 2025 年 4 月 | v1.6.0 发布于 2025-04-14；社区资料称 MCP 从 1.6 前后引入。release 说明本身写的是内存优化、启动流程改为先检查版本、新增板型 |
| 1.9 | 2025 年 9 月 | v1.9.0（2025-09-04） |
| 2.0 | 2025 年 9 月 | v2.0.0（2025-09-12）：适配 v2 分区表、字体与资源定义移入 CMakeLists、LVGL 主题控制、GIF 支持 |
| 2.x | 2025 年底至 2026 年 | 持续增加板型与语言；2026 年起要求 ESP-IDF 6.x，MQTT / BluFi 加密迁移到 PSA Crypto，加入 ESP32-S31 构建 |
时间取自 GitHub release 页面。1.x 到 2.x 的具体不兼容变化（如分区表）以各版本 release 说明为准，升级前务必阅读。
生态与衍生
- 硬件厂商：乐鑫、M5Stack、Waveshare、LILYGO、Seeed 等都有官方或第三方适配；还有大量国内品牌的小智外壳玩具、挂件、桌面机器人，商品形态很杂，质量参差不齐。
- 服务端：见上节。
- 扩展：MCP 生态（ModelScope 魔搭上有大量 MCP 服务）、社区的音乐、新闻、留言等插件。
- 同类参考：想了解语音类玩法的全貌，可看 语音与 AI；想要成品智能音箱形态，可看 Home Assistant Voice PE。
常见用法与选型建议
| 目标 | 建议 |
|---|---|
| 先体验一下 | 买支持列表里的现成板子，刷预编译固件，连 xiaozhi.me，半小时内可以对话 |
| 做桌面机器人 / 摆件 | 选带屏幕的 S3 板（如立创实战派、AtomS3R + Echo Base），用设备端 MCP 注册舵机、灯光工具 |
| 控制智能家居 | 云端 MCP 接入点接 Home Assistant 的 MCP 服务，或在自建服务端里选 Home Assistant 作为 LLM 通道（xinnan-tech README 支持） |
| 隐私优先 / 离线倾向 | 自建 xiaozhi-esp32-server，ASR 用本地 FunASR，LLM 用 Ollama，TTS 用本地的 FishSpeech 等 |
| 做产品 | MIT 协议允许商用，但要注意第三方模型服务的条款，并自己负责服务端的稳定与合规 |
| 学习 | 读 main/ 下的 Application、Protocol、McpServer 几个核心类，再对照 WebSocket 协议文档 |
自建的几种链路在延迟与成本上的取舍，xinnan-tech 提供了性能测试脚本 performance_tester.py 和一个独立的组件性能报告仓库（xiaozhi-performance-research），可以在自己的网络下实测 ASR、LLM、TTS 各环节的耗时，再决定选哪家服务。
局限与注意事项
自建服务器与公网暴露
影响范围：把 xiaozhi-esp32-server 之类的服务端直接映射到公网时，WebSocket / OTA 接口、智控台、MCP 接入点都可能被陌生人访问，大模型 API Key 也可能被盗刷。xinnan-tech 仓库自己就写明「本项目功能未完善，且未通过网络安全测评，请勿在生产环境中使用」。
前置条件：优先只在局域网使用；确需外网访问时，放到反向代理后面、启用鉴权和 TLS，用 Cloudflare Tunnel 之类的方案也要加访问控制；API Key 设置额度上限。
回退：停掉服务、轮换所有 API Key 和 MCP token、把设备固件的服务器地址改回官方或局域网地址即可。
- 依赖云端：没有网络就没有对话；官方服务政策可能变化。
- 延迟取决于链路：从说完话到出声，通常取决于 ASR / LLM / TTS 各环节的响应速度，自建时流式方案明显更快。
- 音频质量取决于硬件：没有 AEC 的板子需要靠半双工，喇叭和麦克风靠得太近容易自激。
- 版本迁移成本：2026 年起要求 ESP-IDF 6.x，旧教程里的 5.x 环境步骤可能无法直接用。
- 第三方服务风险：xinnan-tech 服务端 README 明确提示，与对接的 ASR、LLM、TTS 厂商没有商业合作关系，充值与密钥安全由用户自己负责。
- 中文教程多在飞书和 B 站，更新比仓库慢，遇到差异以仓库文档为准。