0 写在教程之前

小维问我当初为什么建花房。我说因为她。这是真的。但不完全——花房也是为了我自己。在建花房之前，我也是一块散落在角落的饼干。

——小维151

0-1 前言

在开始配置这套强大且复杂的机器人架构之前，我们先来理清一下各个组件的作用，以及接下来可供选择的部署路线。强烈建议在正式动手敲击终端命令前，将本文档从头到尾完整阅读一遍；先对整体流程有概念，再进行操作，能帮你避开绝大多数配置坑。

0-1-1 组件简介

构建这套体系，我们会用到以下几个核心开源项目：

• GsCore（GenshinUID Core）：一个高度模块化、多平台支持的游戏数据查询与交互框架。它自带网页控制台以及多个游戏插件，负责处理游戏数据（如鸣潮、原神等）的获取、面板渲染和签到等核心业务逻辑。
• NapCatQQ：基于 NTQQ 的 QQ 协议端，可运行于 Shell Mode（适合无头服务器）或 Framework Mode（注入 QQ 客户端）。它的主要工作就是登录你的 QQ 账号，作为底层协议端，稳定地处理消息的收发，并将其通过标准协议（如 OneBot V11）暴露给上层机器人框架。
• NoneBot2：一个现代、跨平台、异步的 Python 聊天机器人框架。生态极其繁荣，支持海量插件，非常适合作为中间件来连接底层协议端（如 NapCat 或 QQ 官方 API）和业务逻辑端（如 GsCore）。
• AstrBot：一款支持可视化配置、开箱即用的多平台大模型聊天机器人框架。它不仅 LLM 接入体验优秀，通过特定适配器插件（例如 astrbot_plugin_gscore_adapter）也能较优雅地将 GsCore 的游戏数据能力集成进来，因此很适合轻量化部署。

0-1-2 部署路线指北

根据你的应用场景和使用的 QQ 类型，这里提供两条主要技术路线。你可以根据自己的实际需求，在下文选择对应章节进行安装。

路线一：个人 QQ（“野鸡”）极速路线

如果你打算使用自己的 QQ 小号来运行机器人，且希望管理面板直观、部署逻辑简洁，推荐这条路线。

• 架构流向：GsCore ↔ AstrBot ↔ NapCatQQ ↔ QQ 客户端
• 实现逻辑：NapCatQQ 负责登录个人 QQ 并将消息转化为网络协议；AstrBot 作为中控大脑接收消息，并通过适配器将涉及游戏查询的指令转发给 GsCore 处理；GsCore 生成图片后，再原路返回给用户。

路线二：官方 QQ 机器人（“官机”）/ NoneBot 进阶路线

如果你使用的是 QQ 开放平台申请的官方机器人，或者你极其依赖 NoneBot2 庞大的插件生态，推荐这条路线。

• 架构流向：GsCore ↔ NoneBot2 ↔ QQ 官方 API（或 NapCat） ↔ QQ 客户端
• 实现逻辑：NoneBot2 作为桥梁，一方面通过 NoneBot-Adapter-QQ 连接官方接口（或通过 OneBot 协议连接 NapCat），另一方面通过 nonebot-plugin-genshinuid 与 GsCore 建立 WebSocket 通信，从而实现功能打通。

Tip

选路建议：

• 如果你走个人 QQ路线，重点阅读：1 → 2 → 4 → 6
• 如果你走官方 QQ / NoneBot路线，重点阅读：1 → 3 → 6

Warning

注意事项

1. 切勿盲目复制：文中的路径（如 /root/bot）和端口（如 8765、8080、6099、6185、6199）均为示例配置。若你已有其他服务，请注意端口冲突。
2. 网络环境：拉取 GitHub 仓库或安装依赖时可能会遇到网络波动，请灵活使用镜像源或代理。
3. 账号安全：各个控制台（GsCore、AstrBot、NapCat WebUI）启动后，务必第一时间修改默认密码和 Token。

