看懂任务和日志

出了问题去看日志，这个道理大家都懂。但 Desktop 里的日志不止一份，安装失败和 Bot 不回复，要看的根本不是同一个地方。先弄清楚问题出在哪个环节，再去对应的入口找，会省很多时间。

任务队列

1. 发起安装或部署后，打开侧栏「任务」。切到别的页面去也没关系，后台任务不会因此停下。
2. 用「进行中」筛选找到这个任务，核对标题和目标主机。
3. 点左侧的条目，右侧会显示状态、耗时、进度，以及每一步的日志。
4. 下载的时候能看到当前用的是哪个源、速度多少、为什么换源；Docker 拉镜像还会显示每一层的进度。
5. 等它跑完。如果失败了，记下是哪一步失败、第一条错误是什么。只截一句「任务失败」，别人也帮不上忙。

任务队列：左侧定位任务，右侧检查进度与步骤日志 · 演示数据

显示排队中的任务还没开始。进度百分比也不一定是匀速走的，下载完了后面还有解压、安装、校验这些步骤。

取消、强制停止和清理

选中任务后，可以用界面上的按钮取消排队，或者停止运行。像系统包管理器、Docker 安装这类正在改系统的任务，强行停下来可能会出问题，所以不支持强停，按钮上会写明原因，这种时候只能等当前步骤结束。

取消并不会回滚。之前已经下载或安装好的东西还在，重试前先看看任务说明和组件检测结果。

「已结束」里有成功的、失败的，也有取消的。清理只是把列表里的记录删掉，并不会卸载任何组件。想留着排错信息的话，先复制步骤日志和任务 ID，再清理。自动清理的时间可以在「设置 → 监控 → 任务队列」里调。

检查 Bot 日志

1. 在「机器人」里找到出问题的 Bot，打开日志。
2. 对照你点启动的时间，从启动那一段看起：QQ／运行时路径、端口、WebUI、登录状态和 OneBot 连接。
3. 启动后马上退出的，重点看退出前的那几行错误；只是 QQ 没登录上的，回登录入口去处理。
4. 准备重试的话，先把原始错误记下来，然后每次只改一项配置。

Bot 日志：把错误与启动时间、协议端和账号对应起来 · 演示数据

OneBot 报连接被拒绝，查一下监听的进程、地址和端口；报鉴权失败，就核对两边的 token。详见 连接配置 和 排错。

检查应用端日志

1. 打开「应用端」，进对应实例的「日志」。
2. 先确认实例和主机没选错，再看启动阶段：依赖、配置解析、监听端口有没有报错。
3. 排查「不回复」的问题时，盯住你发测试消息的那一刻：有没有收到事件、规则有没有匹配上、模型或者插件有没有报错。
4. 如果你同时也在用上游的 WebUI，可以对照着那边的状态和日志一起看，但别两边同时改配置。

日志是空的，先确认实例到底有没有启动；显示「等待新日志」，可能只是暂时没有新的输出。AI 请求失败的话，要分清楚是模型名写错、鉴权失败、额度用完、网络不通，还是会话规则拦住了。

Desktop 自身日志

1. 打开「设置 → 日志」。
2. 用级别筛选和关键词搜索缩小范围，比如搜 SSH、某个组件名，或者报错里出现的一段路径。
3. 日志一直在往下滚的话，先暂停自动滚动，再慢慢看操作前后的内容。
4. 点刷新可以重新读取。需要完整的日志文件，点「打开位置」去日志目录里找。
5. 「复制」复制的只是当前能看到的那部分。提交之前看看筛选条件，别把关键的内容滤掉了。

字太小的话，可以用工具栏放大。日志页不需要点「保存设置」。

发 Issue 时给出可复现的信息

按下面这个格式整理一下，别人看了才能复现你的问题：

Desktop 版本：
协议端及版本：NapCat / SnowLuma
运行位置：本机 / 远端 Linux / 远端 Windows
部署方式：原生 / Docker
应用框架及版本（涉及时）：
我做了什么：
1.
2.
预期结果：
实际结果：
错误时间与完整错误：

把相关的任务步骤，或者出错前后的日志一起附上，并把 token、密码、API Key、邮箱授权码、SSH 私钥和私人消息遮掉。错误码、端口对应关系、打过码的路径，这些信息比一张弹窗截图有用得多。

接着看：常见问题逐项排查 · 网络下载 · 远端部署