Codex CLI

OpenAI's command-line coding agent. The command is codex, the configuration directory is ~/.codex, and the npm package is @openai/codex.

On 2026-09-22, stable Codex CLI 0.155.1 completed a minimal live call with gpt-5.5 and the environment-variable configuration below. This does not establish equivalent desktop app or CC-Switch verification.

Method	Best for
CC-Switch GUI	Avoiding config files, and switching between providers quickly
Hand-written config.toml	Precise control over models and parameters, or use on Linux/servers

Use the Responses API

The verified configuration uses wire_api="responses". Your model must support /v1/responses; Chat Completions success does not establish Responses support, and failures do not always return not implemented. See Vendor differences.

Before you start

You need an API Key with available quota. Copy model names from the model list — they are case-sensitive.

Windows one-click setup

Don't want to install the CLI, set environment variables, and edit config.toml by hand? GSS Deploy (Windows one-click setup) can do it automatically. Windows only; follow the steps below on macOS or Linux.

Installing Codex CLI

OS	Command
Windows	`irm https://chatgpt.com/codex/install.ps1 \| iex` (PowerShell, no admin rights needed)
macOS	`curl -fsSL https://chatgpt.com/codex/install.sh \| sh`, or `brew install --cask codex`
Linux	`curl -fsSL https://chatgpt.com/codex/install.sh \| sh`

With Node.js installed, npm install -g @openai/codex works on all three.

Verify the install:

codex --version

Method 1: CC-Switch (GUI)

Download, install and run it from sourceforge.net/projects/cc-switch.mirror.

Click OpenAI in the middle of the top navigation bar
Click + in the top-right to add a provider
Fill in:

Field What to enter
Provider name TokenRoute (your choice)
Website https://www.tokenroute.com/
API Key Your API Key
API endpoint https://api.smartwan.com/v1
Click Save

Field	What to enter
Provider name	`TokenRoute` (your choice)
Website	`https://www.tokenroute.com/`
API Key	Your API Key
API endpoint	`https://api.smartwan.com/v1`

Then run codex and send a test message. A reply means you're set.

Method 2: Hand-written config.toml

See the official configuration guide. A custom provider must go in the user-level ~/.codex/config.toml. Project-level .codex/config.toml does not support defining model_provider or model_providers.

1. Set the environment variable

env_key takes an environment variable name, not the key itself — never put the key in the config file.

OS	Command
Windows (PowerShell)	`$env:TOKENROUTE_API_KEY = "sk-your-token"`
macOS / Linux	`export TOKENROUTE_API_KEY="sk-your-token"`

That only applies to the current session. To persist:

Windows: setx TOKENROUTE_API_KEY "sk-your-token", or press Win+R, run sysdm.cpl and add it under "Advanced → Environment Variables → User variables". setx does not update already-running programs — open a new terminal and start Codex CLI so the new process can read the updated variable.
macOS / Linux: add it to ~/.zshrc or ~/.bashrc.

Confirm a new process picked it up (without printing the key):

if ($env:TOKENROUTE_API_KEY) { "found" } else { "not found" }

Don't echo the key

echo $env:TOKENROUTE_API_KEY puts your real key in the terminal and any screenshot. Use the check above instead.

2. Write the config file

mkdir -p ~/.codex

In Windows CMD, use mkdir %USERPROFILE%\.codex. In PowerShell, use New-Item -ItemType Directory -Force "$env:USERPROFILE\.codex".

~/.codex/config.toml:

model_provider = "tokenroute"
model = "gpt-5.5"
model_reasoning_effort = "low"

[model_providers.tokenroute]
name = "TokenRoute"
base_url = "https://api.smartwan.com/v1"
env_key = "TOKENROUTE_API_KEY"
wire_api = "responses"

Four easy mistakes

wire_api must be "responses"
env_key takes the variable name, not the key
model and model_reasoning_effort must be at the top level, not nested inside [model_providers.tokenroute]
If the file has duplicate notify = [...] lines, keep only one

On Windows, make sure the file extension is .toml and not .txt — if you can't see extensions, enable "File name extensions" under the Explorer "View" menu.

3. Restart and verify

Restart Codex CLI after editing the configuration. Open a new terminal after changing persistent environment variables.

codex --version
codex

If your Windows installation uses the versioned directory below, call it from PowerShell after replacing <version>. Use the actual executable path for other installation methods. A loaded configuration still needs a minimal live call to verify it:

& "$env:LOCALAPPDATA\OpenAI\Codex\bin\<version>\codex.exe" doctor

Alternative auth: auth.json

This uses Codex's own OpenAI auth mode — drop env_key and set requires_openai_auth instead:

