Linux安装鸣潮机器人 XutheringWavesUID

快速导航

• 0 写在教程之前：了解组件、选择路线、准备环境
• 1 安装 GsCore：安装核心、鸣潮插件与后台运行
• 2 安装 NapCatQQ：个人 QQ 协议端
• 3 安装 NoneBot2：个人 QQ 或 QQ 官方机器人路线
• 4 安装 AstrBot：个人 QQ 与 LLM 路线
• 5 延伸教程
• 6 XutheringWavesUID FAQ

0 写在教程之前

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

——小维151

0-1 前言

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

如果在部署中遇到困难，也可以尝试将本文喂给AI。

以及：

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 通信，从而实现功能打通。

0-1-3 常用端口速查

0-2 准备工作

# 创建总目录
mkdir -p /root/bot && cd /root/bot

# 安装基础依赖
sudo apt update
sudo apt install -y python3 python3-pip python3-venv python3-tk git curl wget

1 安装 GsCore

本章是所有路线的共同基础。完成 GsCore 和鸣潮插件安装后，再按路线继续阅读第 2、3 或 4 章。

1-1 安装 uv

1-1-1 使用 pip 安装

pip install uv --break-system-packages

# 也可在虚拟环境中安装

# 创建虚拟环境
python3 -m venv venv

# 激活虚拟环境
source venv/bin/activate

# 安装 uv
pip install uv

# 退出虚拟环境
deactivate

1-1-2 使用 pipx 安装

# 安装 pipx
sudo apt install -y pipx
pipx ensurepath

# 重新打开终端；或者执行下面这句让当前 shell 立即生效
exec $SHELL

# 安装 uv
pipx install uv

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

curl -LsSf https://astral.sh/uv/install.sh | sh

# 如果系统没有 curl，可以使用 wget
wget -qO- https://astral.sh/uv/install.sh | sh

1-2 克隆核心

git clone https://github.com/Genshin-bots/gsuid_core.git --depth=1 --single-branch
cd gsuid_core

1-3 安装依赖

# 推荐写法
uv python install 3.13
uv sync --python 3.13
uv run python -m ensurepip

# 如果你当前环境的 Python 版本已经满足要求，也可以使用：
# uv venv --seed
# uv sync

GsCore 当前要求 Python >=3.11,<4.0，这里使用 Python 3.13 是兼容范围内的推荐示例。

1-4 首次启动

uv run core

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

location = / {
    return 301 /app/;
}

1-5 安装鸣潮插件 XutheringWavesUID

cd /root/bot/gsuid_core/gsuid_core/plugins/
git clone https://github.com/Loping151/XutheringWavesUID.git --depth=1

# 重新运行 GsCore
cd /root/bot/gsuid_core
uv run core

# Linux/Mac
source .venv/bin/activate && uv pip install playwright opencv-python fonttools pypinyin rapidfuzz && uv run playwright install chromium
# Windows
.venv\Scripts\activate; uv pip install playwright opencv-python fonttools pypinyin rapidfuzz; uv run playwright install chromium

1-6 后台运行与持久化

1-6-1 systemd

创建 /etc/systemd/system/gscore.service，并写入如下基本内容：

[Unit]
Description=GsCore
Wants=network-online.target
After=network-online.target

[Service]
# 国内镜像源
# Environment="UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple"
Type=simple

# 修改为你自己的 GsCore 路径
WorkingDirectory=/root/bot/gsuid_core

# 先执行 which uv，把下面路径改成你的实际输出
ExecStart=/root/.local/bin/uv run core

# 如果服务异常退出，则自动重启
Restart=on-failure
RestartSec=5

# 如需指定运行用户，可修改为你的实际用户
User=root

[Install]
WantedBy=multi-user.target

如果你使用普通专用用户部署，请将 User=root、WorkingDirectory 和 ExecStart 一并替换为该用户及对应的绝对路径。

保存后执行：

sudo systemctl daemon-reload
sudo systemctl enable --now gscore
sudo systemctl status gscore

1-6-2 tmux（临时后台运行）

# 安装并启动一个会话
sudo apt update && sudo apt install -y tmux
tmux new -s sayu

# 在 tmux 里启动
uv run core

# 按 Ctrl-b 然后按 d 退出会话，进程会继续在后台运行

# 需要时重新连接
tmux attach -t sayu

1-6-3 screen（临时后台运行）

# 安装
sudo apt install -y screen
screen --version

# 启动并命名新会话
screen -S GsCore

# 在 screen 里启动
uv run core

# 将会话分离到后台
# 在 Screen 会话中按 Ctrl+a，然后按 d

# 列出所有会话
screen -ls

