Codex Provider Access OpenAI Codex models through browser-based OAuth authentication. CCS keeps startup safe for free Codex plans by default and repairs known paid-only defaults when the active account cannot use them.
Overview The Codex provider enables Claude Code to use OpenAI’s Codex models through OAuth authentication - no API keys required. Simply authenticate once and CCS handles token management automatically.
Provider Identifier: codexCommand: ccs codexSupported Models:
GPT-5 Codex - cross-plan-safe default
GPT-5 Codex Mini - cross-plan-safe fast option
GPT-5.2 Codex, GPT-5.3 Codex, GPT-5.3 Codex Spark, and GPT-5.4 on paid Codex plans
Interactive model picker via --config
Plan-Aware Defaults CCS now checks the active Codex quota plan before startup when your settings reference a known paid-only model.
If the active account is on the free Codex plan, CCS rewrites unsupported defaults to gpt-5-codex
or gpt-5-codex-mini
If CCS cannot verify the plan, it keeps your current model and prints a targeted warning with the safe fallback
The repair only touches known paid-only Codex defaults (gpt-5.3-codex, gpt-5.3-codex-spark, gpt-5.4); it does not rewrite unrelated provider settings
Authentication First-Time Setup # Run Codex for the first time ccs codex "explain this code" # Browser opens automatically # → Complete OAuth login # → Token cached at ~/.ccs/cliproxy/auth/ # → Future runs require no re-auth
Authentication Flow:
Authorization Code flow via browser callback
Callback server spawns on provider-specific port
Token cached locally with auto-refresh
Proactive token refresh prevents mid-request failures
Manual Authentication # Authenticate without starting a session ccs codex --auth # Headless mode (server/SSH environments) ccs codex --headless # → Displays URL for manual browser authentication # → Includes SSH tunnel instructions if needed
Logout # Clear all Codex tokens ccs codex --logout
Multi-Account Support Manage multiple OpenAI accounts for different projects:
Add Account # Add new account (preserves existing) ccs codex --auth --add
List Accounts # Show all authenticated Codex accounts ccs codex --accounts # Output: # Accounts for codex: # [default] john (john@example.com) # sarah (sarah@company.com)
Switch Account # Switch to specific account by nickname ccs codex --use sarah # Next command uses sarah's account ccs codex "your prompt"
Rename Account # Rename default account nickname ccs codex --nickname work-account
Account Registry: ~/.ccs/cliproxy/accounts.jsonAuto-Nicknames: Generated from email prefix (e.g., john@gmail.com → john)Real-Time Quota Display CCS displays real-time quota information for Codex accounts via Dashboard and CLI.
Weekly Reset Schedule Since v7.44.0, the dashboard exposes the weekly reset schedule for Codex
accounts, showing exactly when your weekly quota resets.
Dashboard Display Location: Dashboard → OAuth Providers → CodexDisplays:
Daily message usage (e.g., “45/50 messages”)
Weekly message usage (e.g., “210/500 messages”)
Daily limit reset time
Weekly limit reset time (with schedule)
Backend Caching:
Quota data cached for 2 minutes to reduce API load
Automatic re-authentication if token expired
Dashboard shows cached timestamp
CLI Quota Check # View quota for all Codex accounts ccs cliproxy quota --provider codex # Output: # Codex Quota (as of 2026-02-04 18:00:00): # john@example.com: # Daily: 45/50 messages (resets in 6h) # Weekly: 210/500 messages (resets in 2d 6h)
Features:
Displays all authenticated Codex accounts
Shows cached timestamp (2-minute cache)
Indicates if re-authentication needed
Quota Response Caching: CCS caches quota responses to prevent excessive API calls:
Cache Duration Applies To 2 minutes Quota data (usage counts, reset times) Token refresh Automatic if expired during fetch
Cache Location: In-memory (not persisted to disk)Available Models: Model ID Name Max Effort Notes gpt-5-codexGPT-5 Codex highCross-plan-safe default gpt-5-codex-miniGPT-5 Codex Mini highCross-plan-safe fast option gpt-5.2-codexGPT-5.2 Codex xhighPaid Codex plans gpt-5.3-codexGPT-5.3 Codex xhighPaid Codex plans gpt-5.3-codex-sparkGPT-5.3 Codex Spark xhighPaid Codex plans gpt-5.4GPT-5.4 xhighPaid Codex plans
Model Suffixes: Append effort level directly: gpt-5.3-codex-medium, gpt-5.3-codex-high, gpt-5.3-codex-xhigh.Reasoning Effort CCS automatically injects OpenAI’s reasoning.effort parameter. The configured slot requests a default effort, then CCS caps it to the selected model’s supported maximum.
Effort Levels Level Description Token Budget mediumStandard reasoning Base level highDeep reasoning Moderate increase xhighMaximum depth Up to 32K tokens
Automatic Effort Mapping Source Requested Effort Effective Behavior Default / Opus slot xhighCapped by the selected model’s max supported level Sonnet slot highUsed as-is unless the model only supports lower Haiku slot mediumUsed as-is --effort / model suffixExplicit value Used, then capped if the model cannot support it
How It Works When you use Codex, CCS derives the effort from your configuration and then applies model-specific caps:
# Default Codex model is gpt-5-codex, so effective effort is capped at high ccs codex "complex analysis task" # Override effort explicitly ccs codex --effort xhigh "deep analysis" ccs codex --thinking xhigh "same as --effort" # Model suffix pins effort ccs codex # model: gpt-5.3-codex-medium -> effort: medium
Cost Implications Higher reasoning effort increases token consumption:
xhigh: Maximum tokens, deepest analysishigh: Moderate token increasemedium: Standard token usage
Reasoning effort is injected transparently. You don’t need to configure
anything unless you want to override it. Unsupported higher efforts are capped
to the model’s max level automatically.
Trace Logging Enable verbose mode to see reasoning effort in request logs:
ccs codex --verbose "your task" # Output includes: reasoning.effort: xhigh
Commands Basic Usage # Run with Codex ccs codex "implement authentication flow" # Interactive chat ccs codex
Authentication Flags Flag Description --authTrigger OAuth flow (no session) --logoutClear all tokens --headlessDisplay URL for remote auth --auth --addAdd new account (keep existing)
Account Management Flags Flag Description --accountsList all accounts --use <nickname>Switch default account --nickname <name>Rename default account
Storage Locations Path Purpose ~/.ccs/cliproxy/auth/codex-*.jsonOAuth tokens (one per account) ~/.ccs/cliproxy/accounts.jsonAccount registry with nicknames ~/.ccs/codex.settings.jsonModel configuration ~/.ccs/cliproxy/config.yamlCLIProxy unified config
Requirements
OpenAI account with Codex OAuth access
Browser for OAuth (or --headless for servers)
Network access to OpenAI authentication servers
Token Management Storage Format: { "type" : "codex" , "access_token" : "..." , "refresh_token" : "..." , "email" : "user@example.com" , "expired" : "2024-12-31T23:59:59Z" }
Auto-Refresh: Tokens refresh automatically 5 minutes before expirySecurity: Tokens stored locally, never transmitted except to OpenAITroubleshooting Browser Won’t Open # Use headless mode ccs codex --headless # Complete auth on another device # CCS detects when token is cached
Multi-Account Issues # List all accounts to verify state ccs codex --accounts # Clear and re-authenticate ccs codex --logout ccs codex --auth
Token Expiry Tokens refresh automatically. If refresh fails:
# Re-authenticate ccs codex --auth
Plan Access: Free Codex plans can use cross-plan-safe models such as gpt-5-codex and gpt-5-codex-mini. Paid Codex plans unlock paid-only model IDs such as gpt-5.2-codex, gpt-5.3-codex, and gpt-5.4.Usage Limits: Subject to OpenAI’s rate limits and fair use policyNext Steps
Multi-Account Setup Manage multiple Codex accounts
Dashboard Config Configure via web interface
