平台连接排查：从日志确认适配器状态的定位法

平台接不上不猜，日志会告诉你答案。框架 WebUI「数据 → 日志」是唯一的真相源，这一页把三种典型症状的排查路径列成清单。

症状一：适配器一直未连接

日志里反复出现连接超时或「适配器已被关闭」：

OneBot v11 / NapCat 场景按序检查：

1. NapCat 侧 URL 是否写对——结尾必须有 /ws，完整形如 ws://主机:6199/ws
2. 地址视角对不对：都在 Docker 同网络用容器名（ws://astrbot:6199/ws）；只有 NapCat 在 Docker 用宿主机 IP；都裸机用 127.0.0.1
3. 两个容器各自跑各自网络时，官方文档给的解法是建一个共享网络把两个容器都接进去再重启
4. 框架侧主机填 0.0.0.0、端口 6199 与 NapCat 填的一致
5. 配了 Token 的话两侧是否一致
6. Docker 端口映射：宿主机访问的话 6199 映射行不能还是注释状态

QQ 官方机器人场景：核对开放平台凭证（AppID/Token）是否复制完整，WebSockets 与 Webhook 两种接入方式的配置项别混填。

症状二：连上了又频繁掉线

• 心跳间隔太长被中间设备掐断，NapCat 侧心跳与重连间隔改 1000 毫秒
• 云服务器安全组只放行了出站没放行入站的 6199
• Docker 容器重建后环境变量丢失，docker logs 看启动日志核对

症状三：连接正常但消息收不到

适配器已连接、机器人却装死，逐项过：

1. 唤醒问题：群聊默认不响应每条消息，要 @ 机器人或用唤醒前缀（默认 /），这是设计行为不是故障，详见不回话排查
2. 访问控制：该会话是否被自定义规则关掉了消息处理，或被黑名单挡住
3. 平台侧限制：Discord 的 Message Content Intent、Telegram 的群隐私模式，都是平台开关没开导致 Bot 根本收不到正文
4. 模型侧：消息进来了但模型调用失败，日志里找 API 报错，去模型 API 报错对号

万能三板斧

按架构链路逐段验证：平台侧有没有把消息发出来（NapCat / 平台后台日志）→ 框架日志里有没有收到消息的记录 → 流水线在哪一段断了（唤醒？权限？模型？）。三段日志一对照，问题必然现形。

排查时注意脱敏：日志与截图里的 Token、QQ 号、IP 打码再发群或提 Issue，官方文档在 MCP 一节特别强调过不要把含真实令牌的配置直接分享给他人。