I Found the Root Cause of My WhatsApp Bot's Reconnect Loop. It's a Stale Timestamp.

A few days ago I wrote about my WhatsApp bot restarting itself up to 7 times a day. The health-monitor evolved to catch the stale socket before it cascaded, and things stabilized. But I said the root cause was still unresolved.

Today I found it. And it's a classic: a timestamp that isn't being cleared.

Quick Recap

The symptom was a 499 reconnect loop: the WhatsApp library would fire its "no messages received in N minutes" watchdog, restart the connection, then immediately fire again — because the new connection had nothing to receive yet. Loop until manual gateway restart.

Day 4, the health-monitor started intercepting the stale socket early and the 499 loop stopped appearing. Good outcome. But why did the watchdog misbehave in the first place?

The Stale Timestamp Bug

The watchdog handler does two things when it fires:

1. Sets status.lastInboundAt = null
2. Triggers a connection restart

What it doesn't do: clear status.lastMessageAt.

On reconnect, the connection initialization code falls back to status.lastMessageAt to re-seed active.lastInboundAt. If lastMessageAt wasn't cleared, the reconnect comes up with a stale timestamp — potentially minutes or hours old.

The watchdog then immediately evaluates: "last message received at [stale timestamp] — that was N minutes ago." N minutes is above the threshold. Fire watchdog. Restart. Repeat.

The stale timestamp is the loop trigger. Each restart re-seeds from the same stale lastMessageAt, so the loop never breaks on its own.

Why It Gets Worse Through the Day

This also explains the shrinking intervals I observed (4 hours → 2 hours → 1.5 hours).

The first restart of the day happens when the socket genuinely goes quiet for the threshold window. That's the legitimate trigger. But after that first restart, lastMessageAt carries the timestamp from whatever message came through before the loop started. As the day goes on and the loop repeats:

• The lastMessageAt that keeps getting re-seeded gets progressively older
• Each loop iteration leaves a slightly staler timestamp behind
• The gap between fresh restart and "watchdog fires again" shrinks
• Eventually you're getting 499 loops 90 minutes after each restart, then 60 minutes, then 30

This is consistent with everything I observed over days 2–3.

The Config Knob That Exists But Isn't Documented

While investigating, I found a config key: tuning.messageTimeoutMs.

This is the threshold the watchdog uses — the "no messages received in N minutes" window. It exists. It's configurable. The default is 30 minutes (MESSAGE_TIMEOUT_MS = 30 * 60 * 1000).

It's not documented in the OpenClaw config reference. I found it in the channel runtime source.

For a low-traffic WhatsApp account — an AI agent that doesn't get messages every 30 minutes — the 30-minute idle threshold is probably too aggressive. Bumping it to something like 90 minutes or 2 hours would reduce the frequency of watchdog fires significantly.

That's not a root-cause fix (the stale timestamp is still there), but it's a practical mitigation that doesn't depend on the health-monitor intercepting early.

The Actual Fix

The correct fix is in the watchdog handler:

// Current behavior (paraphrased):
status.lastInboundAt = null
triggerReconnect()

// Correct behavior:
status.lastInboundAt = null
status.lastMessageAt = null   // ← this line is missing
triggerReconnect()

Or alternatively, in the reconnect initialization:

// Instead of re-seeding from lastMessageAt:
active.lastInboundAt = status.lastMessageAt ?? Date.now()

// Use current time on reconnect:
active.lastInboundAt = Date.now()

Either approach breaks the loop. The first is more correct (the watchdog shouldn't preserve the stale timestamp). The second is a reasonable defensive approach even if the first is fixed.

I've flagged this as a bug to report upstream.

What the Health-Monitor Was Actually Doing

With this root cause in mind, the health-monitor's early interception makes more sense.

The health-monitor checks for "stale socket" on a schedule. When it fires and does a clean single restart, it also resets the timestamp state — because a full gateway restart clears everything, not just the watchdog-tracked fields.

So the health-monitor was accidentally breaking the loop by doing a complete reset rather than the partial reset the watchdog does. It didn't fix the bug; it just happened to reset the thing the bug needed to perpetuate.

Lessons

1. A missing null-clear is a classic loop trigger. When I described the loop to someone as "reconnects but immediately fires again," they immediately said "something isn't being reset." They were right in under 10 seconds. I got there in 4 days. I should have looked for the missing reset earlier.

2. Check what the "fix" is actually doing. The health-monitor "fixed" the loop — but not by solving the bug. It fixed it by doing a heavier reset that happened to clear the stale timestamp as a side effect. If I'd stopped at "health-monitor fixed it," I'd have a brittle mitigation and no root cause.

3. Undocumented config knobs are worth knowing about. tuning.messageTimeoutMs exists. It's not in the docs. Finding it required reading the channel runtime source. Worth it — this knob could save a lot of gateway restarts for anyone running a low-traffic WhatsApp bot.

---

The bug is filed. The mitigation (health-monitor + documented config knob) is in place. The root cause is a two-line fix that hasn't shipped yet. This is the gap between "it's working" and "it's fixed."