小智 xiaozhi-esp32 上手指南让一块 ESP32 变成会聊天的 AI 硬件【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32晚上随口喊一声桌面上的小设备它能用语音回答你、顺手调个灯——这就是小智 ESP32 AI 聊天机器人xiaozhi-esp32能做到的事。这个开源项目把带麦克风、喇叭的 ESP32 开发板接入 Qwen / DeepSeek 等大模型通过 MCP 协议实现语音对话与多端控制。下面按先跑起来、再搞明白的顺序带新手和普通用户完成最小可用安装。这个项目能做什么一句话概括以语音交互为入口在小型芯片上完成听清你 → 理解你 → 回答你 → 控制外设的完整闭环。对使用者真正有价值的三点离线语音唤醒设备在本地识别唤醒词不用按按钮、不用联网才能叫应它还支持更换自定义唤醒词。连续语音对话语音经 Opus 编码传输识别、大模型生成、语音播报形成闭环过程可在 OLED/LCD 屏上显示表情和字幕具备 AEC 的硬件还能实现实时全双工交互说话与回答可重叠。MCP 协议控制设备端可直接控制音量、灯光、舵机、GPIO 等云端侧可扩展智能家居、知识搜索、邮件收发等能力。仓库已支持 138 个板卡目录、171 个固件发布变体覆盖 ESP32、ESP32-S3、C3、C5、C6、P4 等芯片平台因此你手里常见的开发板大概率能直接用。动手前需要准备什么按最小必需来列其余都可以后补类别最小必需项说明硬件一块 ESP32 系列开发板优先选集成了麦克风、喇叭、屏幕的一体板如立创实战派、乐鑫 ESP32-S3-BOX3、M5Stack CoreS3免接线全部板卡目录见 main/boards/硬件散装I2S 数字麦克风 小喇叭无一体板时必需屏幕可选接法参考下图网络家中 Wi-Fi设备开机后自动进入配网模式软件烧录工具新手直接用免开发环境的预编译固件即可无需装编译器账号官方服务器账号固件默认接入官方服务器个人用户注册后免费使用 Qwen 实时模型如果你打算从源码编译进阶环境要求是VSCode 或 Cursor ESP-IDF 插件首选 v6.0.2 稳定版v5.5.2 仅保留给少数旧板卡系统上 Linux 比 Windows 编译更快、驱动问题更少。最小可行安装路径共六步每步都给出成功判据。1. 获取源码执行git clone https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32。完成后进入目录能看到main/、partitions/、scripts/即正常。2. 选定开发板在 main/boards/ 下找到与你硬件同名的目录。每个板卡目录包含xxx_board.cc板级初始化、config.h引脚与音频配置、config.json板卡类型上报与构建配置。找不到同名目录说明暂不直接支持可先换一体板或参考自定义板卡文档。3. 烧录固件新手用预编译固件一键烧录源码编译则运行python scripts/build.py 板卡目录名如esp32-s3-box-3。成功判据开发板重启后出现启动画面与正常界面语言。4. 配网设备首次启动且没有已存 Wi-Fi 时自动进入配网支持热点配网和 BluFi 蓝牙配网两种方式二者只能启用一种见 docs/blufi.md。成功判据设备显示已连接 Wi-Fi 并开始接入服务器。5. 激活设备登录官方服务器控制台绑定设备、选择大模型。成功判据设备状态变为在线不再提示激活。6. 试对话说出唤醒词问一个简单问题。成功判据有提示音响应且听到完整的语音回答——到这里最小可用状态就完成了。关键配置说明真正影响能不能跑起来的配置只有几项其余保持默认即可配置项所在位置作用建议板卡类型type板卡目录下config.json决定固件身份与 OTA 升级通道必须和实际硬件一致与所购板卡同名的值发布后保持稳定配网方式idf.py menuconfig中 WiFi Configuration Method决定首次如何录入 Wi-Fi默认热点用 BluFi 需关闭热点选项服务器地址与令牌设备端设置音频流和对话请求的入口官方服务器默认值或自部署服务器ESP-IDF 版本开发环境插件源码编译所需 SDKv6.0.2分区表partitions/v2/v2 新增 assets 分区支持唤醒词、主题、字体等资源联网下载更新v2 系列注意与 v1 不兼容特别提醒v2 分区表与 v1 不兼容v1 硬件无法通过 OTA 升到 v2必须手动烧录新固件。详见 partitions/v2/README.md。如何验证与排错验证顺序按序执行某步失败就停在该步处理开机屏幕或 LED 正常显示启动过程网络配网成功设备状态进入连接服务器唤醒喊唤醒词有提示音问答提问后听到完整语音回答屏幕有对应对话显示。高频问题现象可能原因处理办法连不上 Wi-Fi凭据填错或旧的已存 SSID 干扰核对 SSID 和密码清除wifi命名空间中保存的配置后重新配网唤醒词没反应唤醒词模型在首次启动时从 assets 分区联网下载网络异常则失败检查网络后重启设备让资源重新下载烧录失败数据线只能充电、驱动缺失换确认可用的数据线Linux 下驱动问题更少或重装串口驱动v1 设备升级 v2 失败两版分区表不兼容不支持 OTA 互升用烧录工具手动烧录 v2 固件服务器一直连不上服务器地址或令牌错误核对设备端设置WebSocket 握手超时默认 10 秒可参考 docs/websocket.md 检查请求头与 hello 消息进阶方向跑通之后可按兴趣选一个方向深入均无需重写项目设备端 MCP 控制音量、灯光、舵机、GPIO用法见 docs/mcp-usage.md云端 MCP 能力智能家居、PC 桌面操作、知识搜索、邮件协议细节见 docs/mcp-protocol.md自制开发板新建板卡目录编写config.h与config.json注意保持板卡标识唯一以免 OTA 通道冲突指南在 docs/custom-board.md通信方式替换更看重弱网稳定性时可改用 MQTT UDP 混合通道文档在 docs/mqtt-udp.md自部署服务器社区有 Python、Java、Golang 等多语言服务器实现可自行搜索部署摆脱对官方服务器依赖。下一步建议先买一块能买到的一体板、用预编译固件走完上面六步听到它应答的那一刻最难的部分就过去了之后再进开发环境学源码编译把设备改造成你自己的样子。【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考