> ## 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.6 Sol - latest frontier agentic coding model
* GPT-5.6 Terra - balanced agentic coding model for everyday work
* GPT-5.6 Luna - fast, affordable agentic coding model
* 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

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.

### 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.6-sol` | GPT-5.6 Sol | `xhigh` | Yes | Frontier agentic coding model |
| `gpt-5.6-terra` | GPT-5.6 Terra | `xhigh` | Yes | Balanced everyday model |
| `gpt-5.6-luna` | GPT-5.6 Luna | `xhigh` | Yes | Fast, affordable model |
| `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 |

### Catalog Context Windows

In the current development CLI source, programmatic catalog output includes
`contextWindow` when CCS knows an authoritative token limit:

```bash theme={null}
ccs cliproxy catalog --json
```

For Claude-target CLIProxy launches, CCS uses the effective provider and model
catalog entry to set `CLAUDE_CODE_AUTO_COMPACT_WINDOW` automatically. An exact
uppercase environment key already present wins by presence, including an empty
value. Unknown or custom models remain unchanged because CCS does not guess a
window.

This automatic environment injection is specific to Claude-target launch
construction; it does not describe behavior for non-Claude targets.

**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`.

GPT-5.6 Sol, Terra, and Luna support `low`, `medium`, `high`, and `xhigh` suffixes. CCS does not advertise `minimal`, `max`, or `ultra` for those models.

**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.

The same pattern also works for a structured Codex fast alias in CCS config.
For example, a `cliproxy.oauth_model_alias.codex` entry like
`gpt-5.6-sol-fast` can map to upstream `gpt-5.6-sol`, while a matching
`cliproxy.payload.override` rule keeps `service_tier: priority` attached to that
alias through regeneration.

### 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`, and create or edit a
Codex variant. Select a supported Codex model, then use the **Fast** switch
beside **Effort**. The switch adds or removes `-fast` without changing the
selected effort or a routing prefix. It also remains available for a custom
value that already ends in `-fast`. 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"
  }
}
```

```yaml theme={null}
cliproxy:
  oauth_model_alias:
    codex:
      - name: gpt-5.6-sol
        alias: gpt-5.6-sol-fast
        fork: true
  payload:
    override:
      - models:
          - name: gpt-5.6-sol-fast
            protocol: codex
        params:
          service_tier: priority
```

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

### Dashboard Effort And Fast Controls

In `ccs config`, each Codex tier in the CLIProxy model mapping includes an
**Effort** dropdown. **Auto** removes any explicit effort suffix; the other
choices match the selected model's supported effort levels. Changing effort
preserves an existing `-fast` service-tier suffix, such as changing
`gpt-5.4-high-fast` to `gpt-5.4-low-fast`. For supported models, the separate
**Fast** switch controls that suffix without changing the effort selection.

### 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 via CLIProxy's `model(level)` thinking suffix. This
> overrides Claude Code's internal `/effort` setting whenever CCS assigns an effort level.
> To return full effort control to Claude Code's `/effort`, set `thinking.mode: off`
> in your config or run with `CCS_THINKING=off`.

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

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

> [!NOTE]
>
> See [Codex Adapter](https://docs.ccs.kaitran.ca/features/workflow/codex-adapter.md) 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:

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

> [card] [Multi-Account Setup](https://docs.ccs.kaitran.ca/tutorials/multi-account-setup.md)
>
> Manage multiple Codex accounts

> [card] [Dashboard Config](https://docs.ccs.kaitran.ca/getting-started/configuration.md)
>
> Configure via web interface


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.