SnowLuma / QQ 适配器

约 1105 字大约 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 在这一层只做两件事：

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

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

NapCatWebSocket
OB11Protocol
NapCatBotAPI
NapCatEventParser

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

CLI 初始化配置

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

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

自动安装只负责准备 SnowLuma 运行时，不会自动写入 OneBot v11 配置。首次启动后仍需要进入 SnowLuma WebUI 手动启用 WebSocket 端点并扫码登录。

两种运行模式

Setup 模式（默认）

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

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

流程如下：

检测 SnowLuma WebSocket 是否已在线
  ├─ 已在线 → 直接连接
  └─ 未在线 → 下载/更新 SnowLuma → UAC 启动 →
             提示用户在 WebUI 启用 OneBot v11 → 扫码登录 → 等待 WS 就绪

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 进程
首次启动必须在 SnowLuma WebUI 中手动启用 OneBot v11 WebSocket 端点
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: ""

配置项	类型	默认值	说明
`ws_uri`	string	`ws://localhost:3001`	SnowLuma 暴露的 OneBot v11 WebSocket 地址
`ws_token`	string	`""`	WebSocket `access_token`，为空表示不启用鉴权
`webui_uri`	string	`http://localhost:5099`	SnowLuma WebUI 地址
`skip_setup`	bool	`false`	`true` = Connect 模式；`false` = Setup 模式
`enable_update_check`	bool	`false`	启动前是否检查最新 release
`use_lite_package`	bool	`false`	是否优先下载 `-lite` 精简包
`install_dir`	string	`""`	安装目录；留空则使用平台默认目录

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 能打开但 WS 一直超时	尚未启用 OneBot v11 WebSocket 端点	在 SnowLuma WebUI 中启用 WebSocket 服务并确认端口
WS 握手成功但收不到事件	未扫码登录或登录态失效	重新在 WebUI 完成扫码登录
Setup 模式报不支持当前系统	非 Windows x64	改用 `skip_setup: true`，手动管理 SnowLuma

版权所有

版权归属：GEYUANwuqi

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

通用

QQ

Bilibili

GitHub

通用

QQ