NcatBot 文档

外观

NapCat / QQ 适配器

约 884 字大约 3 分钟

2026-03-19

NapCat (OneBot v11) 适配器完整指南 — 两种运行模式、WebUI 登录、配置与诊断。

Quick Reference

属性值
适配器名称napcat
平台标识qq
协议OneBot v11 (WebSocket)
类NapCatAdapter
导入from ncatbot.adapter import NapCatAdapter
# 最小配置
adapters:
  - type: napcat
    platform: qq
    enabled: true
    config:
      ws_uri: ws://localhost:3001
      ws_token: napcat_ws

两种运行模式

NapCat 适配器提供两种模式，适应不同的部署场景：

Setup 模式（默认）

自动完成 NapCat 安装、配置、启动和登录。适合本地开发和首次部署。

config:
  ws_uri: ws://localhost:3001
  ws_token: napcat_ws
  enable_webui: true
  webui_token: napcat_webui
  # skip_setup 默认为 false，即 Setup 模式

流程：

检测 NapCat 服务是否在线
  ├─ 已在线 → 验证账号 → 完成
  └─ 未在线 → 安装/更新 NapCat → 生成配置 → 启动进程 → 登录 → 完成

登录优先尝试快速登录（如果该 QQ 号之前登录过），失败则自动切换到二维码登录（在终端显示 ASCII 二维码，使用手机 QQ 扫码）。

Connect 模式

直接连接已运行的 NapCat 服务，不管理 NapCat 进程。适合 NapCat 独立部署 或 Docker 环境。

config:
  ws_uri: ws://your-napcat-host:3001
  ws_token: napcat_ws
  skip_setup: true

流程：

尝试连接 WebSocket
  ├─ 成功 → 完成
  └─ 失败 → 抛出错误（不会自动安装或启动 NapCat）

配置项详解

bot_uin: '123456789'           # Bot 登录的 QQ 号
root: '987654321'              # 超级管理员 QQ 号

adapters:
  - type: napcat
    platform: qq
    enabled: true
    config:
      # WebSocket 连接
      ws_uri: ws://localhost:3001     # NapCat WebSocket 地址
      ws_token: napcat_ws             # WebSocket 认证 Token

      # WebUI（Setup 模式用于登录引导）
      enable_webui: true              # 是否启用 WebUI
      webui_token: napcat_webui       # WebUI 认证 Token
      # webui_host 和 webui_port 从 webui_uri 解析，默认 localhost:6099

      # 运行模式
      skip_setup: false               # true = Connect 模式, false = Setup 模式
配置项类型默认值说明
ws_uristringws://localhost:3001NapCat WebSocket 地址
ws_tokenstringnapcat_wsWebSocket 认证 Token，需与 NapCat 配置一致
enable_webuibooltrue启用 WebUI（Setup 模式下用于登录引导）
webui_tokenstringnapcat_webuiWebUI 认证 Token
skip_setupboolfalsetrue = Connect 模式，false = Setup 模式

登录流程详解

快速登录

NapCat 会缓存之前登录过的 QQ 号。如果目标 QQ 号在快速登录列表中，会自动完成登录，无需扫码。

二维码登录

快速登录不可用时，会在终端打印 ASCII 二维码：

[INFO] 快速登录列表: []
[INFO] 正在获取二维码...

█████████████████████████████
█████████████████████████████
████ ▄▄▄▄▄ █ ▀▄▀█ ▄▄▄▄▄ ████
...
请使用手机 QQ 扫描二维码登录

扫码后系统会自动检测登录状态并继续。二维码有效期约 60 秒，超时前会提示。

缓存登录

NapCat 启动后会先检查本地缓存的 session。如果 session 仍有效，会跳过登录流程直接连接。

连接诊断

使用 CLI 工具诊断连接问题：

ncatbot napcat diagnose

诊断内容包括：

  • WebSocket 连接测试
  • WebUI 可达性
  • Token 验证
  • NapCat 进程状态

常见问题

问题原因解决方案
WebSocket 连接超时NapCat 未启动或端口不对检查 ws_uri 和 NapCat 是否运行
Token 错误 (retcode=1403)ws_token 与 NapCat 配置不一致确认两端 Token 匹配
WebUI 认证失败webui_token 不匹配检查 NapCat WebUI 配置中的 Token
账号不匹配当前登录 QQ 号与 bot_uin 不同确认 bot_uin 正确，或重新登录
不支持 Setup 模式运行在不受支持的平台使用 skip_setup: true 手动管理 NapCat

示例

  • examples/qq/01_hello_world/ — 最简 QQ Bot
  • examples/qq/02_event_handling/ — 事件处理
  • examples/qq/03_message_types/ — 消息类型
  • examples/qq/04_bot_api/ — Bot API 调用
  • examples/qq/09_full_featured_bot/ — 完整功能 Bot

延伸阅读

版权归属：huan-yp

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

© 2025 NcatBot