SnowLuma 会保留 QQ 的图形界面，所以登录时本来需要你打开远端桌面，找到 QQ 的窗口去扫码。简化扫码帮你省掉了这一步：它从 QQ 原本的登录界面里把二维码抓出来，直接显示在 Desktop 里。你照样用手机 QQ 扫码确认，只是不用一直开着远端桌面了。
1. 确认主机满足条件
| 运行方式 | 取码依赖 | 取不到码时 |
|---|---|---|
| Windows 原生 | UIA 定位登录控件、单窗口捕获；QQ 和扫码辅助在可用的桌面会话里 | QQ 原窗口 |
| Linux SSH 原生 | Python 3、AT-SPI、X11、可用的会话 D-Bus | VNC / QQ 图形窗口 |
| 官方 SnowLuma Docker | 容器内同用户、同显示环境下的无障碍与窗口捕获 | VNC |
自己做的 Docker 镜像只保证能用 VNC 登录，不一定带有官方镜像里那套扫码辅助环境。
简化扫码默认是开着的；如果你以前手动关掉过，会继续保持关闭。开关在 Bot 的「配置 → 高级」里，名字叫「Windows 简化扫码（全局）」或者「简化扫码登录（全局）」。名字里带着「全局」，说明它会影响同一类运行环境下的所有 Bot。
2. 启动 Bot，打开扫码窗口
- 在 Bot 配置里核对 SnowLuma 底座和运行主机，保存。
- 启动 Bot，等 QQ 和 SnowLuma 都起来。
- 点卡片上的「扫码登录」。只有在你打开扫码窗口的时候，Desktop 才会去抓取二维码。
- 第一次打开时，扫码辅助会把 QQ 从账号选择页或者快捷登录页切换到扫码页。放心，它不会替你点快捷登录。
- 用要登录的那个 QQ 号的手机端扫码，然后在手机上确认。
扫完码以后不要去连点刷新。界面识别到已经扫码时，会自动停止抓图、禁用刷新按钮，等你在手机上确认。登录成功后，二维码会被清空，扫码辅助也会退出。
如果 QQ 的主界面已经出来了，但 SnowLuma 还没确认账号，会显示「等待 SL 确认」。这时候稍等一下，等协议端那边更新状态就好。
3. 二维码过期或手机取消了
- 二维码过期了：在扫码窗口里刷新一下，扫新的二维码。
- 手机上点了取消，想重新扫：把扫码窗口关掉，再重新打开。
- 已经扫了，但一直在等：看看手机上是不是还有一步确认没点。已经扫过的二维码是不能强制刷新的。
- 提示扫码辅助清理异常：按提示改用 QQ 原窗口或者 VNC 来登录。
关闭扫码窗口、切换到别的 Bot、隐藏扫码页、关掉这个功能或者停止 Bot，都会取消抓图，并清空二维码图片。
改了开关，当前 QQ 没反应
开关是在下一次冷启动 QQ 时才去准备环境的，它不会自动重启正在运行的 QQ 或容器。
所以改完开关后，找个合适的时间把对应的 Bot 停掉，再由 Desktop 重新启动。在 Linux 上，如果已经在运行的 QQ 有一个可用的无障碍会话，打开扫码时可以直接绑定上去；但要是会话 D-Bus 已经失效，那还是得重启 Bot。
Docker 也是一样，只在冷启动受支持的镜像时准备环境，不会为了抓个二维码就去重建正在运行的容器。不管扫码成功还是取消，都不会删掉 QQ 的启动包装和挂载目录。
取不到码，按顺序查
- Windows 远端： 目标用户登录桌面了吗？桌面解锁了吗？是不是有好几个会话同时开着？先按 Windows 管理 让工作进程就绪。
- Linux： 用的是 X11 吗？Python 3、AT-SPI 和会话 D-Bus 都能用吗？如果是 Wayland，或者缺依赖，直接改用回退入口会更快。
- QQ 窗口： QQ 窗口是不是被最小化了、被别的窗口挡住了，或者登录界面的布局不兼容？把窗口恢复出来再试，还不行就用原窗口 / VNC。
- 刚开启功能： 对应的 QQ 重启过了吗？打开开关不会帮你联网补装缺少的依赖，也不会帮你重启 QQ。
二维码只通过私有通道保存在内存里，不会写进文件、日志或者浏览器缓存，也不会为了取码去开新的公网端口。不过二维码本身就等于一次有效的登录凭据，千万别贴到公开的 Issue 里。
如果你希望 Bot 掉线以后，能由另一个 Bot 把重登二维码发给你，见 值守中的同机互助。这个功能还需要 ncd-watch、管理员和互助连接，单独打开简化扫码是不会给你发通知的。