出了问题，先从这里查

出了问题先别急着重装，大部分时候重装解决不了问题，反而会把现场破坏掉。一个 Bot 从无到能回消息，要依次经过这几个阶段：下载 → 安装 → 进程启动 → QQ 登录 → OneBot 连接 → 应用处理消息。前面一步成功了，不代表后面就一定没问题。先找准卡在哪一步，再对症处理，会快很多。

先记下这四样

1. Desktop、NapCat / SnowLuma 和应用框架各自的版本。
2. 跑在哪里：本机 Windows、远端 Linux 还是远端 Windows；原生运行还是 Docker。
3. 刚才做了什么操作，界面上最先冒出来的错误是什么。
4. 出错前后那段时间的任务日志、Bot 日志或者应用日志。

不同的问题看不同的日志：安装失败看「任务」，QQ 启动和协议上的错误看 Bot 日志，应用报错看应用实例的日志，容器退出看 Docker 日志。也要注意别看错了对象，拿另一个 Bot 或者另一台主机的日志来排查，是查不出结果的。

下载慢或一直失败

先看下载发生在哪

Desktop 里配的代理，不会自动传给 SSH、Docker 或者应用框架，详见 网络设置。

Desktop 自己的下载

1. 打开「设置 → 网络」，看看「代理模式」和你实际在用的代理软件对不对得上，地址和端口有没有填错。
2. 点「测试连接」，检查 GitHub API 和各个下载源。测试不会保存配置，而且测出来的响应耗时也不等于下载速度。
3. 测试通过以后「保存设置」，再重新下载。已经开始的下载不会中途切换代理和线路。
4. 用的是指定镜像、而且失败了的话，换一个镜像，或者改回自动选择。指定镜像是不会自动帮你换源的。
5. 看下载进度里显示的源、速度和换源原因。自动模式有时会重新下载，那是为了避免把不同来源的文件拼在一起，并不是缓存坏了。

GitHub API 和安装包的下载线路是分开配置的，给 API 填了 PAT，并不会让镜像下载变快。PAT 也不要发给下载镜像，更不要贴到公开的地方。

安装任务失败

1. 去「任务」里找到这次失败的任务，看是在哪个阶段失败的：下载、解压、装依赖，还是写入目录。
2. 回到「组件」，确认选中的主机对不对。远端的组件必须装在远端那台机器上，本机装的同名组件替代不了。
3. 下载失败的，按上一节处理；缺系统依赖的，按组件检测结果补齐；写入失败的，查一下目录和执行用户的权限。
4. 先解决第一条具体的错误，再重新提交任务。任务还在跑的时候，不要重复安装同一个组件。

如果是应用实例安装失败，还要看看框架日志、运行时版本，以及仓库能不能正常下载。你手上已经有现成项目的话，可以按 应用端指南 导入进来，别新建一个实例去覆盖一个你不清楚来历的目录。

Bot 一启动就停

原生运行（本机或远端）

1. 打开 Bot 日志，找进程退出前的第一条错误。
2. 看 QQ、底座和运行时是不是都被组件页识别到了，目录是不是在当前运行的这台主机上。
3. Linux 原生运行的，查组件提示缺少的系统库；Windows 远端的，查工作进程和目标用户的桌面会话。
4. 看看同一个 QQ 号或同一个 Bot，是不是已经被别的启动器跑起来了。先弄清楚原来那个进程归谁管，再决定是停掉它还是重新启动。

远端 Windows 如果只有服务在跑、没有用户登录桌面，先去修 托管会话。装 Linux 那套显示环境是解决不了 Windows 的问题的。

Docker 运行

打开「容器」，选好主机，找到这个容器，看「详情」和「日志」，重点关注退出码、是不是因为内存不足被终止、端口和挂载。也可以在远端终端里做一些只读的检查：

docker info
docker ps -a --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'

看到 permission denied，先查 SSH 用户有没有 Docker 权限；容器退出了，就看容器日志；容器在跑但 QQ 没登录，看下一节。更多见 Docker 部署。

显示运行中，但 QQ 没上线

「运行中」只说明进程或者容器还在。打开卡片上的 WebUI 或扫码入口，确认手机上已经点了确认登录，再看协议端识别到的是不是正确的账号。

NapCat Docker 的有效 token，以容器当前使用的 webui.json 为准，不一定是你当初创建容器时填的那个。更新 Desktop、重新连接以后还是失败的话，查一下配置读取权限、有没有被限流、是不是需要两步验证。

SnowLuma 的扫码开关不会自动重启 QQ，也不会帮你补装依赖。刚打开开关的，按 扫码指南 冷启动一次，或者用回退入口登录。

QQ 在线，应用端收不到消息

这种情况最常见。一条一条往下核对，先让一条连接跑通，不要同时建好几条连接去碰运气。

1. 连接方向正确吗？ 正向 WebSocket 是应用端去连协议端，反向 WebSocket 是协议端去连应用端。如果把监听地址填到了负责主动连接的那一边，就会连错。
2. 应用端开着吗？ 应用实例有没有在运行，对应的 OneBot 适配器装了没有、启用了没有。
3. 地址属于哪台机器？ 127.0.0.1 永远指的是当前进程所在的那台机器或者那个容器，代表不了另一台服务器。
4. 端口可到达吗？ 监听 IP、监听端口、Docker 发布的端口、防火墙，以及实际访问的端口，这几样要能对得上。
5. token 和路径一致吗？ 检查两边的鉴权和 WebSocket 路径，留意有没有多出来的空格、大小写对不对、前缀有没有漏。
6. 双方使用相同的 OneBot 版本和连接角色吗？ API、事件和通用连接的用途不一样，一条只收事件的连接，是调不了 API 的。
7. 配置保存并加载了吗？ 保存以后按提示重启或重连，再看两边的日志里有没有建立连接。

