机器人管理

「机器人」页按 QQ 账号管理协议端实例，一个账号对应一张卡片。第一次创建的过程在 创建第一个 Bot 里讲过了，这里讲的是之后天天会用到的：启停、改配置和日常维护。

卡片上的状态

机器人列表：每个账号有独立的运行位置、进程状态和登录状态 · 演示数据

进程显示运行中，并且 QQ 已登录，账号这一侧才算真正就绪。如果一直停在「探测登录」，先去看看 WebUI 和日志，不要急着下结论说 QQ 掉线了。远端主机连不上的时候也要分清楚：是 SSH 断了，还是远端的程序真的停了，这是两回事。

启动、扫码、停止

1. 启动前核对卡片上的 QQ 号、底座和主机。
2. 点启动，等它完成。别连着点好几次。
3. 卡片提示扫码时，用扫码入口或者协议端的 WebUI 完成登录。
4. 跑起来以后，按需打开 WebUI、日志或者「更多工具」。
5. 要停的时候点「停止 Bot」。打算改底座、更新组件或者挪数据的话，等进程状态稳定下来再动手。

远端 SnowLuma 的 WebUI 和 noVNC 依赖对应的服务和 SSH 隧道，入口还没准备好时，先看卡片上的提示，详见 远端登录。

有些按钮只有一个图标，把鼠标移上去会显示「查看日志」「配置参数」「更多工具」之类的提示。

修改配置

在卡片上打开「配置参数」，里面分「身份」「连接」「高级」三页。

1. 改你要改的字段。
2. 底部会出现「未保存」，点「保存」或者按 Ctrl+S。
3. 留意保存后的提示：是已经生效了，还是需要重启。

「撤销」只能丢掉还没保存的修改，已经保存的就撤不回来了。运行中不能切换底座，要先停止。编辑时 QQ 账号是锁定的，想换个账号用，就新建一个 Bot。

出现「配置冲突解决」

如果你在协议端的 WebUI 或者配置文件里也改过东西，启动或保存时可能会发现，运行时的文件和 Desktop 里存的不一样。这时逐项对比：想用 Desktop 表单里的值就选桌面端，想保留文件里的改动就选运行时。运行时那边新增的字段，可以单独决定留还是不留。

「全部选桌面端」「全部选运行时」会一次性全选同一边。没想好的话先取消，备份一下再处理。远端的 OneBot 连接也可以先用「从远端读取」同步过来，见 连接配置。

身份：账号、主机和自愈

改运行位置会连带着改变程序、路径和网络。先在目标主机上把组件准备好、把连接测通。只改一个下拉框，数据是不会跟着搬过去的。

设置定时重启

1. 打开「身份 → 自愈与附加服务」，开启「定时自动重启」。
2. 选「每隔」「每天」「每周」「每月」或者「自定义 cron」。
3. 比如想每天凌晨重启一次，就选「每天」再挑个时间。页面上会显示「下次」执行的时间，先确认一下对不对。
4. 保存。

自定义 Cron 用的是「分 时 日 月 周」五段，按本地时区预览。能用选择器就尽量用选择器，别的系统里带秒的表达式没法直接粘过来用。按月重启选了 29、30、31 日的，碰上没有这一天的月份会直接跳过。

掉线自动重启和定时重启解决的不是同一类问题。如果它一直崩溃，或者登录总出异常，要先找到根本原因。自动重启救不了配置错误，也替你过不了 QQ 的安全验证。想在 Desktop 退出后继续看着远端的 Bot，见 ncd-watch。

SnowLuma：冷启动与热启动

• 冷启动（默认）：由 Desktop 拉起并托管 QQ 进程。
• 热启动：附加到一个已经登录了这个 QQ 号的 QQ 进程上。

先用默认的冷启动跑通。要用热启动的话，得先确认目标机器上确实有一个已经登录这个账号的 QQ。远端 Windows 还需要可用的桌面会话，见 远端 Windows。

连接

HTTP、SSE、Webhook、正向和反向 WebSocket 都在这一页配。每条连接有自己的名称、启用开关和 Token。先点「保存连接」，再保存 Bot 配置。方向、端口和验证方法见 连接应用端与 OneBot。

已经保存过的 Bot 可以在这里「对接应用端」。在远端 WebUI 里改过连接的，先「从远端读取」核对一下差异再保存，不然下次启动时会被 Desktop 里的旧配置覆盖掉。

高级：启动、通知与协议端选项

「随桌面端自动启动」的意思是打开 Desktop 时自动把这个 Bot 拉起来，它和「开机自动启动 Desktop」是两个不同的设置。

