SnowLuma 是面向 QQ 客户端的新一代互操作运行时，把 QQ 原生会话转成 OneBot 接口。 它在 Windows 上体验最完整；Linux 也能跑，但 QQ 扫码登录需要一块能看见的远程桌面。 前置 ：月璃后端已经能跑（ 第一次启动与配置 ）， 准备好两个不同的 QQ 号——机器人号用 小号 。 接入时最容易卡住的就是这四个问题，动手前先花一分钟看完。 一、要建的是「正向 WebSocket 服务端」 ¶ 这个服务由协议端开出来、等着月璃去连，所以叫 正向 。 在 SnowLuma 的 OneBot 网络配置里对应的条目是 wsServers ： wsServers （服务端）—— 对的。SnowLuma 监听端口，月璃主动连上来。 wsClients （客户端）—— 方向反了，月璃不会去当服务端，连不上。 只开 HTTP 服务端 —— 不满足，月璃走的是 WebSocket。 这一条还要 同时提供事件与动作 ：当前配置形态里 role 填 Universal ， 只接事件或只收 API 都会出现「收得到消息、发不出回复」。 二、一共涉及四个端口，只有一个要填进月璃 ¶ 四个端口互不通兑。 只有 WebSocket 那个 要出现在月璃的配置里， 另外三个填进去都会连不上。 三、一共三个 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 条目。 不同版本的字段名略有出入，但只要看到下面这几项，就说明找对地方了： 注意 端口那一行是唯一需要两边抄一致的数字 。上面的管理面板端口、 下面的 HTTP 端口都不要填进月璃，见 上面第二节 。 保存后确认 服务真的开始监听 ——只保存草稿、没有启用，端口是不会开的。 SnowLuma 不同版本的配置键名不一样：有的界面叫 messagePostFormat ， 当前的配置文档用的是 messageFormat 。 哪个存在就改哪个，都设成 array 。 只识别新键名的版本里，写旧键名不会报错但也不生效—— 最终判据是 事件里的 message 是数组而不是字符串 。 第四步：在月璃这边选插件、填连接 ¶ 要改两个文件， 都在项目目录下 ，用记事本打开就行（右键 → 打开方式 → 记事本）。 先打开 config/adapter.toml 。项目装在 D:\YueLiBot 的话，完整路径就是 D:\YueLiBot\config\adapter.toml 。把 plugin 改成： 再打开第二个文件： adapters/yueli-snowluma-adapter/config.toml ，同样在项目目录下。 它可能还不存在 —— 那就从 连接模板 复制一份内容，存成这个路径。 改下面这几个值， 其余字段保留模板里的原样 ： 段名必须是 [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] 名单，重启月璃 在群里用 @ 提及机器人，确认群里有回复 reconnect_interval_sec 管断线重连， action_timeout_sec 管动作等待。 端口、鉴权或账号错了，把等待时间调长解决不了问题。 配置能读通、连接能建立、QQ 真收到回复——这三件事要分别确认。 只读自检见 适配器配置 。