CLI 实战教程
约 1558 字大约 5 分钟
2026-03-19
通过真实场景学习
ncatbot命令行工具的使用。完整命令签名速查请见 CLI 命令参考。
场景一：从零创建并运行一个 Bot
第 1 步 — 初始化项目
mkdir my-bot && cd my-bot
ncatbot init按提示输入机器人 QQ 号和管理员 QQ 号，完成后目录结构如下：
my-bot/
├── config.yaml # 自动生成的配置文件
├── plugins/ # 插件目录
└── plugins/{username}/ # 自动生成的模板插件
├── manifest.toml
└── plugin.py💡 也可以用
ncatbot init --dir ./my-bot在当前目录外创建。
第 2 步 — 以开发模式启动
ncatbot dev将以 debug=True + 热重载启动 Bot。修改插件代码后无需重启。
第 3 步 — 切换到生产模式
ncatbot run关闭 debug 日志并保持热重载。如需禁用热重载：
ncatbot run --no-hot-reload💡 如果尚未运行过
ncatbot init（bot_uin仍为默认值），ncatbot run会自动进入初始化流程。可通过--bot-uin或环境变量NCATBOT_BOT_UIN跳过交互：ncatbot run --bot-uin 1234567890 --root 9876543210 # 或 NCATBOT_BOT_UIN=1234567890 ncatbot run使用
--non-interactive可让运行期所有确认自动采用默认值（适用于 CI / Docker）。
场景二：创建、调试并管理插件
创建一个新插件
ncatbot plugin create weather_bot自动在 plugins/weather_bot/ 下生成 __init__.py、manifest.toml、plugin.py、README.md 标准脚手架。
查看插件详情
ncatbot plugin list # 列出所有已安装插件
ncatbot plugin info weather_bot # 查看 weather_bot 的版本、作者等元信息临时禁用 / 重新启用
ncatbot plugin disable weather_bot # 禁用（加入黑名单）
ncatbot plugin enable weather_bot # 启用（移出黑名单）全局开关：
ncatbot plugin off # 全局关闭插件加载
ncatbot plugin on # 全局开启插件加载删除插件
ncatbot plugin remove weather_bot # 删除目录及黑白名单记录（需确认）场景三：配置调优与安全检查
查看与修改配置
ncatbot config show # 查看全部 YAML 配置
ncatbot config get napcat.ws_uri # 查看某一项
ncatbot config set napcat.ws_uri "ws://localhost:3001" # 修改值（自动类型转换）类型转换规则：true/yes → bool，纯数字 → int，[...] JSON → list。
安全检查
ncatbot config check自动检查弱密码/Token、必填项缺失等安全问题，输出修复建议。
场景四：手动安装 NapCat（Docker / CI）
默认情况下 NapCat 在 ncatbot run 首次启动时交互式安装。如需在 Docker 构建或 CI 中预装：
ncatbot napcat install --yes # 跳过确认，非交互安装Dockerfile 示例：
RUN pip install ncatbot5
RUN ncatbot napcat install --yes若已安装则自动跳过。
场景五：NapCat 连接诊断
Bot 连接不上 NapCat？用诊断命令一键排查：
ncatbot napcat diagnose # 完整诊断（WebSocket + WebUI）
ncatbot napcat diagnose ws # 仅检测 WebSocket 连接
ncatbot napcat diagnose webui # 仅检测 WebUI 状态可临时覆盖配置中的地址：
ncatbot napcat diagnose ws --uri ws://192.168.1.100:3001 --token mytoken停止本机 NapCat（仅 Linux）
如果 NapCat 由当前机器本地运行，可以使用：
ncatbot napcat stop该命令仅在 Linux 下生效，会调用平台层停止本机 NapCat 进程；若当前使用的是远端 ws_uri 或 skip_setup: true 的直连模式，它不会去停止远端服务。
场景六：SnowLuma 安装与诊断
SnowLuma 是独立的 OneBot v11 协议端，协议层与 NapCat 兼容，但首次启用时需要你在 WebUI 中手动打开 OneBot v11 WebSocket 并扫码登录。
预装 SnowLuma（Windows x64）
ncatbot snowluma install --yes使用精简包或指定安装目录：
ncatbot snowluma install --yes --lite
ncatbot snowluma install --install-dir ./runtime/snowluma诊断 WebSocket / WebUI
ncatbot snowluma diagnose # 完整诊断（WebSocket + WebUI）
ncatbot snowluma diagnose ws # 仅检测 WebSocket
ncatbot snowluma diagnose webui # 仅检测 WebUI
ncatbot snowluma version # 查看安装版本与最新 release可临时覆盖配置中的地址：
ncatbot snowluma diagnose ws --uri ws://192.168.1.100:3001 --token mytoken
ncatbot snowluma diagnose webui --uri http://192.168.1.100:5099当前 SnowLuma 自动安装 / 自动启动仅完整支持 Windows x64。Linux / macOS 请使用
skip_setup: true，将 SnowLuma 作为外部服务手动管理。
场景七：交互式操作（REPL）
直接运行 ncatbot（不带子命令）进入交互式 Shell，适合探索性操作：
$ ncatbot
ncatbot [123456789]> config show
ncatbot [123456789]> plugin list
ncatbot [123456789]> config set debug true
ncatbot [123456789]> exitREPL 内支持所有子命令，输入 help 查看可用命令。
场景八：管理多平台适配器
进入适配器管理
ncatbot adapter进入副屏交互式管理界面，显示所有可用适配器及当前启用状态。
操作方式
| 按键 | 操作 |
|---|---|
| ↑ / ↓ | 移动光标 |
| 空格 | 启用/禁用适配器 |
| Enter | 进入适配器配置流程 |
| q / Esc | 保存并退出 |
按 Enter 后进入各适配器的配置交互：
- Bilibili：询问是否扫码登录，选择扫码则自动获取凭据，否则手动输入 Cookie 字段；之后配置直播间 ID 和是否监听私信
- GitHub：按提示输入 Personal Access Token、仓库列表和事件接收模式
- NapCat：询问是否自动安装，选择安装则使用默认值，否则手动输入 WS/WebUI 地址
- SnowLuma：询问是否自动安装，选择安装则返回默认 WS/WebUI 参数；首次启动仍需在 WebUI 手动启用 OneBot v11 端点
退出副屏后，所有变更自动保存到 config.yaml。
同一
BotClient内platform必须唯一，因此不能同时启用 NapCat 和 SnowLuma。
场景九：下载 AI 用户参考资料
ncatbot ref自动从 GitHub Releases 下载最新版 user-reference.zip 并解压到当前目录，包含示例代码、使用指南、API 参考和 AI Agent 技能文件。下载时自动使用 GitHub 代理加速。
未指定 IDE 时会交互式提示选择，也可直接指定：
ncatbot ref --vscode # 适配 VSCode + Copilot
ncatbot ref --trae # 适配 Trae（自动将 .agents 重命名为 .trae）
ncatbot ref --cursor # 适配 Cursor（与 VSCode 相同）指定版本或禁用代理：
ncatbot ref --version 5.2.13 # 下载指定版本
ncatbot ref --no-proxy # 直连 GitHub 下载
ncatbot ref --dir ./my-project # 解压到指定目录延伸阅读
版权所有
版权归属：GEYUANwuqi