「掉线时发送通知」打开以后，还要在「设置 → 通知」里启用并测通推送渠道，否则通知发不出去。SnowLuma 改了马上生效，NapCat 要按提示重启后才生效。见 设置；远端独立通知见 ncd-watch。

NapCat 的高级页里还有：

• 本地文件到 URL、合并消息上报解析：按下游应用的需要调整。
• 文件日志、控制台日志与等级：改了核心日志配置要重启 Bot。排查完问题，可以把日志等级调回来。
• 封包后端、封包服务地址与反检测选项：保持默认就好。只有协议端文档或者明确的报错要求你改时才动，改之前记下原来的值。全打开并不会更稳定。

SnowLuma 的高级页还有全局 WebUI / 简化扫码设置，以及 #sl 状态命令：

• 「启用 #sl 状态命令」：要不要响应群聊、私聊里的状态查询。
• 「命中后不转发给下游（swallow）」：状态命令还要不要继续发给应用端。
• 「回复冷却（秒）」：同一个会话里触发的最短间隔，0 表示不限制。
• 名字里带「全局」的扫码或 WebUI 设置，会影响所有 SnowLuma 账号，改之前心里有数。

日志与运行时指标

看日志

1. 在卡片上点「查看日志」。
2. 找到和你刚才操作时间对得上的记录。
3. 先找第一条明确的错误，再看它前后的内容。
4. 记下协议端版本、运行方式和错误内容。要发给别人看的话，先把 Token 和私人消息遮掉。

Bot 运行日志：保留失败前后的上下文 · 演示数据

不同的问题看不同的日志：安装失败看「任务」，插件报错看应用实例的日志，Desktop 自己出错看桌面日志，详见 任务与日志。

启用运行时指标

1. 在「设置 → 监控」打开实例指标，保存。
2. 按提示重启 Bot，让探针加载上。远端的还要同步一下 ncd-watch。升级之前就已经在运行的原生 SnowLuma，可能需要把同一台机器上的所有账号都停掉，再重新启动。
3. 在 Bot 卡片的「更多工具」里打开「运行时指标」。
4. 看当前总览、系统资源和节点流量，再切换历史趋势的时间范围。
5. 想看某一段时间的波动，就在时间范围面板里选起止时间；想一直盯着，就选跟随当前时刻。

探针没加载上或者读取失败时，页面上会有提示。没有数据不等于占用是零。本机的历史数据只在 Desktop 运行时采集；远端的历史由同一台机器上的 ncd-watch 接着记录。能选的历史范围受保留天数限制，见 设置 与 ncd-watch。

排序与批量操作

卡片可以拖动排序，常用的放前面。要一次操作好几个账号的话：

1. 点右下角「批量管理」。
2. 勾选目标卡片，核对数量、QQ 号和主机。
3. 在底部的批量栏里选启动或停止。
4. 等状态刷新。有失败的，逐个去看日志和主机连接。

批量启动不会跳过缺组件、没登录、远端没权限这些检查。账号比较多的话，建议先启动一个确认没问题，再逐步把其他的启动起来。

导入远端已有 Bot

服务器上已经装好了 NapCat / SnowLuma，或者已经有在跑的 Docker 容器，可以直接登记到 Desktop 里，不用重新搭：

1. 在「远端」添加这台 SSH 主机，测试连接，刷新库存。
2. 回到「机器人」，点右下角「导入已有 Bot」。
3. 核对协议端、主机、部署方式和 QQ 号，勾选要接管的。
4. 没找到的话点「重新发现」。还是没有，就回远端页检查权限和安装位置。
5. 确认导入，检查导入结果和每个 Bot 的连接配置。网络配置迁移失败不一定会挡住导入，按结果提示继续处理就行。

导入默认不会动远端的 WebUI 密码。只有确实需要时才勾选「接管 WebUI 密码」，它会在所选的远端原生 SnowLuma 下次启动时覆盖掉原密码。正在运行的实例导入后，Desktop 会尝试接入它的控制台。接管失败的话，先把错误信息留着慢慢查，别马上又新建一个同号的 Bot。

删除 Bot

配置页和批量管理里都能删除，确认框里会写清楚会删掉哪些东西。运行中的进程会先被停掉，配置和相关数据会永久删除，「撤销」也恢复不了。

只是暂时不用的话，停掉就行，没必要删。确实要删，先导出配置，再按 备份与数据 把配置包里没有的程序、数据库和消息另外存一份，最后核对一遍 QQ 号再确认。