Linux安装鸣潮机器人 XutheringWavesUID
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 类型,这里提供两条手动部署路线,以及一条更省事的 Docker Compose 快速部署路线。你可以根据自己的实际需求,在下文选择对应章节进行安装。
路线一:个人 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 通信,从而实现功能打通。
路线三:Docker Compose 快速部署路线
如果你想尽快把整套服务跑起来,且暂时不想逐个手动安装 GsCore、NapCat、AstrBot,可以使用我整理的 Compose 仓库:
- NAG 版本:
GsCore ↔ AstrBot ↔ NapCatQQ,适合需要 AstrBot 的 WebUI、LLM、多平台管理与插件生态的用户。 - NG 轻量版本:
GsCore ↔ napcat-plugin-gscore-adapter ↔ NapCatQQ,适合不需要 AstrBot,只想让 NapCat 插件直连 GsCore 的用户。 项目地址:
选路建议:
如果你想快速从零部署,优先阅读:0-3
- 如果你走个人 QQ路线,重点阅读:
1 → 2 → 4 → 6 - 如果你走官方 QQ / NoneBot路线,重点阅读:
1 → 3 → 6
注意事项
- 切勿盲目复制:文中的路径(如
/root/bot)和端口(如8765、8080、6099、6185、6199)均为示例配置。若你已有其他服务,请注意端口冲突。 - 网络环境:拉取 GitHub 仓库或安装依赖时可能会遇到网络波动,请灵活使用镜像源或代理。
- 账号安全:各个控制台(GsCore、AstrBot、NapCat WebUI)启动后,务必第一时间修改默认密码和 Token。
0-2 准备工作
下文统一以 /root/bot 为示例目录。若你不是 root 用户,请将后文所有 /root/bot 替换为你自己的实际路径(例如 ~/bot)。
# 创建总目录
mkdir -p /root/bot && cd /root/bot
# 安装基础依赖
sudo apt update
sudo apt install -y python3 python3-pip python3-venv python3-tk git curl wget
0-3 Docker Compose 快速部署
如果你只是想先把服务跑起来,推荐直接使用 Compose 仓库。完整说明、非 root 部署、端口绑定、插件初始化、XutheringWavesUID 额外依赖、NapCat 登录态持久化等细节,都以仓库 README 为准;这里仅放一个入口。
0-3-1 NAG:GsCore + AstrBot + NapCat
适合需要 AstrBot 的用户:
git clone https://github.com/gufei233/NAG.git
cd NAG
cp .env.example .env
# root 用户示例;非 root 用户请按 README 的非 root 路径处理 DATA_ROOT 权限
mkdir -p /opt/nag-data/{astrbot,napcat/config,napcat/qq,gscore/data,gscore/plugins}
docker compose up -d
docker compose ps
详细文档:
0-3-2 NG:GsCore + NapCat 插件直连
适合不需要 AstrBot、只想更轻量接入个人 QQ 的用户:
git clone https://github.com/gufei233/NAG.git
cd NAG/NG
cp .env.example .env
# root 用户示例;非 root 用户请按 README 的非 root 路径处理 DATA_ROOT 权限
mkdir -p /opt/ng-data/{napcat/config,napcat/plugins,napcat/qq,gscore/data,gscore/plugins}
docker compose up -d
docker compose ps
详细文档:
Compose 方式更适合从零部署和日常运维;后面的手动安装章节仍然建议保留阅读,尤其在你需要理解组件关系、排查连接问题、或改用 NoneBot2/官方 QQ 机器人路线时会很有帮助。
1 安装 GsCore
1-1 安装 uv
以下三种方式三选一即可;更推荐 官方脚本 或 pipx 方式。
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
1-4 首次启动
uv run core
网页控制台
- 首次启动会自动生成
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.0TRUSTED_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:
location = / {
return 301 /app/;
}

