Bug Report: Media messages bypass inbound debounce, causing image loss on WeCom channel

Environment

• OpenClaw Version: 2026.3.28 (f9b1079)
• Channel: WeCom (企业微信) via @wecom/[email protected]
• Connection Mode: WebSocket
• Model: dashscope-coding/qwen3.6-plus

Summary

When a user sends multiple images at once via the WeCom channel, some images are lost and never reach the agent. Sending 14 images results in receiving only 11. This is a systemic issue with how messages.inbound.debounceMs handles media messages.

Root Cause

Per the official documentation (Configuration Reference):

Inbound debounce: "Batches rapid text-only messages from the same sender into a single agent turn. Media/attachments flush immediately."

This means:

• Text messages are correctly batched by debounceMs
• Image messages bypass debounce entirely — each image triggers an immediate agent run
• When 14 images arrive via WebSocket within ~1-2 seconds, the first image triggers processing before the remaining images have been fully received/delivered

Reproduction

1. Send 14 images simultaneously in a WeCom DM to the bot
2. Observe: only 11 images are received (3 lost)
3. The lost images are not recoverable — they don't appear in the conversation history or queue

Test Results

Attempted Workarounds (All Failed)

1. messages.inbound.debounceMs

{
  messages: {
    inbound: {
      debounceMs: 10000,
      byChannel: { wecom: 10000 }
    }
  }
}

Result: No effect. Documented behavior — media flushes immediately regardless of debounce setting.

2. messages.queue collect mode

{
  messages: {
    queue: {
      mode: "collect",
      debounceMs: 10000,
      cap: 50,
      drop: "summarize"
    }
  }
}

Result: Partial improvement. Images arriving after an agent run has started get queued, but the first batch (images arriving before the agent run starts) each triggers its own separate agent run. This results in the agent replying to images 1, 2, 3 individually, then batch-processing the remaining 11.

3. Comparing with DingTalk channel

The DingTalk connector (@dingtalk-real-ai/dingtalk-connector) handles multi-image messages better because DingTalk packs multiple images into a single richText message, which is processed as one unit. WeCom sends each image as a separate WebSocket message event, making the problem inherent to the channel architecture.

Expected Behavior

All images sent in a batch should be collected into a single agent turn, similar to how inbound.debounceMs works for text messages. Users should not lose images when sending multiple images at once.

Proposed Fix

Add a mediaCollectWindow (or mediaDebounceMs) option that applies to media messages:

{
  messages: {
    inbound: {
      debounceMs: 2000,
      mediaCollectWindow: 5000  // NEW: wait N ms for media before processing
    }
  }
}

Or alternatively, make inbound.debounceMs apply to media messages by default (with the current "flush immediately" behavior opt-in).

Impact

This affects any use case involving batch image uploads via WeCom:

• Mahjong score tracking (users send 10+ game result screenshots)
• Receipt/invoice batch processing
• Product catalog submissions
• Any multi-image workflow

Workaround for Users

• Send images in smaller batches (5-6 at a time)
• Send as a zip/compressed file instead
• Switch to DingTalk channel (which packs images into a single richText message)

Files Investigated

• ~/.openclaw/extensions/wecom-openclaw-plugin/dist/index.esm.js (WeCom plugin)
  • parseMessageContent() — each image is a separate body.image event
  • processWeComMessage() — called per-image, no batch collection
  • wsClient.on("message") — each WebSocket frame triggers immediate processing
• /usr/lib/node_modules/openclaw/docs/gateway/configuration-reference.md (line ~1703)
• /usr/lib/node_modules/openclaw/docs/concepts/messages.md (line ~64)