SnowLuma: A TypeScript QQ to OneBot Runtime

Why SnowLuma bridges native QQ sessions

SnowLuma is a TypeScript interoperability runtime for QQ clients. Its specific purpose is to convert native QQ conversations into OneBot v11 actions and events, then expose those operations through several interfaces. The intended audience appears to be developers conducting protocol and interoperability research, or people running automation and bot tools in a non-commercial self-hosted environment.

The project does not position itself as an official Tencent or QQ integration. Its README explicitly says that SnowLuma is independent and provides the software for study and research. That distinction matters because the runtime depends on QQ processes rather than describing an official public QQ bot API.

SnowLuma supports text and several media-oriented message segments, including images, voice, video, files, replies, mentions, forwards, and common cards. Multiple accounts can run at once, with each account maintaining its own conversation state, identity mapping, message storage, and network configuration. The WebUI provides account status, logs, connection settings, action debugging, and storage management.

This is a protocol and session bridge, not a general-purpose bot SDK on its own. Its value to an engineer is the standardized OneBot surface between a QQ client and downstream tooling. That boundary also makes SnowLuma unsuitable where an official, vendor-supported QQ integration is required.

SnowLuma's protocol path and component boundaries

The documented runtime path starts with access to a QQ conversation, followed by protocol parsing, identity mapping, conversion into OneBot v11, and network adaptation. These responsibilities are described as separate boundaries. That separation gives the project a clear structure even though the README does not expose the internal package implementation for each stage.

On the output side, OneBot v11 is available through a WebSocket server, a WebSocket client, an HTTP server, and HTTP reporting. This means a downstream tool can consume the same normalized model through different transport arrangements. The WebUI and action debugger provide a management path for operators, while `@snowluma/sdk` and `@snowluma/mcp` provide dedicated developer entry points.

JSON message segments have a compatibility detail worth noting. The documented input accepts a standard `data.data` string containing JSON. It also accepts a non-array object in `data.data`, as well as the shorthand `{ type: "json", data: "..." }`. In every case, `data` is required, and the final parsed content must be a JSON object. This tolerance does not make arbitrary payloads valid.

SnowLuma also documents a constrained quoted-message mechanism. When a OneBot action sends a `reply` segment, SnowLuma can include the cached original text in the QQ reply preview, preserving text, line breaks, and the quoted relationship. Non-text content is represented by a type hint instead of being uploaded again. Nested quoted messages are not expanded recursively, and metadata without cached text does not produce invented preview content.

Those rules indicate that preview generation depends on local cache state. A preview is not reconstructed from arbitrary remote data, which improves consistency but means quote rendering is intentionally partial.

Installing SnowLuma and opening the WebUI

The README directs users to the GitHub Releases page rather than providing a package installation command for the runtime. Download the complete package for the appropriate platform and extract it. For the Lite edition, the documented runtime requirement is Node.js 22.13 or later, except that the Node.js 23 series requires 23.4 or later.

On Linux, mark the launcher executable and start it:

chmod +x launcher.sh
./launcher.sh

The Windows instructions say to run `launcher.bat` directly. After startup, open `http://localhost:5099` in a browser. The WebUI displays an initial password in the startup log, and that password is used for the first login.

The documented first-use sequence is to connect a QQ process through the WebUI guidance, then configure a OneBot connection. The exact fields and connection values are not included in the README, so this article does not invent a host, token, port, or reverse-WebSocket setting for them. After logging in, a reader should see account and connection management areas, with startup logs available as the source of the initial password.

This setup assumes that the released package is appropriate for the target platform and that the user can supply a QQ process. The README does not document headless account bootstrap, credentials storage, automatic restart behaviour, or rollback.

Developer setup for the SnowLuma pnpm workspace

Repository development is based on the `dev` branch rather than the default `main` branch. The documented requirements are Node.js 22.13 or later, with Node.js 23 requiring 23.4 or later, and pnpm 10.28.0. The monorepo `package.json` identifies version 1.14.22, uses ES modules, and defines workspace-level scripts for building, type checking, testing, linting, and coverage.

A source checkout follows this sequence:

git clone https://github.com/SnowLuma/SnowLuma.git
cd SnowLuma
git checkout dev
pnpm install --frozen-lockfile
pnpm typecheck
pnpm test

The frozen lockfile install keeps dependency resolution tied to the checked-in `pnpm-lock.yaml`. The next two commands run all available workspace type checks and package tests. The root test script uses recursive filtering for packages and accepts the absence of a package-specific test script through `--if-present`.

