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: codex Command: ccs codex Supported 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

Available since v7.54.0

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.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 → OAuth Providers → Codex Displays:

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)

Model Information

Available Models:

Model ID	Name	Max Effort	Notes
`gpt-5-codex`	GPT-5 Codex	`high`	Cross-plan-safe default
`gpt-5-codex-mini`	GPT-5 Codex Mini	`high`	Cross-plan-safe fast option
`gpt-5.2-codex`	GPT-5.2 Codex	`xhigh`	Paid Codex plans
`gpt-5.3-codex`	GPT-5.3 Codex	`xhigh`	Paid Codex plans
`gpt-5.3-codex-spark`	GPT-5.3 Codex Spark	`xhigh`	Paid Codex plans
`gpt-5.4`	GPT-5.4	`xhigh`	Paid 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
`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-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 (alias)"

# 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 analysis
high: Moderate token increase
medium: 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

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
ccsxp "your prompt"

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

The Codex adapter uses transient -c overrides and CCS_CODEX_API_KEY env injection — it never rewrites ~/.codex/config.toml.

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: 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 policy

Getting Started

Providers

Features

Tutorials

​Codex Provider

​Overview

​Plan-Aware Defaults

​Authentication

​First-Time Setup

​Manual Authentication

​Logout

​Multi-Account Support

​Add Account

​List Accounts

​Switch Account

​Rename Account

​Real-Time Quota Display

​Weekly Reset Schedule

​Dashboard Display

​CLI Quota Check

​Model Information

​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

Rename Account

Real-Time Quota Display

Weekly Reset Schedule

Dashboard Display

CLI Quota Check

Model Information

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