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

> Route CCS profiles to OpenAI Codex CLI with managed credential delivery

# Codex Adapter

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

CCS can delegate execution to the OpenAI Codex CLI as a native runtime target. Most CCS-backed Codex profiles use transient `-c` overrides and environment variable injection. The `ccsxp` shortcut also self-heals the native Codex provider entry needed for the CLIProxy Codex pool.

## Quick Start

```bash theme={null}
# Run with explicit target flag
ccs codex --target codex

# Use built-in aliases
ccs-codex "your prompt"
ccsx "your prompt"

# Launch a named native Codex auth profile
ccsx auth create work
ccsx work "your prompt"

# Codex-on-Codex shortcut (native Codex + CLIProxy Codex pool)
ccsxp "your prompt"

# Native Codex session (default profile, no CCS routing)
ccsx codex "your prompt"
```

## How It Works

For ordinary `ccsx` / `ccs-codex` launches, the Codex adapter uses transient runtime credential injection:

1. **Default profiles** pass through unchanged -- uses native Codex auth/config
2. **CCS-backed profiles** inject credentials via temporary `-c` overrides
3. API keys are delivered through `CCS_CODEX_API_KEY` env var, not written to disk
4. Profile and variant configs may persist `target: codex` for default routing
5. The Codex binary is probed for `--config` support before attempting overrides

For `ccsxp`, CCS intentionally uses the native Codex `model_provider="cliproxy"` path. Before launching, CCS repairs the active Codex `config.toml` only as far as needed to ensure `[model_providers.cliproxy]` points at the local CLIProxy Codex bridge:

```toml theme={null}
[model_providers.cliproxy]
name = "CLIProxy Codex"
base_url = "http://127.0.0.1:8317/api/provider/codex"
env_key = "CLIPROXY_API_KEY"
wire_api = "responses"
requires_openai_auth = false
supports_websockets = false
```

If a `cliproxy` provider already exists with a custom `env_key`, CCS preserves that key and injects the managed token under the same environment variable for the spawned Codex process. Users should not need to add `CLIPROXY_API_KEY` to their shell profile after updating CCS.

```
CCS profile resolution
  |
  v
Credential build (provider, API key, base URL)
  |
  v
Codex binary detection + capability probe
  |
  v
Transient -c overrides injected:
  -c model_provider="ccs_runtime"
  -c model_providers.ccs_runtime.base_url="..."
  -c model_providers.ccs_runtime.env_key="CCS_CODEX_API_KEY"
  -c model_providers.ccs_runtime.wire_api="responses"
  |
  v
CCS_CODEX_API_KEY set in process env
  |
  v
Codex CLI spawned (replaces CCS process)
```

## Target Resolution Priority

CCS resolves the target CLI in this order:

| Priority    | Source                  | Example                           |
| ----------- | ----------------------- | --------------------------------- |
| 1 (highest) | `--target` flag         | `--target codex`                  |
| 2           | `argv[0]` binary name   | calling via `ccsx` or `ccs-codex` |
| 3           | Profile `target` config | `target: codex`                   |
| 4 (default) | Fallback                | `claude`                          |

<Note>
  API profiles and CLIProxy variants can persist `target: codex` in config. Use `--target codex` for one-off launches and persisted targets for profiles that should default to Codex.
</Note>

## Built-in Aliases

| Binary Name                             | Target                   | Notes                                                                                                               |
| --------------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------- |
| `ccs-codex`                             | `codex` (built-in)       | Any profile on Codex CLI                                                                                            |
| `ccsx`                                  | `codex` (short alias)    | Any profile on Codex CLI                                                                                            |
| `ccsxp`                                 | `codex` (power shortcut) | Forces `ccs codex --target codex`, ignores user `--target` overrides, and uses native `~/.codex` history by default |
| Custom via `CCS_TARGET_ALIASES`         | `codex`                  |                                                                                                                     |
| Custom via `CCS_CODEX_ALIASES` (legacy) | `codex`                  |                                                                                                                     |

### Custom Aliases

```bash theme={null}
# Modern approach (unified env var)
export CCS_TARGET_ALIASES='codex=mycodex'

# Legacy approach (still supported)
export CCS_CODEX_ALIASES='mycodex'

# Create matching launcher
ln -s $(which ccs) /usr/local/bin/mycodex
mycodex "your prompt"
```

## Supported Profile Types

Codex is intentionally narrower than Claude or Droid in which profile types it accepts:

| Profile Type                 | Supported | Notes                                                     |
| ---------------------------- | --------- | --------------------------------------------------------- |
| `default`                    | Yes       | Native Codex auth/config, no CCS routing                  |
| `cliproxy` provider=`codex`  | Yes       | Routed through CLIProxy Codex Responses bridge            |
| `settings` with Codex bridge | Yes       | Only when API profile resolves to a Codex CLIProxy bridge |
| `cliproxy` composite         | No        | Not proven native-Codex-safe                              |
| `settings` generic API       | No        | Claude/Droid only                                         |
| `account`                    | No        | Claude-only account isolation                             |
| `copilot`                    | No        | Not a native Codex provider path                          |

<Warning>
  If your Codex binary does not support `--config` overrides, CCS will throw an error for non-default profiles. Upgrade Codex before using CCS-backed Codex profiles.
</Warning>

## Model Aliases (Reasoning + Service Tier)

Codex models accept trailing tuning suffixes that CCS translates into the
underlying `reasoning_effort` and `service_tier` fields:

| Suffix                                           | Effect                                            |
| ------------------------------------------------ | ------------------------------------------------- |
| `-minimal`, `-low`, `-medium`, `-high`, `-xhigh` | Sets `reasoning_effort`                           |
| `-fast`                                          | Sets `service_tier: priority` (Codex "fast" mode) |

