快速开始

约 1002 字大约 3 分钟

欢迎使用 Minecraft UniBot。本页将带你走完从零到可正常使用的完整部署流程，整个过程大约 10 分钟。

术语说明

在开始之前，先明确以下术语的含义，以避免后续产生歧义：

名称	含义
核心 / 实现端	指 `UniBot` 本体，即一个 NoneBot2 服务器，真正实现机器人功能的项目
机器人	QQ 机器人、Telegram Bot 等，指在各个平台上创建的机器人账号
机器人协议端	部分机器人（如 QQ）需要一个转接服务才能对接核心，该转接服务即协议端；部分平台则无需此环节

步骤	内容	对应章节
①	安装机器人本体	第一步
②	服务器安装并配置鹊桥插件	第二步
③	接入聊天平台	第三步
④	验证机器人可用	第四步

前置要求

组件	要求
Python	3.11+
包管理器	UV（推荐）或 pip
Minecraft 服务端	Fabric / Forge / Spigot / Paper / MCDR 等均可，需已安装鹊桥插件
聊天机器人账号	QQ 机器人、Telegram Bot 等

第一步：安装 UniBot

一键脚本安装（推荐）

从 Releases 页面下载对应平台的一键安装脚本：

平台	脚本
Windows	`Install.bat`，双击运行即可，自动完成安装 uv、克隆仓库、配置 WebUI 并同步依赖
Linux / macOS	`Install.sh`，先执行 `chmod +x Install.sh`，再运行 `./Install.sh`

脚本将自动完成：检测并安装 UV、拉取对应版本仓库、询问是否启用 WebUI、执行 uv sync 同步依赖。

启用 WebUI 后，后续基本无需手动修改配置。 安装脚本会询问是否启用 WebUI，选择启用后，机器人将附带一个可视化管理面板。启动后浏览器访问 http://<你的IP>:<PORT>/webui（默认 http://127.0.0.1:8000/webui），首次访问按提示初始化管理员账户，即可在 WebUI 中配置聊天平台、管理服务器、查看日志，全程无需再手动编辑 .env 或 Config.toml。

手动安装（可选）

# 克隆项目并创建虚拟环境
git clone https://github.com/MineJPGcraft/UniBot
cd UniBot
uv sync

# 按需安装可选功能（图片渲染 / WebUI / AI）
uv sync --extra image --inexact
uv sync --extra webui --inexact
uv sync --extra ai --inexact

# 启动机器人
uv run Watchdog.py

~~也可使用 pip + venv 安装~~，具体命令可参考配置说明，但更推荐使用 uv 进行管理。

第二步：安装鹊桥插件并配置

每一台 Minecraft 服务器 上，均需安装鹊桥插件，才能接入机器人本体。

安装完成后还需进行配置，才能使服务器与机器人建立连接并正常通信。详细的安装方法与插件下载地址，请参阅鹊桥安装&配置说明，可根据需求自行选择安装模式。

第三步：接入聊天平台

此外，还需安装并配置对应的适配器，才能让机器人账号连接上核心。

各平台适配器的具体配置项，请参阅配置说明。

第四步：验证启动

机器人启动后，在聊天群中发送：

.help

若一切正常，机器人将返回可用的命令列表。再发送 .server 即可查看当前在线、已连接的服务器。

常见问题

机器人不响应指令？ 请检查 COMMAND_START 前缀、command_groups 中是否包含当前群，以及 SUPERUSERS 中是否包含你的账号。
连不上服务器？ 请确认两端的 access_token 一致、WebSocket 地址与端口可达，并查看 MCDR 与机器人的日志。

更多配置项，详见 配置说明。