---
url: 'https://bot.mcjpg.dev/guide/quick-start.md'
description: >-
  Minecraft UniBot 快速开始教程：约 10 分钟完成部署——安装 UniBot 核心、在 MC 服务器安装鹊桥插件、接入 QQ /
  Telegram / Discord 等聊天平台并完成授权验证。
---
# 快速开始

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

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

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

## 术语说明

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

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

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

## 部署流程一览

::: steps

1. **安装机器人本体**

   安装并启动 UniBot，详见 [第一步](#第一步-安装-unibot)。

2. **服务器安装并配置鹊桥插件**

   在每台 Minecraft 服务器上安装鹊桥插件，详见 [第二步](#第二步-安装鹊桥插件并配置)。

3. **接入聊天平台**

   安装并配置对应平台的适配器，详见 [第三步](#第三步-接入聊天平台)。

4. **完成授权并验证**

   在 WebUI 中通过快速开始引导完成授权，详见 [第四步](#第四步-验证启动)。

:::

如需先了解整体架构及各组件间的通信方式，可参阅 [架构速览](/unibot/architecture.html)。

## 前置要求

::: table title="前置要求" copy="all"
| 组件 | 要求 |
|------|------|
| Python | 3.11+ |
| 包管理器 | [UV](https://docs.astral.sh/uv/)（推荐）或 pip |
| Minecraft 服务端 | Fabric / Forge / Spigot / Paper / MCDR 等均可，需已安装鹊桥插件 |
| 聊天机器人账号 | QQ 机器人、Telegram Bot 等 |
:::

## 第一步：安装 UniBot

### 脚本安装（推荐）

从 [Releases 页面](https://github.com/MineJPGcraft/UniBot/releases) 下载对应平台的一键安装脚本：

::: table title="一键安装脚本" copy="all"
| 平台 | 脚本 |
|------|------|
| **Windows** | `Install.bat`，双击运行即可，自动完成安装 uv、克隆仓库、配置 WebUI 并同步依赖 |
| **Linux / macOS** | `Install.sh`，先执行 `chmod +x Install.sh`，再运行 `./Install.sh` |
:::

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

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

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

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

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

::: note
WebUI 的完整功能介绍（各页面详解、配置中心、日志查看、令牌授权等）见 [WebUI 管理面板](/guide/webui.html)。
:::

### 手动安装（可选）

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

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

# 启动机器人
uv run Watchdog.py
```

\~~也可使用 pip + venv 安装~~，具体命令可参考 [配置指南](/guide/configuration.html)，但更推荐使用 uv 进行管理。

### Docker 安装

安装 Docker 之后 在终端运行

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

UniBot就会开始在后台运行

### Docker compose 安装

安装 Docker 和 compose 之后运行

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

## 第二步：安装鹊桥并配置

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

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

## 第三步：接入聊天平台

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

各平台适配器的具体配置项，请参阅 [配置指南](/guide/configuration.html)。

## 第四步：验证启动

完成 [第二步](#第二步-安装鹊桥插件并配置) 与 [第三步](#第三步-接入聊天平台) 后，即可进行授权并验证。

### 令牌授权

登录 WebUI 仪表盘，在「快速开始」引导卡片中点击 **令牌授权** 即可完成超级用户授权（也可在任意平台群聊中发送控制台打印的认证令牌）。

::: note
令牌授权的完整说明（操作步骤、令牌即用即刷机制、无需 WebUI 的授权方式）见 [WebUI 管理面板 · 令牌授权](/guide/webui.html#令牌授权)。
:::

### 验证功能

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

```
/help
```

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

## 常见问题

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

更多配置项，详见 *[配置指南](/guide/configuration.html)*。