SnowLuma 通过 OneBot v11 接入 AstrBot。AstrBot 侧和 NapCat 共用同一个适配器;这篇从创建适配器开始写,单独看也能跑通。
1. 在 AstrBot 中创建 OneBot v11 适配器
如果已经按 NapCat 那篇创建过适配器,直接跳到第 2 节。否则打开 AstrBot WebUI,进入「机器人 → 创建机器人」:
创建适配器
创建机器人
消息平台类别选
OneBot v11,机器人名称填qq。填写反向 WebSocket
反向 WebSocket 主机填
0.0.0.0,端口填6199,Token 留空。
消息平台类别 OneBot v11,反向 WebSocket 主机 0.0.0.0,端口 6199 保存并启用
保存后回到机器人列表,确认
qq处于运行中。SnowLuma 后面连的就是这个6199。
qq 使用 aiocqhttp,反向 WebSocket 端口 6199
2. 部署 SnowLuma
以 SnowLuma 为例,1Panel 防火墙放行 6185、5099、6081 即可:

2.1 单独部署 SnowLuma
AstrBot 已经部署好时,只新增 SnowLuma。它使用自己的 snowluma-network,通过 host.docker.internal 访问宿主机上的 AstrBot,并共享 astrbot-data。
单独部署 SnowLuma
保存配置
SnowLuma 需要先设置
VNC_PASSWD,例如VNC_PASSWD=passwd123。services:snowluma:image: ${SNOWLUMA_IMAGE:-motricseven7/snowluma:latest}container_name: ${SNOWLUMA_CONTAINER:-snowluma}restart: unless-stoppeduser: "0:0"shm_size: 1gbcap_add:- SYS_PTRACEsecurity_opt:- seccomp=unconfinedextra_hosts:- "host.docker.internal:host-gateway"environment:VNC_PASSWD: ${VNC_PASSWD:-vncpasswd}SNOWLUMA_UID: ${SNOWLUMA_UID:-1000}SNOWLUMA_GID: ${SNOWLUMA_GID:-1000}SNOWLUMA_WEBUI_PORT: ${SNOWLUMA_WEBUI_PORT:-5099}SNOWLUMA_LOG_LEVEL: ${SNOWLUMA_LOG_LEVEL:-info}SNOWLUMA_SCREEN: ${SNOWLUMA_SCREEN:-1920x1080x16}SNOWLUMA_HOOK_AUTOLOAD: ${SNOWLUMA_HOOK_AUTOLOAD:-1}SNOWLUMA_EXTRA_QQ_HOMES: "${SNOWLUMA_EXTRA_QQ_HOMES:-}"SNOWLUMA_QQ_FLAGS: "${SNOWLUMA_QQ_FLAGS:---disable-gpu --disable-software-rasterizer --disable-gpu-compositing}"ports:- "${VNC_PORT:-5900}:5900"- "${NOVNC_PORT:-6081}:6081"- "${SNOWLUMA_WEBUI_HOST_PORT:-5099}:${SNOWLUMA_WEBUI_PORT:-5099}"- "${ONEBOT_HTTP_PORT:-3000}:3000"- "${ONEBOT_WS_PORT:-3001}:3001"volumes:- snowluma-data:/app/snowluma-data- snowluma-qq-config:/app/.config- snowluma-qq-data:/app/.local/share- astrbot-data:/AstrBot/datanetworks:- snowluma-networknetworks:snowluma-network:name: snowluma-networkdriver: bridgevolumes:snowluma-data:snowluma-qq-config:snowluma-qq-data:astrbot-data:external: true保存为
/opt/astrbot/compose.snowluma.yml。启动
Terminal window cd /opt/astrbotdocker compose -f compose.snowluma.yml up -d
2.2 AstrBot + SnowLuma 一起部署
如果还没有单独部署 AstrBot,可以用一份 Compose 把两者一起拉起。两个容器都在 astrbot-network,共享 astrbot-data,6199 不映射到宿主机。
一起部署
保存配置
SnowLuma 需要先设置
VNC_PASSWD,例如VNC_PASSWD=passwd123。services:astrbot:image: soulter/astrbot:latestcontainer_name: astrbotrestart: alwayssecurity_opt:- no-new-privileges:trueports:- "6185:6185" # AstrBot WebUIenvironment:- TZ=Asia/Shanghaivolumes:- astrbot-data:/AstrBot/data- /etc/localtime:/etc/localtime:ronetworks:- astrbot-networksnowluma:image: ${SNOWLUMA_IMAGE:-motricseven7/snowluma:latest}container_name: ${SNOWLUMA_CONTAINER:-snowluma}restart: unless-stoppeduser: "0:0"shm_size: 1gbcap_add:- SYS_PTRACEsecurity_opt:- seccomp=unconfinedenvironment:- VNC_PASSWD=${VNC_PASSWD:-vncpasswd}- SNOWLUMA_UID=${SNOWLUMA_UID:-1000}- SNOWLUMA_GID=${SNOWLUMA_GID:-1000}- SNOWLUMA_WEBUI_PORT=${SNOWLUMA_WEBUI_PORT:-5099}- SNOWLUMA_LOG_LEVEL=${SNOWLUMA_LOG_LEVEL:-info}- SNOWLUMA_SCREEN=${SNOWLUMA_SCREEN:-1920x1080x16}- SNOWLUMA_HOOK_AUTOLOAD=${SNOWLUMA_HOOK_AUTOLOAD:-1}ports:- "${VNC_PORT:-5900}:5900"- "${NOVNC_PORT:-6081}:6081"- "${SNOWLUMA_WEBUI_HOST_PORT:-5099}:${SNOWLUMA_WEBUI_PORT:-5099}"- "${ONEBOT_HTTP_PORT:-3000}:3000"- "${ONEBOT_WS_PORT:-3001}:3001"volumes:- snowluma-data:/app/snowluma-data- snowluma-qq-config:/app/.config- snowluma-qq-data:/app/.local/share- astrbot-data:/AstrBot/datanetworks:- astrbot-networknetworks:astrbot-network:driver: bridgevolumes:snowluma-data:snowluma-qq-config:snowluma-qq-data:astrbot-data:name: astrbot-data保存为
/opt/astrbot/compose.snowluma.yml。启动
Terminal window cd /opt/astrbotdocker compose -f compose.snowluma.yml up -d
3. 配置 SnowLuma WebSocket
打开 SnowLuma WebUI。
配置 SnowLuma WebSocket
打开 WebSocket 反向客户端
进入「节点配置 → OneBot 协议端点 → WebSocket 反向客户端」。
填写名称
名称填
astrbot。填写 URL
URL 填
ws://astrbot:6199/ws,Token 留空。保存并启用
保存后确认客户端处于启用状态。