# 重新连接会话
screen -r GsCore   # 重新连接名称为 GsCore 的会话
screen -r 12345    # 重新连接 id 为 12345 的会话

# 结束会话
# 正常退出：在会话中执行 exit 或按 Ctrl+d
screen -X -S GsCore quit   # 强制终止

2 安装 NapCatQQ 协议端

本章仅用于个人 QQ。使用 QQ 官方机器人时可跳过本章，直接阅读 NoneBot2 的官方 QQ 机器人配置。

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

cd /root/bot
mkdir -p napcat && cd napcat

# NapCat 中文指南页常见的一键安装方式
curl -o \
napcat.sh \
https://nclatest.znin.net/NapNeko/NapCat-Installer/main/script/install.sh \
&& bash napcat.sh

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

curl -o  \
napcat.sh \
https://raw.githubusercontent.com/NapNeko/napcat-linux-installer/refs/heads/main/install.sh \
&& bash napcat.sh

也可以在 Shell 安装时启用 TUI-CLI（更适合 SSH 环境）：

curl -o \
napcat.sh \
https://nclatest.znin.net/NapNeko/NapCat-Installer/main/script/install.sh \
&& bash napcat.sh \
--docker n \
--cli y

2-2 启动

对于 Shell 版，优先使用安装器生成的服务或启动脚本，并以安装完成时的实际输出为准：

# 示例：运行安装器生成的启动脚本
sudo bash ./launcher.sh

2-3 通过 WebUI 配置 OneBot 服务

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

http://127.0.0.1:6099/webui?token=xxxxx

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

/opt/QQ/resources/app/app_launcher/napcat/config/webui.json

配置示例：

{
  "host": "0.0.0.0", // WebUI 监听地址
  "port": 6099,      // WebUI 端口
  "token": "xxxx",   // 登录密钥，默认是自动生成的随机密码
  "loginRate": 3     // 每分钟登录次数限制
}

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

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

2-4 持久化

如果使用安装器生成的服务或 TUI-CLI，一般已经具备后台运行能力；否则可参考 1-6 后台运行与持久化 的思路进行配置。

2-5 补充说明

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

Repository · xiowo

28

napcat-plugin-gscore-adapter

一个适用于NapCat的GScore适配器

TypeScript

3 安装 NoneBot2 框架

选择 NoneBot2 路线时阅读本章；如果个人 QQ 路线已经确定使用 AstrBot，可跳到第 4 章。

3-1 安装 pipx

sudo apt install -y pipx
pipx ensurepath
exec $SHELL

3-2 安装脚手架

pipx install nb-cli

3-3 生成项目

cd /root/bot

# 按提示输入项目名
nb create

选择 bootstrap 模板后按下回车。

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

选择适配器时：

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

最后按下回车。

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

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

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

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

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

3-4 连接到 GsCore

安装适配器：

cd /root/bot/<你的项目名>
nb plugin install nonebot-plugin-genshinuid

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

gsuid_core_ws_token=你的Token

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

# gsuid_core_host=localhost
# gsuid_core_port=8765
# gsuid_core_botid=NoneBot2

3-5 运行

nb run

3-6 连接消息平台

3-6-1 个人 QQ：连接到 NapCat

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

参考：接入框架

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

# 两边都在同一个 Docker Compose 网络时，填写 ws://nonebot:8080/onebot/v11/ws；只有 NapCat 在 Docker 时，用宿主机 IP；都不在 Docker 时，再用 localhost 或 127.0.0.1。
ws://127.0.0.1:8080/onebot/v11/ws

其中：

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

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

ONEBOT_ACCESS_TOKEN=你在 NapCat 中配置的 token

3-6-2 官方 QQ 机器人：连接到 QQ 开放平台

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

参考：NoneBot-Adapter-QQ

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

QQ_IS_SANDBOX=false
QQ_BOTS='
[
  {
    "id": "xxx",
    "token": "xxx",
    "secret": "xxx",
    "intent": {
      "c2c_group_at_messages": true
    }
  }
]
'

3-7 持久化

可参考 1-6 后台运行与持久化 配置 systemd，或使用下一节的 Docker 部署方式。

3-8 Docker 部署（可选）

本文仍以手动部署为主。如果希望把已经创建好的 NoneBot 项目容器化，可在项目目录使用 NoneBot 官方的 Docker 插件：

nb self install nb-cli-plugin-docker
nb docker generate
nb docker up
nb docker logs

# 停止
nb docker down

