Connect a third-party API to Codex without ChatGPT sign-in

First: ChatGPT login vs API key

Only one credential is active at a time. CLI and Client share it; logging out of one clears both.

Check the active credential with codex login status. Clear with codex logout.

Three ways to attach a key

Platform keys or compatible gateway keys both work. Custom routes need a Responses-capable endpoint (since Feb 2026, wire_api only supports responses).

export OPENAI_API_KEY="sk-..."
printenv OPENAI_API_KEY | codex login --with-api-key
codex login status

{
  "OPENAI_API_KEY": "sk-your-key"
}

CLI: login through verification

Suggested order: export → pipe login → status → start codex. In CI, pipe from secrets — never print the key.

export OPENAI_API_KEY="sk-..."
printenv OPENAI_API_KEY | codex login --with-api-key
codex login status
codex

Setting OPENAI_API_KEY alone is not a login. For the built-in openai route, explicit --with-api-key (or a custom provider with env_key) is the reliable path.

Where credentials live: file / keyring / auto

Control with cli_auth_credentials_store in user-level ~/.codex/config.toml. Check this when login “worked” but nothing reads it.

cli_auth_credentials_store = "file"

auth.json is sensitive. Keep permissions tight; don’t sync it as plain text to shared drives.

Client: same login cache as the CLI

Desktop/app Clients read the same user-level cache. Logging out of one clears the other. Fully quit and reopen after config changes — closing a window is often not enough.

1. 1

   Confirm the user-level directory

   Default ~/.codex. CODEX_HOME relocates it — CLI and Client must agree on the path.

2. 2

   Log in via CLI or finish the provider block

   Clients rarely need a separate pipe-login; they reuse what the CLI already wrote.

3. 3

   Fully quit the Client, then reopen

   Forces a reload of auth.json and config.toml. If it still looks old, check user vs project scope next.

User-level vs project-level: providers belong in user config

One of the most common “I edited config and nothing changed” failures. Project .codex/config.toml can load when trusted, but provider-related keys are ignored.

config.toml: custom compatible gateway

Custom providers cannot reuse reserved ids: openai, ollama, lmstudio. model_provider must match the [model_providers.xxx] table name.

1. 1

   Edit only the user-level file

   Path: ~/.codex/config.toml (or $CODEX_HOME/config.toml).

2. 2

   env_key is a variable name, not the secret

   Example: env_key = "OPENAI_API_KEY", then export the real value in your shell.

3. 3

   Write base_url the way your gateway documents it

   Many compatible hosts end with /v1 and no trailing slash. Azure shapes differ (/openai vs /openai/v1) — follow what you were given.

4. 4

   Restart the session to verify

   New terminal for CLI; fully quit the Client. Or let CC Switch write the files, then restart the same way.

model_provider = "codexfree"
model = "gpt-5"

[model_providers.codexfree]
name = "CodexFree"
base_url = "https://YOUR-GATEWAY-HOST/v1"
wire_api = "responses"
env_key = "OPENAI_API_KEY"
env_key_instructions = "export OPENAI_API_KEY before starting Codex"
requires_openai_auth = false
request_max_retries = 4
stream_max_retries = 5
stream_idle_timeout_ms = 300000

Field cheat sheet

Older guides saying wire_api = "chat" are outdated. Chat Completions support was removed; only Responses remains. If a gateway only speaks /chat/completions, it needs Responses on the host — or a local route that translates (see the toolkit).

Lighter option: openai_base_url only

To point the built-in openai provider at a proxy/router, set openai_base_url in user-level config. For multiple vendors, different keys, or full provider fields, use model_providers.

openai_base_url = "https://YOUR-PROXY-HOST/v1"

Pitfall matrix

Symptom → check this first.

Do not trust the save button: verify the route in four steps

A saved file is not proof. Identity, config location, process state, and provider logs must all agree.

codex login status
printenv CODEX_HOME
cat ${CODEX_HOME:-$HOME/.codex}/config.toml
codex

1. Check 1

   Confirm the active identity

   login status must match the ChatGPT or API-key path you chose. If not, logout and repeat only one path.

2. Check 2

   Confirm the file being read

   Inspect CODEX_HOME. Provider settings belong in user config.toml, not project .codex.

3. Check 3

   Fully restart both surfaces

   Open a new terminal for CLI and fully quit the Client before reopening it. Closing a window may leave the process alive.

4. Check 4

   Send a short task and inspect upstream

   Check provider logs or balance. 401 means key, 404 means Base URL / Responses, and no record means a stale process or wrong model_provider.

FAQ