A zero-dependency Python utility that prevents AI agents from hitting API rate limits through proactive tier-based throttling and automatic exponential backoff.
Install & Download
1. ClawHub CLI
The fastest way to install a skill directly from the registry.
npx clawhub@latest install agent-rate-limiter
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 agent-rate-limiter 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 Agent Rate Limiter?
The Agent Rate Limiter is a technical solution designed to solve the most common bottleneck in autonomous AI workflows: the 429 rate limit error. When agents perform high-frequency tasks like browsing, spawning sub-agents, or filing emails, they often exceed provider limits, causing task failure and token waste. This skill provides a lightweight way to integrate self-awareness into your Openclaw Skills collection, allowing agents to monitor their own consumption and slow down before hitting a hard wall.
Unlike complex monitoring tools, this skill uses a heuristic estimation approach that requires no external API keys or browser scraping. It functions as a local gatekeeper, calculating usage within a rolling window to determine if the agent should proceed normally, reduce activity, or pause entirely to allow the rate limit to reset.
Agent Rate Limiter Use Cases
- Preventing autonomous agent crashes during long-running tasks or heavy background loops.
- Managing multiple agent instances sharing a single API tier safely.
- Automating exponential backoff and recovery scheduling after a genuine rate limit hit.
- Dynamically reducing agent verbosity or sub-agent spawning when approaching usage caps.
How Agent Rate Limiter Works
- The agent calls the gate command before initiating any expensive or token-heavy operation.
- The script analyzes the rolling usage window and returns an exit code representing a specific tier (ok, cautious, throttled, critical, or paused).
- The agent adjusts its behavior based on the tier, such as skipping non-essential tasks or providing shorter responses.
- After completing work, the agent records its estimated usage to update the local state file.
- If a 429 error occurs regardless, the pause command calculates an exponential backoff time and prevents further activity until it is safe to resume.
Agent Rate Limiter Setup
This skill requires Python 3 and uses the standard library only. To integrate it into your Openclaw Skills environment, use the following commands:
# 1. Verify installation
python3 scripts/rate-limiter.py gate && echo "Ready"
# 2. Basic usage in an agent loop
python3 scripts/rate-limiter.py gate || exit 1
python3 scripts/rate-limiter.py record 1000
Configuration is handled via environment variables:
export RATE_LIMIT_PROVIDER="claude"
export RATE_LIMIT_PLAN="max-5x"
export RATE_LIMIT_STATE="./rate-limit-state.json"
Agent Rate Limiter Data Schema & Taxonomy
The skill maintains state in a single JSON file. This structure allows Openclaw Skills to track history across different sessions:
| Key | Description |
|---|---|
tier |
Current status (ok, cautious, throttled, critical, paused) |
estimatedPct |
Percentage of the estimated limit currently consumed |
window |
Object containing duration, request history, and the estimated limit |
backoff |
Tracks consecutive 429 errors to calculate recovery time |
pausedUntil |
Timestamp indicating when the agent is allowed to resume activity |
Agent Rate Limiter Advanced Features
- Multi-tier behavioral prompts that tell the agent exactly how to 'downshift' activity levels.
- Provider presets for Claude (Max-5x, Max-20x) and OpenAI (Plus, Pro) plans.
- Automatic exponential backoff with jitter to ensure recovery doesn't immediately re-trigger limits.
- Support for custom request limits and window durations for niche or enterprise API tiers.
- Clean exit code protocol for easy integration into bash scripts and heartbeat checks.
SKILL.md
Loading
Related Openclaw Skills
GoHighLevel Account & App Setup
A comprehensive guide for AI agents to automate GoHighLevel account registration, developer app creation, and API credential management.
ElevenLabs Open Account
A comprehensive guide for developers and creators to set up ElevenLabs accounts and secure API keys for advanced voice AI integrations.
China Mirror Resolver
A self-healing mirror resolver that automatically finds, validates, and configures the fastest domestic download sources for developers in China.
Godot Shader Pro
An expert resource for developing, optimizing, and debugging Godot 4 shaders across 2D, 3D, and particle systems.
Fastmail JMAP Email Skill
Give your AI agent full email superpowers to read, search, and send messages using Fastmail JMAP.
macOS Native Automation
A zero-dependency Python tool for hardware-level mouse and keyboard automation on macOS using CGEvent and AppleScript.
METADATA
Featured*
