How to Install OpenAI Codex CLI on Windows, macOS, and Linux (2026)

Short answer

Codex CLI installs with one command — npm install -g @openai/codex — on Windows, macOS, and Linux; all you need is Node.js. On Windows it runs natively in PowerShell; WSL is optional. Check it with codex --version. To actually do work, Codex needs access to OpenAI models: either sign in with a ChatGPT account, or connect an API key in ~/.codex/config.toml — the second route is pay-per-token with no subscription. Below: installation on each system, the errors people hit most often, and connecting through TeamoRouter.

What you need

Install on Windows

1. Install Node.js

Download the LTS build from nodejs.org and install with the defaults. Or, in PowerShell:

winget install OpenJS.NodeJS.LTS

Close and reopen PowerShell, then check:

node --version
npm --version

2. Install Codex CLI

In PowerShell (no administrator rights needed):

npm install -g @openai/codex

3. Verify

codex --version

Output like codex-cli 0.158.0 means you're set.

OpenAI also ships a standalone PowerShell installer that downloads from chatgpt.com / releases.openai.com. It's an alternative to npm in regions where OpenAI operates; where those sites are unreachable, npm gives the same result.

The Windows sandbox

Codex runs commands in a sandbox — an isolated environment that keeps the agent from changing files outside your project. On Windows it has two modes:

• elevated (the default choice) — creates a dedicated low-privilege user; the first time, Windows shows a User Account Control (UAC) prompt that you need to approve;
• unelevated (the fallback) — runs as your own user with restricted rights; use it when elevated setup fails, for example because of company policy.

If sandbox setup fails, switch the mode in config.toml (creating the file is covered below):

[windows]
sandbox = "unelevated"

Do I need WSL?

No. Codex runs in PowerShell directly. WSL2 makes sense if your project and tooling already live in Linux: install it with wsl --install, open Ubuntu, and follow the Linux steps below.

Install on macOS

With Homebrew:

brew install codex

Or with npm (Node.js required, e.g. brew install node):

npm install -g @openai/codex

Check with codex --version.

Install on Linux and WSL

Install Node.js 22 from nodejs.org or a version manager, then:

npm install -g @openai/codex
codex --version

If npm fails with a permissions error (EACCES), don't use sudo — move global packages into your home folder:

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
npm install -g @openai/codex

Update and uninstall

Codex updates often, and new models only work in recent versions. To update:

npm install -g @openai/codex@latest

With Homebrew on macOS: brew upgrade codex. To uninstall: npm uninstall -g @openai/codex.

First run: sign in or use an API key

Run codex right after installing and it offers to sign in with a ChatGPT account; usage then counts against your ChatGPT plan's limits. The alternative is an API key: you pay per token, there are no plan limits that reset every few hours, and you can use the same key for other agents. Codex supports this natively through custom model providers.

1. Get a key

Register on TeamoRouter, top up your balance, and create an API key in the console.

2. Create config.toml

Windows (PowerShell):

New-Item -ItemType Directory -Force -Path "$HOME\.codex" | Out-Null
@'
model_provider = "teamorouter"
model = "gpt-6-sol"
model_reasoning_effort = "high"

[model_providers.teamorouter]
name = "TeamoRouter"
base_url = "https://api.teamorouter.cn/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"
'@ | Set-Content -Path "$HOME\.codex\config.toml" -Encoding UTF8

macOS and Linux:

mkdir -p ~/.codex && cat > ~/.codex/config.toml <<'EOF'
model_provider = "teamorouter"
model = "gpt-6-sol"
model_reasoning_effort = "high"

[model_providers.teamorouter]
name = "TeamoRouter"
base_url = "https://api.teamorouter.cn/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"
EOF

If you switched the Windows sandbox mode, add the [windows] block to the end of the same file.

3. Set the key

Windows (PowerShell):

[Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "your TeamoRouter key", "User")

Close the PowerShell window and open a new one.

macOS:

echo 'export OPENAI_API_KEY="your TeamoRouter key"' >> ~/.zshrc
source ~/.zshrc

On Linux, the same but in ~/.bashrc.

4. Run it

Go to your project folder and run codex. Start with "briefly describe the structure of this project" — if an answer comes back, the connection works. The default model is GPT-6 Sol; how it compares with Luna and Astra is covered in the GPT-6 Sol article. Pricing is on the pricing page; you can top up by card or USDT.

Common install errors

Windows: codex.ps1 cannot be loaded because running scripts is disabled on this system. PowerShell blocks scripts by default, and npm creates a script wrapper for Codex. Allow scripts for your user and reopen PowerShell:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

Windows: The term 'codex' is not recognized as the name of a cmdlet…. The terminal can't see global npm packages. Close and reopen PowerShell after installing. If that doesn't help, run npm config get prefix and make sure that folder is on your PATH.

macOS / Linux: EACCES: permission denied. npm has no rights to the system folder. Don't install with sudo — use the fix from the Linux section above, or install Node.js through a version manager.

Windows: sandbox setup fails. Usually a declined UAC prompt or a machine policy. Approve the prompt on the next run, or switch to sandbox = "unelevated" as described above.

Error loading config.toml: wire_api = "chat" is no longer supported. A configuration from an old guide. Replace wire_api = "chat" with wire_api = "responses". We reproduced this message ourselves on Codex CLI 0.158.0.

After installing: unexpected status 401 Unauthorized / 404 Not Found … url: https://api.teamorouter.cn/responses. A 401 means the key is wrong or was copied incompletely; create a new one. A 404 with …/responses (no /v1) means base_url is missing /v1.

FAQ

What's the difference between Codex CLI and the Codex app? The CLI runs in a terminal, the app in a window; they share the key and config.toml. See Codex CLI vs the desktop app, and the desktop app setup guide.

Does Codex CLI work on Windows 10? Yes, from version 1809. Windows 11 is recommended.

How do I check my Codex version? codex --version.

Can I install Codex without npm? On macOS, with Homebrew (brew install codex). On Windows, with OpenAI's PowerShell installer.

Do I need a ChatGPT subscription? Not with an API key — you pay only for tokens used.

Next steps

• Codex CLI setup guide — the short version, plus Fast Mode.
• GPT-6 Sol API — which model to pick.
• Create an API key.