Codex CLI Setup

Overview

Codex CLI is OpenAI's official command-line AI coding tool. This guide covers Windows, Mac, and Linux.

Install Node.js and Git first — see Node.js and Git Setup. For one-click channel management, see CC-Switch Setup.

Install Codex CLI

Install

All three platforms share the same npm command:

npm install -g @openai/codex

Verify:

codex --version

A version number means the install succeeded.

Common issues

Q: permission denied / EACCES (Mac / Linux)

Don't use sudo. Move the npm global prefix to your home directory:

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc   # zsh users: ~/.zshrc
source ~/.bashrc

Q: permission denied (Windows)

Run PowerShell as Administrator:

npm config set prefix "$env:APPDATA\npm"
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Q: command not found: codex

The npm global bin directory is not on PATH. Run npm config get prefix to see the location, then append its /bin directory to the system PATH.

Configure the API

CC-Switch (recommended)

CC-Switch supports both Claude Code and Codex — no need to edit config files by hand, and channel switching is one click.

See CC-Switch Setup.

Note: Codex's Base URL must end with /v1 (unlike Claude Code).

Manual config files

Codex doesn't read environment variables — it reads two config files:

Edit config.toml

Create the .codex directory first if it doesn't exist. Windows: under %USERPROFILE%. Mac / Linux: mkdir -p ~/.codex.

model_provider = "custom"
model = "gpt-5.4"
model_reasoning_effort = "high"
disable_response_storage = true

[model_providers.custom]
name = "custom"
base_url = "https://your-api-url/v1"
wire_api = "responses"
requires_openai_auth = true
model_context_window = 1000000
model_auto_compact_token_limit = 900000

Edit auth.json

{
  "OPENAI_API_KEY": "sk-xxx"
}

Restart your terminal — codex will pick up the config on next launch.

Parameter reference

Get Started

Open a terminal in any project directory and run codex:

cd your/project
codex

Once the prompt appears, describe what you want in plain English (or Chinese), for example:

Implement a binary search tree in Python with insert, delete, and search methods