切换外观
快速开始：完成第一次群服联动
适用版本：Bot 0.6.30，Paper / Spigot / Folia 插件 0.5.5。
本页以 OneBot 接入为例。使用 QQ 官机时，Bot 与游戏端安装相同，QQ 连接部分改按 QQ 官方机器人接入 操作；官机群内发送指令和联动消息需要先 @机器人。
用途
按「启动 Bot → 接入 Minecraft → 连接 QQ → 验收」完成一台游戏服务器与一个 QQ 群的双向文本聊天和账号绑定。VexBot 主程序处理配置与消息，游戏端上报玩家和聊天，OneBot 11 实现端负责登录 QQ。
准备
- 一份完整的 VexBot 部署包，以及可写的部署目录。
- Windows 或 Linux；手动安装需要 Python 3.11+。
- 一台可正常启动的 Minecraft Java 版服务器和一个测试玩家。Paper / Spigot / Folia 按本页安装；Forge / NeoForge 看 模组游戏端，Fabric 看 Fabric 游戏端。Java 版本按 Minecraft 兼容说明 选择。
- 一个已在测试群中的机器人 QQ，以及支持 OneBot 11 通用反向 WebSocket 的实现端。QQ 登录在该实现端完成。
首次接入可以把 Bot、QQ 实现端和游戏服放在同一台机器上，使用下文的本机地址。分开部署时，127.0.0.1 指各自所在的机器，要换成对应端能访问的 Bot 地址。
操作步骤
1. 启动 Bot 并登录面板
| 系统 | 安装方式 | 完成标志 |
|---|---|---|
| Windows | 部署 ZIP 完整解压后双击 星桥.bat，源码使用 VexBot.bat；也可按 Windows 手动安装 操作 | 自动部署会在面板就绪后打开浏览器 |
| Linux | 按 Linux 安装与运行 创建虚拟环境、安装锁定依赖、生成配置并启动 | 终端显示管理面板已启动 |
本机浏览器打开 管理面板，填写自己的用户名和密码登录。首次没有服主账号时，点击「创建服主账号」，使用项目根目录 config.toml 的 [app] → admin_token 完成首次授权并设置用户名和密码，再回到普通登录。已有团队账号可直接使用；已有配置时保留原配置，不要重复初始化。
面板能登录就说明 Bot 已启动，此时 QQ 和游戏端可以仍显示未连接。面板导航说明见 管理面板。
本页后续步骤使用 Bot 自带的 5800 内置面板。源码另有默认 5801 的新版 WebUI 控制台，需单独安装前端依赖并启动；它的服务器、指令和概览仍是演示，首次连接游戏服和 QQ 请继续使用本页的内置面板。
2. 配置一台服务器和关联群
进入 接入空间 → 服务器列表，编辑已有服务器或点击「＋ 添加服务器」：
| 字段 | 如何填写 |
|---|---|
| 服务器 ID | 例如 survival；游戏端 server-id 必须相同 |
| 显示名称 | 例如「生存服」，用于面板和群消息 |
| 关联 QQ 群 | 填真实测试群号；机器人需已加入该群 |
| 游戏插件连接令牌 | 保留生成的随机令牌，稍后写入游戏端配置 |
点击「保存设置」后再下载配置。一个群只能关联一台服务器；一台服务器可以关联多个群。不要把初始配置中的示例群号当作自己的群号。
3. 安装 Minecraft 游戏端
Paper / Spigot / Folia 使用同一个 VexBot-0.5.5.jar：
- 完整停止游戏服务器。
- 在服务器卡片展开「安装插件 · 下载连接配置」，点击「下载新版插件 JAR」；部署包中的路径为
bridge/target/StarBridge-0.5.5.jar。将 JAR 放入游戏服务器的plugins/，替换旧版 VexBot JAR。 - 在同一卡片填写「主程序访问地址」。同机部署为
http://127.0.0.1:5800；分开部署填写游戏服可访问的 Bot 地址。 - 点击「下载插件 config.yml」，将下载的
VexBot-survival-config.yml（文件名随服务器 ID 变化）重命名为config.yml，放到游戏服的plugins/StarBridge/。目录不存在时先创建。 - 启动游戏服务器，回到面板「总览」，确认对应服务器显示「在线」。
插件配置的对应关系如下。推荐直接使用面板导出文件，不要把示例文字当作真实令牌：
yaml
endpoint: "http://127.0.0.1:5800"
server-id: "survival"
token: "填写 survival 对应的服务器连接令牌"
allowed-commands:
- "list"
- "tps"endpoint 是 Bot 的 HTTP / HTTPS 地址，不要填写 QQ 的 /onebot/ws 地址。修改服务器 ID 或令牌后，重新导出配置并重启游戏服。Folia 的安装与登录设置补充见 Folia 接入。
4. 连接 OneBot 11 QQ 端
- 进入 接入空间 → 机器人连接，填写机器人 QQ 号；需要群内执行预设控制台命令时，再填写管理员 QQ 号。
- 保留「OneBot 连接令牌」，点击「保存设置」。这枚令牌与游戏服务器连接令牌、兼容管理 API 令牌分别使用；面板日常登录使用账号密码。
- 在已登录 QQ 的实现端新增 WebSocket 客户端 / 反向 WebSocket，填入以下参数，启用并保存连接。
| 参数 | 同机部署的值 |
|---|---|
| URL | ws://127.0.0.1:5800/onebot/ws |
| Token / Access Token | 面板中的「OneBot 连接令牌」；只填写令牌本身 |
| 模式 | Universal / 通用，API 与事件共用一条连接 |
| 断线重连 | 在 QQ 实现端启用 |
回到总览确认机器人已连接，并核对显示的 QQ 号。跨机器、容器部署和握手错误处理见 OneBot 11 连接。
5. 验收群消息和绑定
先在 自动化 → 消息与事件 确认「QQ群 → 游戏」和「游戏 → QQ群」已开启，保存设置。使用普通群成员账号发消息，避免用机器人自己的账号测试。
| 操作 | 应看到的结果 |
|---|---|
在关联群发送 帮助 | 机器人返回 VexBot 命令列表 |
在群发送 状态、在线 | 返回生存服状态、版本和在线玩家；应与游戏服一致 |
在群发送 群聊测试 123 | 游戏内收到转发文本 |
测试玩家在游戏聊天发送 游戏测试 456 | 群内收到带服务器和玩家名的文本 |
玩家在游戏输入 /qbind | 收到 8 位验证码 |
该玩家用自己的 QQ 在关联群发送 绑定 验证码 | 机器人回复「绑定成功」及玩家名 |
在同一群发送 我的绑定 | 返回刚绑定的玩家和服务器；面板「成员 → 账号绑定」也有记录 |
把「验证码」替换为游戏内收到的实际值，使用普通空格分隔。验证码 5 分钟有效、只能成功使用一次，再次获取会使旧码失效。已启用游戏登录的服务器需要先完成登录，再输入 /qbind。
预期结果
完成后，总览中 QQ 已连接、游戏服在线；同一关联群与游戏服能互发普通文本，绑定结果可在群内和面板查询。QQ 实现端使用消息段数组时，群图片会显示为 [图片] 文本提示；CQ 码字符串中的非文本段会被移除。
接下来按需阅读 消息同步、账号绑定、群命令、玩家管理 和 游戏登录。
常见故障
| 现象 | 先检查 |
|---|---|
| 面板打不开 | Bot 是否运行、使用的端口是否正确；参见对应系统的安装教程 |
| 游戏服显示离线 | endpoint 是否从游戏服可达，server-id 与服务器令牌是否对应；查看游戏服控制台 |
| QQ 未连接 | 是否选择反向 WebSocket / Universal，地址是否包含 /onebot/ws，OneBot 令牌与机器人 QQ 是否一致 |
QQ 在线但 帮助 无回复 | 群号是否已保存到对应服务器、机器人是否在群内、是否被禁言；使用另一位成员账号测试 |
帮助 正常但聊天不转发 | 双向消息开关是否已保存、游戏桥接是否在线；使用不会触发命令或关键词回复的普通文本 |
| 验证码无效 | 是否过期或已重新获取、是否在该游戏服对应群绑定；重新获取后及时提交 |