For a focused core test run, the root package exposes `pnpm test:core`. Build targets are separated as well: `pnpm build` builds `@snowluma/core`, while `pnpm build:sdk` and `pnpm build:mcp` target the corresponding packages. The repository also defines a full `build:all` command, but its component filters should be considered a source-development workflow rather than the quickest setup path for a new self-hoster.

The repository includes `CONTRIBUTING.md`, `CONTEXT.md`, and `RoadMap.md`. Those files are the stated references for contribution rules, module vocabulary, and development direction.

Where SnowLuma's QQ and OneBot bridge falls short

The largest limitation is licensing. SnowLuma is source-visible but not OSI open source. The README permits viewing, learning, non-commercial self-hosting, and private modification. Commercial use requires prior written authorization, as does public distribution of a modified or derivative version. A team cannot assume that moving a SnowLuma-derived runtime into a paid service will be allowed under a conventional open-source licence.

Binary distribution also has a separate legal boundary. `EULA.md` and `PRIVACY.md` apply to binary release packages, while the bundled native add-ons are described as proprietary and outside the source licence. Engineers need to inspect those files for the exact package and component they intend to distribute. This review describes the repository's stated terms, not legal advice.

Operationally, SnowLuma requires a QQ process. The README does not promise an official account API, guaranteed compatibility with future QQ changes, or a supported server deployment model. Its interoperability role is tied to protocol conversion, so client-side changes could affect behaviour without changing the OneBot contract.

The quote preview is another bounded feature. It uses locally cached original text, does not re-upload non-text segments, and does not recursively expand nested quotes. Applications requiring complete media reproduction or deeply recursive quote context need capabilities that SnowLuma does not document.

Finally, the WebUI is local at `http://localhost:5099` in the startup example. The README does not document remote exposure controls, authentication hardening beyond the initial password, or a reverse-proxy deployment procedure. Those omissions should not be treated as either support or prohibition.

SnowLuma versus consuming an existing OneBot adapter

There are two different adoption paths. A team can deploy SnowLuma as the QQ-side interoperability runtime, as described here. Alternatively, a team can use an existing QQ client adapter that already exposes OneBot and connect the same kind of downstream bot or automation tool. That alternative avoids making SnowLuma's TypeScript runtime and its custom source licence part of the deployment boundary, although the availability and terms of any particular adapter must be checked separately.

SnowLuma's documented approach starts with native QQ conversation access, then performs parsing, identity mapping, OneBot conversion, and network adaptation. A downstream OneBot consumer, by contrast, starts after that bridge and only depends on the exposed v11 actions and events. This is a real difference in layer: SnowLuma owns session-facing compatibility work, while a consumer operates against a standardized interface.

The README also says SnowLuma references the protocol definitions of LagrangeV2 and implementation ideas from NapCatQQ. Those references describe lineage and technical influence, not an instruction to adopt either project, and the README does not provide a feature-by-feature comparison of all three systems.

For a prototype, running SnowLuma and connecting a OneBot-aware tool is the most direct path. For production evaluation, the comparison should focus on account isolation, transport requirements, event fidelity, failure recovery, licence obligations, and the exact QQ process dependency. SnowLuma is the relevant choice only when its documented bridge and management surface justify owning that layer.

SnowLuma release activity and upgrade work

The repository is not archived. Its last push was on 2026-10-16, and the documented releases include v1.14.22 on 2026-10-07, v1.14.21 on 2026-10-04, and v1.14.20 on 2026-09-26. These dates indicate recent project activity at the repository level, but the README does not promise compatibility across every release or document a migration guide for each version.

The versioned npm packages `@snowluma/sdk` and `@snowluma/mcp` are presented as separate developer tools. The root workspace also exposes `bump` and `release` scripts, but no public upgrade procedure for deployed installations is included in the README. An operator therefore cannot infer from the available documentation whether configuration is migrated automatically, whether stored accounts remain compatible, or whether a major protocol change can require client updates.

The source tree separates core, SDK, MCP, UI, common, and WebUI-related build targets. That separation can reduce the amount of work required when integrating one interface, but it also means adoption may involve more than the runtime binary. The relevant cost is checking release notes, rebuilding selected packages, validating OneBot actions, and reviewing changes to `LICENSE`, `EULA.md`, and `PRIVACY.md` before distribution.

Editorial conclusion

Researchers and non-commercial self-hosters should consider SnowLuma when they need a QQ session bridge with a OneBot v11 interface and can accept its custom licence. Commercial operators or teams needing independently confirmed open-source licensing should first review LICENSE, EULA.md, PRIVACY.md, and the behaviour of bundled proprietary native components before adoption.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. SnowLuma/SnowLuma on GitHub