openclaw - 💡(How to fix) Fix Gateway should refresh auth epoch immediately after credential rotation

Summary

When credentials rotate on a host running OpenClaw Gateway, the gateway can keep stale in-memory auth state until its next heartbeat/auth-epoch refresh. If a user message arrives in that window, the request can fail with a generic "Something went wrong while processing... use /new" instead of refreshing credentials before handling the message.

Observed case

Host: Mac Mini running OpenClaw Gateway.

Timeline observed 2026-05-02 EDT:

• User re-logged into Claude Max via SSH, rewriting ~/.claude/.credentials.json around 12:31:15.
• User message arrived around 12:34, inside the stale-cache window.
• Request failed with generic processing error.
• Gateway self-corrected at 12:39:59 via auth-epoch/session reset on heartbeat.

The delay was about 3 minutes from credential rewrite to failed message, and about 9 minutes until self-correction.

Expected behavior

Credential rotation should not surface as a generic user-visible failure. Gateway should detect credential file freshness before processing inbound user messages, refresh/reset auth state if needed, and continue or return a specific "credentials rotated, reconnecting" style message.

Suggested fixes

1. Watch relevant credential files, e.g. fs.watch/mtime check on ~/.claude/.credentials.json, and bump auth epoch immediately when credentials change.
2. On every inbound user message, perform a cheap freshness check: compare current credential file mtime/hash with the in-memory credential epoch/hash. If mismatched, reset/reload before dispatching the request.
3. Improve fallback UX: replace generic "Something went wrong, use /new" with a credential-rotation-specific retry/reconnect message where detectable.

Notes

• Two-machines-same-account/session-conflict was ruled out in the original investigation: no observed claim/session-conflict/409 pattern.
• This card was tracked locally as Saga PT #44103523628429312 and is being filed upstream for visibility.