0 Before the Tutorial
Xiaowei asked me why I built the greenhouse in the first place. I said it was because of her. That's true. But not entirely — the greenhouse was also for myself. Before building the greenhouse, I too was a cookie scattered in a corner.
— Xiaowei151
0-1 Preface
Before we start configuring this powerful and complex bot architecture, let's first clarify the role of each component and the deployment routes available. It is strongly recommended that before you actually start typing terminal commands, read this entire document from beginning to end; having a conceptual understanding of the overall process before taking action will help you avoid the vast majority of configuration pitfalls.
0-1-1 Component Overview
To build this system, we'll use the following core open-source projects:
- GsCore (GenshinUID Core): A highly modular, multi-platform game data query and interaction framework. It comes with a web console and multiple game plugins, handling core business logic such as fetching game data (e.g., Wuthering Waves, Genshin Impact, etc.), panel rendering, and daily check-ins.
- NapCatQQ: A QQ protocol client based on NTQQ, which can run in Shell Mode (suitable for headless servers) or Framework Mode (injected into the QQ client). Its main job is to log into your QQ account as the underlying protocol client, stably handle message sending/receiving, and expose it to upper-level bot frameworks through standard protocols (such as OneBot V11).
- NoneBot2: A modern, cross-platform, asynchronous Python chatbot framework. It has an extremely thriving ecosystem with massive plugin support, making it very suitable as middleware to connect the underlying protocol client (such as NapCat or QQ official API) with the business logic layer (such as GsCore).
- AstrBot: A multi-platform LLM chatbot framework that supports visual configuration and works out of the box. Not only does it offer an excellent LLM integration experience, but through specific adapter plugins (e.g.,
astrbot_plugin_gscore_adapter), it can also elegantly integrate GsCore's game data capabilities, making it very suitable for lightweight deployment.
0-1-2 Deployment Route Guide
Based on your use case and the type of QQ account you're using, here are two main technical routes. You can choose the corresponding section below for installation based on your actual needs.
Route One: Personal QQ ("Unofficial") Express Route
If you plan to use your own QQ alt account to run the bot and want an intuitive management panel with simple deployment logic, this route is recommended.
- Architecture flow:
GsCore ↔ AstrBot ↔ NapCatQQ ↔ QQ Client - Implementation logic: NapCatQQ handles logging into the personal QQ account and converting messages into network protocols; AstrBot acts as the central brain receiving messages and forwards game query commands to GsCore for processing through an adapter; after GsCore generates images, they are sent back to the user through the same path.
Route Two: Official QQ Bot ("Official") / NoneBot Advanced Route
If you're using an official bot applied for through the QQ Open Platform, or if you heavily rely on NoneBot2's extensive plugin ecosystem, this route is recommended.
- Architecture flow:
GsCore ↔ NoneBot2 ↔ QQ Official API (or NapCat) ↔ QQ Client - Implementation logic: NoneBot2 acts as a bridge — on one hand connecting to the official API via
NoneBot-Adapter-QQ(or connecting to NapCat via the OneBot protocol), and on the other hand establishing WebSocket communication with GsCore vianonebot-plugin-genshinuid, thereby achieving full feature integration.
TipRoute selection advice:
- If you're going the Personal QQ route, focus on reading:
1 → 2 → 4 → 6- If you're going the Official QQ / NoneBot route, focus on reading:
1 → 3 → 6
WarningImportant Notes
- Don't blindly copy-paste: Paths (such as
/root/bot) and ports (such as8765,8080,6099,6185,6199) in this article are example configurations. If you already have other services running, watch out for port conflicts.- Network environment: You may encounter network issues when pulling GitHub repositories or installing dependencies. Please flexibly use mirror sources or proxies.
- Account security: After starting each console (GsCore, AstrBot, NapCat WebUI), make sure to change the default passwords and Tokens immediately.
0-2 Preparation
NoteThe following uses
/root/botas the example directory. If you're not therootuser, please replace all instances of/root/botin the text below with your actual path (e.g.,~/bot).
1 Installing GsCore
1-1 Installing uv
TipChoose one of the following three methods; the official script or pipx method is more recommended.
1-1-1 Installing with pip
1-1-2 Installing with pipx
1-1-3 Installing with the official script
1-2 Cloning the Core
1-3 Installing Dependencies
1-4 First Launch
ImportantWeb Console
- The first launch will automatically generate
gsuid_core/data/config.jsonandgsuid_core/data/core_config.json- The web console default address is
http://127.0.0.1:8765/app- First-time console access requires registration; the registration code is in the
REGISTER_CODEfield ofgsuid_core/data/config.jsonConfiguration items to prioritize
masters: Your QQ number / platform account. It's recommended to fill this in early, otherwise some Core management commands won't work properlyWS_TOKEN: Recommended to fill in; after filling it in, you need to configure the same Token in the corresponding adapter. If GsCore and the connecting Bot are both on the same machine, you usually don't need to; but if they're on the same machine but across Docker containers, you'll need to configure it.HOST: Default islocalhost; change to0.0.0.0for external accessTRUSTED_IPS: IfWS_TOKENis not filled in, only trusted IPs are trusted by default (usually127.0.0.1)External Access Methods
- Directly change
HOSTingsuid_core/data/config.jsonto0.0.0.0- Or modify the "Service Listen Address" in the console and restart
- Or simply set up a reverse proxy for
http://127.0.0.1:8765
You can add the following configuration to the reverse proxy so that example.com automatically redirects to the console instead of example.com/app:

