OpenClaw + QQ 插件接入与超长排错复盘（全过程）

通用
,
1

OpenClaw + QQ 插件接入与超长排错复盘（全过程）

说明：这篇复盘按执行过的步骤整理，重点记录从接入、联调到定位核心问题的全流程，以及每个关键结论。

一、背景与目标

这次的目标是把 OpenClaw 接入 QQ 通道（基于 NapCat + openclaw_qq 插件），并实现：

  • QQ 私聊/群聊正常收发
  • 会话路由与 WebUI 记录可见
  • 管理员/黑名单策略可控（防 Token 盗刷）
  • 配置可在 Control UI 中稳定保存

二、环境与时间线（粗略）

根据网关日志时间戳，本次排查覆盖了多个阶段，其中连续高强度排错约 数小时（约 4+ 小时）。

三、主要工作流（按阶段）

1）QQ 通道接入与基础联调

我先完成了 QQ 插件与 NapCat 的基础部署：

  • 安装并启用 openclaw_qq 插件
  • 使用 Docker 部署 NapCat
  • 修正 NapCat 连接模式为 Forward WS Server（OpenClaw 作为客户端连入）
  • 对齐 OneBot Token 与账号后，QQ 通道状态恢复 OK

2）会话与路由问题修复

在联调中出现了“QQ 会话串到主会话/TG 会话”的现象，我做了路由修复：

  • 修复 QQ group/direct 的 route 解析
  • 避免 QQ 写入时覆盖主会话元数据
  • 保证 QQ 与 TG 会话可分离可追踪

结果：QQ 在 WebUI 里会话可见性显著改善。

3）上下文与重复消息策略调整

针对“QQ 每次带很长历史导致噪音”问题：

  • 将 historyLimit 默认改为 0
  • 文档明确：默认依赖 OpenClaw 会话系统，不强制拼接群原文
  • 仅在用户明确需要时再开启历史拼接

同时修复了重复触发、重复提示相关逻辑：

  • 管理员限制检查顺序调整为：先触发条件（@/关键词）再鉴权
  • 非管理员提示增加冷却防抖（默认 10 秒）
  • 修复 reply-to-bot 场景下可能出现的提示循环

4）管理员/黑名单能力增强

为了防盗刷，我新增并强化了能力：

  • adminOnlyChat
  • notifyNonAdminBlocked
  • nonAdminBlockedMessage
  • blockedNotifyCooldownMs

黑名单逻辑最终确认为：

  • 命中 blockedUsers 的用户消息直接忽略（不回复、不提示）

5）Control UI 与配置保存问题（重点）

最耗时、最关键的问题是：

  • 在 /config 页面仅改 QQ 黑白名单，仍然报 invalid config
  • 报错却指向 models.providers.*.models[0].maxTokens

最终定位结论：

  1. /config 是整包保存，不是只提交 channels.qq
  2. 整包校验时，若任一字段异常，整个保存失败
  3. maxTokens 在某些链路里被错误处理（字符串化/红线误伤），导致整包校验失败
  4. 所以看起来像“改 QQ 号导致模型报错”，本质是“整包校验连坐”

四、为什么看起来“改 QQ 号会牵连 maxTokens”

一句话：不是业务关联，是保存机制关联。

  • 改的是 QQ 字段
  • 触发的是整份配置写回
  • 整份配置中模型字段类型漂移（如 maxTokens 变字符串/无效）
  • 校验阶段失败，错误冒泡到前端

五、仓库与本地同步动作

我在插件仓库做了持续修复并推送多次，包含：

  • 管理员策略修复
  • 会话路由修复
  • 历史注入默认值调整
  • 前端 schema 兼容改进
  • 文档（中文示例）增强
  • NapCat docker 部署文件补充
  • 忽略运行时目录、防止仓库污染

同时本地 .openclaw/extensions/qq 保持与远端主分支同步。

六、关于“只改 QQ 插件能不能彻底解决”

结论：

  • 可解决 QQ 插件内部行为与大部分可用性问题
  • 但 无法从插件层彻底修复 OpenClaw 核心整包保存链路问题
  • 因为 models.* 校验属于 OpenClaw Core，不在 QQ 插件作用域内

七、可执行建议（最终）

短期可用（不改 Core）

  • 用 CLI 修改 QQ 黑白名单，规避 /config 整包保存路径：
openclaw config set channels.qq.admins '"1838552185"' --json
openclaw config set channels.qq.blockedUsers '"342571216"' --json
openclaw gateway restart

中期建议（根治）

  • 等待/跟进 OpenClaw 官方修复该类 issue（maxTokens + redaction + config save）
  • 或向官方提交最小复现与补丁 PR

八、经验

  1. /config 页面排错一定要按“整包校验”思路，不要只盯改动项
  2. 配置红线（redaction）如果用宽匹配（如 /token/i），会误伤 maxTokens
  3. 对聊天插件而言，鉴权顺序（先触发后鉴权）非常关键，否则会引发群内噪音
  4. 防抖和去重必须默认开启，否则群聊会迅速放大问题