model_provider = "tokenroute"
model = "gpt-5.5"
model_reasoning_effort = "low"

[model_providers.tokenroute]
name = "TokenRoute"
base_url = "https://api.smartwan.com/v1"
wire_api = "responses"
requires_openai_auth = true

The key lives in ~/.codex/auth.json:

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

Newer Codex builds may store it in Windows Credential Manager instead.

Pick one — never mix

Recommended: env_key + a system environment variable
Compatibility: requires_openai_auth = true + Codex credential store

requires_openai_auth = true reads Codex's own credential store and ignores the provider's environment variable, so setting both does not help. It also occupies the generic OpenAI auth slot and may disturb your existing ChatGPT login — new users should prefer the environment variable route.

Deep verification

A config file that looks right, or a green overall codex doctor, does not prove calls work. Verify in four layers.

Layer 1: command available

codex --version

If codex isn't found, check the install and your PATH.

Layer 2: auth and provider are picked up

codex doctor --json

Check	Expected
`config.load`	`ok`, model and provider match `config.toml`
`auth.credentials`	`ok`; the env-var route shows the variable exists
`network.provider_reachability`	`ok`, base URL points at `https://api.smartwan.com/v1`
`network.websocket_reachability`	shows `responses` in use; no WebSocket doesn't affect normal calls

If your npm prefix differs from the actual Codex install directory, installation or updates.status may fail — that only affects upgrades, not your connection. Judge by the real call instead.

Layer 3: minimal real call (the deciding test)

codex exec `
  --ephemeral `
  --skip-git-repo-check `
  --sandbox read-only `
  --json `
  "Reply with OK only. Do not call any tools."

On success the output contains:

{"type":"item.completed","item":{"type":"agent_message","text":"OK"}}

followed by turn.completed and a clean exit. That single result proves the config loaded, the key was read, auth passed, /v1/responses routed, and the model replied.

Layer 4: bypass Codex and call the API directly

When the layers above fail, hit the API directly to tell a Codex problem apart from a gateway problem.

$headers = @{ Authorization = "Bearer sk-your-token" }

Invoke-RestMethod `
  -Uri "https://api.smartwan.com/v1/models" `
  -Headers $headers `
  -Method Get

Once /v1/models works, test Responses:

$headers = @{
  Authorization = "Bearer sk-your-token"
  "Content-Type" = "application/json"
}

$body = @{
  model = "gpt-5.5"
  input = "Reply with OK only"
} | ConvertTo-Json

Invoke-RestMethod `
  -Uri "https://api.smartwan.com/v1/responses" `
  -Headers $headers `
  -Method Post `
  -Body $body

These commands contain your key in plain text

Run them only in a trusted local terminal. Don't share the commands, screenshots or shell history. Rotate any key that has been exposed.

Reading the results

Result	Meaning
Codex replies `OK`	Config, auth, routing and model call all work
`/v1/models` returns a list	Key authentication is fine
`/v1/models` returns `Invalid token`	Problem with the key's value, status, expiry or quota
Model list works but Responses fails	The model may not support the Responses API, or routing is off
`not implemented`	This model has no Responses API support — pick another
Provider not found	`model_provider` doesn't match `[model_providers.<id>]`
Config won't load	Check for duplicate TOML keys, line endings, or a file saved as `config.toml.txt`

Desktop app

ChatGPT also has a desktop client, available from the Microsoft Store.

If the first message triggers Unable to send message, click OK, then click the black Set up button next to the input box to complete sandbox configuration.

Switch models from the dropdown below the input box.

Troubleshooting

Symptom	Fix
No `.codex` directory	Create the directory using the CMD / PowerShell example above
Provider not found	The top-level `model_provider` value must exactly match the ID in `[model_providers.xxx]`
Authentication failure	Confirm the environment variable is set and visible in the current terminal, and that the key starts with `sk-` and hasn't expired
404 or protocol mismatch	`base_url` must include `/v1`; confirm the model supports `/v1/responses`
Returns `not implemented`	That model doesn't support the Responses API — switch models
Desktop app suddenly stops working	Right-click the tray icon, quit, and reopen

To change models, edit the top-level model field in ~/.codex/config.toml, or reselect in CC-Switch. Take model names from Models and confirm Responses API support.

Installing Codex CLI​

Method 1: CC-Switch (GUI)​

Method 2: Hand-written config.toml​

1. Set the environment variable​

2. Write the config file​

3. Restart and verify​

Alternative auth: auth.json​

Deep verification​

Layer 1: command available​

Layer 2: auth and provider are picked up​

Layer 3: minimal real call (the deciding test)​

Layer 4: bypass Codex and call the API directly​

Reading the results​

Desktop app​

Troubleshooting​