连接建立以后，可以先在 调试台 发一个只读的账号信息请求，再给 Bot 发一条测试消息，看看事件有没有过来。如果 API 能调通，应用却不处理消息，那就接着查事件连接和插件的逻辑，问题不在 QQ 登录上。

WebUI 里改过，重启又变回来了

这是因为 Desktop 启动远端 Bot 时，会用它自己保存的连接配置去覆盖远端的配置。打开 Bot 的「配置 → 连接 → 从远端读取」，核对差异后保存到 Desktop 里。只在协议端 WebUI 里改的话，Desktop 这边是不知道的。

聊天页或调试台找不到某个 Bot

先确认 Bot 在线，需要的 OneBot 连接也能用，再看看「设置 → 功能」是不是把对应的入口给隐藏了。另外，后台接收、账号用途和账号托盘都是每个账号单独设置的，打开了一个聊天窗口，不代表所有账号都在后台接收消息。

聊天里的媒体加载、群文件和导出问题，见 聊天指南；接口参数和事件相关的，见 调试台。

SSH 连不上，或重连后状态不对

连接测试直接失败

1. 核对主机地址和 SSH 端口，确认网络路径、安全组和防火墙都放行了你的来源地址。
2. 核对用户名和认证方式。Windows Hello 的 PIN 码不是 SSH 密码；用密钥认证的话，选的应该是私钥文件。
3. 第一次连接时的主机指纹，要和服务器那边核对。如果主机重装过，或者地址被别的机器复用了，指纹会变，先弄清楚是怎么回事。
4. 连上以后刷新一下库存，确认系统类型、路径和权限都没问题。

SSH 恢复了，Bot 状态还是未知

先刷新主机和 Bot 的状态，再看远端日志，确认原来的进程还在不在。在确认之前，不要手动再开一份同账号的 Bot。Desktop 退出了、SSH 断开了、远端进程停了，这是三件不同的事。

如果是远端 Windows，还要看绑定的用户有没有注销、桌面工作进程是不是就绪；Linux 原生的，查一下程序和系统依赖。详见 Linux 或 Windows 指南。

Desktop 退出后没收到通知

1. Bot 的「掉线时发送通知」打开了吗？通知渠道测通了吗？设置保存了吗？
2. 在「设置 → 通知 → 远端脱管监控（NCD Watch）」里刷新主机状态，确认已经安装并且同步成功了。
3. 普通通知要等 Desktop 的心跳过期以后才会接管，默认是 90 秒。Desktop 在线的时候，出现 desktop_present_skip=true 是正常的。
4. 在 Linux 上，看看断开 SSH 以后服务还在不在。如果用户服务被停掉了，按 值守指南 检查 linger 设置。
5. 远端能不能访问到 Webhook / SMTP；互助 Bot 必须和被监控的 Bot 在同一台机器上，而且在线、连接可用。
6. Docker 的话，检查容器名、执行权限和实际的 WebUI 端口，不要只看你推算出来的端口。

开了重登二维码的，查一下 capabilities、relogin-status 和服务日志，注意 once 是不会运行重登指令服务的。第一次等待登录、手动停止、状态未知，这几种情况都不会发重登码。也别去删账本来「重置」，那样可能会导致通知被重复投递。

导入了配置还是启动不了

配置包里不含组件程序、插件程序、数据库和系统密钥库。所以换电脑以后，要先装好框架和插件、核对好安装路径，再恢复配置；SSH 密码、GitHub Token 这些存在密钥库里的凭据，也需要重新填。

到「设置 → 数据」里看看：

• 界面偏好待恢复：点「重试恢复界面偏好」，不用把整个配置包重新导入。
• 框架配置待恢复：先装好实例、停止实例、恢复远端连接，再点「重试恢复框架配置」。
• 远端身份变了：主机地址、端口或用户名改过的，先在远端页重新测试连接，再去恢复。

应用实例的档案保留的是原来的主机和安装路径，换了电脑它不会自动改成新路径。完整的步骤见 备份与迁移。

提 Issue

实在搞不定，就来提个 Issue。复制下面这个模板，把自己的情况填进去：

Desktop 版本：
底座及版本：NapCat / SnowLuma
应用框架及版本（有关时填写）：
运行环境：本机 Windows / 远端 Linux / 远端 Windows
部署方式：原生 / Docker

我想完成的操作：
1.
2.

预期结果：
实际结果：
第一次出现错误的时间：
已核对的项目：
相关日志：

日志只截出错前后那一段就好，但要保留原始的错误、堆栈和必要的上下文。记得把 OneBot token、WebUI 密码、通知地址里的密钥、API Key、SSH 私钥和私人消息都遮掉，不要贴整个配置 ZIP，也不要贴登录二维码。端口、连接类型和替换过的主机角色可以留着，方便别人判断网络方向。

整理好以后，提交到 GitHub Issue。如果只是文档里某一步没看懂，也可以附上页面地址和你卡住的地方，我们会改得更清楚一些。