openclaw - 💡(How to fix) Fix [Matrix Plugin] Messages replayed as new after gateway restart — dedupe state not persisted across restarts [3 comments, 2 participants]

Bug type

Behavior bug (incorrect output/state without crash)

Summary

After a gateway restart (triggered by openclaw update from 2026.3.12 to 2026.3.28), the Matrix plugin re-processed every recent message from all joined rooms as if they were new inbound messages. The agent responded to each one again, causing:

• Duplicate responses sent to all active rooms (8+ rooms affected)
• Significant wasted tokens (Opus-tier model)
• Confused conversation context (duplicate Q&A pairs in session history)
• User confusion from receiving re-answers to already-resolved questions

Root cause analysis

Layer 1 — Core inbound dedupe (in-memory only):

The core inboundDedupeCache in src/auto-reply/reply/inbound-dedupe.ts is a resolveGlobalDedupeCache with 20-minute TTL and max 5000 entries. This cache is purely in-memory and is cleared on process restart. resetInboundDedupe() is exported and may be called during startup.

Layer 2 — Matrix plugin persistent storage:

The Matrix plugin writes inbound-dedupe.json and bot-storage.json (containing savedSync.nextBatch) to disk under ~/.openclaw/matrix/accounts/default/<homeserver>/<tokenHash>/.

However, on restart after update, the storage was recreated fresh:

// storage-meta.json — created at restart time, not preserved from before
{
  "createdAt": "2026-03-29T19:51:06.999Z"
}

// bot-storage.json — unclean shutdown flag
{
  "cleanShutdown": false,
  "savedSync": { "nextBatch": "s852_..." }
}

A migration-snapshot.json was also created with "trigger": "gateway-startup", suggesting the update path recreated storage rather than preserving existing state.

Result: When the Matrix SDK re-synced after restart, the dedupe cache (both in-memory core and plugin persistent) was empty. All backfilled messages from the sync passed the dedupe check and were dispatched as new inbound messages.

Steps to reproduce

1. Have an active Matrix setup with multiple rooms and recent messages
2. Run openclaw update (or trigger a gateway restart via SIGUSR1)
3. Observe that the agent re-processes and re-responds to all recent messages from before the restart

Expected behavior

1. The Matrix sync token (nextBatch) and dedupe state should persist across gateway restarts
2. If storage must be recreated, the plugin should either:
   • Restore the previous sync token so only truly new messages are processed, OR
   • Mark all messages from before the restart as "already seen" during initial sync, OR
   • Apply a time-based filter (e.g., only process messages received after the restart timestamp)
3. The cleanShutdown flag should be set to true on graceful SIGUSR1 restarts (as opposed to crashes)

Environment

• OpenClaw: 2026.3.12 → 2026.3.28 (npm global install)
• Matrix plugin: @openclaw/matrix 2026.3.13 (extension under ~/.openclaw/extensions/matrix/)
• Homeserver: Synapse (self-hosted)
• OS: Ubuntu 24.04 LTS
• Restart method: gateway update.run → SIGUSR1

Relevant file layout (post-restart)

~/.openclaw/matrix/accounts/default/<homeserver>/<tokenHash>/
├── bot-storage.json          # cleanShutdown: false, has savedSync.nextBatch
├── inbound-dedupe.json       # 31 entries (all post-restart, none pre-restart)
├── storage-meta.json         # createdAt matches restart time, not original setup
├── legacy-crypto-migration.json
└── crypto/bot-sdk.json

~/.openclaw/matrix/migration-snapshot.json  # trigger: gateway-startup

Impact

High — data integrity and cost issue. Every gateway restart or update risks:

• Sending duplicate messages to all active Matrix rooms
• Burning tokens on re-processing already-handled messages
• Corrupting session context with duplicate exchanges
• Eroding user trust (receiving repeat answers is confusing)

Suggested fix

1. Persist dedupe state across restarts — restore inbound-dedupe.json entries on startup before the Matrix SDK begins its initial sync
2. Handle SIGUSR1 as graceful shutdown — set cleanShutdown: true before storage is closed so the restart path preserves storage rather than recreating it
3. Fallback safety net — if fresh sync is unavoidable, pre-populate the dedupe cache with message IDs from the backfill window, or skip processing messages with timestamps before the restart

Related issues

• #49247 — Matrix sends messages twice (similar dedupe failure, different trigger)

OpenClaw version

2026.3.28

Operating system

Ubuntu 24.04

Install method

npm global