OAuth vs API Keys in OpenClaw — why you're seeing "rate limit reached" when you shouldn't be
If you've ever stared at "API rate limit reached. Please try again later." and thought "but I haven't even used anything today" — you're not alone. This is the #1 confusion I see, and it comes down to not understanding the difference between OAuth (subscription auth) and API keys. API Key Auth (pay-per-token) This is the straightforward path. You create a key in your provider's console, set it in ~/.openclaw/.env, and you pay per token used. Rate limits = requests per minute or tokens per day (based on your API tier). Errors are real rate limits — you're actually sending too many requests. Fix: wait 60 seconds, upgrade your tier, or add multiple keys (OpenClaw auto-rotates on 429s). The official docs recommend this as the "safe path" for always-on gateways. OAuth / Subscription Auth (flat monthly fee) This is where it gets confusing. If you're on ChatGPT Plus ($20/mo) or Claude Pro/Max and using OAuth/setup-token to auth OpenClaw, you're sharing your subscription's usage cap with the agent. The trap: Your subscription plan has a monthly usage cap. When OpenClaw hits it, the error says "API rate limit reached" — but it's NOT a rate limit. It's your subscription quota being exhausted. Waiting 60 seconds won't fix it. You might need to wait hours. Real example from a GitHub issue this week: A user's primary model (Codex via ChatGPT Plus OAuth) hit the plan cap. OpenClaw's fallback to Anthropic worked perfectly — but the UI still showed the rate limit error. The user thought the whole system was broken for 7 hours when it was actually working fine on the fallback the entire time. The OAuth Token Conflict (the sneaky one) If you're running both Claude Code CLI AND OpenClaw with the same Anthropic subscription, they can invalidate each other's tokens. One randomly gets "logged out." This isn't a bug — it's how OAuth refresh tokens work. Each new login can kill the old token. Fix: Use separate agents (openclaw agents add work / openclaw agents add personal) or just pick one tool per subscription.