Codex Provider

Access OpenAI Codex models through browser-based OAuth authentication. CCS defaults to the current Codex-recommended models and repairs known paid-only or preview-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: codex Command: ccs codex Supported Models:

GPT-5.4 - recommended default for most Codex tasks
GPT-5.4 Mini - fast, lower-cost option for lighter tasks and subagents
GPT-5.2 and GPT-5.3 Codex as older alternatives
GPT-5.3 Codex Spark in research preview for ChatGPT Pro subscribers
Interactive model picker via --config

Plan-Aware Defaults

Available since v7.54.0

CCS now checks the active Codex quota plan before startup when your settings reference a known paid-only or preview-only model.

If the active account is on the free Codex plan, CCS keeps your saved settings but sends runtime requests through gpt-5.4 or gpt-5.4-mini when the configured model is restricted
If CCS cannot verify the plan, it keeps your current model and prints a targeted warning with the safe fallback
The runtime fallback only touches known restricted Codex defaults (gpt-5.5, gpt-5.3-codex, and gpt-5.3-codex-spark); 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"

Reauthenticate Account

Use Dashboard → CLIProxy → Codex → account menu → Reauthenticate to refresh one imported or existing account without creating a duplicate account record.

Rename Account

# Rename default account nickname
ccs codex --nickname work-account

Account Registry: ~/.ccs/cliproxy/accounts.json Auto-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 → CLIProxy → Codex provider view Displays:

Core 5-hour usage window (e.g., “45/50 messages”)
Core weekly usage window (e.g., “210/500 messages”)
5-hour limit reset time
Weekly limit reset time (with schedule)
Additional feature windows such as Codex Spark in tooltip/detail views when the upstream exposes them

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:
#     5-hour: 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
Keeps preview or feature-specific windows separate from the core 5-hour and weekly summary so extra limits do not replace the main account view

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)

Model Information

Available Models:

Model ID	Name	Max Effort	Fast Tier	Notes
`gpt-5.5`	GPT-5.5	`xhigh`	Yes	Newest paid Codex model
`gpt-5.4`	GPT-5.4	`xhigh`	Yes	Recommended Codex default
`gpt-5.4-mini`	GPT-5.4 Mini	`high`	No	Default fast / haiku option
`gpt-5.2`	GPT-5.2	`xhigh`	No	Older general-purpose model
`gpt-5.3-codex`	GPT-5.3 Codex	`xhigh`	No	Older paid Codex model
`gpt-5.3-codex-spark`	GPT-5.3 Codex Spark	`xhigh`	No	Research preview, ChatGPT Pro

Model Suffixes: Append effort level directly: gpt-5.5-minimal, gpt-5.5-low, gpt-5.3-codex-medium, gpt-5.3-codex-high, gpt-5.3-codex-xhigh. Fast Service Tier: Append -fast to supported GPT model IDs. Combine it with an effort suffix when both should be pinned:

gpt-5.4-fast
gpt-5.4-low-fast
gpt-5.4-high-fast
gpt-5.4-xhigh-fast
gpt-5.5-high-fast

CCS translates these aliases before sending the request upstream. For example, gpt-5.4-high-fast becomes upstream model gpt-5.4 with reasoning.effort: "high" and service_tier: "priority", which is the Codex request value for fast mode.

Configure Fast Mode

Use a CLIProxy variant when you want Claude Code or compatible clients to use a specific Codex GPT speed/effort combination:

ccs cliproxy create codex-fast --provider codex --model gpt-5.4-high-fast
ccs codex-fast "review this change"

In the dashboard, open ccs config, go to CLIProxy, create or edit a Codex variant, and select a fast model variant from the model picker. The raw environment form is also valid:

{
  "env": {
    "ANTHROPIC_MODEL": "gpt-5.4-high-fast",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "gpt-5.4-xhigh-fast",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "gpt-5.4-high-fast",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "gpt-5.4-medium-fast"
  }
}

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
`minimal`	Lightest reasoning	Lowest usage
`low`	Light reasoning	Low usage
`medium`	Standard reasoning	Base level
`high`	Deep reasoning	Moderate increase
`xhigh`	Maximum depth	Up to 32K tokens

Automatic Effort Mapping

Source	Requested Effort	Effective Behavior
Default / Opus slot	`xhigh`	Capped by the selected model’s max supported level
Sonnet slot	`high`	Used as-is unless the model only supports lower
Haiku slot	`medium`	Used as-is
`--effort` / model suffix	Explicit 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.4, so xhigh remains available
ccs codex "complex analysis task"

# Override effort explicitly
ccs codex --effort xhigh "deep analysis"
ccs codex --thinking xhigh "same as --effort (alias)"

# Model suffix pins effort
ccs codex  # model: gpt-5.5-low -> effort: low

