Codex CLI

Codex CLI is OpenAI's coding agent. One-click setup is recommended; manual setup needs config.toml and OPENAI_API_KEY.

Recommended: one-click setup

Generate the setup command

Select One-Click Setup beside the key, choose Codex CLI, confirm macOS / Linux or Windows PowerShell, then click Generate Setup Command and copy it.

Paste the command into Terminal on macOS, any terminal on Linux (curl must be installed), or PowerShell on Windows, and run it. When it completes, reopen the terminal and run codex. The script installs Codex CLI with npm: if Node.js is missing, it only writes the configuration, so install Node.js LTS and then run npm install -g @openai/codex.

For a graphical setup, follow the CC Switch guide, select Import CCS from the key menu, and choose Codex CLI.

One-click setup rewrites config.toml.

The existing file is backed up as config.toml.bak.<timestamp>. The new configuration sets model = "gpt-6-astra", model_reasoning_effort = "xhigh", and requires_openai_auth = true; the key is written to ~/.codex/auth.json, and no environment variable is set. xhigh is the highest reasoning level and uses the most tokens; switch to high or medium for everyday work.

Reasoning levels and groups

Setting	Details
`model_reasoning_effort`	`low` / `medium` / `high` / `xhigh`; higher levels think longer and use more tokens
Codex Plus / Codex Pro groups	Both groups offer the same models: `gpt-6-astra`, `gpt-6-sol`, `gpt-6-luna`, `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`, and `gpt-5.5`. `GET /v1/models` with the current key is authoritative
Image generation	Codex groups do not offer `gpt-image-`. For images, add the GPT Image (all models)* group to your key; see Image generation API

Manual setup: edit config.toml

System	Configuration file
macOS / Linux	`~/.codex/config.toml`
Windows	`C:\Users\your-name\.codex\config.toml`

Create the file if it does not exist, then add:

model_provider = "hopbase"
model = "gpt-5.6-sol"

[model_providers.hopbase]
name = "HopBase"
base_url = "https://api.hop-base.com/v1"
wire_api = "responses"
env_key = "OPENAI_API_KEY"

Do not mix the two key methods.

Manual setup reads the key from an environment variable through env_key; one-click setup uses requires_openai_auth = true with auth.json. Do not combine requires_openai_auth = true with the environment-variable method in one configuration: in Codex 0.153 testing, that combination sends no key and the gateway returns 401 missing_api_key.

Set the key and start Codex:

Temporary settings apply only to the current terminal window:

export OPENAI_API_KEY=sk-your-key
codex

Persistent settings belong in your shell startup file:

# zsh (the macOS default)
echo 'export OPENAI_API_KEY=sk-your-key' >> ~/.zshrc
source ~/.zshrc

# bash (common on Linux; use this instead of the zsh block)
echo 'export OPENAI_API_KEY=sk-your-key' >> ~/.bashrc
source ~/.bashrc

Web search and remote compaction are not supported.

Codex web search requests /v1/alpha/search, and remote context compaction requests /v1/responses/compact. Neither endpoint is supported yet; both return 404. The web-search 404 does not affect normal conversations. Turn off web search in Codex if you do not want to see it.

Use a Codex group key.

Use a key from a Codex group (Codex Plus / Codex Pro). For slow responses or 502 / 503 errors, follow Error codes and retries. See Troubleshooting when setup fails.

Next steps

CC Switch: connect Codex App, or switch between several keys
OpenAI SDK: call the same GPT models from your own code
Troubleshooting: look up an error message

Recommended: one-click setup

Select a Codex group key

Generate the setup command

Run and verify

Reasoning levels and groups

Manual setup: edit config.toml

Next steps

On this page