CLIProxyAPI
macOS
Windows

Make Codex App share your CCS account pool

By default, Codex App signs in with one OpenAI OAuth identity. That is fine until you have several ChatGPT subscription accounts and want the app to use the same shared pool you already manage in CCS.

The practical fix: keep Codex App as the interface, point its provider config at local CLIProxyAPI, and let CCS handle account rotation, quota checks, pause/resume, and failover behind the scenes.

After setup: Codex App stays the UI; CCS handles routing behind the scenes.

Setup only changes provider routing and launch environment. It does not replace the app experience. Jump to setup.

config.toml
model_provider cliproxy
model_context_window 272000
wire_api responses
127.0.0.1:8317/api/provider/codex
Codex App
desktop UI

User-facing app stays unchanged.

CLIProxyAPI
127.0.0.1:8317

Local route that speaks Codex Responses.

CCS pool
quota + routing

Rotation, pause/resume, quota checks.

Install

Install Codex App from OpenAI docs

Use the official installation page for the current macOS and Windows app paths. After the app is installed, come back here for CLIProxyAPI routing.

Open official install docs

New to CCS?

CCS sits behind the Codex App route

CCS is the routing layer for Codex account pooling: it manages CLIProxyAPI, quota checks, pause/resume, and dashboard controls. The full Codex App setup is in the next section; the CCS guide is only extra background when you need the broader CCS workflow.

CCS Owns account pool, routing policy, quota visibility, and dashboard controls.
CLIProxyAPI Exposes the local Codex Responses endpoint on port 8317.
Open CCS guide

Setup Codex App with CCS/CLIProxyAPI

Make the desktop app route through the shared pool

Keep the roles clear: Codex App stays the desktop interface, CLIProxyAPI is the local endpoint, and CCS manages routing, account rotation, and quota visibility.

For macOS desktop, follow the steps below in order. After the final verify step, quit Codex App completely and reopen it.

127.0.0.1:8317/api/provider/codex
01

Install and add Codex accounts

Skip if CCS and Codex accounts are already set. Otherwise add accounts in ccs config, then check quota.

optional · ccs + accounts
# Skip this step if CCS is installed and Codex accounts are already in the pool.
npm install -g @kaitranntt/ccs

# Open CCS dashboard, then add accounts in CLIProxy -> Codex -> Accounts.
ccs config

# Confirm CLIProxyAPI can see Codex account state.
ccs cliproxy quota --provider codex
02

Save the current token in Keychain

CLIPROXY_API_KEY is the CLIProxyAPI gateway token. With CCS, the usual value is ccs-internal-managed; self-hosted proxy uses its own key.

shell · keychain
security add-generic-password \
  -a "$USER" \
  -s CLIPROXY_API_KEY \
  -w "$CLIPROXY_API_KEY" \
  -U
03

Create the auth helper

Write this helper file. Codex runs it to read the Keychain token from stdout.

shell · create file
mkdir -p "$HOME/.codex/bin"
touch "$HOME/.codex/bin/cliproxy-token"
file · $HOME/.codex/bin/cliproxy-token
#!/bin/zsh
set -euo pipefail

service="CLIPROXY_API_KEY"
account="${USER:-$(id -un)}"

token="$(security find-generic-password -a "$account" -s "$service" -w 2>/dev/null || true)"

if [[ -z "$token" ]]; then
  token="$(security find-generic-password -s "$service" -w 2>/dev/null || true)"
fi

if [[ -z "$token" ]]; then
  print -u2 "Missing Keychain item: service=$service account=$account"
  exit 1
fi

printf '%s\n' "$token"
shell · chmod 700
chmod 700 "$HOME/.codex/bin/cliproxy-token"
04

Point Codex App to CLIProxyAPI

Set cliproxy as provider and use the helper as auth command. model_context_window is only for custom proxy metadata; omit it on the native OpenAI/OAuth fallback.

toml · config.toml
model = "gpt-5.5"
# Optional for custom providers/proxies when Codex cannot infer model metadata.
# Omit this when falling back to native OpenAI/OAuth; Codex auto-detects there.
model_context_window = 272000
model_provider = "cliproxy"

[model_providers.cliproxy]
name = "CLIProxy"
base_url = "http://127.0.0.1:8317/api/provider/codex"
wire_api = "responses"

[model_providers.cliproxy.auth]
# Created in step 3
# If your Codex build does not expand $HOME here, replace it with the output of: echo "$HOME"
command = "$HOME/.codex/bin/cliproxy-token"
timeout_ms = 5000
refresh_interval_ms = 300000
05

Verify and restart Codex App

Check helper, Keychain, port 8317, and doctor. Reopen Codex App only when doctor shows 0 warn | 0 fail.

shell · verify
# Verify the helper can read a non-empty token from Keychain.
test -n "$("$HOME/.codex/bin/cliproxy-token")" && echo "Keychain helper OK"

# Verify the Keychain item exists. This prints metadata, not the token.
security find-generic-password -a "$USER" -s CLIPROXY_API_KEY

# Verify local CLIProxyAPI is listening on port 8317.
lsof -nP -iTCP:8317 -sTCP:LISTEN

# Verify Codex config/auth/connectivity. The important part is "0 warn | 0 fail".
codex doctor --summary --no-color --ascii

Provider switch

Keep a normal OAuth fallback when CLIProxyAPI is slow

