Codex Provider
Access OpenAI Codex models (GPT-5.1-codex-max) through browser-based OAuth authentication. Requires ChatGPT Plus subscription.
Overview
The Codex provider enables Claude Code to use OpenAI’s premium 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.1-codex-max (ChatGPT Plus)
- Interactive model picker on first run
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
- 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
~/.ccs/cliproxy/accounts.json
Auto-Nicknames: Generated from email prefix (e.g., john@gmail.com → john)
Codex uses a single fixed model:
Available Model:
- GPT-5.1-codex-max (default and only model)
Note: Unlike Gemini and Antigravity providers, Codex does NOT support interactive model selection via --config. The provider uses a fixed model configuration.
Reasoning Effort
CCS automatically injects OpenAI’s reasoning.effort parameter based on the model tier being used. This affects response quality and token consumption.
Automatic Effort Mapping
| Model Tier | Reasoning Effort | Description |
|---|
| Opus (default) | xhigh | Maximum reasoning depth, highest quality |
| Sonnet | high | Balanced reasoning, good quality |
| Haiku | medium | Faster responses, standard reasoning |
How It Works
When you use Codex, CCS detects the model tier from your configuration and automatically sets the appropriate reasoning effort:
# Uses xhigh effort (Opus tier default)
ccs codex "complex analysis task"
# If configured for Sonnet model, uses high effort
# If configured for Haiku model, uses medium effort
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 - CCS handles it automatically based on your model selection.
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 |
|---|
--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
- ChatGPT Plus subscription
- 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"
}
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
Next Steps
