为 OpenClaw 提供可生产使用的 QQ 渠道接入：先快速跑通，再按需启用高级能力。
[在线文档] [3 分钟快速开始] [配置参考] [NapCat 部署] [高级能力]
Important
官方交流论坛（唯一）： https://aiya.de5.net/c/25-category/25
问题反馈、配置经验、更新公告统一在论坛沉淀，便于检索和追踪。
- 新增专题说明：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。
- 修复
channel restart/health-monitor重启循环，避免通道被误判退出后反复拉起。 - 增强 OneBot 连接状态判断：新增
isConnected()防止同账号重复启动。 - 发送失败自动回队并触发重连，降低“日志显示已回复但 QQ 未落地”。
- 新增自动重试 + Fast Fail + Active Model Failover（接入
openclaw.json的fallbacks）。 - 新增并发防漏吞队列与同会话“新消息打断旧回复”。
- 新增 reply/forward 多层上下文解析与长回复自动合并转发。
很多 QQ 插件只做“基础渠道层”；openclaw_qq 的目标是：
- 默认配置可快速跑通。
- 面向生产群聊时，可逐步开启稳定性和风控能力。
- 把复杂能力做成“按需启用”，而不是强制每个人都用。
如果你只需要极简能力，请直接用最小配置；如果你需要高并发和低漏回，再启用高级选项。
- OneBot v11 WebSocket 接入（NapCat / Lagrange 等）
- 私聊、群聊消息收发
- QQ 频道（Guild）支持
- @触发、关键词触发、白名单/黑名单控制
- 连接自愈与指数退避重连
- 发送失败回队
- 模型自动重试（
maxRetries/retryDelayMs） - Fast Fail 错误快速跳过（
fastFailErrors） - Active Model Failover（主模型失败切备用）
- reply/forward 递归解析与分层上下文注入
- 隐藏 QQ 网关元数据注入（
injectGatewayMeta） - 入站上下文补充
MessageSid/senderRole - 同群临时会话槽（
/临时//退出临时//临时列表等） - 可选回复来源会话标记（
showReplySessionSource） - 同会话并发防漏吞队列（
queueDebounceMs） - 新消息打断旧回复（
interruptOnNewMessage） - 长回复自动合并转发（
forwardLongReplyThreshold） - NapCat 原生输入中状态优先，自动回退群名片后缀
- 管理员权限模型（
admins/adminOnlyChat） - 自动通过好友申请/群邀请（可选）
- 基础风控辅助（限速、URL 规避、空回复兜底）
- 已可稳定用于日常 QQ 机器人接入与群聊运营。
- 文档已拆分为“快速开始 / 配置参考 / 高级能力”三级结构。
- 正持续优化多账号、复杂上下文与运维可观测性。
建议按下面顺序阅读：
/临时 是 openclaw_qq 里已经落地的会话隔离工作流，主要解决“同一个 QQ 群里同时跑多个话题，但又不想把主会话上下文搅乱”这个问题。
- 同一群内可维护一个主会话和多个命名临时会话槽，底层会写入独立 session key（形如
::tmp:<名称>）。 - 群管理员可用
/临时 <名称>进入或创建一个临时会话，把后续消息写进这个槽，不占用主会话上下文。 - 临时会话支持
/临时状态、/临时列表、/临时重命名、/退出临时、/临时结束，适合把“查日志、修配置、写方案”这类任务拆开管理。 showReplySessionSource=true时，回复前会自动加(from 会话xxx)或(from 主会话)，这样即使群里同时有多个临时任务，也能快速看出当前回复属于哪个槽。- 当前实现重点是“上下文隔离 + 来源标记”。也就是说，完整结果仍然会发回原 QQ 群消息面；如果你想看更完整的命令列表和边界说明，见
docs/advanced.md。
- 已安装并运行 OpenClaw
- 已运行 OneBot v11 服务端（推荐 NapCat / Lagrange）
- OneBot 配置中
message_post_format = array
cd openclaw/extensions
git clone https://github.com/constansino/openclaw_qq.git qq
cd ../..
pnpm install && pnpm build在 OpenClaw WebUI 中直接配置 channels.qq，比手写 JSON 更直观，也更不容易出现格式错误。
建议先填以下核心项：
wsUrlaccessTokenrequireMentionadmins（可选）allowedGroups（可选）
编辑 ~/.openclaw/openclaw.json：
{
"channels": {
"qq": {
"wsUrl": "ws://127.0.0.1:3001",
"accessToken": "your_token",
"requireMention": true
}
},
"plugins": {
"entries": {
"qq": { "enabled": true }
}
}
}openclaw gateway restart验证：
- 私聊机器人可回复
- 群聊 @ 机器人可回复
- 日志无持续鉴权失败/重连风暴
- 文档中心：
docs/index.md - 中文主文档：本
README.md
- 问题反馈 / 使用经验 / 需求建议：
- 代码问题可直接提 GitHub Issue / PR。
MIT