Do not delete the CLIProxyAPI setup. Keep the cliproxy provider block, then either remove/comment out the active model_provider line or set it explicitly to openai. When unset, Codex defaults to the built-in openai provider. openai uses the normal Codex/OpenAI OAuth path and does not need model_context_window; cliproxy routes through CCS/CLIProxyAPI and may need it when metadata cannot be inferred.

Use normal OAuth path

Use this when CLIProxyAPI adds noticeable latency or the local proxy is unhealthy. model_provider = "openai" is explicit but optional; omitting model_provider also falls back to OpenAI. Codex App must already be signed in with ChatGPT/OpenAI OAuth.

toml · OAuth fallback
# Fast fallback when CLIProxyAPI feels slow
# Codex defaults to OpenAI when model_provider is unset.
# Either comment out/remove the CLIProxy selector, or set the fallback explicitly:
model_provider = "openai"

# Do not set model_context_window here.
# Native OpenAI/OAuth lets Codex auto-detect model metadata.

# Leave the [model_providers.cliproxy] block unchanged.
# Only change or remove the active model_provider line above.

Switch back to CLIProxyAPI

Use this again when you need CCS account rotation, quota checks, pause/resume, or failover.

toml · CLIProxyAPI route
# Switch back after CLIProxyAPI quota/latency looks healthy
model_provider = "cliproxy"

# Reuse the existing [model_providers.cliproxy] block and auth helper.

Verify after every switch

After changing or removing model_provider, run doctor once. Pass signal: 0 warn | 0 fail. Then fully quit and reopen Codex App so the desktop process reloads ~/.codex/config.toml.

shell · verify switch
codex doctor --summary --no-color --ascii
# OK when the summary ends with "0 warn | 0 fail".
# Then quit Codex App completely and reopen it.

Troubleshooting

Missing CLIPROXY_API_KEY on macOS

This is the case fixed by steps 3-5 above. If Codex App still says Missing environment variable: CLIPROXY_API_KEY, the active provider is probably still reading env_key from ~/.codex/config.toml instead of [model_providers.cliproxy.auth].

Why the setup avoids env_key

CLI launches may work because zsh/bash has CLIPROXY_API_KEY. Dock, Finder, Spotlight, and Login Items do not reliably inherit that shell env.

That is why the main setup uses [model_providers.cliproxy.auth] instead of env_key for macOS desktop.

toml · env_key mode to avoid on macOS desktop app
model_provider = "cliproxy"

[model_providers.cliproxy]
name = "CLIProxy"
base_url = "http://127.0.0.1:8317/api/provider/codex"
env_key = "CLIPROXY_API_KEY"
wire_api = "responses"

Plugin behavior

App plugin UI and CLI plugin runtime are gated differently

CLIProxyAPI does not automatically break plugin runtime. The catch is the Codex App Plugins UI: the bundled app disables the Plugins tab/sidebar when authMethod !== "chatgpt" and shows a tooltip like Please sign in with ChatGPT to use plugins.

Codex App UI

If routing through CLIProxyAPI makes the app fall into API-key auth mode, the Plugins browser/management UI will be disabled. To make that UI active again, Codex App must be authenticated with ChatGPT.

Codex CLI / agent runtime

Local plugins still work when config has [plugins."..."] enabled = true and the marketplace/cache files exist. This is separate from the Codex App Plugins browser UI.

CLIPROXY_API_KEY

Fallback: env_key mode

Skip this section if you completed the macOS Keychain helper setup above. Use it only when you intentionally keep env_key = "CLIPROXY_API_KEY" or when testing the unverified Windows path.

Windows expected path

Unverified

Use only if the Windows Codex App provider still uses env_key = "CLIPROXY_API_KEY". This has not been tested end-to-end on a Windows Codex App environment yet; verify from a new PowerShell session and a fresh Codex App launch before relying on it.

  • Open a new PowerShell session.
  • Confirm the user env value exists.
  • Restart Codex App.
  • Run `codex doctor` before relying on it.

Terminal-launched Codex only

Use only when Codex is started from zsh, bash, fish, or terminal-launched scripts while the provider still uses `env_key`.

shell · env
# zsh/bash
export CLIPROXY_API_KEY="ccs-internal-managed"

# fish
set -gx CLIPROXY_API_KEY ccs-internal-managed

macOS desktop fallback

Fallback only. Use this instead of the Keychain helper only if you intentionally keep `env_key`; you may need to repeat it after reboot.

shell · launchctl
launchctl setenv CLIPROXY_API_KEY ccs-internal-managed
launchctl getenv CLIPROXY_API_KEY

Windows

Unverified

PowerShell guidance for env_key mode. Treat this as expected behavior until it is tested on Windows Codex App.

powershell · unverified env_key
# PowerShell: current session
$env:CLIPROXY_API_KEY = "ccs-internal-managed"

# Persist for new Windows sessions
setx CLIPROXY_API_KEY "ccs-internal-managed"

# Verify in a new PowerShell after restarting the app
[Environment]::GetEnvironmentVariable("CLIPROXY_API_KEY", "User")
codex doctor --summary --no-color --ascii

Want Remote Control to share this route too?

This page only covers Codex App request routing. Remote Control has its own Codex path because it also needs an app server, remote identity checks, and session handoff behavior.

Remote Control for Codex