#8390: feat: notify user when fallback model is used (#8182)
size: M
experienced-contributor
Cluster:
Model Fallbacks and Rate Limiting
Fixes #8182
When the primary model fails and OpenClaw silently falls over to a fallback, users have no idea they're talking to a different model.
**Changes:**
- New `fallback-notify.ts` module with per-session dedup
- Exported `FallbackAttempt` type from `model-fallback.ts`
- Threaded `fallbackAttempts` through `AgentRunLoopResult`
- Notification prepended to `finalPayloads` in agent-runner when a fallback is used
- Example output: `⚡ Using fallback model \`anthropic/claude-haiku-3-5\` — primary \`openai/gpt-4.1-mini\` is unavailable (rate_limit)`
**Dedup behavior:**
- Notifies once per failover event per session
- Clears tracker when primary model recovers
- Re-notifies if a different fallback model is selected
9 unit tests covering all scenarios.
<!-- greptile_comment -->
<h2>Greptile Overview</h2>
<h3>Greptile Summary</h3>
This PR threads model-fallback attempt metadata through the agent run loop and prepends a user-visible notice when a fallback model is selected instead of the configured primary. It introduces a new `fallback-notify.ts` helper with per-session deduplication behavior, exports `FallbackAttempt` from `src/agents/model-fallback.ts`, and adds unit tests covering the notification/dedup scenarios.
Overall this fits cleanly into the existing `runWithModelFallback` → `runAgentTurnWithFallback` → `runReplyAgent` flow: `model-fallback` produces `attempts`, the execution layer returns them in `AgentRunLoopResult`, and `agent-runner` decides whether to emit an extra payload based on that context.
<h3>Confidence Score: 4/5</h3>
- This PR is largely safe to merge; changes are localized and covered by tests.
- The notification logic is straightforward and threaded through existing result plumbing with minimal behavioral impact outside of adding a new user-facing message. Main concern is the module-level dedup Map potentially retaining session keys indefinitely in long-running processes.
- src/auto-reply/reply/fallback-notify.ts
<!-- greptile_other_comments_section -->
<!-- /greptile_comment -->
Most Similar PRs
#23738: feat(fallback): first-class transition visibility + low-noise autom...
by SmithLabsLLC · 2026-02-22
86.0%
#13658: fix: silent model failover with fallback notification
by taw0002 · 2026-02-10
85.8%
#23318: feat(agents): emit model:fallback hook event for fallback visibilit...
by anillBhoi · 2026-02-22
84.1%
#19252: fix(agents): continue model fallback on failover text payloads
by mahsumaktas · 2026-02-17
82.5%
#13191: pi-embedded: enable failover when per-agent fallbacks are configured
by zesty-clawd · 2026-02-10
81.9%
#11349: fix(agents): do not filter fallback models by models allowlist
by liuxiaopai-ai · 2026-02-07
81.4%
#21963: fix(cli): models fallbacks add now includes primary model in allowlist
by ashiabbott · 2026-02-20
81.1%
#22064: fix(failover): bypass models allowlist for configured fallback models
by winston-bepresent · 2026-02-20
80.5%
#20275: fix(cli): include primary model in allowlist when adding fallbacks
by MFS-code · 2026-02-18
80.4%
#23816: fix(agents): model fallback skipped during session overrides and pr...
by ramezgaberiel · 2026-02-22
80.0%