Minecraft UniBot

外观

Minecraft 适配器

约 913 字大约 3 分钟

nonebot-adapter-minecraft 是 NoneBot 的 Minecraft 协议适配器，随 UniBot 一起使用，负责通过 鹊桥 协议与服务器端的插件 / Mod 互通。完整文档可参阅其 Wiki。

安装

UniBot 已内置该适配器作为依赖，无需单独安装。若需单独使用：

pip install nonebot-adapter-minecraft

配置

在 UniBot 的 .env 中配置：

# Minecraft WebSocket 地址（支持多服）
MINECRAFT_WS_URLS={"server1": ["ws://127.0.0.1:8080/mc"]}

# 服务器接入鉴权 Token
MINECRAFT_ACCESS_TOKEN=""

配置字段

字段类型说明
MINECRAFT_WS_URLSJSON 对象服务器名 → WebSocket 地址列表，支持多服。键名中的服务器名须与服务器端 server_name 一致
MINECRAFT_ACCESS_TOKEN字符串服务器接入鉴权 Token，须与服务器端 access_token 一致，留空则不校验

在 pyproject.toml 中注册适配器：

[[tool.nonebot.adapters]]
name = "Minecraft"
module_name = "nonebot.adapters.minecraft"

连接模式

适配器（即本项目核心，运行于 NoneBot 服务器）与服务器端（MCDR 插件 / 鹊桥官方实现）通过 WebSocket 通信，支持 WS 客户端 与 WS 服务端 两种方式，任选其一即可。两种方式均要求两端 server_name 与 access_token 一致，否则连接会被拒绝。

WS 客户端（推荐）

推荐使用 WS 客户端方式。 即适配器（核心）作为 WebSocket 客户端，主动连接服务器端（MCDR 插件 / 鹊桥官方实现）暴露的 WebSocket 服务端。此时 MINECRAFT_WS_URLS 中填写的正是 服务器端 WebSocket 服务端的地址。

该方式下，适配器主动外连，服务器端无需关心连接来源，无需在服务器上开放对外监听端口，服务器可位于内网 / NAT 之后，是绝大多数场景下的最佳选择。

示例配置

适配器侧（.env）

# 键名为服务器名，地址为服务器端 WebSocket 服务端地址
MINECRAFT_WS_URLS={"survival": ["ws://127.0.0.1:8080/mc"]}
MINECRAFT_ACCESS_TOKEN="your_access_token"

服务器端（MCDR 插件 config.json）

{
  "server_name": "survival",
  "access_token": "your_access_token",
  "server": {
    "enable": true,
    "host": "0.0.0.0",
    "port": 8080
  },
  "client": {
    "enable": false
  }
}

服务器端（鹊桥官方实现 config.yml）

server_name: "survival"
access_token: "your_access_token"

websocket_server:
  enable: true
  host: "0.0.0.0"
  port: 8080

websocket_client:
  enable: false

WS 服务端

WS 服务端方式即适配器（核心）作为 WebSocket 服务端（路径 /minecraft/ws），服务器端（MCDR 插件 / 鹊桥官方实现）以客户端模式主动连接适配器。此时适配器不主动外连，MINECRAFT_WS_URLS 留空即可。

适用于服务器端无法对外提供 WebSocket 服务、但可以主动外连的场景（如服务器处于严格内网）。

示例配置

适配器侧（.env）

# 适配器不主动外连，留空即可
MINECRAFT_WS_URLS={}
MINECRAFT_ACCESS_TOKEN="your_access_token"

服务器端（MCDR 插件 config.json）

{
  "server_name": "survival",
  "access_token": "your_access_token",
  "client": {
    "enable": true,
    "url": "ws://127.0.0.1:8080/minecraft/ws"
  },
  "server": {
    "enable": false
  }
}

服务器端（鹊桥官方实现 config.yml）

server_name: "survival"
access_token: "your_access_token"

websocket_client:
  enable: true
  reconnect_interval: 5
  reconnect_max_times: 5
  url_list:
    - "ws://127.0.0.1:8080/minecraft/ws"

websocket_server:
  enable: false

与服务器对接

适配器通过 鹊桥 协议与服务器端的插件/Mod 通信。服务器端可作如下选择：

对接时需保证两端一致：

  • 服务器名称：MINECRAFT_WS_URLS 键名与服务器端 server_name 一致。
  • 鉴权 Token：MINECRAFT_ACCESS_TOKEN 与服务器端 access_token 一致（不为空时校验）。
  • 地址可达：WebSocket 地址与端口互通。

数据模型

适配器提供以下核心类型：

  • Bot：机器人实例
  • Message / MessageSegment：消息对象
  • Adapter：适配器类
  • 各类事件模型（玩家事件、聊天事件等）

开发调试

你可以在 tests/ 目录下运行适配器的测试套件：

uv run pytest

贡献与支持