- name
- redline
- description
- Live rate-limit awareness for Claude.ai (Max/Pro) and OpenAI (Plus/Pro/Codex). Never hit the red line again — your agent checks remaining budget every heartbeat and automatically throttles from full-send to conservation mode. Two CLI scripts + a 4-tier pacing strategy (GREEN/YELLOW/ORANGE/RED) that keeps you running at maximum token efficiency 24/7.
- metadata
- openclaw
- requires
- bins
- [python3]
Usage Pacing
Check live rate-limit usage for Claude.ai and OpenAI/Codex plans, then apply pacing tiers to avoid hitting limits.
Scripts
claude-usage
Reads the Claude Code OAuth token from macOS Keychain and calls the Anthropic usage API.
# Human-readable output with color bars
scripts/claude-usage
# JSON output (for programmatic use)
scripts/claude-usage --jsonRequirements:
- macOS with
securityCLI (Keychain access) - Claude Code OAuth token in Keychain (run
claude loginto set up) - Token needs
user:profilescope (standard Claude Code login provides this)
Token location: macOS Keychain, service Claude Code-credentials, account = your macOS username.
openai-usage
Reads the OpenAI OAuth token from OpenClaw's auth-profiles and calls the ChatGPT usage API.
# Human-readable output with color bars
scripts/openai-usage
# JSON output
scripts/openai-usage --jsonRequirements:
- OpenClaw with an authenticated
openai-codexprofile (runopenclaw auth openai-codex) - Auth profiles at
~/.openclaw/agents/main/agent/auth-profiles.json
Pacing Tiers
Wire both scripts into your heartbeat to automatically pace work based on remaining budget:
| Tier | Remaining | Behavior |
|---|---|---|
| 🟢 GREEN | >50% | Normal operations |
| 🟡 YELLOW | 25-50% | Skip sub-agents, defer non-urgent research |
| 🟠 ORANGE | 10-25% | Essential replies only, no proactive checks |
| 🔴 RED | <10% | Critical only, warn user |
Heartbeat integration
Add to your HEARTBEAT.md:
## Usage pacing (every heartbeat)
- Run `scripts/claude-usage --json` and `scripts/openai-usage --json` to check rate limits.
- Store readings in memory/heartbeat-state.json under "usage.claude" and "usage.openai".
- Apply pacing tiers:
- GREEN (>50% left): normal ops
- YELLOW (25-50%): skip sub-agents, defer non-urgent research
- ORANGE (10-25%): essential replies only, no proactive checks
- RED (<10%): critical only, warn user
- If entering YELLOW or worse, mention it briefly when next messaging.JSON output format
Claude (--json):
{
"five_hour": {"utilization": 39.0, "resets_at": "2026-02-18T04:00:00Z"},
"seven_day": {"utilization": 12.0, "resets_at": "2026-02-24T03:00:00Z"},
"extra_usage": {"is_enabled": true, "used_credits": 5044, "monthly_limit": 5000}
}OpenAI (--json):
{
"plan_type": "plus",
"rate_limit": {
"primary_window": {"used_percent": 0, "limit_window_seconds": 10800, "reset_at": 1771556400},
"secondary_window": {"used_percent": 34, "limit_window_seconds": 86400, "reset_at": 1771556400}
},
"credits": {"balance": "882.99"}
}