OpenClaw QQ 插件（OneBot v11）

为 OpenClaw 提供可生产使用的 QQ 渠道接入：先快速跑通，再按需启用高级能力。

[在线文档] [3 分钟快速开始] [配置参考] [NapCat 部署] [高级能力]

[!IMPORTANT] 官方交流论坛（唯一）： https://aiya.de5.net/c/25-category/25
问题反馈、配置经验、更新公告统一在论坛沉淀，便于检索和追踪。

最近更新（2026-04）

• 新增专题说明：2026-04-30 原生文件 / 媒体收发更新。
• QQ 普通文件附件现在默认只进入 <attachments> 元数据，不再自动展开 TXT 正文污染模型上下文。
• 入站文件会保留 name、url、local_path、file_id、size、mime 等元数据；需要读正文时再按 local_path 显式读取。
• 出站图片、语音、视频、压缩包已收进 QQ 插件原生逻辑，不再依赖旧的发文件 skill。
• sendMedia 会按媒体类型自动分流到 OneBot image / record / video / 文件上传接口。
• sendPayload 支持 mediaUrl、mediaUrls、files，可处理文本 + 多附件同发。
• 普通文件优先走 upload_group_file / upload_private_file，rich media 失败时会尝试文件上传 fallback。
• 已实测引用压缩包入站、引用 TXT metadata-only、原生发送图片、语音与 .zip 压缩包。

最近更新（2026-03）

• 新增专题说明：2026-03-20 默认行为调整。
• 新增专题说明：2026-03-27 媒体链路与传输模式更新。
• 本轮以“QQ 插件默认值/默认输出策略调整”为主，不改 OpenClaw core 的既有设计；如果你更喜欢旧体验，仍可通过配置项手动恢复。
• 默认关闭 interruptOnNewMessage，且仅在显式设为 true 时才会用“新消息打断旧回复”。
• 默认启用 blockStreaming=true + blockStreamingBreak=message_end，让 commentary / final 按完整 assistant message 落地，减少 QQ 侧碎片化输出。
• 默认 forwardLongReplyThreshold=300，长 final_answer 超过阈值时自动改用 QQ 合并转发；commentary 仍按普通消息发送。
• 默认 forwardNodeCharLimit=0，转发时不按长度拆节点，尽量把同一轮长回复合并成一个转发。
• 默认 allowBareGroupCommands=false，群聊里裸 /model 不再直接触发；推荐使用 椰子 /model 这类“唤醒词 + 指令”形式。
• 默认 enableDynamicModelCatalog=false，本地 /model 不主动探测 provider /models 全量目录，保持更保守的默认行为。
• reply / forward 上下文解析已补强，QQ 引用消息与合并转发中的文本线索可继续注入给模型。
• QQ 插件现统一走 OneBot WebSocket，插件侧 HTTP + webhook 传输模式已移除。
• 新增入站图片/文件/语音本地缓存链路，reply / forward 里的媒体也会尽量注入 MediaPaths / MediaUrls。
• 新增 cacheInboundImagesToLocal，默认把当前消息及引用链里的图片缓存到本地，便于 ACP 与多模态 agent 读图。
• 仓库文档现统一维护中文版本，仓库内英文 Markdown 已清理。
• QQ 私聊 session key 已回归官方命名风格：peer id 使用纯 QQ 号，不再写成 qq:user:<id>；旧本机会话会在启动时自动规范化。
• 新增 keywordOnlyTrigger：群聊可切换为“仅关键词触发”，忽略 @ / 回复触发，适合与其他机器人共用同一 QQ 账号。
• 新增 showReplySessionSource：回复前可标注来源会话，方便区分主会话与 /临时 会话。
• 主 README 补充 /临时 会话槽说明，便于快速理解“同群分话题”的实际用法。
• 自动重试 / Fast Fail / 并发合并 / 新消息打断 / 隐藏网关元数据等高级控制现已默认关闭，按需开启即可。
• 群聊 ConversationLabel 现会优先使用真实群名，减少模型只看到群号时的歧义。
• 入站上下文现会补充 MessageSid；开启 injectGatewayMeta 时，隐藏 <qq_context> 也会透传 senderRole。
• NapCat 下“处理中”状态现优先使用原生 set_input_status；不支持时才回退到群名片后缀。
• WebUI 参数说明已补强；复杂配置说明统一下沉到 docs/advanced.md 与 docs/config-reference.md。

最近更新（2026-02）

• 修复 channel restart / health-monitor 重启循环，避免通道被误判退出后反复拉起。
• 增强 OneBot 连接状态判断：新增 isConnected() 防止同账号重复启动。
• 发送失败自动回队并触发重连，降低“日志显示已回复但 QQ 未落地”。
• 新增自动重试 + Fast Fail + Active Model Failover（接入 openclaw.json 的 fallbacks）。
• 新增并发防漏吞队列与同会话“新消息打断旧回复”。
• 新增 reply/forward 多层上下文解析与长回复自动合并转发。