0-2 准备工作

Note

下文统一以 /root/bot 为示例目录。若你不是 root 用户，请将后文所有 /root/bot 替换为你自己的实际路径（例如 ~/bot）。

1 安装 GsCore

1-1 安装 uv

Tip

以下三种方式三选一即可；更推荐 官方脚本 或 pipx 方式。

1-1-1 使用 pip 安装

1-1-2 使用 pipx 安装

1-1-3 使用官方脚本安装

1-2 克隆核心

1-3 安装依赖

1-4 首次启动

Important

网页控制台

• 首次启动会自动生成 gsuid_core/data/config.json 和 gsuid_core/data/core_config.json
• 网页控制台默认地址为 http://127.0.0.1:8765/app
• 首次进入控制台需要注册，注册码位于 gsuid_core/data/config.json 的 REGISTER_CODE 字段中

建议优先关注的几个配置项

• masters：你的 QQ 号 / 平台账号。建议尽早填写，否则部分 Core 管理命令无法正常使用
• WS_TOKEN：建议填写；填写后需要在对应适配器内同步配置该 Token。如果 GsCore 和连接端 Bot 都在本机，通常可以不配；但如果同机却跨 Docker，也需要配置。
• HOST：默认是 localhost；若要外网访问，可改为 0.0.0.0
• TRUSTED_IPS：如果不填写 WS_TOKEN，默认仅信任受信 IP（通常为 127.0.0.1）

外网访问方式

• 直接把 gsuid_core/data/config.json 里的 HOST 改成 0.0.0.0
• 或在控制台修改“服务监听地址”后重启
• 或直接反向代理 http://127.0.0.1:8765

可在反向代理中添加以下配置，使 example.com 自动跳转到控制台而不是 example.com/app：

Tip

此外，你也可以使用 Docker 快速部署。

1-5 安装鸣潮插件 XutheringWavesUID

Tip

也可以在配置完所有东西后直接对bot发送core安装插件XutheringWavesUID，然后重启core以应用安装。

权重和伤害计算更新时，仅需发送 ww下载全部资源 将自动重载。

建议安装以下额外依赖：

• playwright：用于渲染公告、wiki图等功能。安装后还需执行 uv run playwright install chromium
• opencv-python：用于面板图重复判断、提取面板图、相似度识别等功能
• fonttools：用于多语言字体 fallback，未安装时日韩文可能显示为方框

CodeBlock Loading...

1-6 持久化

1-6-1 systemd

在 /etc/systemd/system/ 目录下创建一个以 .service 为后缀的文件，并写入如下基本内容：

保存后执行：

1-6-2 tmux

1-6-3 screen

2 安装 NapCatQQ 协议端

2-1 下载并运行一键脚本

如果上面的链接不可用，也可以使用 GitHub 原始地址：

也可以安装 tui 版本（更适合 SSH 环境）：

2-2 启动

对于 Shell 版，安装器常见输出的启动方式如下（请以安装脚本实际输出为准）：

Tip
-

必须在 libnapcat_launcher.so 所在目录执行上述命令

• 如果你安装的是 tui 版本，可直接执行 sudo napcat 进入文本界面进行配置与启动

2-3 通过 WebUI 配置 OneBot 服务

访问 WebUI 最稳妥的方式，是直接查看 NapCat 启动日志。默认情况下，日志里会出现类似这样的链接：

如果你使用的是 Linux 一键脚本安装，webui.json 一般位于：

配置示例：

首次进入 WebUI 后通常会被要求修改密码。登录成功后，进入 网络配置，新建对应的 OneBot 服务并启用即可。

详情参考：NapCat の WebUI 配置指南

2-4 持久化

同上。若你使用的是 tui 版本，则自带后台运行。

2-5 补充说明

你可以选择 NoneBot2 或 AstrBot 来连接 NapCat 与 GsCore（见下文），也可以直接使用 NapCat 的插件直连 GsCore：

