explaingit

napneko/napcatqq

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

TLDR

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
Click or tap to explore — scroll the page freely

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

Things people build with this

USE CASE 1

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

USE CASE 2

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

USE CASE 3

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

USE CASE 4

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

Tech stack

TypeScriptNode.jsDockerOneBot 11

Getting it running

Difficulty · moderate Time to first run · 1h+

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

In plain English

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.

Copy-paste 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.
Open on GitHub → Explain another repo

← napneko on gitmyhub — every repo by this author, as a profile.

Verify against the repo before relying on details.