错误码与排查

设备接入按阶段分段排查。看不到后台日志时，优先用控制台「设备管理 → 实时联调」观察链路在哪一步中断。

连接 / 握手阶段

现象	常见原因	排查建议
WebSocket 立即断开	JWT 无效或过期	重新调用 /api/ota/ 刷新 token
连上但无响应	设备未绑定	先完成激活绑定流程，OTA 响应不再含 activation 即表示已绑定
握手无 server hello	hello 报文格式错误	检查 type/transport/audio_params 字段
MQTT 拒绝连接	client_id 格式或密码(JWT)错误	使用 OTA 返回的 client_id 与 password 原样填入

现象	常见原因	排查建议
无 ASR 结果	上行音频未到 / 格式不符	确认 Opus 60ms 16kHz；联调台看 audio_in 帧数是否在涨
UDP 音频被丢弃	nonce/key 不匹配	使用 hello 下发的最新 key/nonce，ssrc 取自 nonce
听不到 TTS	设备未播放下行音频	联调台看 audio_out 帧数；若已下发则为设备播放问题
MQTT 正常但无语音	UDP NAT 映射失效 / 防火墙拦 UDP	实现 type=0x02 心跳；无 Pong 则重新 hello；或降级 WebSocket
动作不执行	name 未实现 / 参数解析失败	对照「指令字典」，params 是 JSON 字符串需二次解析