ratelimit-retry

An OpenClaw plugin that automatically retries agent conversations killed by provider rate limits.

Problem

When your LLM provider hits a rate limit or budget cap (HTTP 429), every running agent task dies mid-conversation. Nothing resumes them. If you close the dashboard, those conversations are gone. You have to manually find and re-trigger each one after the budget resets.

Solution

This plugin hooks into OpenClaw's agent_end event, detects retriable errors (429s, rate limits, budget exhaustion), and parks the failed session in a persistent queue on disk. A background service waits for the provider's budget window to reset, then sends chat.send to the original session -- resuming the conversation with its full transcript context, as if the user had typed a message.

Installation

openclaw plugins install @cheapestinference/openclaw-ratelimit-retry

Or copy manually to your extensions directory:

cp -r openclaw-plugin-ratelimit-retry ~/.openclaw/extensions/ratelimit-retry

Enable it in OpenClaw config:

openclaw config set plugins.ratelimit-retry.budgetWindowHours 5
openclaw config set plugins.ratelimit-retry.maxRetryAttempts 3

No npm install needed. The plugin has zero runtime dependencies.

Complete example

# ~/.openclaw/config.yaml
plugins:
  ratelimit-retry:
    budgetWindowHours: 5
    maxRetryAttempts: 3
    checkIntervalMinutes: 5
    retryMessage: "Continue where you left off. The previous attempt failed due to a rate limit that has now reset."

How It Works

Agent run fails (429)
  |
  v
agent_end hook fires
  |-- Non-retriable error? --> ignore
  |-- Retriable error?     --> queue to disk
                                 |
                                 v
                  Background timer (every 5 min)
                    |
                    |-- Budget window not reset? --> wait
                    |-- Budget window reset?     --> chat.send to session
                                                       |
                                                       |--> Ack received: wait for result
                                                       |     |--> agent_end success: remove from queue
                                                       |     |--> agent_end 429: re-queued automatically
                                                       |--> Send failed: wait for next window

The retry uses chat.send with the original sessionKey, which means the gateway loads the complete JSONL transcript and the agent resumes with full context. This is equivalent to the user typing a message in the chat.

The model is fire-and-forget with re-detection: chat.send returns an immediate ack ({ ok, runId, status: "started" }), not the final result. If the retried run fails again with a 429, the agent_end hook fires again and the session is re-queued with an incremented attempt counter. This loop continues until the retry succeeds or maxRetryAttempts is reached.

Configuration

Option	Type	Default	Description
budgetWindowHours	number	5	Budget reset window in hours, aligned to UTC clock boundaries
maxRetryAttempts	number	3	Max retries per session before abandoning
checkIntervalMinutes	number	5	How often the background service checks for pending retries
retryMessage	string	"Continue where you left off..."	Message sent to the session to resume the conversation

How the Retry Timing Works

Many LLM providers (including LiteLLM) reset budget counters on fixed UTC-aligned windows. With a 5-hour window, the boundaries are:

00:00  05:00  10:00  15:00  20:00  (next day) 00:00
  |------|------|------|------|------|

When an error is queued, the plugin calculates the next boundary after the current time and adds a 1-minute margin (retries at HH:01:00 instead of HH:00:00) to avoid racing the provider's reset.

When 24 is not evenly divisible by windowHours: the math still works. If windowHours is 7, boundaries fall at 0, 7, 14, 21, and the next one would be 28 -- which overflows to 04:00 the next day. The plugin handles day overflow correctly.

Error Classification

Non-retriable patterns are checked first. If an error matches a non-retriable pattern, it is never retried, even if it also matches a retriable pattern.

Retriable (queued for retry)

Pattern	Catches
429	"Error code: 429 - ..."
rate limit, rate_limit	"RateLimitError: ..."
too many requests	HTTP 429 reason phrases
budget	"Budget exceeded for ..."
quota exceeded	Provider quota messages
resource exhausted	gRPC-style exhaustion errors
tokens per minute, tpm	TPM limit messages

Non-retriable (ignored)

Pattern	Reason
401, 402, 403, 404	HTTP client errors -- won't succeed on retry
invalid api key, unauthorized	Auth errors -- fix your credentials
invalid request, malformed	Bad request format -- won't succeed on retry
model not found	Model doesn't exist
context length, prompt too large	Context overflow -- message is too long
insufficient credits	Billing issue -- requires user action

Edge Cases

• Server restarts: the queue is persisted to {stateDir}/ratelimit-retry/queue.json and reloaded on startup.
• Same session errors multiple times: deduplicated by sessionKey. The existing entry is updated with incremented attempts and a recalculated retryAfter.
• Retry fails with 429 again: agent_end fires again, re-queuing with incremented attempts. Natural loop until success or maxRetryAttempts.
• Gateway unreachable during retry: connection error is caught, entry's retryAfter is pushed to the next budget window to avoid hammering a down gateway every tick.
• Max attempts exceeded: entry is removed from queue and a warning is logged.
• Sub-agent sessions: handled identically -- sessionKey format agent:X:subagent:Y works the same way.
• Timer fires during active retry: a retryInProgress guard prevents overlapping batches.
• Queue file corrupted: JSON parse errors are caught; service starts with an empty queue and logs a warning.
• Queue overflow: capped at 100 entries. Oldest entries are evicted when full.
• Atomic writes: queue is written to a uniquely-named .tmp file first, then renamed, to prevent corruption on crashes or concurrent writes.

Limitations

• Fire-and-forget window: after chat.send returns its ack, there is a brief period where the retried run is in progress. If it fails with 429 again immediately, there is a small window before the agent_end hook fires and re-queues it. This is by design -- the re-detection loop handles it.
• chat.send requires a non-empty message: the retry always sends the configured retryMessage. It cannot send an empty message to silently resume.
• No partial-run recovery: the plugin resumes the conversation from the last completed turn. It does not replay partial streaming output that was interrupted.
• Single-instance only: the queue is a local JSON file with no locking. Running multiple OpenClaw instances sharing the same ~/.openclaw/ directory is not supported.
• No backpressure on the provider: the plugin retries all ready sessions in sequence. If you have many queued sessions, they all fire at the start of the next window.

License

MIT

Contributing

Contributions are welcome. Please open an issue first to discuss what you would like to change.

git clone https://github.com/cheapestinference/openclaw-plugin-ratelimit-retry
cd openclaw-plugin-ratelimit-retry
# No build step. OpenClaw loads .ts files directly via Jiti.