NapCatQQ: an NTQQ protocol-side framework for OneBot 11 bots

What NapCatQQ replaces, and who it is actually for

A QQ bot has two halves. One half is the bot logic: command parsing, plugins, scheduled jobs. The other half speaks to QQ itself, holds the session, and exposes an HTTP or WebSocket interface the bot logic can call. NapCatQQ is the second half. The README describes it as "a modern implementation of the Bot protocol based on NTQQ", and the repository topics list onebot and onebot11, so the interface it presents is the OneBot 11 standard rather than a bespoke API.

That positioning decides the audience. If you already run NoneBot, AstrBot or another OneBot 11 client, NapCatQQ is the piece you put underneath it. The README goes out of its way to recommend two such frameworks, AstrBot (described as a perfect fit for this project) and MaiBot. If you have no bot framework yet, NapCatQQ gives you the transport but not the bot; you would still be writing the plugin layer yourself.

The project is also explicit about what it will not do for you. The Quick Start section states that the project is non-profit and that questions about integration, basics or the underlying framework should be solved by searching on your own, because the community does not provide answers to them. Read that as a real constraint on adoption, not a formality. A team that needs a vendor-style support channel should stop here.

How the protocol side is structured: a pnpm monorepo with a shell, a framework and a WebUI

The repository is a pnpm workspace. The root package.json is private and named napcat, versioned 0.0.1, and it carries no runtime code of its own. Instead it holds build scripts that fan out to workspace packages: build:shell targets napcat-shell, build:framework targets napcat-framework, build:webui targets napcat-webui-frontend, and build:plugin-builtin targets napcat-plugin-builtin. There is a separate build:openapi script on napcat-schema, which suggests the API surface is generated into an OpenAPI description rather than hand-maintained.

The split matters when something breaks. napcat-shell is the entry point you build and run; napcat-framework holds the protocol logic; the WebUI is a separate front end that is built independently and then served. A misbehaving bot can therefore be a framework issue, a shell issue, or a front-end issue, and the scripts let you rebuild one without the others. The root dependencies are small: express and ws. The WebSocket dependency is consistent with an OneBot 11 implementation that offers a reverse or forward WebSocket transport.

TypeScript is the implementation language and the toolchain is Vite plus vitest, with eslint configured through neostandard. Nothing in the repository layout indicates a compiled binary distribution; the Releases page is where the packaged artifacts live, and the README points there directly.

Installing NapCatQQ from Releases and getting a first OneBot connection

The README does not give a step-by-step install. It says to go to the Release page and download the latest version, and that first-time users must read the documentation site for the tutorial. So the commands below are the ones the repository itself defines for building from source, not an invented installer.

Clone the repository and install workspace dependencies with pnpm:

pnpm install

Build the shell, which is the runnable entry point, and then the WebUI front end:

pnpm run build:shell
pnpm run build:webui

If you only want to check that the tree type-checks before building, the root script runs across all workspace packages:

pnpm run typecheck

The root package.json also defines a combined script that builds the shell and then copies the environment files through the napcat-develop package:

pnpm run build:shell:config

Once the shell is running, the WebUI is where you configure the connection. The README mentions a WebUI about page as the place to obtain the QQ group join key, which confirms the WebUI is served by the running instance rather than being a static site. Point your OneBot 11 client at the address and port the WebUI shows. The README does not document the default port, so read it off the WebUI rather than assuming a value.

For a packaged deployment, the Releases page is the supported route. The README does not document a Docker image, an npm package, or a systemd unit, so treat any container recipe you find elsewhere as community work rather than something this repository ships.

Where NapCatQQ will let you down

The licence is the first hard limit. The README describes the project as using a mixed licence: third-party code or modified portions follow their original open source licences, some parts are covered by authorisation the project obtained and are outside certain constraints, and the remaining logic uses the licence in the repository's LICENSE file. The repository metadata reports the licence as NOASSERTION, meaning GitHub could not classify it automatically. The README adds a restriction that is unusual for open source: no project may develop based on NapCat code without the repository author's authorisation. If your plan involves forking NapCatQQ, embedding it in a product, or shipping a modified build, that clause is the one to read first. This is a description of the terms, not legal advice.

Support is the second limit, and the README states it plainly rather than burying it. Integration problems, basic problems and problems in the underlying framework are out of scope for the community. The QQ groups are gated too: the README says entry requires a key obtained from the WebUI about page, that only the latest 100 versions of the key are valid, and that group admission is rate-limited over time. A user on an older release may find the key expired.

The third limit is scope. NapCatQQ implements the protocol side for message push style functionality. If you need a bot that reasons, schedules, or stores state, that is your framework's job. And because the project builds on NTQQ, its behaviour is tied to a client it does not control; the README does not describe how protocol changes are absorbed.

NapCatQQ against Lagrange and Go-CQHTTP

The README credits Lagrange (LagrangeDev/Lagrange.Core) for support and says part of its code was referenced with authorisation. That makes Lagrange the closest comparison and a real alternative. Both target the QQ bot protocol space, but Lagrange.Core is a .NET implementation of the protocol itself, whereas NapCatQQ is a TypeScript framework layered on top of NTQQ. The practical difference is where the protocol knowledge lives: with Lagrange you are closer to the wire, and with NapCatQQ you are closer to the client, which is also what makes NapCat depend on NTQQ's behaviour.

Go-CQHTTP is the older reference point in this space and still shows up in search data around NapCat. It is a Go implementation that presented the same OneBot style interface. For a bot operator, the migration path is mostly on the client side: an OneBot 11 client that worked against Go-CQHTTP can generally be pointed at NapCatQQ instead, because the interface contract is the same standard. What changes is the runtime you keep alive and the licence you accept.

The README also points at SnowLuma as a newer alternative to the NapCat GUI. That is a narrower substitution than it looks: SnowLuma replaces the management interface, not the protocol framework underneath it.

Maintenance, releases and the upgrade cost of a fast release cadence

The repository is not archived and the last push to main was on 2026-09-14. The release history is dense: v4.18.26, v4.18.27 and v4.18.28 were all tagged on 2026-09-14, within about an hour of each other. Patch releases arriving in the same hour usually mean a fix was published and then corrected again, so pinning to a specific tag rather than tracking latest is the safer operating choice.

That cadence sets the upgrade cost. The root package.json version stays at 0.0.1 while releases move through 4.18.x, so the workspace version is not a signal of what you are running; the release tag is. Upgrading means replacing the shell build and rebuilding the WebUI if you built it from source, or downloading a new artifact from Releases. There is no documented migration guide and no documented rollback procedure, so keep the previous artifact before you replace it.

The licence cost is ongoing rather than one-off. Because the terms are mixed and include an authorisation requirement for derivative development, an upgrade is also a moment to re-read the LICENSE file and the README's licence section, in case the terms moved with the release.

Editorial conclusion

Adopt NapCatQQ if you already run a OneBot 11 client such as NoneBot or AstrBot and need the QQ side, and you accept that the community does not answer integration or basic questions. Do not adopt it if you need a permissive licence, an officially supported deployment, or a project you may fork and redistribute. Before installing, read the docs at napneko.github.io, check the LICENSE file for the mixed-licence terms, and confirm the release you download matches a version listed on the Releases page. The last push to main was on 2026-09-14, the same day v4.18.28 was tagged.

Frequently asked questions

Official sources

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