gitwtfhub

wtf is napcatqq?

napneko/napcatqq — explained in plain English

Analysis updated 2026-06-24

8,934TypeScriptAudience · developerComplexity · 3/5Setup · moderate

TL;DR

NapCatQQ is a low-memory framework for building automated bots on QQ, China's major messaging platform, implementing the OneBot 11 standard so bot code works across multiple QQ backends without changes.

Mindmap

mindmap
  root((repo))
    What It Does
      QQ bot framework
      Implements OneBot 11
      Low memory footprint
      Streaming file API
    Tech Stack
      TypeScript
      Node.js
      Docker
    Use Cases
      Group management bot
      Auto-reply systems
      Media file handling
    Setup
      Install NTQQ
      Configure web UI
      Connect bot backend

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

Why would anyone build with this?

REASON 1

Build a QQ group management bot that auto-replies to messages and handles group events using the OneBot 11 API.

REASON 2

Create a long-running QQ bot on modest hardware that streams large media files to and from group chats.

REASON 3

Develop a QQ automation bot that manages users and group settings through a web-based configuration UI.

REASON 4

Write OneBot 11-compatible bot logic that can switch QQ backends without rewriting your code.

What's in the stack?

TypeScriptNode.jsDockerOneBot 11

How it stacks up

napneko/napcatqqsoftwarebrothers/adminjsmidudev/aprendiendo-react
Stars8,9348,9358,936
LanguageTypeScriptTypeScriptTypeScript
Setup difficultymoderatemoderateeasy
Complexity3/53/52/5
Audiencedeveloperdeveloperdeveloper

Figures from each repo's GitHub metadata at analysis time.

How do you spin it up?

Difficulty · moderate Time to first run · 1h+

Requires NTQQ running as the underlying QQ client, most documentation is in Chinese.

Wtf does this do

NapCatQQ is a framework for building automated bots on QQ, the large Chinese social messaging platform owned by Tencent. It works by implementing a bot protocol on top of NTQQ, which is QQ's modern client version. The protocol it implements is called OneBot 11, a community-standard interface that lets bot developers write their logic once and have it run across multiple QQ bot backends without changes. The project is written in TypeScript and is designed to run with low memory usage over long periods, making it practical to host on modest hardware. It exposes a rich API that covers most of the standard OneBot interface, including sending and receiving messages, managing groups, and handling events. A web-based UI is included for configuration and monitoring. In version 4.8.115 the project added support for a streaming API, which addresses problems with uploading and downloading large media files in Docker environments or across different devices. It also switched to using string types for message, user, and group IDs, which avoids integer overflow problems that JavaScript has when handling large 64-bit numbers. The README is mostly in Chinese. The project maintains several community groups on QQ itself and a Telegram channel. Documentation is hosted on multiple mirrors for reliability. The license is described as a mixed open-source license: third-party library code follows its original licenses, and the project-specific code uses the license in the repository. The README explicitly states that the project is non-commercial and that users are responsible for complying with local laws.

Yoink these prompts

Prompt 1
Show me how to set up NapCatQQ in Docker and connect it to my OneBot 11 bot backend to handle QQ group messages.
Prompt 2
Write a NapCatQQ bot handler that listens for messages mentioning a keyword and auto-replies with a fixed response.
Prompt 3
How do I use the NapCatQQ streaming API to handle large file uploads and downloads inside a Docker environment?
Prompt 4
Help me configure NapCatQQ's web UI and set up group management permissions for my QQ bot.

Frequently asked questions

wtf is napcatqq?

NapCatQQ is a low-memory framework for building automated bots on QQ, China's major messaging platform, implementing the OneBot 11 standard so bot code works across multiple QQ backends without changes.

What language is napcatqq written in?

Mainly TypeScript. The stack also includes TypeScript, Node.js, Docker.

How hard is napcatqq to set up?

Setup difficulty is rated moderate, with roughly 1h+ to a first successful run.

Who is napcatqq for?

Mainly developer.

View the repo → Decode another repo

This repo across BitVibe Labs

Don't trust strangers blindly. Verify against the repo.