NcatBot 文档

外观

SnowLuma / QQ 适配器

约 1338 字大约 4 分钟

2026-05-15

SnowLuma (OneBot v11) 适配器指南 — 协议层复用 NapCat，实现独立的下载、启动与 WebUI 引导。

Quick Reference

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

SnowLumaAdapter 与 NapCatAdapter 的 platform 都是 qq，同一个 BotClient 里只能二选一。

适配器定位

SnowLuma 是自带 Node.js 运行时的独立 OneBot v11 协议端，不依赖系统 QQNT 客户端。NcatBot 在这一层只做两件事：

  1. 连接 SnowLuma 暴露的 OneBot v11 WebSocket
  2. 在 Setup 模式下按需下载、启动并引导用户进入 WebUI 完成首次配置

协议实现完全复用 NapCat 适配器中的以下组件：

  • NapCatWebSocket
  • OB11Protocol
  • NapCatBotAPI
  • NapCatEventParser

因此 SnowLuma 与 NapCat 在事件模型和 QQ Bot API 能力上保持一致，差异主要集中在 setup/ 流程。

CLI 初始化配置

通过 ncatbot init 或 ncatbot adapter 进入适配器管理并选择 SnowLuma 时，CLI 会调用 SnowLumaAdapter.cli_configure()：

  1. 询问是否立即自动下载并安装 SnowLuma（当前仅 Windows x64 支持）
  2. 若选择自动安装：跳过 WS / WebUI 地址输入，直接返回默认连接参数
  3. 若选择手动管理：依次输入 ws_uri、ws_token、webui_uri 和 skip_setup

自动安装只负责准备 SnowLuma 运行时，不会自动写入 OneBot v11 配置。首次启动时 NcatBot 会进入交互式引导，等待用户在 WebUI 中完成配置后按回车继续，随后自动收集 ws_uri / ws_token 并写回 config.yaml。

两种运行模式

Setup 模式（默认）

适合本机运行 SnowLuma，并希望由 NcatBot 负责下载和拉起协议端。

config:
  ws_uri: ws://localhost:3001
  ws_token: ""
  webui_uri: http://localhost:5099
  skip_setup: false

流程如下：

检测 SnowLuma WebSocket 是否已在线
  ├─ 已在线 → 直接连接
  └─ 未在线 → 下载/更新 SnowLuma → UAC 启动 →
             ├─ 已有历史配置 (configured=true 或 ws_token 非空)
             │   → 直接探针验证 WebSocket（最多重试 3 次）
             └─ 首次配置
                 → 快速探针（SnowLuma 可能已自带配置可用）
                   ├─ 通过 → 直接连接
                   └─ 未通过 → 交互式引导：
                       1. 打印 WebUI 地址与配置步骤
                       2. 等待用户按回车（无超时限制）
                       3. 收集 ws_uri / ws_token
                       4. 探针验证（失败可重试，最多 3 次）
                       5. 成功后自动写回 config.yaml

首次配置完成后，configured 字段会自动写入 config.yaml。后续启动时如果 WebSocket 服务正常，将跳过交互直接连接。

Connect 模式

适合 SnowLuma 由你手动或外部进程管理的场景，例如远端主机、现有运维脚本、或 Linux 手动部署。

config:
  ws_uri: ws://your-snowluma-host:3001
  ws_token: your_ws_token
  webui_uri: http://your-snowluma-host:5099
  skip_setup: true

流程如下：

直接探测并连接 OneBot v11 WebSocket
  ├─ 成功 → 完成
  └─ 失败 → 抛出错误（不会自动安装或启动 SnowLuma）

平台支持与限制

  • 自动安装 / 自动启动当前仅完整支持 Windows x64
  • Linux / macOS 请使用 skip_setup: true，手动管理 SnowLuma 进程
  • 首次启动时 NcatBot 会等待用户在 WebUI 中完成配置（无超时限制），完成后按回车继续
  • Windows 下 ncatbot snowluma stop 不会按进程名强杀 node.exe，只会提示手动关闭对应窗口

配置项详解

adapters:
  - type: snowluma
    platform: qq
    enabled: true
    config:
      ws_uri: ws://localhost:3001
      ws_token: ""
      webui_uri: http://localhost:5099

      skip_setup: false
      enable_update_check: false
      use_lite_package: false
      install_dir: ""
      configured: false
配置项类型默认值说明
ws_uristringws://localhost:3001SnowLuma 暴露的 OneBot v11 WebSocket 地址
ws_tokenstring""WebSocket access_token，为空表示不启用鉴权
webui_uristringhttp://localhost:5099SnowLuma WebUI 地址
skip_setupboolfalsetrue = Connect 模式；false = Setup 模式
enable_update_checkboolfalse启动前是否检查最新 release
use_lite_packageboolfalse是否优先下载 -lite 精简包
install_dirstring""安装目录；留空则使用平台默认目录
configuredboolfalse是否已完成首次交互配置（由框架自动写入，无需手动设置）

CLI 命令

SnowLuma 提供独立 CLI 命令组：

ncatbot snowluma install --yes
ncatbot snowluma diagnose
ncatbot snowluma diagnose ws --uri ws://localhost:3001 --token mytoken
ncatbot snowluma diagnose webui --uri http://localhost:5099
ncatbot snowluma version

常用命令：

  • ncatbot snowluma install [--yes] [--lite] [--install-dir PATH]：下载并解压 SnowLuma
  • ncatbot snowluma diagnose：同时检测 WebSocket 与 WebUI
  • ncatbot snowluma diagnose ws：只检测 OneBot v11 WebSocket
  • ncatbot snowluma diagnose webui：只检测 WebUI 可达性
  • ncatbot snowluma version：打印已安装版本与 GitHub 最新 release

常见问题

问题原因解决方案
retcode=1403 / Token 校验失败ws_token 与 WebUI 中配置的不一致对齐 ws_token 与 OneBot v11 端点的 access_token
交互引导后探针仍失败WebUI 中 OneBot v11 端点未启用或端口不匹配确认 WebUI 中已启用 WebSocket 服务，端口与 ws_uri 一致
WS 握手成功但收不到事件未扫码登录或登录态失效重新在 WebUI 完成扫码登录
Setup 模式报不支持当前系统非 Windows x64改用 skip_setup: true，手动管理 SnowLuma
每次启动都被要求输入配置configured 未被写入（可能是权限问题）手动在 config.yaml 的 snowluma config 中添加 configured: true

延伸阅读

版权归属：GEYUANwuqi

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

© 2025-2026 NcatBot