Windows 手动部署

在 Windows 上 SnowLuma 原生运行，不需要 Docker、不需要 WSL2。你只要装好桌面版 QQ，下载对应的 SnowLuma 发行包解压，运行即可——SnowLuma 会自动发现 QQ.exe 并注入 hook。

想用容器跑？见 Windows · Docker Desktop（注意：镜像是 Linux 的，跑的是 Linux QQ）。

准备工作

1. 安装桌面版 QQ（NTQQ）

从腾讯官网下载并安装 Windows 桌面版 QQ（NT 架构），装好后能正常打开 QQ.exe。SnowLuma 注入的是这个正在运行的 NTQQ 进程。

2. 下载 SnowLuma 发行包

到 GitHub Releases 选 win-x64，两种风味二选一：

把 <TAG> 换成你要的版本号（例如 v1.10.0）。

3.（仅精简版）安装 Node.js

SnowLuma 需要 Node.js ≥ 22。截至 2026 年，Node 24（“Krypton”）是 Active LTS，22（“Jod”）是 Maintenance LTS。精简版请安装 Node 24 LTS（22 也能跑）。

到 nodejs.org 下载 Windows 安装包，装完用 PowerShell 验证：

node -v
# 应输出 v24.x.x（或 v22.x.x）

完整版自带运行时，跳过这一步。

解压并运行

把下载的 tarball 解压到一个固定目录，例如 C:\SnowLuma\。解压后目录里有 index.mjs、launcher.bat、webui/、native/ 等。

tar -xzf SnowLuma-<TAG>-win-x64.tar.gz -C C:\SnowLuma

进入解压目录后，双击 launcher.bat 启动（它本质就是跑 node ./index.mjs 再 pause，方便你看输出）。或者在终端里手动跑：

cd C:\SnowLuma
node ./index.mjs

完整版若用了内置 Node，请按 README 指引启动（一般直接 launcher.bat 即可）；具体见 WebUI / README。

QQ 与 SnowLuma 的启动顺序

SnowLuma 默认开启 hook 自动加载：它会持续探测系统里的 QQ 主进程，发现 QQ.exe 就自动把 hook 注入进去（先进入被动观察），等你扫码登录完成后，hook 自动从被动观察切到工作模式。

所以两种顺序都行：

• 先开 QQ 再开 SnowLuma：SnowLuma 启动后立刻发现已在运行的 QQ.exe 并注入。
• 先开 SnowLuma 再开 QQ：SnowLuma 会等到 QQ.exe 出现后再注入。

登录

登录只支持扫码：在桌面上打开的 QQ 窗口里用手机 QQ 扫码登录。原生 Windows 上你本来就能看到 QQ 窗口，不需要 VNC/noVNC（那是 Linux 无头环境才用的）。

关闭自动注入（可选）

想保留传统的“WebUI 里手动 Load”流程，把 runtime.json 里的 hookAutoLoad 设为 false，或设环境变量 SNOWLUMA_HOOK_AUTOLOAD=0。环境变量优先。

访问 WebUI 和 OneBot

启动后，默认监听这些端口：

浏览器打开 WebUI：

http://127.0.0.1:5099/

找 WebUI 临时密码

全新数据目录首次启动时，会在控制台 / 日志里输出一次性管理员密码。从 launcher.bat 弹出的控制台窗口里翻一下即可（找含“临时密码 / initial credentials”的那行）。

配置文件落在哪

首次运行会在数据目录下自动创建配置：

环境变量优先级高于 runtime.json。多账号无需手动配置：每登录一个 UIN，SnowLuma 自动拉起一个 OneBot 实例。配置项详解见 配置参考。

防火墙

首次启动时，Windows 防火墙可能弹窗询问是否放行 node / SnowLuma 的网络访问。

• 只在本机访问（127.0.0.1）时，可以不放行公网。
• 想让局域网内其它设备访问 WebUI / OneBot，需要在防火墙放行对应端口（5099 / 3000 / 3001）。

下一步

• 配置参考 —— OneBot / runtime 配置项详解。
• 快速开始 —— 连接你的第一个 OneBot 客户端。
• MCP 使用 / SDK —— 二次开发。
• 其它平台：Docker（Linux）、WSL2、部署方式总览。