Codex Adapter
CCS can delegate execution to the OpenAI Codex CLI as a native runtime target. Unlike the Droid adapter which persists credentials to disk, the Codex adapter uses transient -c overrides and environment variable injection — no files are rewritten.
Quick Start
# Run with explicit target flag
ccs codex --target codex
# Use built-in aliases
ccs-codex "your prompt"
ccsx "your prompt"
# Codex-on-Codex shortcut (forces ccs codex --target codex)
ccsxp "your prompt"
# Native Codex session (default profile, no CCS routing)
ccsx codex "your prompt"
How It Works
The Codex adapter is runtime-only in v1. It never rewrites ~/.codex/config.toml. Instead:
- 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
- The Codex binary is probed for
--config support before attempting overrides
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 (default) | Fallback | claude |
Unlike Claude and Droid targets, Codex does not support per-profile target: codex in config.yaml. Target resolution is CLI-only in v1.
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 |
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.
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) |
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 and CCS transient overrides (-c flags, CCS_CODEX_API_KEY).
Docs Tab
- Upstream Codex documentation links
- CLIProxy provider setup guidance
- CCS Codex adapter reference
Security
- No disk writes — credentials are never persisted to
~/.codex/config.toml
- 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"
# 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 ccs codex --target codex. It strips any user-supplied --target flags before forcing the Codex-on-Codex route, making it the fastest way to launch CCS’s built-in Codex provider on the native Codex CLI.
