配置项

约 1142 字大约 4 分钟

2025-02-08

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

NcatBot 的配置项通过位于 ncatbot.utils.config 中的全局变量 config 来保存和指定. 同时也提供了在运行时指定的快速方法.

配置项列表

以下给出了所有的配置项及其默认值:

class SetConfig:

    default_root = "123456"
    default_bt_uin = "123456"
    default_ws_uri = "ws://localhost:3001"
    default_webui_uri = "http://localhost:6099"
    default_webui_token = "napcat"

    def __init__(self):
        # 内部状态
        # 可设置状态
        self.root = self.default_root  # root 账号
        self.bt_uin = self.default_bt_uin  # bot 账号
        self.ws_uri = self.default_ws_uri  # ws 地址, 可自定义端口, 默认 3001
        self.webui_uri = self.default_webui_uri  # webui 地址, 可自定义端口, 默认 6099
        self.webui_token = self.default_webui_token  # webui 令牌, 默认 napcat
        self.ws_token = ""  # ws_uri 令牌, 默认留空
        self.ws_listen_ip = "localhost"  # ws 监听 ip, 默认只监听本机
        self.remote_mode = False  # 是否远程模式, 即 NapCat 服务不在本机运行

        """
        如果纯远程模式, 则 NcatBot 不对 NapCat 的行为做任何管理.
        只使用 ws_uri 和 webui_uri 和 NapCat 进行交互, 不会配置启动 NapCat
        """

        # 更新检查
        self.check_napcat_update = False  # 是否检查 napcat 更新
        self.check_ncatbot_update = True  # 是否检查 ncatbot 更新

        # 开发者调试
        self.debug = False  # 是否开启调试模式
        self.skip_ncatbot_install_check = False  # 是否跳过 napcat 安装检查
        self.skip_plugin_load = False  # 是否跳过插件加载

        # NapCat 行为
        self.stop_napcat = False  # NcatBot 下线时是否停止 NapCat
        self.enable_webui_interaction = True  # 是否允许 NcatBot 与 NapCat webui 交互

        """
        如果 enable_webui_interaction 为 False, 则 NcatBot 不会与 NapCat webui 交互
        账号检查, 引导登录等行为均不会发生, 只使用 ws_uri 与 NapCat 交互
        """

bot_uin: 就是 Bot QQ 号. 这个千万不能填错了喵~
root: root QQ 号, 具有超管权限, 一般填你的 QQ 大号.

一般来说除了 root 和 bt_uin 需要指定外, 其它配置项推荐使用默认值，如果有端口冲突也许需要自行替换。

需要改动 ws_uri、 ws_token、 webui_uri 和 webui_token 的情况是使用远端 NapCat 接口.

通过 `BotClient.run` 运行时指定(推荐)

引导程序中, 在 bot.run() 时可以添加命名参数来指定大部分配置项, 例如:

bot.run(
    bt_uin="123456", # 注意不是 bot_uin, 这里应该和 config 的成员名一致
    ws_uri="ws://127.0.0.1:3001",
    ws_token="",
    webui_uri="http://127.0.0.1:6099",
    webui_token="napcat",
    check_napcat_update = False, # 不检查 NapCat 更新
    check_ncatbot_update = True, # 检查 NcatBot 更新
)

在代码里指定配置项(推荐)

部分常用配置项可以在代码里直接指定.

注意

由于历史原因, bot_uin 的设置函数名叫 set_bot_uin 但变量名叫 bt_uin.

from ncatbot.utils import config

config.set_bot_uin("123456")  # 设置 bot qq 号 (必填)
config.set_root("123456")  # 设置 bot 超级管理员账号 (建议填写)
config.set_ws_uri("ws://localhost:3001")  # 设置 napcat websocket server 地址
config.set_ws_token("")  # 设置 token (websocket 的 token)
config.set_webui_uri("http://localhost:6099")  # 设置 napcat webui 地址
config.set_webui_token("napcat")  # 设置 token (webui 的 token)

通过文件指定配置项

文件指定的配置项优先级较低，可以被其它方式覆盖。

NcatBot 会读取工作目录下 config.yaml 中的配置信息，并作为配置项加载。以下是完整配置项：

# NcatBot 配置文件

# 基本配置
root: "123456"  # root 账号
bt_uin: "123456"  # bot 账号
ws_uri: "ws://localhost:3001"  # ws 地址
webui_uri: "http://localhost:6099"  # webui 地址
webui_token: "napcat"  # webui 令牌
ws_token: ""  # ws_uri 令牌
ws_listen_ip: "localhost"  # ws 监听 ip, 默认只监听本机
remote_mode: false  # 是否远程模式, 即 NapCat 服务不在本机运行

# 更新检查
check_napcat_update: false  # 是否检查 napcat 更新
check_ncatbot_update: true  # 是否检查 ncatbot 更新

# 开发者调试
debug: false  # 是否开启调试模式
skip_ncatbot_install_check: false  # 是否跳过 napcat 安装检查
skip_plugin_load: false  # 是否跳过插件加载

# 插件加载控制
# 白名单和黑名单互斥，只能设置其中一个
# 如果都不设置，则加载所有插件
# plugin_whitelist:  # 插件白名单，为空表示不启用白名单
#   - "plugin1"
#   - "plugin2"
# plugin_blacklist:  # 插件黑名单，为空表示不启用黑名单
#   - "plugin3"
#   - "plugin4"

# NapCat 行为
stop_napcat: false  # NcatBot 下线时是否停止 NapCat
enable_webui_interaction: true  # 是否允许 NcatBot 与 NapCat webui 交互
report_self_message: false  # 是否报告 Bot 自己的消息