Release Notes - v0.8.21

GA 正式版 — 晋升自 0.8.21-beta.0，经社区验证稳定后发布。
General Availability — Promoted from 0.8.21-beta.0 after community validation.

🎉 本次重点 / Highlights

本版本聚焦 WebSocket 连接稳定性 + 群聊体验，与 0.8.21-beta.0 功能完全一致：

修掉本仓 listener 注册时机错乱导致的 ~30s 一次幽灵重连（社区贡献 #566）
修掉消息处理保活 interval 与 TIMEOUT_THRESHOLD 不匹配的兜底失效（#594）
过滤上游 dingtalk-stream@2.1.4 SDK 直接走 console.info 的噪音（#571 / #536 / #573）
群聊 @ 机器人空回复时，把无信息的「任务执行完成」改为带 openclaw.json 修复指引的可操作文案（#589）

This release focuses on WebSocket stability + group-chat UX. Functionally identical to 0.8.21-beta.0:

Fix root cause of ~30s phantom reconnect cycle caused by listener-registration timing (community contribution, #566)
Fix message-processing keepalive interval mismatch with TIMEOUT_THRESHOLD (#594)
Filter noisy console.info calls from upstream dingtalk-stream@2.1.4 (#571 / #536 / #573)
Group @ mention's empty-reply fallback now embeds an actionable openclaw.json fix hint (#589)

🐛 修复 / Fixes

WebSocket phantom reconnect 根因修复 (#566)

现象：约每 30 秒一次的 WebSocket 重连，Disconnecting. / connect success 成对出现，看起来像连接频繁掉线。

根因：setupPongListener / setupMessageListener / setupCloseListener 在 client.connect() 之前被调用，此时 client.socket === undefined，函数体里 client.socket?.on(...) 的可选链让调用静默成 no-op——三个 listener 实际从未挂上。

pong listener 缺失 → lastSocketAvailableTime 不刷新 → 命中 TIMEOUT_THRESHOLD = 20s → doReconnect() 触发
message listener 缺失 → 服务端真实下发的 disconnect topic 也无法响应
close listener 缺失 → socket close 不能立即触发重连

修复：

删除模块初始化时的 no-op setup 调用
初次 client.connect() 成功后立即注册三个 listener
doReconnect() 里把 setup 挪到 client.connect() 之后、await for OPEN 之前——避免 keepAlive 期间 ping 的 pong 回来时 listener 还没挂被丢的 race window

致谢：感谢 @Majorshi 提交 PR #566，并感谢 @lizhiyao / @edokeh / @jeikl 验证修复有效。

消息处理保活 interval 兜底 bug (#594)

根因：markMessageProcessingStart 启动的兜底定时器原本 30s 间隔，但 TIMEOUT_THRESHOLD 已在 d90916b 中从 90s 降到 20s——30s 间隔无法在 AI 长任务期间防住超时（AI 任务跑到约 21s 就可能触发 keepAlive 幽灵重连，下次刷新还要等 9 秒）。

修复：interval 调整为 15s（< TIMEOUT_THRESHOLD = 20s），让保活真正生效。同时清理文件头 docstring 与相关注释里的 stale 90 秒超时 文案。

上游 SDK `console.info` 噪音过滤 (#571 / #536 / #573)

现象：日志反复出现 Disconnecting. / [time] connect success 成对刷屏。

修复：

在 src/core/connection.ts 新增 silenceDingtalkStreamConsoleNoise()：模块级一次性 patch console.info，只过滤这两条精确字符串，其他 console.info 不受影响
在首个账号连上时通过 printConnectionNoticeOnce() 打印一次连接生命周期说明，解释过滤动机以及「高频重连不正常」的预期，多 bot 启动时不重复
setupMessageListener 收到 disconnect topic 时加一行 logger.debug，便于排查时查看完整生命周期

🩹 改进 / Improvements

群聊空回复兜底文案带修复指引 (#589)

现象：群聊 @ 机器人时只看到「✅ 任务执行完成（无文本输出）」，没有任何模型回复内容。

根因：当 OpenClaw messages.groupChat.visibleReplies 未设为 "automatic" 时，上游 source-reply-delivery-mode.ts 对群聊默认走 message_tool_only：

不调 onPartialReply → connector accumulatedText 始终为空
大多数情况下也不调 deliver(final) → 三处空 final 兜底全部打到原文案

修复：

新增 src/utils/empty-reply.ts 集中兜底文案
reply-dispatcher.ts 的 closeStreaming / deliver 空 final 分支：群聊改用带 openclaw.json 修复指引的可操作文案
新增 maybeSendGroupVisibleRepliesIdleNudge：在 onIdle / onError 时若本轮无任何用户可见输出（覆盖上游 message_tool_only 根本不调 deliver() 的盲区），主动 nudge 一条配置指引
core/message-handler.ts 异步模式同点位分流
warn 日志同步打印完整 openclaw.json 修复片段
单聊文案保持不变

新群聊兜底文案

ℹ️ 暂未收到模型回复内容。
若群聊频繁出现该提示，请联系机器人管理员检查 OpenClaw 配置：
`messages.groupChat.visibleReplies` 需设为 `"automatic"`
（详见 README / TROUBLESHOOTING.md）。

用户/运维侧修复

~/.openclaw/openclaw.json 加上：

{
  "messages": {
    "groupChat": { "visibleReplies": "automatic" }
  }
}

然后 openclaw gateway restart。

跟进调研：插件侧直接覆盖 sourceReplyDeliveryMode: "automatic" 让用户不需要改 openclaw.json 的方案在 Issue #591 跟踪。

📚 文档 / Docs

TROUBLESHOOTING.md：新增「群聊 @ 机器人只返回『任务执行完成（无文本输出）』」条目
silenceDingtalkStreamConsoleNoise 周边的注释 / 函数命名 / banner 文案统一收紧（#592）
清理 src/core/connection.ts 中的 stale 90 秒超时 文档残留（#594）

🔒 兼容性 / Compatibility

API 无变化、配置 schema 无变化、导出符号无变化
不影响 #437 的心跳超时检测修复语义
单聊行为完全不变（兜底文案、流式行为都保持原样）
已配置 messages.groupChat.visibleReplies = "automatic" 的群聊行为完全不变

🧪 验证 / Verification

已验证组合 / Verified combo：

OpenClaw Gateway 2026.5.7
Connector 0.8.21-beta.0 (已晋升为 0.8.21)
平台 macOS（darwin 23.2.0）

验证场景：

单 bot 30s 周期重连已消失
群聊 @ + messages: {} → 看到新的可操作指引
群聊 @ + visibleReplies = "automatic" → 恢复正常流式
单聊空 final → 文案不变

社区验证：beta.0（2026-05-17 发布）经过约 2 天社区使用，相关 issue（#571 / #536 / #573 / #545）均确认修复有效。

📥 安装升级 / Installation & Upgrade

npx openclaw@latest add @dingtalk-real-ai/dingtalk-connector@0.8.21

或：

npm install @dingtalk-real-ai/dingtalk-connector@latest

⏭ 下一步 / Next steps

Issue #591：插件侧 sourceReplyDeliveryMode 调研（让用户不再需要改 openclaw.json）
PR #566 review 中 P2 跟进：抽 attachSocketListeners() 单一入口 + listener 注册时机回归测试

🔗 相关链接 / Related Links

完整变更日志 / Full Changelog
Beta release notes (v0.8.21-beta.0)
关联 PRs / issues：#566 / #589 / #592 / #594 / #571 / #536 / #573 / #545

发布日期 / Release Date：2026-05-19
版本号 / Version：v0.8.21
兼容性 / Compatibility：OpenClaw Gateway 2026.4.9+

DingTalk-Real-AI/dingtalk-openclaw-connector v0.8.21 v0.8.21 — WebSocket stability + group-chat UX on GitHub