常见问题与排查顺序
每次只改变一个条件，先确认问题发生在哪一步，再修改配置。反复刷不同板型固件，往往会把一个问题变成多个问题。
先定位问题
| 卡在哪一步 | 从这里开始 |
|---|---|
| 电脑找不到设备或烧录失败 | 串口与烧录 |
| 烧录完成但不开机、反复重启 | 启动与供电 |
| 找不到热点、无法联网 | 配网与网络 |
| 有设备码但绑定不了 | 账号与设备归属 |
| 无声音、听不见我、无法唤醒 | 音频与唤醒 |
| 黑屏、花屏、显示不全 | 显示问题 |
| 本地编译报错 | 开发环境 |
| MCP 工具没有出现或调用失败 | MCP 排查 |
串口与烧录
没有串口：先换一条确定能传数据的线，直接连接电脑，插拔观察设备列表；按板卡说明确认 USB-UART/原生 USB 和驱动。再尝试手动下载模式。
有端口但无法连接：关闭 IDE 监视器、串口工具和其他烧录页，重新进入下载模式。不要同时让两个工具占用同一个端口。
浏览器无连接按钮或提示不支持：使用桌面 Chrome/Edge 与 HTTPS；普通网页能打开，不等于具备 Web Serial。也可用离线烧录。
启动与供电
- 断电检查电源、相邻排针短接和扬声器输出；不通过反接来判断故障。
- 使用可靠 USB 电源和短线，先断开新增的电池/4G 等扩展恢复基础方案。
- 查看启动日志，记录版本、芯片、Flash/PSRAM 初始化及第一条错误。
- 如果只在播放或联网时重启，先检查供电、音量与负载；日志出现 brownout 时尤其如此。
- 如果 PSRAM、分区或显示驱动初始化失败，对照固件选择核对硬件。
日志采集可使用本地开发环境的 idf.py -p <端口> monitor，或串口工具。本文基础板通常使用 115200 波特率；其他板型按其说明。启动监视前释放烧录端口，分享日志前遮盖 Wi-Fi 密码、令牌和个人标识。
配网与网络
找不到 Xiaozhi 热点：先核对固件是否选择 BluFi 或其他网络方案，再确认进入配网。不能仅凭找不到热点就判定天线损坏，更不要缠线、触碰天线来“增强信号”。
连上设备热点但网页打不开：确认手机仍连着设备热点，直接输入 http://192.168.4.1，检查自动切网、VPN/代理。详细步骤见热点配网。
Wi-Fi 连上但设备不能对话：联网不等于能访问 OTA/对话服务。检查路由器互联网、DNS 和是否存在网页认证；可换可直接联网的 2.4GHz 手机热点对照测试。
更换网络：按具体板型的重新配网操作进入配置，不预设所有版本都只保存一个网络，也不把一次全片擦除作为默认解决方法。
账号与设备归属
| 问题 | 先做什么 |
|---|---|
| 收不到短信 | 确认区号、现有账号和页面提示；国际新账号按页面引导使用 Google |
| 验证码不正确 | 分清短信码与设备六位码，使用设备此刻显示的新码 |
| 设备已绑定 | 用原持有人账号按设备管理流程解绑；重刷不会清除服务器归属 |
| 添加到已有智能体失败 | 读取当前设备类型/数量限制提示，确认自己的操作入口和账号 |
不要在公开 Issue 中发布设备验证码、完整 MAC、账号手机号或身份证明。归属争议通过官网控制台提供的支持渠道处理。
音频与唤醒
- 有提示音，但听不见我：先用按键发起对话，核对麦克风电源、数据方向、L/R 和拾音孔；基础方案见麦克风接线。
- 识别到问题，但扬声器无声：核对音量、功放使能、DIN/BCLK/LRC 和负载。不要把扬声器端改接共地耳机；见音频输出。
- 按键可对话但唤醒不了：检查固件是否关闭唤醒、所选模型与芯片/内存是否匹配。C3 与 S3 可用模型不同，不能笼统断言所有 C3 都不支持唤醒。
- 想改唤醒词：先看在线编译提供的兼容值；自定义词还受芯片、PSRAM 与配置条件限制，不是所有板型都能直接输入任意文字。
- 开了 AEC 仍有回声：确认音频参考信号与支持的硬件路径。编译开关不能代替电路与声学设计，参照固件音频配置。
BluFi 是 Wi-Fi 配网能力，不能由此推断可以连接蓝牙耳机。
显示问题
黑屏时按“型号/驱动 → 供电 → I2C/SPI 引脚 → 地址/分辨率 → 固件变体”核对。SSD1306 128×32、128×64、SH1106 和 SPI LCD 不是同一个配置。
有声音但无显示时，先保存日志，不直接判定主控损坏。板载 RGB 在不同硬件修订中管脚也可能不同，不能用一种颜色作为全平台错误码。
开发环境
本页适用小智固件 v2.6.0：最低 ESP-IDF 6.0.1，建议 release/v6.1 分支。不要混用 IDF 5.x 的环境、旧 sdkconfig 和新源码。切换 SDK 后按本地构建清理并重新配置。
Windows 出现 Ninja CreateProcess 命令行过长错误时，查看构建指南中的 response file 处理；不要把关闭安全软件作为通用步骤。
MCP 工具
按“本地工具能启动 → 桥接连上端点 → 控制台发现工具 → 对话实际调用”逐段核验。端点所属智能体、进程退出、标准输出混入日志都会影响接入，详见MCP 快速开始。
串口采集的完整步骤见获取串口日志，账号归属问题见登录与解绑。
反馈前记录这些信息
提供页面地址、实际步骤、预期/实际结果、芯片与板型变体、固件版本、供电方式和经过遮盖的错误日志。接线问题附断电状态下能辨认丝印的照片。
下一步
回到快速开始重走对应环节。仍无法定位时，使用页面下方的“反馈文档问题”，说明哪一步不能复现。