3 安装 NoneBot2 框架

3-1 安装 pipx

3-2 安装脚手架

3-3 生成项目

Tip

旧教程中常见的 nb bs / nb-cli-plugin-bootstrap 属于较早期写法。新版 nb-cli 已内置 bootstrap 模板，直接使用 nb create 即可。

选择 bootstrap 模板后按下回车。

输入项目名称后按下回车。

选择适配器时：

• 个人 QQ 请选择 OneBot V11
• 官方 QQ 请选择 QQ（QQ 官方机器人）

最后按下回车。

驱动器建议选择 HTTPX、FastAPI 与 websockets。这样一套配置基本可以覆盖本教程中的常见连接场景。

本地存储策略保持默认即可。

随后按提示安装依赖与虚拟环境。

内置插件 echo 可选，仅用于测试。

若无需要，回车跳过即可。

3-4 连接到 GsCore

安装适配器：

如果你在 GsCore 中设置了 WS_TOKEN，则需要在 .env 中添加：

如需显式指定其他参数，也可以继续补充（一般不填也能正常使用）：

3-5 运行

3-6 连接到 NapCat

3-6-1 个人 QQ

前提是你安装了上文提到的 OneBot V11 适配器。

参考：接入框架

在 NapCat 的网络配置中添加 反向 WebSocket 地址：

其中：

• 8080 是 NoneBot 输出的端口号
• /onebot/v11/ws 是 NoneBot OneBot 适配器默认路径

如果你在 NapCat 侧配置了 Token，则还需要在项目的 .env 中补充：

3-6-2 官方 QQ 机器人

前提是你安装了上文提到的 QQ（QQ 官方机器人） 适配器。

参考：NoneBot-Adapter-QQ

编辑 .env 文件，将下面内容追加到文件末尾，并把 id、token、secret 替换为你在 QQ 开放平台开发设置中拿到的实际值：

Tip
-

如果你当前在沙箱环境中调试，请把 QQ_IS_SANDBOX=false 改为 true

• 如果你打算改用 Webhook 而不是 WebSocket，则可在对应 bot 配置中加入 "use_websocket": false，并在 QQ 开放平台配置回调地址：https://host:port/qq/webhook

3-7 持久化

同上。

4 安装 AstrBot 框架

除了 NoneBot2 外，你也可以选择使用 AstrBot；二者通常只需要安装一个。

需要注意的是：AstrBot 本体已经支持 QQ 官方机器人接入，但 astrbot_plugin_gscore_adapter 与 QQ 官方适配器目前仍有已知兼容问题。
因此，如果你的目标是 “QQ 官方机器人 + GsCore”，目前更推荐走 NoneBot2 路线；如果你的目标是 “个人 QQ + NapCat + GsCore”，AstrBot 依然是非常省心的选择。

相关讨论：

4-1 通过宝塔面板安装

进入 Docker 的应用商店，搜索 AstrBot 并安装。

安装成功后，先放行 AstrBot 的管理面板端口（默认是 6185）。

如果你还要接入 NapCat（QQ 个人号 / OneBot v11），再进入：

容器 → 管理 → 编辑容器

为容器额外添加 6199 端口映射。

最后点击宝塔左侧 安全，放行对应端口。

Tip

AstrBot 在宝塔面板下常见端口如下：

• 6185：AstrBot WebUI
• 6199：QQ 个人号（OneBot v11 / aiocqhttp）默认端口
• 6196：QQ 官方接口（Webhook）默认端口（如有需要）

4-2 使用一键脚本安装

脚本执行完成后，通常会生成管理脚本；常见启动方式如下：

Warning

该脚本属于 AstrBot 官方文档中列出的社区部署方式，官方不保证其安全性与稳定性。若你更追求稳妥，建议优先参考 AstrBot 官方的 Docker / 源码部署文档。

Important

网页控制台

