Codex Adapter
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
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) |
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
--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, 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)
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.
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.
