Summary

When running openclaw models status --probe, the gateway already makes live API calls to each configured provider. The provider responses include rate-limit headers (x-ratelimit-remaining-requests, x-ratelimit-remaining-tokens, x-ratelimit-reset-requests, etc.) but these are currently consumed internally and not surfaced.

Use Case

I'd like to gate expensive automated tasks on remaining rate-limit headroom — e.g., skip or defer a heavy job if RPM/TPM is low. This is especially useful when multiple tools share the same API key (e.g., OpenClaw + IDE extensions + other integrations).

Currently there's no way to check this programmatically. The only signal is a 429 after the request already failed.

Proposal

Expose rate-limit data from provider responses, for example:

Option A: Extend models status --probe --json

Add a rateLimit field to each probe result:

{
  "provider": "anthropic",
  "model": "anthropic/claude-opus-4-6",
  "status": "ok",
  "latencyMs": 3796,
  "rateLimit": {
    "remainingRequests": 950,
    "limitRequests": 1000,
    "remainingTokens": 78000,
    "limitTokens": 80000,
    "resetRequestsAt": "2026-03-10T18:30:00Z",
    "resetTokensAt": "2026-03-10T18:30:00Z"
  }
}

Option B: New subcommand

openclaw models ratelimit [--provider anthropic] — lightweight probe that returns just rate-limit info.

Option C: Gateway tool / session_status

Expose the last-seen rate-limit headers from the gateway's internal tracking, accessible via the agent tooling (e.g. session_status or a new tool).

Context

• Applicable to all providers (Anthropic, OpenAI, Google, etc.) that return rate-limit headers
• The headers are already in the HTTP responses — this is about surfacing them, not adding new API calls
• Would enable programmatic pre-flight checks before expensive operations