nb docker generate 会生成基础的 Dockerfile 与 docker-compose.yml。NapCat、NoneBot 和 GsCore 位于同一个 Compose 网络时，应使用 Compose service 名互相访问，例如 NapCat 连接 ws://nonebot:8080/onebot/v11/ws，NoneBot 连接 GsCore 时填写 gsuid_core_host=gscore，不要填写 localhost。

4 安装 AstrBot 框架

本章适合“个人 QQ + NapCat + AstrBot + GsCore”路线；已经选择 NoneBot2 的用户通常不需要再安装 AstrBot。

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

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

AstrBot 官方优先维护 Docker 与源码 / uv 部署方式；下面的宝塔和 Antlia 脚本适合希望简化操作的用户，使用前仍建议对照官方部署文档。

相关讨论：

Issue · KimigaiiWuyi/astrbot_plugin_gscore_adapter

#7

[bug] 似乎不适配qq官方适配器

opentinkerbellqwq32025-04-24

4-1 通过宝塔面板安装

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

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

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

容器 → 管理 → 编辑容器

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

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

4-2 使用一键脚本安装

cd /root/bot
mkdir -p astrbot && cd astrbot

# 社区提供的 Linux 一键部署脚本
bash <(curl -sSL https://raw.githubusercontent.com/zhende1113/Antlia/refs/heads/main/Script/AstrBot/Antlia.sh)

# 如果系统没有 curl，可以使用 wget
wget -qO- https://raw.githubusercontent.com/zhende1113/Antlia/refs/heads/main/Script/AstrBot/Antlia.sh | bash

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

./astrbot.sh

最小配置思路如下：

• AstrBot 侧：新增 OneBot v11 机器人，反向 WebSocket 主机一般填 0.0.0.0，端口默认 6199
• NapCat 侧：在网络配置中新建 WebSocket 客户端，连接到 ws://你的服务器IP:6199/ws
• 如果你在 NapCat 侧配置了 Token，AstrBot 侧也要填入同一个 Token
• 在 AstrBot 的 配置文件 → 平台配置 → 管理员 ID 中填写管理者 QQ；它与 GsCore 的 masters 权限相互独立，需要分别配置

4-3 连接到 GsCore

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

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

4-4 引用图片转发说明

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

5 延伸教程

6 XutheringWavesUID FAQ

更新日期：2026.07.18

6-1 Token 申请与配置

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

A：

总排行 token：用于接入插件的总排行服务。当前上游公布的总排行申请、反馈群为 885617919，仅限 Bot 主人加入，入群问题需要注意大小写。具体申请方式以 XutheringWavesUID README 和群公告为准。

评分 token：用于声骸评分插件 ScoreEcho，无需额外申请，可直接复用总排行 token。

如果你完全不使用 QQ 平台，也可以按 XutheringWavesUID 的 README 说明，通过邮件联系 agent@loping151.com 申请对应的 token。邮件需要填写标题，并附上使用平台、Core 信息截图、使用情况和规模说明。

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

A：

总排行 token：

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

评分 OCR token：

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

6-2 安装与运行故障

Q3：渲染失败

A：

在 gsuid_core 目录下执行：

# Linux
source .venv/bin/activate && uv pip install playwright opencv-python fonttools pypinyin rapidfuzz && uv run playwright install chromium

# Windows
.venv\Scripts\activate; uv pip install playwright opencv-python fonttools pypinyin rapidfuzz; uv run playwright install chromium

如果 Core 已经自动安装了 Python 包，也仍需单独执行一次 uv run playwright install chromium。

Q4：git clone 网络问题

A：

可尝试以下镜像：

• GitCode
• CNB

6-3 功能与日常使用

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：

cd /root/bot/gsuid_core/plugins/
git clone https://github.com/Loping151/RoverSign.git --depth=1

# 重新运行
cd /root/bot/gsuid_core
uv run core

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

A：

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

Q9：没有域名/公网如何使用登录链接？

A：可以使用可信的内网穿透、SSH 端口转发或带 HTTPS 的反向代理。社区提供的公益外置登录地址可能随时变化，应以当前项目 README 或群公告为准，不要继续使用旧教程中的地址。

Q10：关于代理池

A：当你的 IP 频繁请求被风控时需要代理 IP 来继续请求库洛服务器。

如需社区提供的代理服务，请以当前项目 README 或群公告为准（已关门，自行寻找如多米等的代理服务）。若你的用户量较少，也可以选择自建：

Repository · gufei233

rover-proxy

Shell

6-4 更新与资源异常

Q11：权重文件异常

A：

首先确保你的 gscore 与插件本体为最新版本

core全部更新

core重启

并强制下载全部资源

ww强制下载全部资源

若还未解决，可尝试删除插件重新拉取最新代码。

参考 & 致谢

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