这个项目的定位

很多 QQ 插件只做“基础渠道层”；openclaw_qq 的目标是：

• 默认配置可快速跑通。
• 面向生产群聊时，可逐步开启稳定性和风控能力。
• 把复杂能力做成“按需启用”，而不是强制每个人都用。

如果你只需要极简能力，请直接用最小配置；如果你需要高并发和低漏回，再启用高级选项。

功能总览

基础渠道能力

• [x] OneBot v11 WebSocket 接入（NapCat / Lagrange 等）
• [x] 私聊、群聊消息收发
• [x] QQ 频道（Guild）支持
• [x] @触发、关键词触发、白名单/黑名单控制

稳定性与容错

• [x] 连接自愈与指数退避重连
• [x] 发送失败回队
• [x] 模型自动重试（maxRetries / retryDelayMs）
• [x] Fast Fail 错误快速跳过（fastFailErrors）
• [x] Active Model Failover（主模型失败切备用）

上下文与交互增强

• [x] reply/forward 递归解析与分层上下文注入
• [x] 隐藏 QQ 网关元数据注入（injectGatewayMeta）
• [x] 入站上下文补充 MessageSid / senderRole
• [x] 同群临时会话槽（/临时 / /退出临时 / /临时列表 等）
• [x] 可选回复来源会话标记（showReplySessionSource）
• [x] 同会话并发防漏吞队列（queueDebounceMs）
• [x] 新消息打断旧回复（interruptOnNewMessage）
• [x] 长回复自动合并转发（forwardLongReplyThreshold）
• [x] NapCat 原生输入中状态优先，自动回退群名片后缀

管理与安全

• [x] 管理员权限模型（admins / adminOnlyChat）
• [x] 自动通过好友申请/群邀请（可选）
• [x] 基础风控辅助（限速、URL 规避、空回复兜底）

当前进度（推荐阅读路径）

1. 已可稳定用于日常 QQ 机器人接入与群聊运营。
2. 文档已拆分为“快速开始 / 配置参考 / 高级能力”三级结构。
3. 正持续优化多账号、复杂上下文与运维可观测性。

建议按下面顺序阅读：

1. 3 分钟快速开始
2. 配置参考（分组版）
3. 2026-04-30 原生文件 / 媒体收发更新
4. 2026-03-27 媒体链路与传输模式更新
5. 2026-03-20 默认行为调整
6. 高级能力与完整参数
7. NapCat 部署说明（GitHub）

/临时 会话槽是什么

/临时 是 openclaw_qq 里已经落地的会话隔离工作流，主要解决“同一个 QQ 群里同时跑多个话题，但又不想把主会话上下文搅乱”这个问题。

• 同一群内可维护一个主会话和多个命名临时会话槽，底层会写入独立 session key（形如 ::tmp:<名称>）。
• 群管理员可用 /临时 <名称> 进入或创建一个临时会话，把后续消息写进这个槽，不占用主会话上下文。
• 临时会话支持 /临时状态、/临时列表、/临时重命名、/退出临时、/临时结束，适合把“查日志、修配置、写方案”这类任务拆开管理。
• showReplySessionSource=true 时，回复前会自动加 (from 会话xxx) 或 (from 主会话)，这样即使群里同时有多个临时任务，也能快速看出当前回复属于哪个槽。
• 当前实现重点是“上下文隔离 + 来源标记”。也就是说，完整结果仍然会发回原 QQ 群消息面；如果你想看更完整的命令列表和边界说明，见 docs/advanced.md。

3 分钟快速开始

1. 前置条件

• 已安装并运行 OpenClaw
• 已运行 OneBot v11 服务端（推荐 NapCat / Lagrange）
• OneBot 配置中 message_post_format = array

2. 安装

cd openclaw/extensions
git clone https://github.com/constansino/openclaw_qq.git qq
cd ../..
pnpm install && pnpm build

3. 优先使用 WebUI 配置（推荐）

在 OpenClaw WebUI 中直接配置 channels.qq，比手写 JSON 更直观，也更不容易出现格式错误。

建议先填以下核心项：

• wsUrl
• accessToken
• requireMention
• admins（可选）
• allowedGroups（可选）

4. 手动 JSON 配置（可选）

编辑 ~/.openclaw/openclaw.json：

{
  "channels": {
    "qq": {
      "wsUrl": "ws://127.0.0.1:3001",
      "accessToken": "your_token",
      "requireMention": true
    }
  },
  "plugins": {
    "entries": {
      "qq": { "enabled": true }
    }
  }
}

5. 启动与验证

openclaw gateway restart

验证：

• 私聊机器人可回复
• 群聊 @ 机器人可回复
• 日志无持续鉴权失败/重连风暴

文档

• 文档中心：docs/index.md
• 中文主文档：本 README.md

反馈与贡献

• 问题反馈 / 使用经验 / 需求建议：
• https://aiya.de5.net/c/25-category/25
• 代码问题可直接提 GitHub Issue / PR。

License

MIT