qq — constansino/openclaw_qq plugin

<!-- ╔══════════════════════════════════════════════════════════════════════╗ ║ DreamSeed 种梦计划 — AI创造者大赛官方 README 模板 ║ ║ ║ ║ 使用说明： ║ ║ 1. 将本模板放在参赛仓库根目录 README.md 的顶部 ║ ║ 2. 头图使用 DreamField 官方公开活动图片地址 ║ ║ 3. 请保留 DREAMFIELD_README_HEADER_START / END 标识 ║ ║ 4. 分割线以下供创作者自由编写项目内容 ║ ╚══════════════════════════════════════════════════════════════════════╝

-->

<h1 align="center">OpenClaw QQ 插件（OneBot v11）</h1>

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

[<a href="https://constansino.github.io/openclaw_qq/">在线文档</a>] [<a href="./docs/quickstart.md">3 分钟快速开始</a>] [<a href="./docs/config-reference.md">配置参考</a>] [<a href="https://github.com/constansino/openclaw_qq/blob/main/deploy/napcat/README.md">NapCat 部署</a>] [<a href="./docs/advanced.md">高级能力</a>]

> [!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 更直观，也更不容易出现格式错误。

!OpenClaw WebUI 配置示例

建议先填以下核心项：

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

qq

Summary

Install to Claude Code

最近更新（2026-04）

最近更新（2026-03）

最近更新（2026-02）

这个项目的定位

功能总览

基础渠道能力

稳定性与容错

上下文与交互增强

管理与安全

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

`/临时` 会话槽是什么

3 分钟快速开始

1. 前置条件

2. 安装

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

4. 手动 JSON 配置（可选）

5. 启动与验证

文档

反馈与贡献

License

Related plugins

qq

Summary

Install to Claude Code

最近更新（2026-04）

最近更新（2026-03）

最近更新（2026-02）

这个项目的定位

功能总览

基础渠道能力

稳定性与容错

上下文与交互增强

管理与安全

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

/临时 会话槽是什么

3 分钟快速开始

1. 前置条件

2. 安装

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

4. 手动 JSON 配置（可选）

5. 启动与验证

文档

反馈与贡献

License

Related plugins

`/临时` 会话槽是什么