English

No-login setup · Visual tools

Start with CC Switch, then solve the unusual cases

You do not need to find config files. Download CC Switch, choose Codex, add your API, and click Enable. Use the diagnostics below only for 401, 404, or protocol errors.

Request free API accessRead the full setup guide
Top pickWindows · macOS · Linux

CC Switch

Manage Codex APIs, models, and providers in one desktop interface. Pick a preset, paste a key, and enable it—without hunting for auth.json or config.toml.

✓ Visual provider management✓ One-click Codex switching✓ Chat → Responses translation✓ Config backups

Choose your system

Recommended install

brew install --cask cc-switch

Download CC Switch ↗GitHub ↗

Open-source third-party tool. Verify the publisher and latest release on GitHub before downloading.

CC Switch
ClaudeCodexGemini

My GPT API

Active · Responses

DeepSeek

Local routing available

  1. 1

    Open the Codex tab

    Claude, Codex, and Gemini are managed separately. Start in Codex.

  2. 2

    Add a provider

    Choose a preset or enter Base URL, key, and model. Enable local routing when translation is needed.

  3. 3

    Click Enable

    CC Switch writes the config. Fully restart the Client or open a new CLI terminal.

config.toml generator

Enter a provider name, Base URL, and model. The user-level config updates live. This tool never asks for or collects your API key.

Enter an environment variable name here, not a secret beginning with sk-. Keep the real key in your own shell or credential store.

Copy into ~/.codex/config.toml

model_provider = "my-gateway"
model = "gpt-5.6"

[model_providers.my-gateway]
name = "my-gateway"
base_url = "https://api.example.com/v1"
wire_api = "responses"
env_key = "OPENAI_API_KEY"
requires_openai_auth = false
Free mini-tool · pick a symptom

Codex error doctor

Skip the long guide first. Pick the symptom on your screen and inspect the most likely causes in order.

Most likely problem

The key Codex reads does not match the target API, or requires_openai_auth made it use the official login cache.

Check in this order

  1. 1env_key must contain an environment variable name, not the sk- secret.
  2. 2Run printenv for that variable in the same terminal that starts Codex.
  3. 3Custom gateways normally use requires_openai_auth = false.
  4. 4After switching from official auth, fully quit Client and open a new terminal.

CC Switch — provider switching for Codex

For people with multiple APIs. It switches providers and can locally translate Chat Completions into the Responses protocol Codex expects. Open a new terminal / restart the Client after every switch.

Files it touches

  • ~/.codex/auth.json
  • ~/.codex/config.toml
  1. 1Install CC Switch and switch the top bar to Codex (not Claude).
  2. 2If you want to preserve the official account, remote control, or official plugins, complete official login first, then enable Settings → General → Codex App Enhancements → Keep official login when switching third-party providers.
  3. 3Click + and enter Base URL, API key, and model. Responses-native gateways connect directly; Chat-Completions-only providers need local routing.
  4. 4For protocol translation, open Settings → Routing → Local Routing, turn on the main service, then enable Codex under Routing Enabled.
  5. 5Enable the provider and inspect ~/.codex/config.toml for the expected model_provider, base_url, and model.
  6. 6Quit running Codex: close the terminal window; fully quit the Client.
  7. 7Open a new terminal, run codex (or reopen the Client), send a short message.
  8. 8Finally inspect CC Switch route logs or provider balance to prove where the request landed.
FieldWhat to put
Base URLAPI root. Compatible hosts often include /v1; homepage URLs 404.
wire_api / protocolCodex speaks responses. Enable local routing for chat/completions-only gateways.
API KeyThe newer enhancement mode can place third-party auth in provider-scoped config while preserving official auth.json.
modelDefault model id your gateway actually serves.
Full URL modeEnable when the vendor requires an exact upstream URL with no path joining.

Troubleshooting

Enabled but still on the old provider

Suspect a stale terminal first. Then cat ~/.codex/config.toml.

404 / Unsupported endpoint

Check /v1, trailing slashes, and whether Responses exists on the gateway.

You only edited the Claude tab

Codex has its own provider list. Switch the top bar to Codex.

Official ↔ third-party flipping

With auth preservation enabled, auth.json keeps official identity while config.toml routes third-party model calls. Restore a backup and check the enhancement toggle if identity is overwritten.

CC Switch is most useful for frequent switches or protocol translation. Its write behavior can change by version, so back up ~/.codex first and never race GUI writes with hand edits.

Hand-written auth.json

Same end state as CLI login in file mode — without a GUI.

Files it touches

  • ~/.codex/auth.json
  1. 1Ensure cli_auth_credentials_store is file (or auto falling back to file).
  2. 2Write OPENAI_API_KEY; chmod 600 is safer.
  3. 3Custom base_url still needs user-level model_providers.
  4. 4Restart CLI / Client.

Never commit auth.json or paste it into chat.

Hand-written config.toml

Best when the gateway is fixed or you need reviewable snippets. Full field notes live in the setup guide.

Files it touches

  • ~/.codex/config.toml
  1. 1User-level only — project providers are ignored.
  2. 2model_provider must match [model_providers.xxx].
  3. 3wire_api = "responses"; env_key is a variable name.
  4. 4export the secret, then open a new terminal.

Connectivity check

Prove the gateway and key before blaming Codex.

  1. 1Hit the base_url from your email/console with a Bearer token (path per provider docs).
  2. 2401 → key/ACL; 404 → path/protocol; TLS/timeout → network.
  3. 3Only then login or Enable in CC Switch.

Shell multi-profile snippets

Juggle an official key and a gateway with shell functions; for many profiles prefer CC Switch or Codex --profile.

  1. 1Add functions in ~/.zshrc that export different KEY names.
  2. 2Run the function, then start a fresh Codex session.
  3. 3Ensure env_key points at the variable you just exported.

Keep digging: Codex companions worth bookmarking

Not every GitHub project belongs here. These fill real gaps in account switching, provider management, and protocol translation, with cautions included.

CodexSwitch CLI

Account & provider switcher

Save official accounts, API keys, and custom providers as local profiles, then switch atomically and inspect status.

It manages local credentials and optional config.toml. Review managed_config_keys and back up ~/.codex first.

Open source project ↗

codex-proxy

Responses translation

Accept Codex /v1/responses locally and forward to APIs that only support Chat Completions or Anthropic Messages.

Upstream keys live under ~/.codexproxy and config changes require a proxy restart. Review the project before local use.

Open source project ↗

codex-as

Lightweight profile launcher

For shell users: keep OAuth, API-key, and custom-provider setups separate, then launch Codex by profile.

Third-party scripts touch config and credentials. Inspect storage paths, permissions, and recovery before install.

Open source project ↗

CC Switch

Desktop switching & routing

Graphical provider management with official-auth preservation, backups, and local Chat → Responses routing.

Write behavior can change by version. Recheck auth.json, config.toml, and enhancement toggles after upgrades.

Open source project ↗

FAQ

Can I mix CC Switch and hand edits?

Yes, but don’t race the same files. After changes, verify ~/.codex on disk.

Why does Claude hot-reload but Codex needs a restart?

Codex caches the route at process start. Always open a new terminal or restart the Client.

Gateway only has chat/completions?

Current Codex needs Responses. Use a Responses-capable host, or a local translating route (some CC Switch builds offer takeover).

Also see: Free API · Client + CLI