配置说明

约 1072 字大约 4 分钟

UniBot 采用 双配置文件 体系，分别管理框架层与业务层配置，各司其职。

配置文件概览

文件	位置	用途	格式
`.env`	项目根目录	NoneBot 框架配置与适配器配置	INI 风格
`Config.toml`	项目根目录	机器人自定义配置（指令、消息、图片、AI 等）	TOML
`Config/Messages.toml`	`Config/` 目录	对外发送的消息文本（可自定义）	TOML

`.env` — 框架与适配器

.env 用于配置 NoneBot 框架本身，以及各平台的适配器。

框架配置

# 监听端口与主机
PORT=8000
HOST="127.0.0.1"

# 超级用户（管理员账号，可多个）
SUPERUSERS=["1234567890"]

# 命令起始字符与分隔符
COMMAND_START=["."]
COMMAND_SEP=[" "]

# 日志级别
LOG_LEVEL="INFO"

Minecraft 服务器配置

# Minecraft WebSocket 地址（支持多服）
# 格式：{服务器名}: [{地址列表}]
MINECRAFT_WS_URLS={"server1": ["ws://127.0.0.1:8080/mc"]}

# 服务器接入鉴权 Token（需与鹊桥插件一致）
MINECRAFT_ACCESS_TOKEN=""

平台适配器配置

以 OneBot V11（QQ）为例：

# OneBot 连接方式（forward / ws / reverse 等）
ONEBOT_ACCESS_TOKEN=""
ONEBOT_WS_URLS=["ws://127.0.0.1:6700"]

其他平台（Telegram、Discord、Kook 等）可参考对应适配器的文档，在 .env 中配置对应的 BOT_TOKEN 等字段。

`Config.toml` — 机器人配置

Config.toml 是机器人业务层的主要配置，采用 TOML 格式。嵌套表会自动展平成配置字段（例如 [ai] 下的 enabled → ai_enabled）。

基础配置

# 是否将所有的管理员视为超级用户
admin_superusers = true

# 假人前缀，list 指令的分类依据，以及进服广播的判定依据
# 无假人或不想分类时留空
bot_prefix = ""

# 指令群：机器人只响应这些群的指令
# 格式 "{平台}:{群ID}"
command_groups = ["qq_client:123456789"]

# 消息群：发送消息到游戏、以及同步游戏消息到群的群
message_groups = ["qq_client:123456789"]

# 可通过指令远程执行的命令白名单 / 黑名单
command_minecraft_whitelist = []
command_minecraft_blacklist = ["kill"]

消息同步

# 是否播报服务器开启/关闭
broadcast_server = true

# 是否播报玩家进入/离开
broadcast_player = true

# 是否把消息群内的所有消息转发到服务器内
sync_all_qq_message = true

# 是否把服务器内消息转发到 QQ 群
sync_all_game_message = false

# 是否把服务器内消息转发到其他服务器
sync_message_between_servers = false

# 敏感词过滤（命中后不转发，并提醒违禁）
sync_sensitive_words = ["敏感词", "你妈", "色图"]

# 转发消息颜色（支持 16 种 MC 颜色或 #hex）
sync_color_source = "gray"
sync_color_player = "gray"
sync_color_message = "gray"

# 绑定 QQ 号的最大数量，0 表示不限制
qq_bound_max_number = 1

白名单配置

# 白名单指令名称
whitelist_command = "whitelist"

# 获取玩家列表的兼容模式（监听玩家进出更新，可能不准确）
list_compatible_mode = false

WebUI 管理面板

[webui]
# 是否启用 WebUI（需额外安装 webui 依赖）
enabled = true

图片渲染模式

[image]
# 是否启用图片模式（需额外安装 image 依赖）
mode = false

# 生成图片的背景（CSS background-image 属性）
# 支持 random 函数，从本地目录随机取一张
background = 'random("./Resources/Backgrounds/")'

AI 智能对话

[ai]
# 是否启用 AI 功能（需额外安装 ai 依赖）
enabled = false

# OpenAI 兼容格式的 BaseUrl
base_url = ""

# 模型名称
model_name = ""

# OpenAI 兼容格式的 ApiKey
api_key = ""

# AI 的提示词（定义其角色）
system_prompt = "你是一个可爱的小女孩，乖巧可爱，听父母的话……"

关键词自动回复

[auto_reply]
# 是否启用自动回复
enabled = false

# 关键词及回复内容
# 多个关键词用逗号隔开；需同时匹配多个关键词用空格隔开
[auto_reply.keywords]
"看群公告里的 IP 地址。" = ["服务器 在哪", "服务器", "服务器地址"]

`Config/Messages.toml` — 消息文本

机器人的所有对外提示/播报文本均集中于此文件，支持 {占位符} 格式化，修改后重启生效。

[events]
player_join = "玩家 {player} 加入了游戏。"
player_join_group = "玩家 {player} 加入了 [{server}] 服务器，喵～"

[commands.send]
sent = "已向服务器发送消息：{content}。"

[commands.luck]
result = "你今天的人品为 {point}，{tips}"

注意：请勿删除已有键。 缺失必填项将导致机器人启动失败。

依赖与可选功能

不同的可选功能需要额外的依赖，请在启用前同步对应的 extra：

# 图片渲染模式
uv sync --extra image --inexact

# WebUI 管理面板
uv sync --extra webui --inexact

# AI 对话
uv sync --extra ai --inexact

Watchdog 会自动检测配置变化并同步对应的依赖。