# Model suffix pins effort and fast service tier
ccs codex  # model: gpt-5.4-high-fast -> effort: high, service_tier: priority

Cost Implications

Higher reasoning effort increases token consumption:

xhigh: Maximum tokens, deepest analysis
high: Moderate token increase
medium: Standard token usage
low / minimal: Lower usage for lightweight tasks

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

Runtime Targets

Available since v7.62.0

CCS can route the Codex provider to different CLI runtimes:

Native Codex Runtime

Use ccs-codex, ccsx, or ccsxp to run the Codex provider on the native Codex CLI:

# Built-in aliases
ccs-codex "your prompt"
ccsx codex "implement auth flow"

# Codex-on-Codex power shortcut: native Codex + CLIProxy Codex pool
ccsxp "your prompt"

# Explicit target flag
ccs codex --target codex "your prompt"

Most Codex target launches use transient -c overrides and CCS_CODEX_API_KEY env injection. ccsxp is the managed exception: it repairs the native Codex [model_providers.cliproxy] entry if missing or incomplete, then injects the managed token into that provider’s configured env_key for the spawned Codex process. No API key is written to ~/.codex/config.toml. ccsxp keeps Codex history in native ~/.codex by default, even if the parent shell has another CODEX_HOME set. Use CCSXP_CODEX_HOME only when you intentionally want separate ccsxp history. Pooling and round-robin behavior are controlled by CLIProxy routing, not by the Codex config file:

ccs cliproxy routing
ccs cliproxy routing set round-robin

See Codex Adapter for full details on supported profile types, alias configuration, and the dashboard control center.

Droid Runtime

Use Codex with the ccs-droid target for automated agent workflows:

ccs-droid codex "run this task autonomously"

This routes the Codex provider through CCS’s Droid runtime for non-interactive automated execution.

Commands

Basic Usage

# Run with Codex
ccs codex "implement authentication flow"

# Interactive chat
ccs codex

# With reasoning effort
ccs codex --thinking xhigh "design this system"

Authentication Flags

Flag	Description
`--auth`	Trigger OAuth flow (no session)
`--logout`	Clear all tokens
`--headless`	Display URL for remote auth
`--auth --add`	Add new account (keep existing)

Account Management Flags

Flag	Description
`--accounts`	List all accounts
`--use <nickname>`	Switch default account
`--nickname <name>`	Rename default account

Storage Locations

Path	Purpose
`~/.ccs/cliproxy/auth/codex-*.json`	OAuth tokens (one per account)
`~/.ccs/cliproxy/accounts.json`	Account registry with nicknames
`~/.ccs/codex.settings.json`	Model configuration
`~/.ccs/cliproxy/config.yaml`	CLIProxy 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 expiry Security: Tokens stored locally, never transmitted except to OpenAI

Troubleshooting

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

Cost Information

Plan Access: Use gpt-5.4 for the default Codex path and gpt-5.4-mini for the fast path. gpt-5.5 and older models such as gpt-5.3-codex require paid Codex access, while gpt-5.3-codex-spark is a research preview model for ChatGPT Pro subscribers. Usage Limits: Subject to OpenAI’s rate limits and fair use policy

​Codex Provider

​Overview

​Plan-Aware Defaults

​Authentication

​First-Time Setup

​Manual Authentication

​Logout

​Multi-Account Support

​Add Account

​List Accounts

​Switch Account

​Reauthenticate Account

​Rename Account

​Real-Time Quota Display

​Weekly Reset Schedule

​Dashboard Display

​CLI Quota Check

​Model Information

​Configure Fast Mode

​Reasoning Effort

​Effort Levels

​Automatic Effort Mapping

​How It Works

​Cost Implications

​Trace Logging

​Runtime Targets

​Native Codex Runtime

​Droid Runtime

​Commands

​Basic Usage

​Authentication Flags

​Account Management Flags

​Storage Locations

​Requirements

​Token Management

​Troubleshooting

​Browser Won’t Open

​Multi-Account Issues

​Token Expiry

​Cost Information

​Next Steps

Multi-Account Setup

Dashboard Config

Codex Provider

Overview

Plan-Aware Defaults

Authentication

First-Time Setup

Manual Authentication

Logout

Multi-Account Support

Add Account

List Accounts

Switch Account

Reauthenticate Account

Rename Account

Real-Time Quota Display

Weekly Reset Schedule

Dashboard Display

CLI Quota Check

Model Information

Configure Fast Mode

Reasoning Effort

Effort Levels

Automatic Effort Mapping

How It Works

Cost Implications

Trace Logging

Runtime Targets

Native Codex Runtime

Droid Runtime

Commands

Basic Usage

Authentication Flags

Account Management Flags

Storage Locations

Requirements

Token Management

Troubleshooting

Browser Won’t Open

Multi-Account Issues

Token Expiry

Cost Information

Next Steps