Model Fallback Retry is an automatic API failure-recovery and queue-management utility designed for Openclaw Skills to guarantee zero message loss.
Install & Download
1. ClawHub CLI
The fastest way to install a skill directly from the registry.
npx clawhub@latest install model-fallback-retry
2. Manual Installation
Copy the skill folder to one of these locations
~/.openclaw/skills/ <project>/skills/ Priority: Workspace > Local > Bundled
3. Prompt Installation
Copy this prompt to OpenClaw to install it automatically.
Help me install model-fallback-retry using Clawhub. If Clawhub is not installed, install it first (npm i -g clawhub).
Prefer to download?
Get the raw skill files in a ZIP archive.
What is Model Fallback Retry?
The Model Fallback Retry plugin is a robust error recovery layer designed for AI agents built using Openclaw Skills. When downstream LLM APIs experience rate limiting (HTTP 429), quota exhaustion (HTTP 402), or server overloads (HTTP 503), this skill prevents agent lockups and missing responses by intercepting the failure.
By introducing a three-tier error detection pipeline (structured errors, HTTP status codes, and regex pattern matching), failed messages are systematically cached inside a persistent queue. A cron job then schedules dynamic retries with exponential backoff, ensuring your automated workflows recover gracefully without manual intervention.
Model Fallback Retry Use Cases
- Handling Rate Limits (429): Automatically queue and retry requests when AI providers throttle your throughput (TPM/RPM limits).
- Handling Quota Exhaustion (402/2056): Safely park messages and retry over longer intervals when your Token Plan caps are reached.
- Preventing Midnight Agent Lockups: Keep conversational sessions alive during server outages or high-traffic periods without manual restarts.
- Message Preservation across Channels: Safeguard communications across channels like Feishu (Lark) and WeChat by persisting state in case of network disruptions.
How Model Fallback Retry Works
- Error Interception: When an agent invocation fails, the memory-resident plugin (
index.mjs) evaluates the issue against three criteria (structured error categories, HTTP status codes, and text-based regex patterns). - Queueing: Verified failures are immediately written to
retry_queue.jsonin apendingstate, containing the original session context, prompt, and error details. - Cron Evaluation: A configurable cron task runs periodically to check for eligible pending messages in
retry_queue.jsonthat have completed their wait interval. - Exponential Backoff: Each successive retry doubles the wait time (e.g., 30 mins, then 60, then 120, up to a maximum of 5 attempts) to prevent overwhelming the upstream API.
- Re-injection & Completion: The skill issues a special format retry command back to the session, prompting the agent to process the original user query and transfer the item from
pendingtocompletedupon success.
Model Fallback Retry Setup
Follow these steps to deploy and activate the skill in your ecosystem of Openclaw Skills:
# 1. Install the skill to the local directory
cp -r model-fallback-retry ~/.openclaw/skills/
# 2. Restart the gateway to load the plugin
openclaw gateway restart
# 3. Add the cron job to execute the retry checks periodically
openclaw cron add --name "model-fallback-retry-check" --every 30m --agent xiaoxiao --to YOUR_FEISHU_OR_WECHAT_ID
# 4. Verify that the cron task is configured successfully
openclaw cron list
Make sure to configure your ~/.openclaw/skills/model-fallback-retry/config.json file. Update the cron.agent and cron.notify_to values to match your execution agent and notification receiver ID.
Model Fallback Retry Data Schema & Taxonomy
The skill maintains state via retry_queue.json containing three primary datasets: pending, completed, and cleared.
Schema Fields in retry_queue.json
| Field | Type | Description |
|---|---|---|
id |
String (UUID) | Unique identifier for the retry item |
sessionKey |
String | Target agent and channel session identifier |
originalMessage |
String | The raw prompt sent by the user |
errorOutput |
String | The raw error message returned by the LLM provider |
errorType |
String | Intercept classification (e.g., quota_error) |
sent_at |
String | Timestamp when the error was captured |
retry_count |
Integer | Counter tracking the number of execution attempts |
next_retry_at |
String | Target time for the next scheduled retry run |
max_retry_count |
Integer | Maximum retry boundary (default: 5) |
initial_wait_minutes |
Integer | Initial backoff time in minutes (default: 30) |
Model Fallback Retry Advanced Features
- Three-Tier Interception Mechanism: Analyzes structured Openclaw Skills error categories, standard HTTP statuses, and customizable fallback regular expressions.
- Flexible Queue Commands: Developers or users can interact with the queue dynamically via text triggers like
#队列状态(status check),#清空(clear all), and#清空 [ID](clear specific queue message). - Exponential Backoff: Mitigates persistent service outages through exponential scaling of wait intervals, reducing server overhead on overloaded endpoints.
- Multi-Channel Feishu/WeChat Support: Seamlessly maps retry queues back to specific platform communication sessions, maintaining native UI continuity for your users.
SKILL.md
Loading
Related Openclaw Skills
pattern-converter
An advanced paradigm-shifting skill designed to analyze the underlying structures of existing concepts and seamlessly migrate those abstract patterns into entirely new solutions.
Dimensional Strong Correlation
An advanced possibility space navigator that deconstructs concepts into core dimensions, forces connections between unrelated domains, and generates highly innovative, counter-intuitive solutions.
agentsmd-creator
An intelligent skill designed to scan repository workspaces and generate standardized AGENTS.md context files to instantly onboard AI coding agents.
Mobile Responsive Layout Fixer
A specialized AI-assisted workflow skill to help frontend developers and product teams quickly diagnose and fix mobile responsiveness, navigation layout, and cross-device UI issues.
Eight Cuisines Chinese Cooking Skill
An AI-powered professional culinary knowledge base covering China's eight major cuisines, complete with precise recipes, step-by-step techniques, and seasoning guides.
Web Scraper & Summarizer
An AI-powered local web scraper and summarizer that extracts clean page content and generates structured summaries using Ollama and curl.
Featured*
