CLI 命令参考

约 2067 字大约 7 分钟

2026-03-19

ncatbot 命令行工具完整 API 参考。基于 Click 构建。

Quick Start

ncatbot --help          # 查看所有命令
ncatbot <command> --help  # 查看单个命令帮助

入口点

# pyproject.toml
[project.scripts]
ncatbot = "ncatbot.cli:main"

也可通过模块方式调用：

python -m ncatbot.cli

顶层命令

ncatbot [OPTIONS] [COMMAND]

选项	说明
`--version`	显示版本号
`--help`	显示帮助信息

无子命令时进入交互模式（REPL）。

init

ncatbot init [OPTIONS]

初始化项目，创建 config.yaml、plugins/ 目录，以及一个以当前计算机用户名命名的模板插件。

选项	类型	默认值	说明
`--dir`	`str`	`.`	目标目录

交互式提示：

提示	说明
请输入机器人 QQ 号	写入 `bot_uin`
请输入管理员 QQ 号	写入 `root`
选择启用的适配器	checkbox 多选，调用各适配器的 `cli_configure()` 钩子

各适配器的 cli_configure() 含智能跳过逻辑：

适配器	选择	行为
NapCat	自动安装	跳过 WS/WebUI 地址输入，使用默认值（启动时自动配置）
NapCat	不自动安装	交互式输入 WS 地址、Token、WebUI 地址、Token
SnowLuma	自动安装	跳过 WS/WebUI 地址输入，返回默认连接参数；首次启动进入交互式引导，等待用户在 WebUI 完成配置后按回车
SnowLuma	手动管理	交互式输入 WS 地址、Token、WebUI 地址和 `skip_setup`
Bilibili	扫码登录	跳过 sessdata 等凭据手动输入（扫码自动获取）
Bilibili	不扫码	交互式输入 sessdata / bili_jct / buvid3 等 Cookie 字段
GitHub	—	输入 PAT、仓库、Webhook/Polling 模式

若 config.yaml 已存在，提示是否覆盖。

生成的模板插件位于 plugins/{username}/，包含 manifest.toml 和 plugin.py，实现群聊/私聊发送 hello 回复 hi。若模板插件目录已存在则跳过。

run

ncatbot run [OPTIONS]

启动 NcatBot（连接 NapCat + 加载插件 + 监听事件）。

选项	类型	默认值	说明
`--debug`	flag	`False`	启用调试模式
`--no-hot-reload`	flag	`False`	禁用插件热重载
`--plugins-dir`	`str`	（使用 config 默认）	插件目录路径
`--non-interactive`	flag	`False`	非交互模式运行（所有确认自动使用默认值）
`--bot-uin`	`str`	（使用 config / 环境变量）	机器人 QQ 号（覆盖 config 和环境变量）
`--root`	`str`	（使用 config / 环境变量）	管理员 QQ 号（覆盖 config 和环境变量）

若 bot_uin 未配置（仍为默认值 123456），自动进入 ncatbot init 初始化流程。通过 --bot-uin 或环境变量 NCATBOT_BOT_UIN 提供有效值可跳过。

dev

ncatbot dev [OPTIONS]

以开发模式启动（debug=True + 热重载）。

选项	类型	默认值	说明
`--plugins-dir`	`str`	（使用 config 默认）	插件目录路径

config

ncatbot config COMMAND

配置管理命令组。

config show

ncatbot config show

以 YAML 格式显示当前全部配置。

config get

ncatbot config get CONFIG_KEY

参数	类型	说明
`CONFIG_KEY`	`str`	配置项路径，支持点分（如 `napcat.ws_uri`）

config set

ncatbot config set CONFIG_KEY CONFIG_VALUE

参数	类型	说明
`CONFIG_KEY`	`str`	配置项路径，支持点分
`CONFIG_VALUE`	`str`	值（自动类型转换）

类型转换规则：

输入值	转换类型
`true` / `yes`	`bool (True)`
`false` / `no`	`bool (False)`
纯数字字符串	`int`
`[...]` JSON 格式	`list`
其它	`str`

config check

ncatbot config check

检查配置安全性和必填项，输出问题列表。

plugin

ncatbot plugin COMMAND

插件管理命令组。

plugin list

ncatbot plugin list

列出已安装插件，显示名称、版本、作者、状态。读取每个插件目录下的 manifest.toml。

plugin create

ncatbot plugin create NAME

参数	类型	说明
`NAME`	`str`	插件名（字母开头，仅字母/数字/下划线）

在插件目录下生成标准脚手架，包含 __init__.py、manifest.toml、plugin.py、README.md。

plugin info

ncatbot plugin info NAME

参数	类型	说明
`NAME`	`str`	插件名

显示插件 manifest.toml 元数据。

plugin enable

ncatbot plugin enable NAME

启用插件：从黑名单移除，若白名单存在则加入白名单。

plugin disable

ncatbot plugin disable NAME

禁用插件：从白名单移除，加入黑名单。

plugin remove

ncatbot plugin remove NAME

参数	类型	说明
`NAME`	`str`	插件名

删除插件目录（含所有文件），并从黑名单/白名单中移除。

plugin on / plugin off

ncatbot plugin on
ncatbot plugin off

全局开关：on 启用插件加载，off 禁用插件加载。

adapter

