SnowLuma 接入¶

本篇把 SnowLuma 的 OneBot 正向 WebSocket 接到月璃。 先完成后端安装，准备两个不同 QQ 账号。 群聊白名单和参与规则见接入总览。

安装并登录协议端¶

Windows 原生部署先安装与 SnowLuma 发行版兼容的桌面 QQ。 从 SnowLuma 发布页面选择 win-x64 包，解压到独立目录。 完整版内置 Node，精简版需要自行安装 Node 22 或更新版本。 运行包内 launcher.bat，同时打开 QQ，用机器人账号扫码登录。 QQ 与 SnowLuma 应使用同一 Windows 用户和相同权限等级运行。

检查 SnowLuma 的 QQ 连接或注入状态，再用启动输出提供的地址进入 WebUI。 首次全新数据目录的管理密码由启动输出提供；它不是 OneBot 访问令牌。 QQ 版本不匹配或注入未完成时，先解决协议端自身状态，再连接月璃。 无头 Linux 的 QQ 登录需要可见的远程桌面扫码；月璃本身没有代登录入口。 协议端独立运行，其发行包应解压到月璃插件目录以外的位置。

建立正向 WebSocket 服务端¶

进入 SnowLuma 的 OneBot 网络配置，使用 wsServers 服务端条目。 wsClients 为反向客户端，不适用于本接入方式。 配置一个同时支持事件与动作的服务端，根路径为 /。 当前配置形态中的 role 使用 Universal，避免仅接事件或仅收 API。

同机示例可设主机为 127.0.0.1、端口为 8095，启用该服务。 8095 为示例端口；保留协议端原有端口时，须同步修改月璃插件配置。 访问令牌使用该 OneBot 服务的 accessToken。 保存后确认服务实际开始监听。

消息上报必须为数组。 如果所用界面提供 messagePostFormat，必须改为 array。 当前 SnowLuma 配置文档使用的是 messageFormat，该字段也应设为 array。 仅识别新字段的版本中，添加旧字段不会改变上报格式，应使用该版本支持的配置键。 最终判据是事件中的 message 为数组，而不是字符串。 月璃不读取协议端这份 JSON，只会校验它实际收到的消息段。

选择插件与填写两个 QQ 号¶

编辑月璃的 config/adapter.toml：

plugin = "yueli-snowluma-adapter"

从连接模板准备真实配置， 落点是 adapters/yueli-snowluma-adapter/config.toml。 连接段名须与当前插件一致，不得沿用其他插件的段名。 以下片段修改已有段，QQ 号需换成实际账号：

[snowluma]
enabled = true
self_qq = "123456789"
host = "127.0.0.1"
port = 8095
token = ""

[owner]
qq = "987654321"

把 token 填为协议端 OneBot 服务的访问令牌。 self_qq 对应协议端登录的机器人号，owner.qq 是用户本人。 两者相同会被拒绝，实际登录号与配置不同也会在连接后报错。 保留模板的版本、重连设置、私聊与群聊名单。

网络位置要对齐¶

host 仅填主机或 IP，不带协议、端口和路径。 当前月璃连接固定使用普通 ws://主机:端口，不提供自定义路径设置。 协议端须通过根路径 / 提供服务；仅支持自定义路径的服务端不满足连接条件。 服务器填 0.0.0.0 表示监听范围，月璃连接时要填可到达的实际地址。

容器内的 127.0.0.1 指容器自身，不是宿主机。 月璃在宿主机时，要连已经映射到宿主机的 WS 端口； 月璃位于其他容器时，应使用容器网络可达的地址。 SnowLuma 管理面板端口、OneBot HTTP 端口与 WS 端口用途不同，不可互换。

启动与验收¶

保持 QQ 和 SnowLuma 在线，在月璃根目录运行 uv run bot.py。 检查适配器连接状态及实际登录号，并使用本人 QQ 发送私聊短消息。 确认 QQ 收到实际回复后，添加测试群白名单并用真实 @ 验证群聊。 收到入站事件只证明上报方向；仍需确认出站动作成功。

连不上的常见原因¶

reconnect_interval_sec 管断线重连，action_timeout_sec 管动作响应等待。 端口、鉴权或账号错误不能靠加长等待解决。 自检与文件关系见适配器配置。