0 Before You Begin

0-1 Preface

Before you start configuring this powerful and complex bot architecture, let's first clarify the role of each component and the deployment paths available next. It is highly recommended that, before you actually begin typing terminal commands, you read this document from beginning to end in full. Having an overall understanding of the process before you operate will help you avoid the vast majority of configuration pitfalls.

0-1-1 Component overview

To build this system, we will 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 powerful web console and multiple game plugins, and is responsible for handling heavy-duty business logic such as retrieving game data (for Wuthering Waves, Genshin Impact, etc.), panel rendering, and sign-ins.
• NapCatQQ: a headless QQ bot server based on the modern NTQQ architecture. Its main job is to log in to your QQ account, act as the underlying protocol endpoint, handle sending and receiving messages stably, and expose them to upper-layer bot frameworks through standard protocols such as OneBot V11.
• NoneBot2: a modern, cross-platform, asynchronous Python chatbot framework. Its ecosystem is extremely rich and supports a huge number of plugins, making it ideal as middleware to connect the underlying protocol endpoint (such as NapCat or the official QQ API) and the business-logic layer (such as GsCore).
• AstrBot: a multi-platform LLM chatbot framework that supports visual configuration and works out of the box. In addition to offering an excellent LLM integration experience, it can also elegantly integrate GsCore's game-data capabilities through specific adapter plugins (such as astrbot_plugin_gscore_adapter), making it an excellent choice for lightweight deployment.

0-1-2 Deployment route guide

Depending on your use case and the type of QQ you use, there are two main technical routes here. Based on your actual needs, you can choose the corresponding section below for installation:

Route 1: Personal QQ (“Unofficial”) Fast Track

If you plan to run the bot with your own secondary QQ account and want an intuitive admin panel and a simple deployment flow, this route is recommended.

• Architecture flow: GsCore $\leftrightarrow$ AstrBot $\leftrightarrow$ NapCatQQ $\leftrightarrow$ QQ 客户端
• How it works: NapCatQQ logs in to your personal QQ and converts messages into network protocols; AstrBot, acting as the central controller, receives messages and forwards commands involving game queries to GsCore through the adapter; after GsCore generates beautiful images, they are returned to the user along the same path.

Route 2: Official QQ Bot (“Official Bot”) / Advanced NoneBot Route

If you are using an official bot applied for through the QQ Open Platform, or you rely heavily on NoneBot2's massive plugin ecosystem, this route is recommended.

• Architecture flow: GsCore $\leftrightarrow$ NoneBot2 $\leftrightarrow$ QQ 官方 API (或 NapCat) $\leftrightarrow$ QQ 客户端
• How it works: NoneBot2 acts as a bridge. On one side, it connects to the official API through NoneBot-Adapter-QQ (or to NapCat through the OneBot protocol); on the other, it establishes WebSocket communication with GsCore through the nonebot-plugin-genshinuid plugin, enabling full feature integration.

Warning

Notes

1. Do not blindly copy: The paths (such as /root/bot) and ports (such as 8765, 8080, 6199) in this document are example configurations. If you have your own website (for example, a blog hosted on Nginx), please watch out for port conflicts.
2. Network environment: You may encounter network instability when cloning GitHub repositories or installing dependencies. Please make flexible use of the mirror sources provided in this document (such as changing the pip source, uv proxies, or mirror repositories).
3. Account security: After each console (GsCore, AstrBot, NapCat WebUI) starts up, be sure to change the default password and Token immediately.

0-2 Preparations

1 Install GsCore

1-1 Install uv

1-1-1 Install with pip

1-1-2 Install with pipx

1-1-3 Install with the official script

1‑2 Clone the core

1‑3 Install dependencies

1‑4 Run

Important

Web console: generated on first startup. The default address is localhost:8765/genshinuid, and the username and password are root/root. Be sure to log in and change the password.

WS_TOKEN: it is recommended to fill this in. After setting it, you should configure the same token in the corresponding adapter. If it is not filled in, only the IPs in the TRUSTED_IPS configuration item can connect to GsCore.

For external access, change HOST in bot/gsuid_core/data/config.json to 0.0.0.0 and restart, or simply reverse-proxy localhost:8765.

You can add the following configuration to the reverse proxy so that example.com points to the console instead of example.com/genshinuid:

CodeBlock Loading...

Tip

Besides that, you can also use Docker for quick deployment

1‑5 Install the Wuthering Waves plugin XutheringWavesUID

1-6 Persistence

1-6-1 systemd

Create a file with the .service suffix in the /etc/systemd/system/ directory and write the following basic content:

1-6-2 tmux

1-6-3 screen

2 Install NapCatQQ protocol endpoint

2‑1 Download and run the one-click script

You can also install the tui version:

2‑2 Start

Tip

If you are using the tui version, you can enter sudo napcat and configure and start it in the visual interface.

2-3 Configure the OneBot service through WebUI