Combine in either order:

```bash theme={null}
ccs codex --model gpt-5.4-minimal       # minimal reasoning, default tier
ccs codex --model gpt-5.4-high          # high reasoning, default tier
ccs codex --model gpt-5.4-fast          # default reasoning, priority tier
ccs codex --model gpt-5.4-high-fast     # high reasoning + priority tier
ccs codex --model gpt-5.4-fast-high     # equivalent
```

Use `--thinking` for cross-provider control; use suffix aliases when you need
to pin a model identity (e.g., in saved profiles or API payloads).

## Environment Variables

| Variable             | Description                                                                                   |
| -------------------- | --------------------------------------------------------------------------------------------- |
| `CCS_TARGET_ALIASES` | Unified alias map (e.g., `codex=mycodex`)                                                     |
| `CCS_CODEX_ALIASES`  | Legacy comma-separated argv0 names for codex target                                           |
| `CCS_CODEX_API_KEY`  | Injected at runtime for CCS-backed profiles (do not set manually)                             |
| `CLIPROXY_API_KEY`   | Injected at runtime for `ccsxp` when the Codex `cliproxy` provider uses the default `env_key` |
| `CCSXP_CODEX_HOME`   | Optional history/config root override for `ccsxp`; otherwise native `~/.codex` is used        |

## Native Codex Auth Profiles

`ccsx auth` manages native Codex account profiles under `~/.ccs/codex-instances/`.
After creating a profile, launch it directly by name:

```bash theme={null}
ccsx auth create work
ccsx work "your prompt"
```

`ccsx <name>` resolves `<name>` from the Codex profile registry before normal
CCS profile resolution, so Codex profiles stay separate from Claude account
profiles. `ccsxp` is intentionally separate from `ccsx auth`; it ignores
`CCS_CODEX_PROFILE` and keeps using its CLIProxy Codex pool behavior.

Each `ccsx auth` profile keeps its own `auth.json`, history, and sessions, while
linking shared native Codex resources from `~/.codex`: `config.toml`, `agents/`,
and `skills/`. `ccsx auth create <name>` and `ccsx <name>` both repair those
links idempotently, so relative Codex agent role entries such as
`agents/reviewer.toml` continue to resolve inside the isolated `CODEX_HOME`.

If you launch `ccsx` from your home directory, native Codex may also report that
`~/.codex/config.toml` contains user-level-only keys such as `model_providers` or
`notify` in a project-local config. That warning comes from Codex's current
working directory config discovery, not from `ccsx auth` profile selection.

## Dashboard: Codex Page

The dashboard includes a dedicated Codex page at `ccs config` -> Sidebar -> Compatible -> Codex CLI, with three tabs:

### Overview Tab

* **Binary detection** -- shows whether Codex CLI is installed and its path
* **Config file status** -- checks `~/.codex/config.toml` existence and validity
* **Supported flows table** -- which profile types work with Codex target
* **Quick command snippets** -- copy-paste starters for common Codex commands

### Control Center Tab

Guided editor for the user-layer Codex config (`~/.codex/config.toml`):

* **Top-level settings** -- model defaults, history, instructions
* **Project trust** -- trusted directory paths (validated as absolute or `~/...`)
* **Profiles** -- named configuration profiles
* **Model providers** -- custom provider endpoints
* **MCP servers** -- Model Context Protocol server configuration
* **Feature flags** -- toggle experimental features (reset to Codex defaults available)

<Note>
  The Control Center edits only the user config layer. The effective runtime config may differ due to trusted repo layers, CCS transient overrides (`-c` flags, `CCS_CODEX_API_KEY`), and the `ccsxp` managed `model_providers.cliproxy` repair.
</Note>

**Raw TOML editor** is available as an escape hatch for unsupported or fidelity-sensitive edits. Structured controls are disabled while raw TOML is dirty or invalid.

### Docs Tab

* Upstream Codex documentation links
* CLIProxy provider setup guidance
* CCS Codex adapter reference

## Security

* **No persisted credentials** -- API keys are injected into the spawned Codex process, not written to `~/.codex/config.toml`
* **Scoped provider repair** -- `ccsxp` may create or repair `[model_providers.cliproxy]`, but does not store the API key there
* **Process-scoped keys** -- `CCS_CODEX_API_KEY` exists only in the spawned process environment
* **Anthropic env stripping** -- CCS removes stale `ANTHROPIC_*` env vars before spawning Codex
* **Binary validation** -- Codex binary is probed for capability before credential injection

## Usage Examples

```bash theme={null}
# Default Codex session (native auth)
ccsx "explain this code"

# Named native Codex auth profile
ccsx work "summarize this repo"

# CCS-backed Codex via CLIProxy bridge
ccsx codex "implement auth flow"

# Codex-on-Codex power shortcut (strips any --target override)
ccsxp "your prompt"

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

# With reasoning effort
ccsx codex --effort xhigh "deep analysis"
```

<Note>
  `ccsxp` is an opinionated shortcut equivalent to native Codex using CCS's CLIProxy Codex pool. It strips any user-supplied `--target` flags, repairs the native `cliproxy` provider entry when needed, and injects the managed token into the provider's configured `env_key`. By default, `ccsxp` pins `CODEX_HOME` to native `~/.codex` so history and resume state stay with regular Codex sessions. Set `CCSXP_CODEX_HOME` only when you intentionally want a separate ccsxp history root.
</Note>

## Related

* [Codex Provider](/providers/oauth/codex) -- OAuth authentication and model configuration
* [Droid Adapter](/features/workflow/droid-adapter) -- Alternative CLI target (Factory Droid)
* [Dashboard](/features/dashboard/overview) -- Visual configuration interface
* [Target Architecture](/reference/architecture) -- Technical details of the adapter system