切换外观
OneBot 11：连接 QQ 机器人
适用版本：Bot 0.6.30。
本页针对 OneBot 11 接入。使用 QQ 开放平台官机时，改按 QQ 官方机器人接入 配置 AppID / AppSecret；同一实例一次使用一种接入方式。
用途
将一个已登录的 QQ 账号通过 OneBot 11 通用反向 WebSocket 接入 VexBot，使机器人接收关联群消息并发送回复。VexBot 作为 WebSocket 服务端，QQ 实现端主动连接 VexBot；QQ 登录在实现端完成。
当前一个 Bot 实例接入一只 QQ 机器人，可以服务多个关联群。
准备
- Bot 已启动，管理面板能登录。安装入口见 Windows 或 Linux。
- 一个支持 OneBot 11 反向 WebSocket 的 QQ 实现端，例如 NapCat，且机器人 QQ 已登录、已加入测试群。
- 已在 接入空间 → 服务器列表 保存真实群号。一群关联一台服务器，一服可关联多个群。
- QQ 实现端能访问 Bot 的监听地址和端口。默认 Bot 只监听本机
127.0.0.1:5800。
操作步骤
1. 在 VexBot 设置 QQ 账号和令牌
从侧栏进入 接入空间 → 机器人连接，点击机器人卡片上的「接入设置」。窄屏设备先通过顶部菜单按钮打开导航：
- 填写「机器人 QQ 号」，与实现端当前登录账号一致。留空时 VexBot 按连接头识别账号；首次配置建议明确填写。
- 在「管理员 QQ 号」填写允许执行预设控制台命令的 QQ，每行一个。机器人接收普通消息和处理本人绑定不要求管理员身份。
- 保留初始化生成的「OneBot 连接令牌」，或生成新的随机令牌。
- 复制令牌和反向 WebSocket 地址，点击「保存全部设置」。保存会同时应用面板中其他尚未保存的设置；关闭弹窗会保留草稿。
配置文件中的对应字段是 onebot.self_id、onebot.admins、onebot.token。QQ 号和群号在配置中均为字符串。更改 QQ 号或 OneBot 令牌会断开旧连接，需要同步到实现端。
2. 在 QQ 实现端添加连接
在实现端的网络配置中选择 WebSocket 客户端 / 反向 WebSocket。不同实现端的菜单名称可以不同，填写下列连接参数后保存并启用：
| 参数 | 值或要求 |
|---|---|
| URL | 同机默认 ws://127.0.0.1:5800/onebot/ws |
| Token / Access Token | VexBot「OneBot 连接令牌」；填令牌本身，不加 Bearer |
| 连接模式 | Universal / 通用，API 与事件共用一条连接 |
| 消息格式 | 推荐消息段数组；VexBot 也接收 CQ 码字符串 |
| 断线重连 | 在实现端启用，可设置 3–5 秒间隔 |
VexBot 的 OneBot 连接使用 onebot.token，Minecraft 游戏端使用对应服务器的 servers.token。面板日常登录使用用户名和密码；app.admin_token 仅用于首次创建服主账号的授权和兼容管理 API。各类凭据不可混用。
3. 按部署位置选择地址
| QQ 实现端与 Bot 的位置 | QQ 实现端填写的 URL | Bot 侧处理 |
|---|---|---|
| 同一台机器、直接运行 | ws://127.0.0.1:5800/onebot/ws | 保留默认监听即可 |
| 不同机器 | ws://Bot实际地址:5800/onebot/ws | 在「设置 → 软件设置」改为实际网卡地址或 0.0.0.0，保存后重启主程序；允许所用网络访问该端口 |
| QQ 实现端在容器中 | 使用容器内能访问的 Bot 地址，保留 /onebot/ws | 容器内的 127.0.0.1 是容器自身；核对容器网络、Bot 监听和端口映射 |
| 已部署 HTTPS 反向代理 | wss://Bot域名/onebot/ws | 代理转发到 Bot，并支持 WebSocket 升级与连接头透传 |
0.0.0.0 只用于监听，不是客户端访问地址。面板给出的地址来自当前浏览器地址；通过 SSH 隧道访问面板时，复制出的本机地址未必能被 QQ 实现端访问，要从 QQ 实现端所在位置核对。
修改端口后同步更新 URL。原始 Bot 监听不直接提供 TLS；wss:// 示例用于已配置 HTTPS 的代理入口。
4. 确认连接和群回复
- 从侧栏打开 接入空间 → 机器人连接，确认机器人卡片显示「已连接」，QQ 号与预期一致；卡片同时展示关联群数、管理员人数和连接地址。连接状态来自实际 WebSocket 会话，尚未连入时显示「等待连接」。
- 打开 活动 → 运行日志，确认有「机器人 QQ号 已连接」记录。
- 使用另一位成员账号，在已关联群发送
帮助，应收到命令列表；不需要艾特机器人。 - 发送
状态或在线。已接入游戏端时应显示实际状态；游戏端尚未接入时可返回「桥接离线」，这仍说明 QQ 收发链路正常。
机器人自己的消息和匿名群消息不会作为普通群命令处理。常规验收使用普通成员的文本消息。游戏端接入、聊天与绑定测试见 快速开始的「验收群消息和绑定」。
预期结果
VexBot 总览与连接日志显示正确的机器人 QQ，关联群能收到 帮助 回复。只打开实现端、只完成 QQ 登录，或者只配置群号，都还不代表 OneBot 已连接成功。
常见故障
握手失败
VexBot 检查以下连接头。正常实现端应按协议发送，管理员只需在实现端填写 QQ 账号和 Token：
| 连接头 | VexBot 要求 |
|---|---|
Authorization | Bearer <onebot.token> |
X-Self-ID | 数字 QQ 号；VexBot 填写了机器人 QQ 时必须与其相同 |
X-Client-Role | 提供该头时必须为 Universal，大小写不敏感 |
| 错误或现象 | 处理方法 |
|---|---|
401 / OneBot token 不正确 | 同步 onebot.token；检查是否误用了面板令牌、游戏令牌或在 Token 输入框加了 Bearer |
403 / X-Self-ID 缺失或与配置不符 | 核对实际登录 QQ 与 VexBot 配置；检查实现端或代理是否发送、保留 X-Self-ID |
400 / 请选择 Universal / 通用反向 WebSocket | 将实现端改为通用连接，API 与事件共用一条连接 |
409 / 已有机器人连接 | 断开旧连接，保留一个启用的反向连接配置；当前实例只接受一条 QQ 连接 |
404 | 核对完整路径 /onebot/ws，以及代理路径是否正确转发 |
| 连接被拒绝、超时 | 先确认 Bot 运行，再检查 QQ 实现端可访问的地址、监听端口、容器网络和防火墙 |
已连接但群里没有回复
按顺序检查：
- 「服务器列表」是否已保存该群的真实群号，机器人是否仍在群内。
- 是否使用普通成员账号发送
帮助，群中是否限制机器人发言。 - QQ 实现端是否上报群消息事件，并接收、返回 API 调用结果。事件里的
self_id应与连接 QQ 一致。 - 「运行日志」是否出现
send_group_msg失败或处理群事件失败；同时查看实现端日志。