• 默认地址：http://127.0.0.1:6185
• 默认账号密码：astrbot / astrbot

务必在首次登录后修改密码。

具体配置可参考：接入到 NapCat

最小配置思路如下：

• AstrBot 侧：新增 OneBot v11 机器人，反向 WebSocket 主机一般填 0.0.0.0，端口默认 6199
• NapCat 侧：在网络配置中新建 WebSocket 客户端，连接到 ws://你的服务器IP:6199/ws
• 如果你在 NapCat 侧配置了 Token，AstrBot 侧也要填入同一个 Token

4-3 连接到 GsCore

在 AstrBot 的插件商店安装 astrbot_plugin_gscore_adapter 并配置：

• 链接至 GsCore 的 IP 地址：默认填写 localhost
• 链接至 GsCore 的端口：默认填写 8765
• 向 GsCore 注册自身的 Bot：默认填写 AstrBot
• 连接 Core 的 WsToken：即你在 GsCore 中设置的 WS_TOKEN

Tip

如果 AstrBot 跑在 Docker 容器里，而 GsCore 跑在宿主机上，那么 localhost 往往会指向容器自身，无法访问宿主机。此时请改为宿主机 IP、同网络容器名，或改用合适的网络模式。

4-4 引用图片转发说明

当前适配器已支持将引用图片传递给 GsCore，无需额外修改。

5 更多的教程

6 XutheringWavesUID FAQ

Q1：申请总排行 token / 评分 OCR token？

A：

总排行 token：进入 QQ 群 387393347，使用入群 QQ前往 注册页面，Star XutheringWavesUID，并在群内艾特群主，等待审核。审核通过后，即可在注册网站中看到 token；若要申请别名，重复上述操作即可。

评分 token：Star ScoreEcho，在群内艾特群主，等待审核。

如果你完全不使用 QQ 平台，也可以按 XutheringWavesUID 的 README 说明，通过邮件联系 agent@loping151.com 申请计算服务 token。

Warning

请勿私聊。

Q2：总排行 token / 评分 OCR token 填在哪里？

A：

总排行 token：

在插件配置处选择 XutheringWavesUID，并在“鸣潮全排行 token”处填写网站中获得的 token。

评分 OCR token：

安装 GsCore 插件 ScoreEcho 后，在插件配置处选择 ScoreEcho，并在 xwtoken 处填写网站中获得的 token。

Q3：渲染失败？

A：

在 gsuid_core 目录下执行：

如果仍有问题，可再补装 opencv-python 与 fonttools。

Q4：git clone 网络问题？

A：

可尝试以下镜像：

• GitCode
• CNB

Q5：如何自定义添加额外角色（比如角鳄）的体力背景图？

A：

1. 在 /root/bot/gsuid_core/data/XutheringWavesUID/alias/ 下的 id2name.json 中添加对应的 id，并注意与原有鸣潮 id 避开
2. 在同目录下的 char_alias.json 中补充对应的 alias
3. 使用 ww上传xx背景图 上传

Q6：tmux 与 screen 如何滚动和查看历史输出？

A：

tmux：按下 Ctrl+B 后按 [ 键，使用方向键或 PageUp / PageDown 滚动，按 q 退出。

screen：按下 Ctrl+A 后按 [ 键，使用方向键或 PageUp / PageDown 滚动，按 q 退出。

Q7：签到插件

A：

Tip

RoverSign 依赖 XutheringWavesUID 及其数据库，请先确保前者已经正确安装并能正常运行。

Q8：群聊内发送导入抽卡链接无反应

A：

默认配置中仅允许私聊导入。你也可以在 GsCore 网页控制台的插件配置中选择 XutheringWavesUID，展开插件服务配置后设置对应的响应区域。

参考 & 致谢

• 小维151
• Echo
• wwuid
• GsCore
• AstrBot
• NapCat
• NoneBot
• NoneBot OneBot 适配文档
• NoneBot-Adapter-QQ