You can configure WebUI-related settings in /root/bot/napcat/napcat/config/webui.json or in tui.

For details, refer to NapCat WebUI Configuration Guide

2-4 Persistence

Same as above.

3 Install the NoneBot2 framework

3-1 Install pipx

3‑2 Install the scaffolding

3-3 Generate the project

You can also install and generate the project directly with the following commands

After selecting the bootstrap template, press Enter.

Enter the project name and press Enter.

Use ↑ ↓ to move and Space to select. For personal QQ, choose OneBot V11; for official QQ, choose QQ（QQ 官方机器人）; then press Enter.

Likewise, select the HTTPX and websockets drivers and press Enter.

Keep the defaults and press Enter.

Install the dependencies and the virtual environment.

The echo plugin is optional.

If you do not need it, just press Enter to skip.

3‑4 Connect to GsCore

Install the adapter

If you set WS_TOKEN in GsCore, you need to add the following to .env:

3‑5 Run

3-6 Connect to NapCat

3-6-1 Personal QQ

This assumes you installed the OneBot V11 mentioned above.

Refer to Framework Integration

Add a reverse WS address in the NapCat configuration: ws://127.0.0.1:8080/onebot/v11/ws. Here, 8080 is the port exposed by NoneBot, /onebot/v11/ws is the default path of the NoneBot OneBot adapter, and you should also set the Token.

Modify the NoneBot configuration file .env in the project and add ONEBOT_ACCESS_TOKEN=你在 NapCat 中配置的 token.

3-6-2 Official QQ Bot

This assumes you installed the QQ（QQ 官方机器人） mentioned above.

Refer to NoneBot-Adapter-QQ

Edit the .env file. Append the following block to the file, then change id、token、secret to your own bot information from the developer settings.

3-7 Persistence

Same as above.

4 Install the AstrBot framework

Besides NoneBot2, you can also choose to use AsrtBot; you only need to install one of the two. Note that AstrBot's support for official bots is not very good. It currently cannot send messages properly through GsCore, so if you need to build an official bot, please choose NoneBot2.

4-1 Install through aaPanel

Go to the Docker app store, search for AstrBot, and install it.

After the installation succeeds, click 容器 in the Docker section, find the AstrBot container, click 管理, then 编辑容器, and add port 6199 (the default port of the QQ personal account (aiocqhttp) messaging platform).

Finally, click 安全 in aaPanel's left sidebar and allow the corresponding AstrBot port (default 6185) and port 6199.

4-2 Install with the one-click script

Important

Web console: generated on first startup. The default address is http://127.0.0.1:6185, and the username and password are astrbot/astrbot. Be sure to log in and change the password.
For specific configuration, refer to Integrating with NapCat

4-3 Connect to GsCore

Install astrbot_plugin_gscore_adapter from AstrBot's plugin store and configure it.

• IP address for connecting to GsCore: default localhost
• Port for connecting to GsCore: default 8765
• Bot name registered with GsCore: should default to AstrBot
• WsToken for connecting to Core: the value set in GsCore.

4-4 Add forwarding of quoted images to the GsCore adapter

The adapter now already supports passing quoted images to GsCore.

6 More tutorials

7 XutheringWavesUID FAQ

Q1: How do I apply for an overall ranking token / score OCR token?

A:

Overall ranking token: join the QQ group 653696746387393347, use the QQ account used to join the group to register, star XutheringWavesUID, @ mention the group owner in the group, and wait for approval. After approval, you will be able to see the token on the registration website. If you want to apply for an alias, repeat the steps above.

Score token: star ScoreEcho, @ mention the group owner in the group, and wait for approval.

Warning

Please do not send private messages.

Q2: Where do I enter the overall ranking token / score OCR token?

A:

Overall ranking token:

Score OCR token:

After installing the GsCore plugin ScoreEcho, fill it in here:

Q3: Rendering failed?

A: Run this in the gsuid_core directory:

Q4: Network issues with git clone?

A: Use mirrors: GitCode CNB

Q5: How do I add custom stamina background images

A:

1.In id2name.json under /root/bot/gsuid_core/data/XutheringWavesUID/alias/, add the corresponding id, and make sure it is complex enough to avoid conflicts with Wuthering Waves ids

2.In char_alias.json in the same directory, add its alias

3.Use ww上传xx背景图 to upload it.

Q6: tmux and screen scrolling and viewing historical output

A:

tmux: press Ctrl+B, then [; use 方向键 or PageUp/PageDown to scroll, and press q to exit.

screen: press Ctrl+A, then [; use 方向键 or PageUp/PageDown to scroll, and press q to exit.

Q7: Sign-in plugin

A:

Q8: No response when sending a gacha import link in a group chat

A: By default, the configuration only allows importing through private chat. You can also modify the feature service configuration of the corresponding command in the GsCore web console.

References & Acknowledgements

wwuid

 GsCore

AstrBot

NapCat

NoneBot

https://github.com/Loping151

https://github.com/tyql688