Codex Adapter

Available since v7.62.0

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

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

Default profiles pass through unchanged — uses native Codex auth/config
CCS-backed profiles inject credentials via temporary -c overrides
API keys are delivered through CCS_CODEX_API_KEY env var, not written to disk
Profile and variant configs may persist target: codex for default routing
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:

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

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.

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

# 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

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.

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:

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:

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. Native Codex resources stay shared from ~/.codex: config.toml, agents/, skills/, and plugins/cache/.

~/.ccs/codex-instances/<name>/
├── auth.json, history.jsonl, sessions/       # Profile-local state
├── config.toml -> ~/.codex/config.toml
├── agents/ -> ~/.codex/agents/
├── skills/ -> ~/.codex/skills/
└── plugins/                                  # Local parent for profile metadata
    └── cache/ -> ~/.codex/plugins/cache/     # Shared plugin payloads

Only the cache subtree is linked; the profile’s parent plugins/ directory remains local and may hold profile-specific plugin metadata. ccsx auth create <name> and direct ccsx <name> launches repair the shared links idempotently before Codex starts. This keeps relative entries such as agents/reviewer.toml valid and prevents stale first-launch skill warnings after plugin installs or updates.

On Windows, symlinks may require Developer Mode or elevated privileges. When a cache symlink is unavailable, CCS copies the current ~/.codex/plugins/cache/ snapshot into the profile. Later plugin updates may require another profile launch or ccsx auth create <name> --force repair to copy newly missing entries; existing profile-local cache files are preserved.

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)

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.

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

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

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.

Codex Provider — OAuth authentication and model configuration
Droid Adapter — Alternative CLI target (Factory Droid)
Dashboard — Visual configuration interface
Target Architecture — Technical details of the adapter system

Getting Started

Providers

Features

Tutorials

Codex Adapter

Codex Adapter

Quick Start

How It Works

Target Resolution Priority

Built-in Aliases

Custom Aliases

Supported Profile Types

Model Aliases (Reasoning + Service Tier)

Environment Variables

Native Codex Auth Profiles

Dashboard: Codex Page

Overview Tab

Control Center Tab

Docs Tab

Security

Usage Examples

​Codex Adapter

​Quick Start

​How It Works

​Target Resolution Priority

​Built-in Aliases

​Custom Aliases

​Supported Profile Types

​Model Aliases (Reasoning + Service Tier)

​Environment Variables

​Native Codex Auth Profiles

​Dashboard: Codex Page

​Overview Tab

​Control Center Tab

​Docs Tab

​Security

​Usage Examples

​Related

Codex Adapter

Quick Start

How It Works

Target Resolution Priority

Built-in Aliases

Custom Aliases

Supported Profile Types

Model Aliases (Reasoning + Service Tier)

Environment Variables

Native Codex Auth Profiles

Dashboard: Codex Page

Overview Tab

Control Center Tab

Docs Tab

Security

Usage Examples

Related