本文档由 AI 编写，已经人工审核。

QQ#

NextBridge 通过 OneBot 11 WebSocket 协议连接 QQ。支持多种协议后端：NapCat（默认）、Lagrange.OneBot，以及任何通用 OneBot 11 实现。

准备工作#

1. 安装并运行你选择的 OneBot 11 后端（如 NapCat），将其配置为 WebSocket 服务端模式。

2. 记录 WebSocket 地址（默认：ws://127.0.0.1:3001）和你设置的访问令牌。

3. 在 data/config.json 中添加实例配置。

配置项#

在 config.json 的 qq.<实例ID> 下添加：

{
  "qq": {
    "qq_main": {
      "protocol": "napcat",
      "ws_url": "ws://127.0.0.1:3001",
      "ws_token": "your_secret",
      "max_file_size": 10485760
    }
  }
}

规则频道键#

在 rules.json 的 channels 或 from/to 下使用：

{
  "qq_main": { "group_id": "947429526" }
}

消息段解析#

收到的消息依据 OneBot 11 消息段数组解析：

发送#

file_send_mode 和 stream_threshold 配置项控制视频和文件的上传方式。Stream 模式（upload_file_stream → upload_group_file）为默认值，对大文件更可靠。如果你的 OneBot 后端不支持流式上传，可改为 "base64"；配置 stream_threshold 可在文件超过指定大小时自动回退到 stream 模式。

合并转发渲染#

当 forward_render_enabled 为 true 时，QQ 合并转发消息会被渲染为独立的 HTML 页面，支持完整的媒体内容（图片、语音、视频、文件）。渲染页面可通过 HTTP 服务器在配置的 forward_render_mount_path 路径访问。

• 页面销毁：合并转发页面在销毁或过期后会直接失效，刷新时会返回 404，不会再次打开旧页面。

• 页面设置：合并转发页面右上角提供设置入口，可切换颜色模式与合并转发显示方式，并使用 LocalStorage 记忆。

• 不可靠 UID 标记：当 OneBot 后端在同一批合并转发中无法可靠对应发送者 ID 时，页面会把该 UID 标记为不可靠。

• 按规则覆盖 TTL：forward_render_ttl_seconds 可通过规则中的 msg 配置按规则覆盖。

消息编辑同步#

QQ（OneBot 11）没有原生的「编辑消息」API，因此其他平台（Discord/Telegram）上的编辑无法就地应用到 QQ 上的原始消息。NextBridge 转而模拟编辑：

• 当编辑被桥接到 QQ 时，NextBridge 会发送一条新消息，该消息**引用（回复）**原始桥接消息，并在前面添加 edit_prefix 前缀（默认 [编辑]）。

• 重复编辑始终引用原始桥接消息，因此编辑始终锚定在原消息上。

• 仅同步文本内容，编辑时不会重新发送附件。

• 将 edit_via_reply 设为 false 可关闭此行为并忽略收到的编辑。

消息撤回同步#

QQ（OneBot 11）原生支持消息撤回，因此撤回可以双向同步：

• 检测：QQ 端撤回消息时，OneBot 后端会推送 group_recall（群聊）或 friend_recall（私聊）通知事件，NextBridge 据此将撤回桥接到其他平台。

• 应用：其他平台（Discord/Telegram）上的撤回会通过原生 delete_msg API 应用到 QQ 上对应的桥接消息。

• 若一条源消息被拆分成多条 QQ 消息，撤回时会一并删除全部对应消息。

• 将 enable_recall 设为 false 可完全禁用撤回的检测与应用。

注意事项#

• 自身消息回显：OneBot 后端会将机器人自己发送的消息作为真实事件回传。NextBridge 通过对比 user_id 与 self_id 自动过滤这类消息。

• 自动重连：WebSocket 连接断开后，NextBridge 每隔 5 秒自动重新连接。