> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ccs.kaitran.ca/llms.txt
> Use this file to discover all available pages before exploring further.

# Codex Provider

> Access OpenAI Codex models via OAuth authentication

# 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

<Note>Available since v7.54.0</Note>

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

```bash theme={null}
# 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:**

1. Authorization Code flow via browser callback
2. Callback server spawns on provider-specific port
3. Token cached locally with auto-refresh
4. Proactive token refresh prevents mid-request failures

### Manual Authentication

```bash theme={null}
# 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

```bash theme={null}
# Clear all Codex tokens
ccs codex --logout
```

## Multi-Account Support

Manage multiple OpenAI accounts for different projects:

### Add Account

```bash theme={null}
# Add new account (preserves existing)
ccs codex --auth --add
```

### List Accounts

```bash theme={null}
# Show all authenticated Codex accounts
ccs codex --accounts

# Output:
# Accounts for codex:
#   [default] john (john@example.com)
#   sarah (sarah@company.com)
```

### Switch Account

```bash theme={null}
# 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

```bash theme={null}
# 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

<Note>
  Since v7.44.0, the dashboard exposes the weekly reset schedule for Codex
  accounts, showing exactly when your weekly quota resets.
</Note>

### 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

```bash theme={null}
# 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:

```bash theme={null}
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:

```bash theme={null}
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:

```json theme={null}
{
  "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:

```bash theme={null}
# 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

<Note>
  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.
</Note>

### Trace Logging

Enable verbose mode to see reasoning effort in request logs:

```bash theme={null}
ccs codex --verbose "your task"
# Output includes: reasoning.effort: xhigh
```

## Runtime Targets

<Note>Available since v7.62.0</Note>

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:

```bash theme={null}
# 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:

```bash theme={null}
ccs cliproxy routing
ccs cliproxy routing set round-robin
```

<Info>
  See [Codex Adapter](/features/workflow/codex-adapter) for full details on
  supported profile types, alias configuration, and the dashboard control
  center.
</Info>

### Droid Runtime

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

```bash theme={null}
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

```bash theme={null}
# 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:**

```json theme={null}
{
  "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

```bash theme={null}
# Use headless mode
ccs codex --headless

# Complete auth on another device
# CCS detects when token is cached
```

### Multi-Account Issues

```bash theme={null}
# 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:

```bash theme={null}
# 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

## Next Steps

<CardGroup cols={2}>
  <Card title="Multi-Account Setup" icon="users" href="/tutorials/multi-account-setup">
    Manage multiple Codex accounts
  </Card>

  <Card title="Dashboard Config" icon="gauge" href="/getting-started/configuration">
    Configure via web interface
  </Card>
</CardGroup>