CLI 实战教程
约 675 字大约 2 分钟
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 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 连接诊断
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场景五：交互式操作（REPL）
直接运行 ncatbot（不带子命令）进入交互式 Shell，适合探索性操作：
$ ncatbot
ncatbot [123456789]> config show
ncatbot [123456789]> plugin list
ncatbot [123456789]> config set debug true
ncatbot [123456789]> exitREPL 内支持所有子命令，输入 help 查看可用命令。
延伸阅读
版权所有
版权归属：huan-yp