WS_TOKEN、TRUSTED_IPS 与 HOST 的修改
此外,你也可以使用 Docker 快速部署。
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
也可以在配置完所有东西后直接对bot发送core安装插件XutheringWavesUID,然后重启core以应用安装。
权重和伤害计算更新时,仅需发送 ww下载全部资源 将自动重载。
建议安装以下额外依赖:
playwright:用于渲染公告、wiki图等功能。安装后还需执行uv run playwright install chromiumopencv-python:用于面板图重复判断、提取面板图、相似度识别等功能fonttools:用于多语言字体 fallback,未安装时日韩文可能显示为方框
# Linux/Mac
source .venv/bin/activate && uv pip install playwright opencv-python fonttools && uv run playwright install chromium
# Windows
.venv\Scripts\activate; uv pip install playwright opencv-python fonttools; uv run playwright install chromium
1-6 持久化
1-6-1 systemd
在 /etc/systemd/system/ 目录下创建一个以 .service 为后缀的文件,并写入如下基本内容:
[Unit]
Description=GsCore
After=network.target
[Service]
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
保存后执行:
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 协议端
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
也可以安装 tui 版本(更适合 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 版,安装器常见输出的启动方式如下(请以安装脚本实际输出为准):
./napcat --shell
Xvfb :1 -screen 0 1x1x8 +extension GLX +render > /dev/null 2>&1 &
export DISPLAY=:1
sudo su
LD_PRELOAD=./libnapcat_launcher.so qq --no-sandbox
# 或直接运行安装器生成的启动脚本
sudo bash ./launcher.sh
必须在 libnapcat_launcher.so 所在目录执行上述命令
- 如果你安装的是
tui版本,可直接执行sudo napcat进入文本界面进行配置与启动
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 版本,则自带后台运行。
2-5 补充说明
你可以选择 NoneBot2 或 AstrBot 来连接 NapCat 与 GsCore(见下文),也可以直接使用 NapCat 的插件直连 GsCore:
3 安装 NoneBot2 框架
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
旧教程中常见的 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
安装适配器:
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 连接到 NapCat
3-6-1 个人 QQ
前提是你安装了上文提到的 OneBot V11 适配器。
参考:接入框架
在 NapCat 的网络配置中添加 反向 WebSocket 地址:
# 两边都在 Docker 时,把 NapCat 的 WS 地址改成 ws://astrbot:6199/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 官方机器人) 适配器。
编辑 .env 文件,将下面内容追加到文件末尾,并把 id、token、secret 替换为你在 QQ 开放平台开发设置中拿到的实际值:
QQ_IS_SANDBOX=false
QQ_BOTS='
[
{
"id": "xxx",
"token": "xxx",
"secret": "xxx",
"intent": {
"c2c_group_at_messages": true
}
}
]
'
如果你当前在沙箱环境中调试,请把 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 端口映射。
最后点击宝塔左侧 安全,放行对应端口。
AstrBot 在宝塔面板下常见端口如下:
6185:AstrBot WebUI6199:QQ 个人号(OneBot v11 / aiocqhttp)默认端口6196:QQ 官方接口(Webhook)默认端口(如有需要)
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 官方文档中列出的社区部署方式,官方不保证其安全性与稳定性。若你更追求稳妥,建议优先参考 AstrBot 官方的 Docker / 源码部署文档。
最小配置思路如下:
- 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
如果 AstrBot 跑在 Docker 容器里,而 GsCore 跑在宿主机上,那么 localhost 往往会指向容器自身,无法访问宿主机。此时请改为宿主机 IP、同网络容器名,或改用合适的网络模式。
4-4 引用图片转发说明
当前适配器已支持将引用图片传递给 GsCore,无需额外修改。
5 更多的教程
6 XutheringWavesUID FAQ
更新日期:2026.06.08
Q1:申请总排行 token / 评分 OCR token
A:
总排行 token:用于接入插件的总排行服务。使用Bot 主人 QQ进入 QQ 群 387393347,使用入群 QQ前往 注册页面,Star XutheringWavesUID,并在群内艾特群主,等待审核。审核通过后,即可在注册网站中看到 token;若要申请别名,重复上述操作即可。
评分 token:用于声骸评分插件 ScoreEcho,无需额外申请,可直接复用总排行 token。
如果你完全不使用 QQ 平台,或者想单独使用声骸评分插件,也可以按 XutheringWavesUID 的 README 说明,通过邮件联系 agent@loping151.com 申请对应的 token。
请勿私聊。
Q2:总排行 token / 评分 OCR token 填在哪里
A:
总排行 token:
在插件配置处选择 XutheringWavesUID,并在“鸣潮全排行 token”处填写网站中获得的 token。


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

Q3:渲染失败
A:
在 gsuid_core 目录下执行:
# Linux
source .venv/bin/activate && uv pip install playwright && uv run playwright install chromium
# Windows
.venv\Scripts\activate; uv pip install playwright; uv run playwright install chromium
如果仍有问题,可再补装 opencv-python 与 fonttools。
Q4:git clone 网络问题
A:
可尝试以下镜像:
Q5:如何自定义添加额外角色(比如角鳄)的体力背景图
A:
- 在
/root/bot/gsuid_core/data/XutheringWavesUID/alias/下的id2name.json中添加对应的id,并注意与原有鸣潮id避开 - 在同目录下的
char_alias.json中补充对应的alias - 使用
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
RoverSign 依赖 XutheringWavesUID 及其数据库,请先确保前者已经正确安装并能正常运行。
Q8:群聊内发送导入抽卡链接无反应
A:
默认配置中仅允许私聊导入。你也可以在 GsCore 网页控制台的插件配置中选择 XutheringWavesUID,展开插件服务配置后设置对应的响应区域。


Q9:没有域名/公网如何使用登录链接?
A:可以选择使用群友搭建的公益外置登录[^1],也可以使用内网穿透。

配置外置登录url如https:example.com,并关闭强制为自己域名
Q10:关于代理池
A:当你的 IP 频繁请求被风控时需要代理 IP 来继续请求库洛服务器。
你可以选择小维的付费服务(详见QQ群)。若你的用户量较少,也可以选择自建:
Q11:权重文件异常
A:
首先确保你的 gscore 与插件本体为最新版本
core全部更新
core重启
并强制下载全部资源
ww强制下载全部资源
若还未解决,可尝试删除插件重新拉取最新代码。
参考 & 致谢
- 小维151
- Echo
- wwuid
- GsCore
- GsCore Docker 镜像
- AstrBot
- NapCat
- NapCat-Docker
- NoneBot
- NoneBot OneBot 适配文档
- NoneBot-Adapter-QQ
- 1: 群指 3873933,并按下图配置。返回1