配置项

约 1257 字大约 4 分钟

2025-02-08

本文介绍 NcatBot 的各个配置项和配置项的指定方式。

访问配置项

可以从 ncatbot.utils 中导入配置项：

from ncatbot.utils import ncatbot_config

print(ncatbot_config.bt_uin) # 123456
print(ncatbot.napcat.ws_uri) # ws://localhost:3001
print(ncatbot.plugin.plugins_dir) # plugins

配置项列表

根配置项

提示

在 4.4.0 及以后的版本中，设置 debug=True 可以实验性启用插件热重载。

通过 ncatbot_config.<config_name> 访问。

配置项	类型	默认值	说明
`bt_uin`	`str`	`"123456"`	机器人 QQ 号
`root`	`str`	`"123456"`	根用户 QQ 号，用于权限管理
`enable_webui_interaction`	`bool`	`True`	是否启用 WebUI 交互
`debug`	`bool`	`False`	是否启用调试模式，调试模式会打印部分异常的堆栈信息
`github_proxy`	`str`	`None`	GitHub 代理 URL，可通过环境变量 `GITHUB_PROXY` 设置
`check_ncatbot_update`	`bool`	`True`	是否检查 NcatBot 更新
`skip_ncatbot_install_check`	`bool`	`False`	是否跳过 NcatBot 安装检查

NapCat 配置项

通过 ncatbot_config.napcat.<config_name> 访问。

配置项	类型	默认值	说明
`ws_uri`	`str`	`"ws://localhost:3001"`	WebSocket URI 地址
`ws_token`	`str`	`"NcatBot"`	WebSocket 令牌
`ws_listen_ip`	`str`	`"localhost"`	WebSocket 监听 IP
`webui_uri`	`str`	`"http://localhost:6099"`	WebUI URI 地址
`webui_token`	`str`	`"NcatBot"`	WebUI 令牌
`enable_webui`	`bool`	`True`	是否启用 WebUI
`check_napcat_update`	`bool`	`False`	是否检查 NapCat 更新
`stop_napcat`	`bool`	`False`	退出时是否停止 NapCat
`remote_mode`	`bool`	`False`	是否启用远程模式
`report_self_message`	`bool`	`False`	是否报告自身消息
`report_forward_message_detail`	`bool`	`True`	是否上报解析合并转发消息

自动检测配置项

这些配置项会根据其他配置自动生成，不需要手动设置：

配置项	类型	说明
`ws_host`	`str`	WebSocket 主机，从 `ws_uri` 自动检测
`ws_port`	`int`	WebSocket 端口，从 `ws_uri` 自动检测
`webui_host`	`str`	WebUI 主机，从 `webui_uri` 自动检测
`webui_port`	`int`	WebUI 端口，从 `webui_uri` 自动检测

Plugin 配置项

通过 ncatbot_config.plugin.<config_name> 访问。

配置项	类型	默认值	说明
`plugins_dir`	`str`	`"plugins"`	插件目录
`plugin_whitelist`	`List[str]`	`[]`	插件白名单
`plugin_blacklist`	`List[str]`	`[]`	插件黑名单
`skip_plugin_load`	`bool`	`False`	是否跳过插件加载

从文件设置配置项（推荐）

NcatBot 使用 YAML 格式的配置文件。默认配置文件路径为当前工作目录下的 config.yaml，可以通过环境变量 NCATBOT_CONFIG_PATH 自定义。

配置文件结构

root: '123456' # Bot 管理员 QQ 号
bt_uin: '123456' # Bot QQ 号
enable_webui_interaction: true # 启用 webui 交互
check_ncatbot_update: true # 检查 NcatBot 更新
skip_ncatbot_install_check: false # 跳过 NcatBot 安装检查
debug: false # 调试模式, 开启将会打印更多调试信息
napcat:
  ws_uri: ws://localhost:3001
  webui_uri: http://localhost:6099
  webui_token: NcatBot
  ws_token: 'NcatBot'
  ws_listen_ip: localhost
  enable_webui: true
  remote_mode: false
  check_napcat_update: false
  stop_napcat: false
  report_self_message: false
  report_forward_message_detail: true # 上报解析合并转发消息