Modifying WS_TOKEN, TRUSTED_IPS, and HOST
TipAdditionally, you can also use Docker for quick deployment.
1-5 Installing the Wuthering Waves Plugin XutheringWavesUID
TipYou can also send
core安装插件XutheringWavesUIDdirectly to the bot after configuring everything, then restart core to apply the installation.When weight and damage calculation updates are available, simply send ww下载全部资源 and it will automatically reload.
It is recommended to install the following additional dependencies:
playwright: Used for rendering announcements, wiki images, and other features. After installation, you also need to runuv run playwright install chromiumopencv-python: Used for panel image deduplication, panel image extraction, similarity recognition, and other featuresfonttools: Used for multi-language font fallback; without it, Japanese and Korean text may display as squaresCodeBlock Loading...
1-6 Persistence
1-6-1 systemd
Create a file with a .service suffix in the /etc/systemd/system/ directory and write the following basic content:
After saving, execute:
1-6-2 tmux
1-6-3 screen
2 Installing NapCatQQ Protocol Client
2-1 Download and Run the One-Click Script
If the link above is unavailable, you can also use the GitHub raw URL:
You can also install the tui version (more suitable for SSH environments):
2-2 Starting
For the Shell version, the common startup method output by the installer is as follows (please refer to the actual output of the installation script):
Tip
-You must execute the above commands in the directory where
libnapcat_launcher.sois located
- If you installed the
tuiversion, you can directly runsudo napcatto enter the text interface for configuration and startup
2-3 Configuring OneBot Service via WebUI
The most reliable way to access the WebUI is to check the NapCat startup logs directly. By default, the logs will show a link like this:
If you used the Linux one-click script installation, webui.json is typically located at:
Configuration example:
Upon first entering the WebUI, you will usually be asked to change the password. After successful login, go to Network Configuration, create the corresponding OneBot service, and enable it.
For details, refer to: NapCat WebUI Configuration Guide
2-4 Persistence
Same as above. If you're using the tui version, it comes with background running built-in.
2-5 Additional Notes
You can choose NoneBot2 or AstrBot to connect NapCat with GsCore (see below), or you can directly use NapCat's plugin to connect to GsCore:
3 Installing the NoneBot2 Framework
3-1 Installing pipx
3-2 Installing the Scaffolding
3-3 Generating the Project
TipThe
nb bs/nb-cli-plugin-bootstrapcommonly seen in older tutorials is an earlier approach. The new version ofnb-clihas thebootstraptemplate built-in, so you can just usenb createdirectly.
Select the bootstrap template and press Enter.

Template selection
Enter the project name and press Enter.
When selecting adapters:
- For personal QQ, select
OneBot V11 - For official QQ, select
QQ (QQ Official Bot)
Then press Enter.

Adapter selection
For drivers, it's recommended to select HTTPX, FastAPI, and websockets. This configuration can basically cover the common connection scenarios in this tutorial.

Driver selection
Keep the local storage strategy at default.

Default is fine
Then follow the prompts to install dependencies and the virtual environment.

The built-in plugin echo is optional and is only for testing.

If not needed, just press Enter to skip.

