On Windows, SnowLuma runs natively — no Docker, no WSL2 needed. Install the desktop QQ client, download and unpack the matching SnowLuma release, and run it. SnowLuma discovers QQ.exe and injects the hook automatically.
Want to run it in a container instead? See Windows · Docker Desktop (note: the image is Linux and runs Linux QQ).
Download and install the Windows desktop QQ client (the NT architecture) from Tencent's official site. Make sure QQ.exe launches normally. SnowLuma injects into this running NTQQ process.
Version matching matters. SnowLuma's native hook is aligned to a specific QQ version. If QQ auto-updates to a newer version SnowLuma doesn't support yet, the hook may fail to load — check the WebUI / README version-compatibility notes if you hit trouble.
Go to GitHub Releases, pick win-x64, and choose one of two flavors:
| Package | Notes |
|---|---|
SnowLuma-<TAG>-win-x64.tar.gz |
Full — bundles a Node.js runtime, no separate Node install, larger. |
SnowLuma-<TAG>-win-x64-lite.tar.gz |
Lite — no Node.js, you install Node yourself first, much smaller. |
Replace <TAG> with the version you want (e.g. v1.10.0).
If you don't want to fuss, grab the full package — it ships Node and runs straight out of the box.
SnowLuma needs Node.js ≥ 22. As of 2026, Node 24 ("Krypton") is Active LTS and 22 ("Jod") is Maintenance LTS. For the lite package, install Node 24 LTS (22 still works).
Download the Windows installer from nodejs.org, then verify in PowerShell:
The full package ships its own runtime — skip this step.
Unpack the tarball into a fixed directory, e.g. C:\SnowLuma\. After unpacking you'll find index.mjs, launcher.bat, webui/, native/, etc.
.tar.gz can be unpacked with the built-in tar (shipped on Win10/11):
7-Zip and similar tools work too.
From the unpacked directory, double-click launcher.bat (it just runs node ./index.mjs then pause so you can read the output). Or run it manually from a terminal:
If the full package uses its bundled Node, follow the README's launch instructions (usually launcher.bat is enough); see WebUI / README for specifics.
SnowLuma has hook auto-load on by default: it continuously probes the system for QQ main processes, and when it finds QQ.exe it injects the hook automatically (starting in passive observation). After you finish the QR login, the hook switches from passive observation to working mode.
So either order works:
QQ.exe and injects on startup.QQ.exe appears, then injects.Run SnowLuma as the same Windows user as QQ. Injection needs access to the target process; if SnowLuma and QQ run under different users (or mismatched privileges), injection fails. Running one elevated (as administrator) and the other not can also block injection — keep their privileges consistent.
Login is QR-scan only: scan the QR in the QQ window on your desktop with the QQ mobile app. On native Windows you can see the QQ window directly — no VNC/noVNC needed (that's only for Linux headless setups).
To keep the traditional "Load from the WebUI" flow, set hookAutoLoad to false in runtime.json, or set the env var SNOWLUMA_HOOK_AUTOLOAD=0. Env vars take precedence.
Once running, SnowLuma listens on these ports by default:
| Port | Purpose |
|---|---|
5099 |
SnowLuma WebUI |
3000 |
OneBot HTTP (default) |
3001 |
OneBot WebSocket (default) |
Open the WebUI in a browser:
On the first start with a fresh data dir, a one-time admin password is printed to the console / logs. Scroll through the console window that launcher.bat opens (look for the line containing "临时密码 / initial credentials").
The temporary password is printed only on the first start with a fresh data dir — reusing an existing dir or restarting won't regenerate it. See the WebUI / README for the exact wording.
The first run auto-creates config files under the data dir:
| File | Purpose |
|---|---|
config/onebot.json |
Global default OneBot config. |
config/onebot_<uin>.json |
One per account (by UIN). |
config/runtime.json |
Runtime settings: WebUI port, hookAutoLoad, log level… |
Env vars take precedence over runtime.json. Multi-account needs no manual config: each UIN you log in spins up its own OneBot instance. Full details in the Configuration reference.
The exact data-dir location is in the WebUI / README (it can differ by packaging).
On first start, the Windows Firewall may prompt whether to allow node / SnowLuma network access.
127.0.0.1), you don't need to allow public access.5099 / 3000 / 3001) through the firewall.Never expose the WebUI / OneBot ports raw on the public internet. These ports give full control over your QQ. For remote access, go through a reverse proxy with auth or an authenticated tunnel, and change the default credentials.