通过真实场景学习 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    # 启用（移出黑名单）

插件加载时黑名单优先；白名单非空时，只有白名单中的插件可以加载。enable 在白名单非空时也会将插件加入白名单。这些名单不影响内置插件。

全局开关：

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]> exit

REPL 内支持所有子命令，输入 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        # 解压到指定目录

---

延伸阅读

• CLI 命令参考 — 全部命令签名、选项、参数速查
• 配置管理指南 — config.yaml 字段详解
• 插件开发指南 — 插件开发完整教程

版权所有

版权归属：GEYUANwuqi

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