通过真实场景学习 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 的直连模式，它不会去停止远端服务。

---

场景六：交互式操作（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 list

输出所有内置和第三方适配器，以及当前启用状态。

启用 Bilibili 适配器

ncatbot adapter enable bilibili

执行后询问是否扫码登录：

• 选择扫码：自动弹出二维码，扫码成功后凭据写入 config.yaml，跳过 sessdata 等手动输入
• 选择不扫码：逐项输入 sessdata / bili_jct 等 Cookie 字段（留空则启动时再扫码）

之后继续配置直播间 ID 和是否监听私信。

启用 GitHub 适配器

ncatbot adapter enable github

按提示输入 Personal Access Token：

配置 GitHub 适配器:
  需要 GitHub Personal Access Token (PAT)
  GitHub Token: ****

查看适配器状态

ncatbot adapter status

显示已配置适配器的平台、启用状态和关键配置摘要。

禁用适配器

ncatbot adapter disable bilibili

在 config.yaml 中将适配器标记为禁用，不删除配置。

---

场景八：下载 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 字段详解
• 插件开发指南 — 插件开发完整教程

版权所有

版权归属：MI

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