openclaw - 💡(How to fix) Fix Embedded agent retry on 429 rate limit does not follow fallback chain

Bug type

Behavior bug (incorrect output/state without crash)

Beta release blocker

No

Summary

When the embedded agent receives a 429 (Too Many Requests) rate limit from a model provider, it retries the same rate-limited model instead of falling back to the next model in the configured fallback chain.

Steps to reproduce

1. Configure agents.defaults.model.fallbacks with multiple models:

   • primary: google-gemini/gemini-2.5-flash
   • fallbacks: [google-gemini-2/gemini-2.5-flash, custom-ai-sumopod-com/qwen3.6-plus]

2. Send enough requests to hit Google Gemini FREE tier rate limit (15 RPM).

3. Observe that subsequent requests receive 429 Too Many Requests.

4. The embedded agent retries on the same rate-limited model (google-gemini/gemini-2.5-flash) repeatedly instead of attempting the next fallback model.

Expected behavior

When a 429 rate limit is received, the agent should recognize it as a provider-level rate limit and automatically proceed to the next model in the configured fallbacks chain, consistent with how OpenClaw handles other non-recoverable errors.

Actual behavior

The agent retries the same rate-limited model until all retry attempts are exhausted. Session becomes stuck and unresponsive despite valid fallback models being configured. Manual config edit and gateway restart were required to restore functionality. Confirmed by config-audit.jsonl showing correct fallback chain configuration on 2026-05-24.

OpenClaw version

2026.5.18

Operating system

Linux 6.6.117-45.1.oc9.x86_64 (OpenCloudOS, x64)

Install method

npm install (Node.js v22.22.1)

Model

google-gemini/gemini-2.5-flash

Provider / routing chain

Embedded agent → google-gemini provider → Gemini 2.5 Flash (FREE tier, 15 RPM limit) → Fallback chain: google-gemini-2/gemini-2.5-flash → custom-ai-sumopod-com/qwen3.6-plus

Additional provider/model setup details

• Gateway mode: local
• Config path: /root/.openclaw/openclaw.json
• Telegram surface (direct chat)
• Fallback chain was correctly configured via config.set command, confirmed by config-audit.jsonl entries at 2026-05-24T00:24:57Z and 2026-05-24T00:30:00Z
• Session became stuck during Gemini rate limit window without attempting any fallback

Logs, screenshots, and evidence

config-audit.jsonl confirms fallback chain was correctly set and written:
- 2026-05-24T00:24:57Z: fallbacks = [qwen3.6-plus, gemini-flash, gemini-flash-2]
- 2026-05-24T00:30:00Z: fallbacks = [gemini-flash, gemini-flash-2, qwen3.6-plus]

Despite correct configuration, 429 retries did not traverse the fallback chain. Session file became corrupted and required manual deletion.

Impact and severity

• Affected users: Any user with fallback chains using rate-limited providers (e.g. Gemini FREE tier 15 RPM)
• Severity: Blocks workflow — session becomes unresponsive, requires manual intervention (config edit + gateway restart)
• Frequency: Always — reproducible by hitting the rate limit on the primary provider
• Consequence: Missed messages, failed automation (cron jobs), potential extra cost from failed retries

Additional information

Workaround: Remove duplicate/rate-limited models from config and restart gateway. This is not sustainable.

Reporter: Wahyu Maulana Ishaq (@wmaulanaaishq) Affiliation: Student, Universitas Alma Ata, Yogyakarta, Indonesia