4. 登录 SnowLuma
登录 SnowLuma
获取访问令牌
浏览器打开
http://<服务器IP>:5099。首次登录需要访问令牌,令牌在容器日志里:Terminal window docker logs snowluma 2>&1 | grep -i -E "webui|token|凭证|访问令牌"日志里会打印 WebUI 的访问令牌,不同镜像版本的字段名可能不一样。把它填到登录页:

在「输入访问令牌」处填入日志里的 Token 同意用户协议
首次进入会显示 EULA,勾选「我已阅读并同意」后点「同意并继续」。

勾选同意 EULA 后继续 设置访问密码
按提示设置新的访问密码并确认。

设置并确认新的访问密码 进入控制台并加载 QQ
设置完成后进入「概览」页;如果 QQ 还没启动,在「进程注入」里加载它,确认状态为「等待登录」。

在概览页确认服务状态 
进程注入里显示 qq 等待登录 登录 noVNC
浏览器打开
http://<服务器IP>:6081,输入 VNC 密码后就能看到 SnowLuma 的桌面,容器会自动启动 QQ。VNC 密码来自 compose 里的
VNC_PASSWD;没有改过时默认是vncpasswd。
输入 VNC_PASSWD,点击发送凭证 扫码登录 QQ
在桌面里用手机 QQ 扫码登录:

用手机 QQ 扫描 noVNC 桌面里的二维码 登录成功后,回到控制台的「进程注入」,可以看到 QQ 已在线:

进程注入里显示 QQ 已在线
5. 验证连接
验证连接
看 SnowLuma 概览
「OneBot 连接」里出现
astrbot的 WS 客户端「已连接」。
在线账号 1,astrbot WS 客户端已连接 看 AstrBot 日志
日志里出现
aiocqhttp(OneBot v11) 适配器已连接。
aiocqhttp(OneBot v11) 适配器已连接
常见问题
SnowLuma 的 WS 客户端一直显示未连接
2.2 一起部署:确认两个容器在同一个 Docker 网络,URL 里的 astrbot 能解析到 AstrBot 容器。
单独部署或跨网络:见 不同网络下的 OneBot WebSocket 通信。
AstrBot 和 SnowLuma 一起部署时出现 Network 错误
检查 compose 里的网络名是否和 AstrBot 实际使用的网络一致;同一份 compose 里的两个服务必须加入同一个网络。
AstrBot 提示 Token 不匹配
AstrBot 的反向 WebSocket Token 和 SnowLuma 的 Token 必须一致;不想校验就两边都留空。
SnowLuma 的 VNC 密码在哪里设置
在 2.1 单独部署 / 2.2 AstrBot + SnowLuma 一起部署 的 Compose 环境变量里设置 VNC_PASSWD。
分享文章
生成精美分享图或复制链接,与更多人分享本文。
继续阅读
换条路线
从其他文章中稳定抽取