Medium🔗 Connectivity#Telegram#Discord

网关重启后的消息通道故障

作者 Jason Guo发布于 2026年9月5日

这三个故障看起来互不相关，根因却是同一个：网关在启动时重新注册通道状态，却没有先清掉上一次留下的东西。它们通常在升级或崩溃重启之后一起出现，所以值得一次性排查完，而不是一个一个追。

Telegram 技能命令重复出现 _2、_3 后缀

重启网关后，Telegram 显示重复的技能命令，如 /summarize_2、/summarize_3。这是因为 Telegram Bot API 在重新注册命令时附加后缀，而不是替换现有命令。

duplicate-commands-1.sh

✅ 修复方法 1 — 重启前清除 Telegram 机器人命令

在重新注册前清除服务器端命令注册表

# 重启前清除所有 Telegram 机器人命令
openclaw telegram clear-commands --bot YOUR_BOT_TOKEN

# 或清除特定聊天范围
openclaw telegram clear-commands --bot YOUR_BOT_TOKEN --scope all_private_chats

# 然后重启网关
openclaw gateway restart

duplicate-commands-2.sh

✅ 修复方法 2 — 在配置中启用命令去重

添加到 openclaw.yaml — 防止重复后缀

channels:
  telegram:
    commands:
      deduplicate: true        # 重新注册前自动清除
      clearOnStartup: true     # 启动时移除过期命令

ℹ 为什么会发生这种情况

Telegram 的 Bot API 在服务器端保留命令注册表。当 OpenClaw 在启动时重新注册命令而不先清除现有命令时，Telegram 会附加 _2、_3 后缀以避免冲突。

心跳消息泄露到错误频道 / Discord 私信

升级到 v2026.2.24+ 后，之前只发送到配置频道的心跳消息开始出现在 Discord 私信和不相关的频道中。这是 v2026.2.24-beta 中引入的传递默认值变更。

heartbeat-dm-leak-1.sh

✅ 修复方法 1 — 明确限定心跳传递范围

将心跳传递限定到特定频道/范围

agents:
  defaults:
    heartbeat:
      deliverTo:
        - channel: discord
          scope: guild_channel  # 仅限服务器频道，不含私信
          channelId: "1234567890123456789"

heartbeat-dm-leak-2.sh

✅ 修复方法 2 — 为受影响的频道禁用心跳

临时修复：按频道禁用心跳

channels:
  discord:
    heartbeat:
      enabled: false  # 完全禁用 Discord 的心跳

ℹ v2026.2.24 中的变更

心跳传递默认值从'仅配置频道'更改为'所有活动会话'。这意味着心跳消息现在可以到达有打开会话的 DM 和群聊。修复方法：添加明确的 deliverTo 范围。

流式传输 UI 在代理轮次之间显示合并/拼接的文本

v2026.3.1 及更早版本中的已知缺陷：在多轮流式传输响应时，deltaBuffer 缺少跨轮次分隔符。这导致一个代理响应的末尾与下一个响应的开头合并。

表现形式

→代理说：'当然，以下是您的摘要：您好！我能帮您什么？'（两个响应合并）
→Markdown 渲染不正确 — 上一响应的关闭 ``` 流入下一个
→只在流式传输模式下可见 — 非流式传输正常工作

merged-streams-1.sh

✅ 修复方法 1 — 升级到 v2026.3.2（官方修复）

deltaBuffer 缺陷在 v2026.3.2 中已修复

# 升级到 v2026.3.2 或更高版本
npm install -g openclaw@latest

# 验证
openclaw --version
# 应该显示 2026.3.2 或更高

merged-streams-2.sh

✅ 修复方法 2 — 暂时禁用流式传输（解决方案）

旧版本的解决方案 — 完全禁用流式传输

# 在 openclaw.yaml 中临时禁用流式传输
agents:
  defaults:
    streaming: false

🐛 技术细节

Issue #35308：deltaBuffer 在代理轮次之间没有刷新分隔符（换行符+空值）就累积 token 块。这是在 v2026.2.25-beta.1 的流式传输重构中引入的。在 v2026.3.2 中已修复。

❓ 常见问题

Q1. 为什么 Telegram 添加后缀而不是替换？

Telegram Bot API 的 setMyCommands 不会覆盖——如果同名命令已存在则追加。在重新注册前调用 deleteMyCommands 可防止此问题。

Q2. 有永久修复方案吗？

有。v2026.3.7 起 OpenClaw 在启动时先调用 deleteMyCommands 再注册。更新到最新版本即可。

Q3. 如何清理重复命令？

在 Telegram 中使用 BotFather：/setcommands 并发送空列表，或直接使用 Bot API：POST /bot<token>/deleteMyCommands

Q4. v2026.2.24 改变了什么？

投递默认值已更改，心跳消息默认发送到所有活动频道。添加显式频道过滤器可恢复旧行为。

Q5. 可以完全禁用心跳消息吗？

可以。在 config.yaml 中设置 heartbeat.enabled: false 或将间隔设为 0。

Q6. 这会影响 Telegram 等其他频道吗？

是的。同样的投递默认值变更适用于所有频道。建议为每个心跳任务添加明确的 channel_filter。

Q7. 哪个版本修复了这个问题？

deltaBuffer 分隔符修复包含在 v2026.3.2 中。更新到 3.2 或更高版本即可解决。

Q8. 这会影响实际对话数据吗？

不会。拼接只是流式 UI 中的显示 bug。底层对话历史和记忆存储正确。

Q9. Telegram/WhatsApp 也会出现吗？

不会。此 bug 仅存在于基于 Web 的控制 UI 流式渲染器中。Telegram 和 WhatsApp 接收完整消息。

← 返回故障排除