plugin:
  plugin_whitelist: [] # 插件白名单, 留空表示不启用白名单, 只加载白名单内的插件
  plugin_blacklist: [] # 插件黑名单, 留空表示不启用黑名单, 不加载黑名单内的插件
  # 同时启用白名单和黑名单时, 白名单优先级更高(即只有白名单内的插件会被加载, 黑名单无效)
  plugins_dir: plugins
  skip_plugin_load: false

使用特定接口设置配置项

NcatBot 提供了一些特定的方法来动态修改配置项，优先级高于从默认的配置文件加载：

基本配置修改

from ncatbot.utils import ncatbot_config

# 设置机器人 QQ 号
ncatbot_config.set_bot_uin("1234567890")

# 设置管理员 QQ 号
ncatbot_config.set_root("9876543210")

NapCat 配置修改

# 设置 WebSocket 连接地址
ncatbot_config.set_ws_uri("ws://127.0.0.1:3001")

# 设置 WebSocket 令牌
ncatbot_config.set_ws_token("new_secure_token")

# 设置 WebUI 地址
ncatbot_config.set_webui_uri("http://127.0.0.1:6099")

# 设置 WebUI 令牌
ncatbot_config.set_webui_token("new_webui_token")

# 设置监听 IP
ncatbot_config.set_ws_listen_ip("0.0.0.0")

从文件更新配置

from ncatbot.config import Config

# 从文件更新现有配置
ncatbot_config.update_from_file("/path/to/new/config.yaml")

通用配置更新

对于 NapCat 配置项和 Plugin 配置项，只需要写最后一级名字即可，例如 ws_token、plugins_dir。

# 使用 update_config 方法批量更新
ncatbot_config.update_config(
    bt_uin="1234567890",
    debug=True,
    root="9876543210"
)

# 使用 update_value 方法更新单个配置
# ncatbot_config.debug
ncatbot_config.update_value("debug", True)
# ncatbot_config.napcat.ws_token
ncatbot_config.update_value("ws_token", "new_secure_token") 
# ncatbot_config.plugin.plugins_dir
ncatbot_config.update_value("plugins_dir", "/path/to/plugins")

在运行时指定配置项

执行 BotClient.run_xxxend() 时可以传入配置项参数，优先级最高。

from ncatbot.core import BotClient
bot = BotClient()
bot.run_frontend(
  bt_uin="1234567890", # ncatbot_config.bt_uin
  root="9876543210", # ncatbot_config.root
  ws_uri="ws://127.0.0.1:3001", # ncatbot_config.napcat.ws_uri
  plugins_dir="/path/to/plugins" # ncatbot_config.plugin.plugins_dir
)

注意事项

文件编码

配置文件必须使用 UTF-8 编码。

自动检查项目

QQ 号格式验证：QQ 号支持字符串和整数格式，处理时会自动转为字符串；使用默认 QQ 号时会要求手动输入。
URI 格式标准化：使用 http/ws 协议，不支持 https/wss，会自动补充或替换协议前缀。
端口和主机提取：从 URI 中自动提取主机名和端口。
目录存在性检查：自动创建不存在的插件目录。

安全检查

强密码检查：当 ws_listen_ip 设置为 0.0.0.0 时，要求 ws_token 为强密码
WebUI 安全：启用 WebUI 时要求 webui_token 为强密码
远程连接警告：连接非本地 NapCat 服务时给出提示

强密码要求：

至少 12 位字符
包含数字、字母和特殊符号
特殊符号包括：!@#$%^&*()_+-=[]{}|;:,.<>?

常见问题

Q: 为什么我的配置项没有生效？

A: 参阅 NcatBot 生命周期，配置项指定需要在调用 BotClient.run_xxxend() 之前完成。

ncatbot_config.update_from_file("config.yaml")

版权所有

版权归属：huan-yp

许可证：署名 4.0 国际 (CC-BY-4.0)