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 via nonebot-plugin-genshinuid, thereby achieving full feature integration.

Tip

Route 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

Warning

Important Notes

1. Don't blindly copy-paste: Paths (such as /root/bot) and ports (such as 8765, 8080, 6099, 6185, 6199) in this article are example configurations. If you already have other services running, watch out for port conflicts.
2. Network environment: You may encounter network issues when pulling GitHub repositories or installing dependencies. Please flexibly use mirror sources or proxies.
3. Account security: After starting each console (GsCore, AstrBot, NapCat WebUI), make sure to change the default passwords and Tokens immediately.

0-2 Preparation

Note

The following uses /root/bot as the example directory. If you're not the root user, please replace all instances of /root/bot in the text below with your actual path (e.g., ~/bot).

1 Installing GsCore

1-1 Installing uv

Tip

Choose 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

Important

Web Console

• The first launch will automatically generate gsuid_core/data/config.json and gsuid_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_CODE field of gsuid_core/data/config.json

Configuration 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 properly
• WS_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 is localhost; change to 0.0.0.0 for external access
• TRUSTED_IPS: If WS_TOKEN is not filled in, only trusted IPs are trusted by default (usually 127.0.0.1)

External Access Methods

• Directly change HOST in gsuid_core/data/config.json to 0.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:

Tip

Additionally, you can also use Docker for quick deployment.

1-5 Installing the Wuthering Waves Plugin XutheringWavesUID

Tip

You can also send core安装插件XutheringWavesUID directly 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 run uv run playwright install chromium
• opencv-python: Used for panel image deduplication, panel image extraction, similarity recognition, and other features
• fonttools: Used for multi-language font fallback; without it, Japanese and Korean text may display as squares

CodeBlock 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.so is located

• If you installed the tui version, you can directly run sudo napcat to 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

Tip

The nb bs / nb-cli-plugin-bootstrap commonly seen in older tutorials is an earlier approach. The new version of nb-cli has the bootstrap template built-in, so you can just use nb create directly.

Select the bootstrap template and press Enter.

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.

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

Keep the local storage strategy at default.

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:

• 8080 is the port number output by NoneBot
• /onebot/v11/ws is 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=false to true

• If you plan to use Webhook instead of WebSocket, you can add "use_websocket": false to 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.

Tip

Common ports for AstrBot under aaPanel:

• 6185: AstrBot WebUI
• 6199: QQ personal account (OneBot v11 / aiocqhttp) default port
• 6196: 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:

Warning

This 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.

Important

Web Console

• Default address: http://127.0.0.1:6185
• Default username/password: astrbot / astrbot

Make 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 v11 bot; the reverse WebSocket host is usually 0.0.0.0, and the port defaults to 6199
• NapCat side: Create a new WebSocket Client in the network configuration, connecting to ws://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_TOKEN you set in GsCore

Tip

If AstrBot is running in a Docker container while GsCore is running on the host machine, then localhost will 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.

Warning

Do 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:

• GitCode
• CNB

Q5: How to customize and add stamina background images for additional characters (e.g., Jue)?

A:

1. In id2name.json under /root/bot/gsuid_core/data/XutheringWavesUID/alias/, add the corresponding id, making sure to avoid conflicts with existing Wuthering Waves ids
2. In char_alias.json in the same directory, add the corresponding alias
3. Use ww上传xx背景图 to upload

Q6: How to scroll and view history output in tmux