qqBot runs a NoneBot2 QQ bot on top of go-cqhttp

A feature set for one QQ account, not a bot platform

qqBot is a concrete bot application rather than a library. The project describes it as a multifunction bot that posts anime images, chats, does data analysis and natural language processing, and the listed features give that claim a shape: entertainment commands such as a roulette wheel, an Arknights gacha pull simulation and a roasting feature, Twitch clip handling, Pixiv image posting that needs a Pixiv account, reverse image search triggered either by replying to an image with a search command or by a direct search command, a permission system where you decide which groups and which users may use which features, Bilibili video and live stream monitoring with stream analysis, and Discord monitoring. The permission layer is the part worth understanding first. The project asks you to set your own QQ number in the SUPER_USER parameter of config.py and then add yourself as an administrator with the administrator grant command, which means the bot ships with a super user concept where administrators are granted at runtime rather than only in a static file.

The three piece stack: NoneBot2, OneBot V11 and go-cqhttp

The bot does not talk to QQ directly. It sits in the middle of a three layer arrangement, and the packaging makes that explicit. The project metadata names the framework adapter and the plugin set, and it also names the directory where local plugins are loaded from:

[tool.nonebot]
adapters = [
    { name = "OneBot V11", module_name = "nonebot.adapters.onebot.v11" }
]
plugins = ["nonebot_plugin_apscheduler"]
plugin_dirs = ["awesome/plugins"]

OneBot V11 is the protocol between the bot logic and the protocol implementation, go-cqhttp provides that implementation as a separate process, and NoneBot2 is the framework that dispatches events to your handlers. The APScheduler plugin is enabled from the start, which is what allows scheduled jobs such as the monitoring features to run on a timer rather than only in reaction to chat messages. Loading plugins from a directory rather than only the installed list means you can drop a module into awesome/plugins and have it picked up, which is the main extension point the repository exposes.

Two conflicting NoneBot2 version instructions in the same repository

Here is where the documentation needs care. The setup notes say that if you used an earlier nonebot version of this bot, you must run a destructive upgrade before using the latest commit:

pip uninstall nonebot;
pip install nonebot2~=2.3.2;

The dependency file, however, lists nonebot2>=2.4.4 along with nonebot-adapter-onebot>=2.4.6. Those two instructions cannot both describe the same environment, since the pinned range in the setup note excludes the version the dependency file asks for. Anyone following the steps in order will install a 2.3.x release and then run a repository whose declared dependency wants 2.4.4 or newer. This is the single most useful thing to check before deploying the bot, and it is a documentation defect rather than a design decision. A second inconsistency sits next to it: the setup section states Python 3.10 or newer is required, while the project metadata declares requires-python as >=3.8, <4.0.

Installing from source and starting the bot for the first time

Setup is a source checkout, a dependency install, a config file and a protocol process. The requirements are installed from the file in the repository root with pip install -r requirements.txt, and the framework start command is the one from the NoneBot2 quick start, nb run, issued in the same root directory. The three core framework pins in the dependency file are:

nonebot2>=2.4.4
nonebot-adapter-onebot>=2.4.6
nonebot-plugin-apscheduler~=0.5.0

Before the first launch you need go-cqhttp running as a separate service, since the bot depends on it for the QQ connection, and the project links to the go-cqhttp documentation for that part. Configuration starts by copying sample_config.py to config.py and filling in the values you need. The dependency list gives a fair picture of what the feature set costs at install time. Beyond the bot framework and the APScheduler plugin, it pulls in HTTP clients (aiohttp, httpx, requests, urllib3), the numerical and text stack (numpy, scipy, matplotlib, wordcloud, jieba for Chinese word segmentation), pillow for images, lxml and markdown2 for parsing, an openai client, pixivpy3 for the Pixiv features, playwright for browser automation, loguru for logging, and youtube-dl for media download. That is a heavy install, and the analytics and plotting dependencies are there because the bot does charts and word clouds rather than simple chat replies.

go-cqhttp configuration is where the network exposure is decided

The repository includes a full go-cqhttp configuration example, and the interesting parts are the listening sockets and the middleware defaults. The HTTP server listens on port 5700, a forward WebSocket server on 6700, and a reverse WebSocket client points back at ws://127.0.0.1:5700/ws/api/ and ws://127.0.0.1:5700/ws/event/ with a reconnect interval of 3000 milliseconds. The middleware block defines a global API rate limit that is off by default, implemented as a token bucket with a reply frequency of 1 per second and a bucket size of 6. The comment on the access-token setting says the access key is strongly recommended on a publicly reachable server, and the configuration leaves it empty, which means the shipped default is the unsafe one for a public deployment. The pprof performance server is disabled by default and the file explicitly warns against exposing it publicly because it supports neither middleware nor authentication. The example also notes that enabling the server issued reconnect address can make connections worse on overseas servers.

Where the code lives in the repository

The tree explains how the project is organised. The entry point is qq_bot_core.py at the root, and the plugin style directories sit alongside it: Services/, model/, util/, config/, data/, awesome/, blivedm/ and dungeon_adventure_util/, plus a standalone blive_danmaku_report_generator.py for turning Bilibili live danmaku into a report and for_download.py. There are also two environment files, .env.dev and .env.prod, and a pyproject.toml alongside requirements.txt, so dependency information is split across two places that can drift apart. The architecture is a plugin collection rather than a clean library, and the plugins are what carry the feature set: the Arknights simulation lives in dungeon_adventure_util/, the danmaku handling in blivedm/, and local plugins are read from awesome/plugins. For a reader trying to judge effort, the split between scheduled jobs and event handlers is the thing to look for, and the APScheduler plugin already loaded in the configuration is the mechanism that separates them.

Maintenance reality, licensing, and what a user inherits

The project is licensed AGPL-3.0, which matters more than usual for a bot because a hosted deployment is a distribution question rather than a private use question, and no legal reading is offered here beyond that observation. On maintenance, the project itself sets expectations plainly: the author has a full time job, so updates will slow, and feature requests are directed to pull requests and issues rather than a maintainer queue. The last push was on 2026-09-05, but the three tagged releases are all beta builds from 2021 and 2022, with 3.0.0 dated 2022-02-07, so tags are not a useful upgrade path here and the master branch is what changes. Separate documentation lives in the remiliacn/Lingye-Bot repository, and permission problems are pointed at a specific issue thread. The README also does not document rollback, does not describe a supported upgrade path between nonebot versions, and does not state which QQ client versions go-cqhttp supports.

Editorial conclusion

qqBot is worth adopting if you run a single QQ account, already have go-cqhttp deployed, and want a ready made set of group commands rather than a framework to build on. It is the wrong choice for a production service, a multi account deployment or a Python version above the range the project supports, and the NoneBot2 version mismatch between the setup notes and the pinned dependency is the first thing to verify before anything else. The last push was on 2026-09-05, while the tagged releases still carry beta names from 2021 and 2022, so treat the master branch as the moving target and pin your own commit.

Frequently asked questions

Official sources

1. Issues
2. License: AGPL-3.0
3. README
4. Releases
5. remiliacn/qqBot on GitHub