设备连接失败：从头诊断
设备"连不上"可能发生在任何一层：启动、配网、激活、服务端连接或对话。按下面的顺序逐层排查，先确定断在哪一层，再进入对应解法；每一步都给出"怎么判断"与"去哪里修"。
第一步：设备能启动吗
判断：通电后屏幕或指示灯有反应（表情、配网提示或 LED 变化）。
| 现象 | 最可能原因 | 解法 |
|---|---|---|
| 完全无反应 | 供电不足或接线错误（候选）；烧录场景还可能是 USB 线只供电不传数据 | 核对硬件搭建指南的接线与供电；面包板方案确认 VDD/GND 未接反；烧录不通时换一根确认支持数据传输的 USB 线 |
| 反复重启 | 固件与板型不匹配、供电不稳 | 确认烧录的变体与板型一致（见固件下载），换供电再试 |
第二步：能进入配网吗
判断：首次通电后设备屏幕显示 Xiaozhi-XXXX 热点提示。
- 找不到热点：确认设备没有已保存的 Wi-Fi（有则长按按钮重新进入配网，见 FAQ Q10/Q11）；
- 热点连上但
192.168.4.1打不开：换手机浏览器或关闭移动数据再试； - 详细步骤与失败处理见首次启动与网络配置。
第三步：能连上 Wi-Fi 吗
判断：配网页选择路由器并输入密码后，设备重启并显示联网成功（屏幕显示时间或在线状态）。
| 现象 | 最可能原因 | 解法 |
|---|---|---|
| 一直"连接中"后失败 | 密码错误；频段候选原因之一 | 多数小智芯片只支持 2.4GHz，路由器双频同名 SSID 时可能关联失败（ESP32-C5 等双频芯片不受此限）；给 2.4G 单独设 SSID 再试 |
| 连上很快断开 | 信号弱、路由器拒绝新设备 | 靠近路由器；检查路由器的设备准入与 MAC 过滤 |
| 4G 模组连不上 | 4G 需要安全连接 | 自建服务端场景见自建服务端的 4G 说明 |
第四步：能激活吗
判断：联网后设备显示并朗读 6 位激活码；在官方控制台输入后绑定成功。
| 现象 | 最可能原因 | 解法 |
|---|---|---|
| 看不到激活码 | 设备实际未联网或连的是别的服务端 | 回到第三步；自建服务端场景确认 OTA 地址已生效 |
| 控制台提示绑定失败 | 激活码过期或设备已绑定其他账号 | 重启设备获取新码；解绑后再试 |
| 完整排查表 | — | 首次启动末尾的排查表 |
第五步：能连上服务端吗
判断：绑定成功后唤醒设备，服务端有响应（官方服务有声音与表情反馈；自建服务端看日志）。
- 用官方服务：先确认服务本身可用（控制台能登录、其他设备正常），再检查设备 OTA 地址是否为官方地址；
- 自建服务端：设备 OTA 地址指向你的服务器；用浏览器打开 OTA 地址应返回正常提示，WebSocket 地址用局域网 IP 而不是
localhost；语音链路按自建服务端的「预期检查」分阶段排查（识别文本 → 模型响应 → TTS/音频帧 → 设备实际播放）； - 4G 设备连自建服务端：需要 TLS（nginx + 证书），详见该项目 FAQ。
第六步：能对话吗
服务端链路全部正常（第五步的分阶段检查通过）而仍"说话没反应"或"没有声音"时，才进入音频层排查：
- 唤醒没反应：麦克风问题或唤醒词不适用当前板型（见 FAQ Q9）；
- 有回应没声音：喇叭接线与音量（FAQ Q6/Q8）；
- 音质异常：FAQ Q7。
已核实的社区案例（来源绑定）
以下案例来自上游仓库已关闭的高互动 Issue，只在其声明的固件版本与硬件组合内成立，本站未复现；新版本是否已修复以对应 Issue 与 Release 说明为准：
| 症状 | 适用范围 | 报告与条件（非通用修复） | 来源 |
|---|---|---|---|
语音请求拍照后屏幕锁死、再次唤醒报 AFE: ringbuffer is full，可稳定复现 | bread-compact-wifi-s3cam + OV3660，报告固件 v2.0.5-20-gf408817（日志为 2.1.0） | 报告人个人的条件性结论：XCLK 改 24 MHz、分辨率 240x240 后拍照成功（12-23 评论），12-24 以"24M 较合适、240x240 或 640x480 可用"关闭（关闭总结）；但 12-30 另一用户同配置（240x240/24M）仍失败（评论），维护者询问 menuconfig 是否启用 OV3660（评论），该用户确认已启用仍失败（评论）。同配置 OV2640 正常、#1245 完成 esp_video 迁移是背景事实，但均不构成本案例的通用根因或已验证修复；参数调整只在这位报告人的板子上验证过。本站未复现 | Issue #1588（2025-12-24 关闭，31 评论） |
排查原则
- 先分层再深入：启动 → 配网 → Wi-Fi → 激活 → 服务端 → 对话，逐层确认；
- 版本与变体优先：板型与固件变体不匹配是"奇怪现象"的常见候选原因之一（非唯一来源，亦非统计结论）；
- 一次只改一处：改完立即验证，避免多变量叠加无法定位。