QQbot_awa

QQbot_awa 使用教程

基于QQ官方机器人API的Minecraft服务器管理机器人

适用版本：v1.2.1 及以上（基于 botpy 重构版）

v1.2 及以前版本和napcat版本请戳这里

---

环境要求

• Python：3.8 及以上
• 依赖安装：

pip install botpy aiohttp pycryptodome

---

快速开始

1. 配置机器人信息

编辑代码顶部的配置区：

APP_ID = "你的AppID"
APP_SECRET = "你的AppSecret"

2. 服务器连接模式

默认模式（推荐）

机器人自动连接指定服务器：

DEFAULT_SERVER_MODE = True            # 开启默认服务器模式
DEFAULT_SERVER_URL = "example.com:25565"   # 服务器地址
DEFAULT_SERVER_PASS = "password"           # 服务器密码

开启后无需手动 /link，机器人自动关联服务器

手动模式

关闭 DEFAULT_SERVER_MODE = False，通过指令手动绑定。

3. 运行机器人

python qqbot_client.py

---

Bot 端指令（QQ 私聊/群聊）

所有指令以 / 开头，支持群聊和私聊

基础指令

指令	说明
/ping	测试机器人连通状态
/help	发送帮助图片
/changelog	查看更新日志

服务器绑定（仅手动模式）

指令	说明
/link [IP:端口] [密码]	手动绑定服务器
/unlink	解除当前服务器绑定

账号绑定

指令	说明
/bind	查看绑定状态和指南
/bind bot	获取快捷绑定码（需私聊）
/bind server [验证码]	提交游戏内生成的验证码
/unbind	解绑QQ与游戏账号
/state [1/2]	设置状态：1=在线，2=隐身

查询指令

指令	说明
/server	查看在线人数与玩家列表
/tps	查看服务器 TPS
/player [ID]	查询玩家数据（绑定后可查自己）

管理员指令

需要服务器管理员权限

指令	说明
/admin	查看管理员列表
/request	查看进服审核列表
/accept [编号/all]	通过审核
/refuse [编号/QQ]	拒绝申请
/ban [玩家名] [小时]	封禁玩家（不填=永久）
/unban [玩家名]	解除封禁
/clean [ID/QQ]	清理并解绑玩家
/changelog edit [内容]	编辑更新日志

---

玩家使用流程

默认服务器模式（最常用）

1. 加入QQ群 → 机器人已自动关联服务器
2. 私聊机器人发送 /bind bot → 获取验证码
3. 进入游戏输入 /qqbot bind bot [验证码] → 完成绑定
4. 绑定后可使用 /player 查询自己的游戏数据

---

服务端 Mod 安装与配置

兼容性：仅支持 Fabric 服务器

安装步骤

1. 将 Mod 文件放入服务器的 mods 文件夹
2. 首次启动 Mod，自动在 config 文件夹下生成 awabot.properties 配置文件

⚙️ 配置项详解

配置项	说明	可选值
port=	Mod 开放的 API 端口号	数字（如 1146）
password=	机器人连接时的验证密码	任意字符串
safety=	入服验证等级	见下表
prevent_multi_bind=	绑定限制规则	见下表

safety — 入服验证等级

值	效果
0	开放模式：无需绑定，任何人都能进服
1	绑定模式：必须绑定QQ才能进服，绑定后自动通过
2	审核模式：必须绑定QQ + 管理员人工批准才能进服

prevent_multi_bind — 绑定限制规则

值	效果
0	一个QQ可绑定多个游戏账号（不限制）
1	一个QQ只能绑定一个游戏账号（防多开）

---

🎮 游戏内指令（服务端）

所有指令以 /qqbot 开头

玩家指令

指令	说明
/qqbot bind server	生成 4 位绑定验证码（有效期5分钟）
/qqbot bind bot [验证码]	提交 Bot 端获取的快捷绑定码

管理员指令（仅控制台）

指令	说明
qqbot admin <玩家名>	将已绑定/待审核玩家设为管理员
qqbot admin <玩家名> <QQ号>	强制绑定并设为管理员
qqbot unadmin <玩家名或QQ号>	移除管理员权限

其他指令

指令	说明
/qqbot unbind	提示换绑请联系管理员（仅提示）

---