openclaw - 💡(How to fix) Fix Inbound message queue during agent reload (prevent message loss)

Problem

When openclaw.json is modified (e.g. adding a provider), the gateway performs a session reset/reload for all topic agents. During this reload window, inbound Telegram messages are silently dropped — they arrive at the gateway but no agent is available to process them since the session is being reset.

Evidence from production

• Session reset file: sessions/*.jsonl.reset.2026-05-17T07-35-46.420Z
• New session file starts at 07:35:52, while user messages at 07:29, 07:31, 07:32 never reached any agent.
• Liveness warnings during the window show the agent queue was empty/resetting.

Proposed solution

Maintain a transient inbound message queue per agent/channel. When the target agent session is in reset/reload state, buffer messages instead of discarding them. Drain the queue FIFO once reload completes.

Key behaviors

1. Enqueue on unavailable agent: queue message with timestamp when session is resetting
2. Drain on ready: process queued messages after session load completes
3. TTL/expiry: drop messages older than N seconds (configurable)
4. Limit: configurable queue depth per session

Configuration suggestion

{
  "channels": {
    "telegram": {
      "inbox": {
        "queueOnReset": true,
        "maxQueueDepth": 50,
        "queueTTLSeconds": 60
      }
    }
  }
}

Current workaround

• messages.queue.mode: collect with cap: 50 helps serialize responses but does NOT prevent message loss during reload.
• Custom watchdog script polls sessions.json.telegram-messages.json and re-enqueues orphans.

But this should be handled natively in the gateway.

Impact

• Medium: silent message loss under specific conditions (config change + concurrent messaging)
• Reproducible: edit openclaw.json while talking to a topic agent in a Telegram group