ncatbot adapter

进入副屏（alternate screen）交互式适配器管理界面。

在副屏中可完成适配器的查看、启用/禁用、配置，退出后自动保存到 config.yaml。

交互操作

按键	操作
↑ / ↓（或 k / j）	移动光标
空格	切换当前适配器的启用/禁用
Enter	进入当前适配器的配置流程（调用 `cli_configure()` 钩子）
q / Esc	保存并退出

适配器配置钩子

按 Enter 后进入的配置流程由各适配器自身的 cli_configure() 钩子提供：

适配器	交互内容
`napcat`	询问是否自动安装；选择自动安装则跳过 WS/WebUI 输入（使用默认值），否则输入地址和 Token
`snowluma`	询问是否自动安装；选择自动安装则返回默认 WS/WebUI 参数，否则输入 WS 地址、Token、WebUI 地址与 `skip_setup`
`bilibili`	询问是否扫码登录；选择扫码则跳过 sessdata 等凭据输入（扫码自动获取），否则手动填写 Cookie
`github`	提示输入 Personal Access Token、仓库列表、Webhook/Polling 模式
`lark`	提示输入 App ID 和 App Secret
`ai`	提示输入 API Key、Base URL、模型名

状态标识

标识	含义
`[x]`	已启用
`[ ]`	未启用
`● 已配置`	启用且已完成配置
`◐ 未配置`	启用但尚未配置

非交互降级

在非交互终端（CI / 管道）中自动降级为编号输入模式。

napcat

ncatbot napcat COMMAND

NapCat 管理命令组。

napcat install

ncatbot napcat install [OPTIONS]

安装 NapCat + QQ。若已安装则跳过。

选项	类型	默认值	说明
`--yes` / `-y`	flag	`False`	跳过交互确认，直接安装（Docker/CI 场景）

Docker 构建示例：

RUN ncatbot napcat install --yes

napcat stop

ncatbot napcat stop

停止本机 NapCat 进程。该命令仅支持 Linux；在非 Linux 平台会直接报错退出。

适用场景：

停止当前机器上由 NapCat CLI 或 screen 管理的本地 NapCat 进程
清理本机残留的 NapCat / QQ 运行时

不适用场景：

停止远端服务器上的 NapCat
仅断开 NcatBot 与 NapCat 的 WebSocket 连接

napcat diagnose

ncatbot napcat diagnose [COMMAND]

无子命令时运行完整诊断（WebSocket + WebUI）。

napcat diagnose ws

ncatbot napcat diagnose ws [OPTIONS]

选项	类型	默认值	说明
`--uri`	`str`	读取配置	WebSocket URI
`--token`	`str`	读取配置	WebSocket Token

napcat diagnose webui

ncatbot napcat diagnose webui [OPTIONS]

选项	类型	默认值	说明
`--uri`	`str`	读取配置	WebUI URI
`--token`	`str`	读取配置	WebUI Token

snowluma

ncatbot snowluma COMMAND

SnowLuma 管理与诊断命令组。

snowluma install

ncatbot snowluma install [OPTIONS]

下载并解压 SnowLuma。自动安装 / 自动启动当前仅完整支持 Windows x64。

选项	类型	默认值	说明
`--yes` / `-y`	flag	`False`	跳过确认，直接安装
`--lite`	flag	`False`	使用 `SnowLuma-vX.Y.Z-win-x64-lite.zip` 精简包
`--install-dir`	`str`	平台默认目录	指定安装目录

snowluma stop

ncatbot snowluma stop

尝试停止本机 SnowLuma 运行时。

Windows：不会按进程名强杀 node.exe，而是提示手动关闭对应窗口
Linux / macOS：当前不提供自动停止，建议以外部进程方式手动管理

snowluma diagnose

ncatbot snowluma diagnose [COMMAND]

无子命令时运行完整诊断（WebSocket + WebUI）。

snowluma diagnose ws

ncatbot snowluma diagnose ws [OPTIONS]

选项	类型	默认值	说明
`--uri`	`str`	读取配置	WebSocket URI
`--token`	`str`	读取配置	WebSocket Token

snowluma diagnose webui

ncatbot snowluma diagnose webui [OPTIONS]

选项	类型	默认值	说明
`--uri`	`str`	读取配置	WebUI URI

snowluma version

ncatbot snowluma version

打印当前安装的 SnowLuma 版本和 GitHub 最新 release 版本。

ref

下载 AI 用户参考资料（user-reference.zip）并解压到项目目录。自动从 GitHub Releases 获取最新版本，支持 GitHub 代理加速。必须指定 IDE 类型（或交互式选择），Trae 会自动将 .agents 重命名为 .trae。

用法： ncatbot ref [OPTIONS]

选项	类型	默认值	说明
`--dir`	`str`	`.`	解压目标目录
`--version`	`str`	（最新）	指定版本号
`--no-proxy`	flag	`False`	禁用 GitHub 代理，直连下载
`--vscode`	flag	`False`	适配 VSCode（默认格式）
`--trae`	flag	`False`	适配 Trae（将 `.agents` 重命名为 `.trae`）
`--cursor`	flag	`False`	适配 Cursor（与 VSCode 相同）

未指定 IDE 时交互式提示用户选择。

版权所有

版权归属：GEYUANwuqi

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