快速开始

约 1821 字大约 6 分钟

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

提示

下面是从零开始部署对接官方 QQ 机器人的保姆级教程，可供参考：

https://www.bilibili.com/video/BV1xW8R6gEE8

术语说明

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

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

术语说明

UniBot 默认启用匿名数据上报，用于统计在线机器与消息量，不含消息内容或用户身份。可在 Config.toml 的 [telemetry] 中关闭。

部署流程一览

安装机器人本体
安装并启动 UniBot，详见第一步。
服务器安装并配置鹊桥插件
在每台 Minecraft 服务器上安装鹊桥插件，详见第二步。
接入聊天平台
安装并配置对应平台的适配器，详见第三步。
完成授权并验证
在 WebUI 中通过快速开始引导完成授权，详见第四步。

如需先了解整体架构及各组件间的通信方式，可参阅架构速览。

前置要求

组件	要求
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、从 GitHub Release 下载并解压对应版本的安装包、询问是否启用 WebUI、执行 uv sync 同步依赖。

注

完成安装后，脚本会在 UniBot 目录下生成一个 Start.sh 或 Start.bat 仅需执行即可启动核心。

若要手动启动，直接在根目录执行 uv run Watchdog.py 即可。

使用 WebUI 后续基本无需手动修改配置。 启动后浏览器访问 http://<IP>:<PORT>/（默认 http://127.0.0.1:8000/webui），首次访问按提示初始化管理员账户，即可在 WebUI 中配置聊天平台、管理服务器、查看日志。

接下来按照引导即可快速完成整个配置流程，全程无需再手动编辑 .env 或 Config.toml，也无需对照文档。

注

WebUI 的完整功能介绍（各页面详解、配置中心、日志查看、令牌授权等）见 WebUI 管理面板。

手动安装（可选）

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

# 安装核心与 WebUi 的依赖
uv sync --extra webui

# 启动机器人
uv run Watchdog.py

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

Docker 安装

安装 Docker 之后在终端运行

docker run -d -p 8000:8000 ghcr.io/minejpgcraft/unibot:latest

UniBot就会开始在后台运行

Docker compose 安装

安装 Docker 和 compose 之后运行

git clone https://github.com/MineJPGcraft/UniBot
cd UniBot
docker compose up -d

第二步：安装鹊桥并配置

每一台 Minecraft 服务器 上，均需安装 鹊桥插件/模组，才能接入核心。

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

第三步：接入聊天平台

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

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

第四步：验证启动

完成第二步与第三步后，即可进行授权并验证。

令牌授权

注

令牌授权的完整说明（操作步骤、令牌即用即刷机制、无需 WebUI 的授权方式）见 WebUI 管理面板 · 令牌授权。

验证功能

完成授权后，引导卡片自动收起。此时在聊天群中发送：

/help

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

常见问题

机器人不响应指令？ 请检查 COMMAND_START 前缀、command_groups 中是否包含当前群，以及 SUPERUSERS 中是否包含你的账号。
连不上服务器？ 请确认两端的 access_token 一致、WebSocket 地址与端口可达，并查看 MCDR 与机器人的日志。
/list 指令不准，始终显示没有玩家在线？ 若服务器内 list 指令被插件或权限修改导致获取玩家列表异常，请在 Config.toml 中开启兼容模式（list_compatible_mode = true），机器人将改用监听玩家进出事件来维护在线列表，但可能略有延迟且不完全准确。
机器人不会主动发消息？ 若使用官方 QQ 机器人，请进入 QQ 群 → 群设置 → 群机器人，确认已同时开启 允许机器人主动发送消息 与 允许机器人接收消息；缺少前者会导致播报、进群欢迎、上下线通知等主动推送无法发出，缺少后者会导致群内 @ 机器人的消息收不到，表现为「指令不响应」。部分平台还需检查机器人权限范围，如 Telegram 需在 BotFather 中启用 Group Privacy 关闭或授权群管理权限。此外检查 Config.toml 中的播报开关（broadcast_server / broadcast_player）是否为 true。
不会写代码，怎么给机器人加功能？ 使用内置 AiStudio（创意工坊）：在 WebUI 扩展管理页右上角点击「创意工坊」，即可自动下载并启动，用自然语言描述需求就能自动生成、校验并安装扩展。详见使用 AiStudio 零代码开发扩展。

更多配置项，详见 配置指南。