SnowLuma 接入¶
SnowLuma 是面向 QQ 客户端的新一代互操作运行时，把 QQ 原生会话转成 OneBot 接口。 它在 Windows 上体验最完整；Linux 也能跑，但 QQ 扫码登录需要一块能看见的远程桌面。
前置：月璃后端已经能跑（第一次启动与配置）， 准备好两个不同的 QQ 号——机器人号用小号。
先看清这四件事¶
接入时最容易卡住的就是这四个问题，动手前先花一分钟看完。
一、要建的是「正向 WebSocket 服务端」¶
这个服务由协议端开出来、等着月璃去连，所以叫正向。
在 SnowLuma 的 OneBot 网络配置里对应的条目是 wsServers：
wsServers（服务端）—— 对的。SnowLuma 监听端口，月璃主动连上来。wsClients（客户端）—— 方向反了，月璃不会去当服务端，连不上。- 只开 HTTP 服务端 —— 不满足，月璃走的是 WebSocket。
这一条还要同时提供事件与动作：当前配置形态里 role 填 Universal，
只接事件或只收 API 都会出现「收得到消息、发不出回复」。
二、一共涉及四个端口，只有一个要填进月璃¶
| 端口 | 谁在用它 | 要填进月璃吗 |
|---|---|---|
| 协议端管理面板端口（默认 5099） | 浏览器打开 SnowLuma 的 WebUI 改配置 | 不填 |
| OneBot HTTP 服务端口 | HTTP 上报或 API 调用 | 本接入方式用不到 |
| 正向 WebSocket 端口 | 月璃连过去收发消息 | 要填，就是 [snowluma].port，示例用 8095 |
| 月璃后端端口 7999 | 浏览器打开月璃的管理面板 | 不填，和协议端没有关系 |
四个端口互不通兑。只有 WebSocket 那个要出现在月璃的配置里， 另外三个填进去都会连不上。
三、一共三个 token，也只有一个要填进月璃¶
| 名字 | 干什么用 | 填到哪 |
|---|---|---|
协议端 OneBot 访问令牌（accessToken） |
月璃连协议端时握手用的凭据 | 月璃的 [snowluma].token；协议端没设这项就留空 |
| 协议端管理面板初始密码 | 登录 SnowLuma 自己的 WebUI | 不填 |
| 月璃面板 token | 登录月璃的管理面板 | 不填 |
前两个都在协议端，但只有第一个是给月璃用的 —— 把管理面板密码填进 token
是接入时最常犯的错，表现是握手返回 401 或 403。
四、月璃这边要改两个文件¶
两个文件都在项目目录下（项目装在 D:\YueLiBot 就是 D:\YueLiBot\config\adapter.toml
与 D:\YueLiBot\adapters\yueli-snowluma-adapter\config.toml），用记事本打开即可。
config/adapter.toml：只改plugin一行adapters/yueli-snowluma-adapter/config.toml：改[snowluma]与[owner]段里的几个值
两个文件的分工，见适配器配置。
第一步：装 SnowLuma¶
两条都可以：
走桌面控制台——到
NapCatQQ Desktop 的 Releases
下载 NapCatQQ-Desktop-<版本>-x64.msi 安装。这个控制台同时管 NapCat 和
SnowLuma，能一键装组件、起停、看日志。
走官方发行包——到
SnowLuma 的 Releases
下载 Windows 完整发行包，解压到独立目录，运行 launcher.bat。
Lite 版不带运行时，需要自己装 Node.js 22.13 以上（23 系要 23.4 以上）。 不确定就下完整版。
第二步：登录机器人 QQ¶
打开桌面 QQ 并用机器人小号登录，然后启动 SnowLuma。 两者应当用同一个 Windows 用户、相同的权限等级运行，否则注入会失败。
启动日志里会打印 WebUI 地址，默认是：
用日志里给的初始密码登录（全新数据目录时由启动日志提供）。 这个密码是 SnowLuma 自己的管理面板密码，不是 OneBot 访问令牌。
进面板先看 QQ 的连接／注入状态：状态不对时先解决协议端自己的问题， 这时候去连月璃只会白费功夫。
第三步：建一个正向 WebSocket 服务端¶
在 SnowLuma 的面板里进入 OneBot 网络配置，新建一个 wsServers 条目。
不同版本的字段名略有出入，但只要看到下面这几项，就说明找对地方了：
| 界面上的字段 | 填什么 | 月璃那边对应哪个值 |
|---|---|---|
| 启用 | 打开（只保存不启用，端口不会真的监听） | 插件连接段的 enabled = true |
| 主机 / 监听地址 | 127.0.0.1（同机部署） |
host = "127.0.0.1" |
| 端口 | 8095，或任意没被占用的端口 |
port，两边必须一模一样 |
| 角色 / role | Universal（事件与动作都要） |
不用填 |
| 路径 | /（月璃固定用根路径，不支持自定义路径） |
不用填 |
访问令牌 / accessToken |
自定义；不想设就留空 | 有值就原样填进 token，留空则 token = "" |
| 消息格式 | array |
适配器按消息段解析 |
注意端口那一行是唯一需要两边抄一致的数字。上面的管理面板端口、 下面的 HTTP 端口都不要填进月璃，见上面第二节。
保存后确认服务真的开始监听——只保存草稿、没有启用，端口是不会开的。
消息上报必须是数组格式
SnowLuma 不同版本的配置键名不一样：有的界面叫 messagePostFormat，
当前的配置文档用的是 messageFormat。哪个存在就改哪个，都设成 array。
只识别新键名的版本里，写旧键名不会报错但也不生效——
最终判据是事件里的 message 是数组而不是字符串。
第四步：在月璃这边选插件、填连接¶
要改两个文件，都在项目目录下，用记事本打开就行（右键 → 打开方式 → 记事本）。
先打开 config/adapter.toml。项目装在 D:\YueLiBot 的话，完整路径就是
D:\YueLiBot\config\adapter.toml。把 plugin 改成：
再打开第二个文件：adapters/yueli-snowluma-adapter/config.toml，同样在项目目录下。
它可能还不存在 —— 那就从
连接模板
复制一份内容，存成这个路径。
改下面这几个值，其余字段保留模板里的原样：
[snowluma]
enabled = true # 启用前先在协议端建好 wsServers 条目
self_qq = "123456789" # 机器人小号，与协议端登录的号一致
host = "127.0.0.1" # 只填地址，不带 ws://、端口和路径
port = 8095 # 与协议端实际监听端口一致
token = "" # 填成协议端的 accessToken；没有就留空
[owner]
qq = "987654321" # 你自己的 QQ 号，与上面必须是两个不同的号
段名必须是 [snowluma]，不能沿用别家插件的段名。
token 填的是协议端的 accessToken；三个 token 的区别见
上面第三节。
地址怎么填才对¶
host 只填主机名或 IP。 月璃当前固定使用普通 ws://主机:端口 连接，
不支持自定义路径——协议端必须在根路径 / 上提供服务。
服务器上写 0.0.0.0 是监听范围，不是连接地址。 月璃这边要填能连到的实际地址。
容器里的 127.0.0.1 指容器自己。 月璃跑在宿主机就填映射到宿主机的端口；
月璃也在容器里，就填容器网络里能到达的地址。
别把端口搞混：管理面板端口、OneBot HTTP 端口和 WebSocket 端口是三回事，
只有 WS 端口能填进 port。
第五步：启动并确认¶
保持 QQ 与 SnowLuma 在线，在月璃项目根目录运行：
看后端终端里的适配器连接状态与识别到的登录号，然后：
- 用你自己的 QQ 私聊机器人号，确认 QQ 里收到回复
- 把测试群写进
[group]名单，重启月璃 - 在群里用 @ 提及机器人，确认群里有回复
连不上的常见原因¶
| 现象 | 先查这里 |
|---|---|
| 面板能打开，但 QQ 里没反应 | QQ 登录了吗、注入成功了吗、版本对得上吗 |
| WS 连接失败 | wsServers 条目启用了吗、端口与容器映射一致吗 |
| 401 / 403 | 填的是 accessToken 吗，是不是把管理员密码填了进去 |
| 收得到事件、发不出消息 | 服务端的 role 是不是 Universal，看动作报错 |
| 消息格式校验失败 | 实际生效的那个格式键（messageFormat 或 messagePostFormat）设成 array 了吗 |
| 插件配置校验失败 | 段名是不是 [snowluma]，两个 QQ 号是不是填成了同一个 |
| 私聊正常、群里不回 | 群号进白名单了吗、@ 到了吗、她是不是在睡眠 |
reconnect_interval_sec 管断线重连，action_timeout_sec 管动作等待。
端口、鉴权或账号错了，把等待时间调长解决不了问题。
配置能读通、连接能建立、QQ 真收到回复——这三件事要分别确认。 只读自检见适配器配置。