Summary

OpenClaw should provide native Codex/ChatGPT OAuth reliability handling by separating quota-window exhaustion from true OAuth credential failure, and by supporting brokered reauth execution when reauthentication is actually required.

User-facing goal

As a user, I want one reliable ChatGPT/Codex OAuth experience:

• if I only hit my rolling usage window, OpenClaw should tell me the quota state and when it renews
• if my OAuth refresh token is actually invalid, OpenClaw should tell me that reauth is required
• if a bounded host-side reauth adapter exists, OpenClaw should be able to invoke it instead of leaving recovery entirely manual

Problem

Today, quota exhaustion and unrecoverable OAuth failure can be confused operationally.
For example:

• rolling usage-window exhaustion should not trigger reauth
• refresh_token_reused should trigger guided reauth
• a normal access-token expiry with a valid refresh token should refresh automatically

These are different states, but they are easy to collapse into a single generic "auth failed" workflow.

Requested feature set

1. Native quota/auth diagnosis in OpenClaw

OpenClaw should distinguish at least:

• ok
• expiring_soon
• quota_wait
• reauth_required

Behavior:

• quota_wait: do not trigger reauth
• reauth_required: prompt for or invoke a bounded reauth adapter
• normal expired access token + valid refresh token: refresh automatically

2. Native Codex quota display

OpenClaw should surface Codex rate-limit state natively, including both the 5-hour and weekly windows.

Recommended display format:

Codex rate limits
5h: 96%, renews 05:45 AM
Weekly: 60%, renews 2026-03-25 3:04 PM

Formatting rules:

• use system local timezone automatically
• 5h window: percent + local time
• weekly window: percent + local date and time

3. Brokered reauth execution

When OpenClaw determines the state is reauth_required, it should support invoking a narrow reauth adapter rather than assuming it must handle browser-based reauth itself.

This is especially important for Docker/sandboxed deployments where:

• the app can diagnose the problem natively
• the actual browser-based OAuth flow needs to run outside the container

Conceptually:

• native decision inside OpenClaw
• bounded external execution via a broker/adapter

Control UI impact

Yes, this should include Control UI changes.

Suggested Control UI behavior:

• show the current Codex rate-limit state in a human-readable form
• when the state is quota_wait, show renewal times instead of suggesting reauth
• when the state is reauth_required, show a clear guided reauth action if a reauth adapter is available
• avoid ambiguous generic auth-failure messaging when the real issue is rolling-window quota exhaustion

Why this matters

For users, this is one feature set: a more reliable ChatGPT/Codex OAuth experience.
Internally, it can still be split into:

• native quota/auth diagnosis
• optional brokered reauth execution

That split keeps the trust boundary clean while delivering one coherent recovery UX.

Additional context

I implemented a local host-side prototype in a Docker-based OpenClaw sandbox that:

• classifies quota_wait separately from reauth_required
• formats local-time 5h/weekly renewal info
• auto-triggers a bounded host-side reauth bridge only for reauth_required

I am not attaching that patch directly here because parts of it are deployment-specific, but it validated the behavior and UX split described above.