接入 QQ（OneBot）

LenBot 本身不直接实现 QQ 客户端协议，通过标准 OneBot v11 WebSocket 接口连接已登录 QQ 的协议端（例如 SnowLuma，推荐使用）收发消息。协议端自身的安装与扫码登录步骤见对应项目的文档。

选择连接方式

连接方式	连接方向	LenBot 一侧填写	OneBot 一侧开启
正向 WebSocket	LenBot 主动连接 OneBot	OneBot 地址，例如 ws://127.0.0.1:3001	WebSocket 服务端（Server）
反向 WebSocket	OneBot 主动连接 LenBot	监听地址和监听端口（向导默认 127.0.0.1 与 8080）	WebSocket 客户端（Client），目标填 ws://<LenBot 地址>:<端口>

两者部署在同一台机器上时优先选用正向 WebSocket；跨容器或跨主机部署时按网络可达方向选择。

访问令牌在两侧填写完全一致的字符串。反向 WebSocket 监听 127.0.0.1 以外的地址（例如 0.0.0.0）时，必须设置非空访问令牌。

使用反向 WebSocket 时，OneBot 客户端需同时满足三项要求，否则 LenBot 会拒绝握手：

• 使用合并事件与 API 调用的 Universal 连接模式。
• 同一时刻只向 LenBot 建立一条活跃连接。
• 协议端当前登录的 QQ 号与 lenbot.config.json 中的 bot_id 一致。

首次配置时点击测试连接，返回 已连接：… 即握手通过。后续可在系统 → 设置 → 连接中修改连接参数（保存并重启后生效），当前连接状态实时显示在面板顶栏与总览页。

消息上报格式与自发消息

OneBot 客户端的消息上报格式需设为 array（消息段数组），例如在 NapCat 中将 messagePostFormat 设为 array。

如果希望 Bot 账号在手机或电脑 QQ 客户端手动发出的消息也进入群聊上下文，可在 OneBot 客户端开启自身消息上报（例如 NapCat 的 reportSelfMessage）。LenBot 会接收 message_sent 事件，按平台消息 ID 自动去重 Bot 自己刚发出的回显，并将人工代发的消息记入对应场景历史。

断线自动恢复

运行期间连接中断时，LenBot 自动恢复连接：

• 正向 WebSocket：按指数退避自动重连，首次等待 1 秒，随后翻倍直至上限 30 秒；连接恢复并稳定保持 30 秒后重置退避计数。每次重连成功后都会重新校验登录的 QQ 号。断线原因与重试倒计时展示在总览页，并以 platform_error（平台连接出错）事件记入系统 → 日志。
• 反向 WebSocket：保持端口监听，等待 OneBot 客户端重新连入。

以下两种情形不会自动重连，需人工操作：

• 进程启动时首次握手失败（例如 OneBot 尚未启动或地址有误）：排查后在总览状态卡点击手动连接。
• 在总览点击了断开连接：点击连接重新接入平台，已配置的群继续使用原来的会话。

控制群聊参与

接入平台后直接发送回复。在总览的群列表中用开关开启或关闭群，点击方形按钮切换聊天／插件模式，并选择活跃／适中／安静唤醒档位。

容器网络注意事项

• OneBot 在容器中、LenBot 在宿主机上：正向连接需将 OneBot 容器的 WebSocket 端口映射到宿主机（建议绑定 127.0.0.1:<端口>），LenBot 填 ws://127.0.0.1:<端口>；反向连接时容器内的 127.0.0.1 指向容器自身，需将 LenBot 监听地址设为 Docker 网桥可达地址并配置访问令牌，再在容器内连接宿主机地址。
• LenBot 在容器中、OneBot 在宿主机上：正向连接在 LenBot 中填写 ws://host.docker.internal:<端口>；反向连接在 LenBot 容器内监听 0.0.0.0:<端口>、设置访问令牌并将端口发布到宿主机。

语音大小与文件上传

• 大体积语音消息：开启语音转写且调大了单条语音字节上限时，OneBot WebSocket 帧包含 Base64 编码的音频数据，需在系统 → 设置 → 连接 → 更多设置中同步调大单条数据上限（onebot.max_frame_bytes），计算公式见 ASR 部署说明。
• 发送任务交付文件：交付文件以 base64:// 随上传请求发送，单个文件最大 36MiB。通过 HTTP 发送动作时，SnowLuma 的 HTTP 接口只接受 2MB 以内的请求体，较大的文件需要改用 WebSocket 发送动作，详见后台任务。

分享卡片解析

QQ 小程序、图文链接和音乐分享卡片会提取提示词、标题和简介文本交给聊天模型（每项截断至最多 80 字，不含跳转 URL 和图标）；无文本字段或内部 JSON 无法解析的卡片显示为 [json]。