排查接入与运行问题

优先记录请求路径、发生时间、HTTP 状态、业务 code 和关联任务 ID，再按下面的顺序排查。

现象	先检查什么	相关文档
无法连接 API	IP、网络路由、8898 监听端口；不要沿用旧 8899	连接设备
API 返回 401	当前认证方式、唯一的 Authorization 头、API 与终端 token 是否混用	认证规则
健康检查成功但无法导航	运动、扫描、导航容器、地图和定位状态	导航环境
启动返回失败步骤	failed_step 与 steps_completed；已成功步骤不会自动回滚	导航环境
请求成功但机器人没有完成任务	是否仅受理；查询关联任务状态与错误	任务与状态
建图结束后看不到可用地图	建图任务是否成功、文件保存校验是否通过	建图指南
修改参数后没有生效	保存值、运行值和逐参数应用结果；是否等待启动回放	导航参数
地图内容冲突	父版本、当前安装版本和返回冲突信息	地图同步
SSE 鉴权失败	启用 Bearer 时使用能携带请求头的客户端	实时协议
MQTT 有回执但任务仍执行中	回执只表示命令处理结果，继续查询任务	MQTT

提供问题信息

向交付或支持人员提供设备型号、软件版本、相关任务 ID、复现步骤以及错误响应。分享日志前移除访问令牌、密码和业务敏感数据。

日志接口见 日志管理。