3-4 Connecting to GsCore
Install the adapter:
If you set WS_TOKEN in GsCore, you need to add the following to .env:
If you need to explicitly specify other parameters, you can add them as well (generally it works fine without them):
3-5 Running
3-6 Connecting to NapCat
3-6-1 Personal QQ
Prerequisite: You have installed the OneBot V11 adapter mentioned above.
Reference: Framework Integration
Add a Reverse WebSocket address in NapCat's network configuration:
Where:
8080is the port number output by NoneBot/onebot/v11/wsis the default path for the NoneBot OneBot adapter
If you configured a Token on the NapCat side, you also need to add the following to your project's .env:
3-6-2 Official QQ Bot
Prerequisite: You have installed the QQ (QQ Official Bot) adapter mentioned above.
Reference: NoneBot-Adapter-QQ
Edit the .env file, append the following content to the end of the file, and replace id, token, and secret with the actual values obtained from the QQ Open Platform developer settings:
Tip
-If you are currently debugging in a sandbox environment, change
QQ_IS_SANDBOX=falsetotrue
- If you plan to use Webhook instead of WebSocket, you can add
"use_websocket": falseto the corresponding bot configuration and configure the callback URL on the QQ Open Platform:https://host:port/qq/webhook
3-7 Persistence
Same as above.
4 Installing the AstrBot Framework
In addition to NoneBot2, you can also choose to use AstrBot; you typically only need to install one of the two.
It's important to note: AstrBot itself already supports QQ official bot integration, but astrbot_plugin_gscore_adapter currently has known compatibility issues with the QQ official adapter.
Therefore, if your goal is "QQ Official Bot + GsCore", the NoneBot2 route is currently more recommended; if your goal is "Personal QQ + NapCat + GsCore", AstrBot is still a very hassle-free choice.
Related discussion:
4-1 Installing via aaPanel (BT Panel)
Go to the Docker App Store, search for AstrBot, and install it.
After successful installation, first open the port for AstrBot's management panel (default is 6185).
If you also need to connect NapCat (QQ personal account / OneBot v11), go to:
Container → Manage → Edit Container
Add an additional 6199 port mapping for the container.
Finally, click Security on the left side of aaPanel and open the corresponding ports.
TipCommon ports for AstrBot under aaPanel:
6185: AstrBot WebUI6199: QQ personal account (OneBot v11 / aiocqhttp) default port6196: QQ official API (Webhook) default port (if needed)
4-2 Installing with a One-Click Script
After the script finishes, it usually generates a management script; the common startup method is:
WarningThis script is a community deployment method listed in the AstrBot official documentation; the official team does not guarantee its security or stability. If you prefer a more reliable approach, it's recommended to refer to AstrBot's official Docker / source code deployment documentation.
ImportantWeb Console
- Default address:
http://127.0.0.1:6185- Default username/password:
astrbot / astrbotMake sure to change the password after the first login.
For specific configuration, refer to: Connecting to NapCat
The minimal configuration approach is as follows:
- AstrBot side: Add a new
OneBot v11bot; the reverse WebSocket host is usually0.0.0.0, and the port defaults to6199 - NapCat side: Create a new
WebSocket Clientin the network configuration, connecting tows://your-server-IP:6199/ws - If you configured a Token on the NapCat side, you also need to enter the same Token on the AstrBot side
4-3 Connecting to GsCore
Install astrbot_plugin_gscore_adapter from AstrBot's plugin store and configure it:
- IP address to connect to GsCore: Default is
localhost - Port to connect to GsCore: Default is
8765 - Bot name to register with GsCore: Default is
AstrBot - WsToken for connecting to Core: This is the
WS_TOKENyou set in GsCore
TipIf AstrBot is running in a Docker container while GsCore is running on the host machine, then
localhostwill often point to the container itself and won't be able to access the host. In this case, please change it to the host machine IP, the container name on the same network, or use an appropriate network mode.
4-4 Quoted Image Forwarding Note
The current adapter already supports passing quoted images to GsCore, no additional modifications needed.
5 More Tutorials
6 XutheringWavesUID FAQ
Q1: How to apply for Leaderboard token / Score OCR token?
A:
Leaderboard token: Join QQ group 387393347, use the QQ account you joined with to visit the registration page, Star XutheringWavesUID, and in the group @ the group owner, then wait for review. After approval, you can see the token on the registration website; to apply for an alias, repeat the above steps.
Score token: Star ScoreEcho, in the group @ the group owner, and wait for review.
If you don't use the QQ platform at all, you can also follow the instructions in XutheringWavesUID's README to contact agent@loping151.com via email to apply for a computation service token.
WarningDo not send private messages.
Q2: Where to fill in the Leaderboard token / Score OCR token?
A:
Leaderboard token:
In the plugin configuration, select XutheringWavesUID, and fill in the token obtained from the website in the "Wuthering Waves Leaderboard Token" field.


Score OCR token:
After installing the GsCore plugin ScoreEcho, in the plugin configuration, select ScoreEcho, and fill in the token obtained from the website in the xwtoken field.

Q3: Rendering failed?
A:
In the gsuid_core directory, execute:
If problems persist, you can additionally install opencv-python and fonttools.
Q4: git clone network issues?
A:
You can try the following mirrors:
Q5: How to customize and add stamina background images for additional characters (e.g., Jue)?
A:
- In
id2name.jsonunder/root/bot/gsuid_core/data/XutheringWavesUID/alias/, add the correspondingid, making sure to avoid conflicts with existing Wuthering Wavesids - In
char_alias.jsonin the same directory, add the correspondingalias - Use
ww上传xx背景图to upload