How to Install Codex CLI and Set Up config.toml (2026 Guide)

We ran every install method and config example below on an Apple-silicon Mac with Codex CLI 0.162.1 on October 15, 2026. Windows steps follow OpenAI's documentation. If you set Codex up from an older guide, check what changed first, because a few of the old config keys now stop Codex from starting.

Install methods at a glance

Pick one. Two installs of Codex on the same machine means your PATH order decides which one runs, and that gets confusing fast.

What changed in 2026

• There's an official standalone installer. You no longer need Node.js just to get Codex.
• wire_api = "chat" is gone. Codex only uses the Responses API now. Configs that still set chat fail to load.
• Profiles moved to their own files. Since 0.134.0, [profiles.name] tables inside config.toml no longer work with --profile.
• The Codex desktop app is now part of the ChatGPT desktop app.

Which plan you need

The CLI is free, and model usage is what you pay for:

• ChatGPT Plus, Pro, Business, Edu or Enterprise: Codex works in the CLI, IDE extension, web and desktop app, using your plan's included usage. Plus is $20/month.
• ChatGPT Free and Go: limited Codex access in the ChatGPT desktop app only, not in the CLI.
• OpenAI API key: works in the CLI and IDE extension and is billed at standard API rates. Cloud features like GitHub code review aren't available this way.
• A compatible provider or gateway: any service that implements the OpenAI Responses API. See custom providers.

Install on macOS and Linux

curl -fsSL https://chatgpt.com/codex/install.sh | sh

On our Mac this took 14 seconds:

==> Installing Codex CLI
==> Detected platform: macOS (Apple Silicon)
==> Resolved version: 0.162.1
==> Downloading Codex CLI
==> Installing standalone package to ~/.codex/packages/standalone/releases/0.162.1-aarch64-apple-darwin
==> Current terminal: export PATH="~/.local/bin:$PATH" && codex
==> Future terminals: open a new terminal and run: codex
==> PATH was added to ~/.zprofile
Codex CLI 0.162.1 installed successfully.

The installer puts a codex command in ~/.local/bin and adds that folder to your PATH for you, in ~/.zprofile on a Mac. That only applies to new terminal windows, so open one before running codex.

If it finds an existing npm, Homebrew or bun install, it warns Multiple managed Codex installs can be ambiguous and, when run interactively, offers to remove the old one. Saying yes saves you trouble later.

Install on Windows

Open PowerShell and run:

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

The -ExecutionPolicy ByPass part only relaxes PowerShell's script policy for this one command and doesn't change your system settings. Codex installs to %LOCALAPPDATA%\Programs\OpenAI\Codex\bin and runs natively on Windows with its own sandbox. You don't need WSL, though Codex works inside WSL2 too.

Install with npm or Homebrew

npm works on every platform:

npm install -g @openai/codex

added 2 packages in 2s

The two packages are the @openai/codex wrapper and the native binary for your platform, such as @openai/codex-darwin-arm64. The package declares Node.js 16 or later; we used Node 22. Avoid sudo npm install -g, which leaves root-owned files that break later updates.

Homebrew on macOS:

brew install --cask codex

The cask was current when we checked (0.162.1, same as npm).

Verify the install

Open a new terminal:

codex --version

codex-cli 0.162.1

For a full health check, run codex doctor. It inspects the install, config, sign-in, network, Git and sandbox without starting a session. On a fresh install that isn't signed in yet:

Codex Doctor v0.162.1 · macos-aarch64
   ✗ auth         no Codex credentials were found - Run codex login or provide an API key through a supported auth env var.
   ⚠ websocket    Responses WebSocket failed; HTTPS fallback may still work - Check proxy, VPN, firewall, DNS, custom CA, and WebSocket policy support.
  ✓ runtime      standalone (…)
  ✓ install      consistent
  ✓ search       file exists (bundled …)
  ✓ config       loaded

The auth failure goes away once you sign in. The websocket warning means Codex couldn't open a WebSocket connection. We saw it on a signed-out install behind a proxy. It isn't fatal, because Codex falls back to plain HTTPS. If it persists after you sign in, check your proxy, VPN or firewall, as the message suggests.

Sign in

Run codex inside a project folder. On first launch you choose:

• Sign in with ChatGPT to use your plan. A browser window opens and hands the credentials back to the CLI.
• An API key for usage-based billing. Pipe it in so it doesn't sit in your shell history as an argument:

printenv OPENAI_API_KEY | codex login --with-api-key

codex login status shows which method is active, and codex logout clears saved credentials. They're stored in ~/.codex/auth.json, which the CLI and the IDE extension share.

Set up config.toml

Where it lives

In the VS Code extension, the gear icon → Codex Settings → Open config.toml opens the same user file. The CLI and the extension read the same configuration.

When the same key is set in several places, the more specific one wins: command-line flags, then project config (the folder closest to where you're working), then the profile you selected, then your user config, then system defaults.

A starter config

# ~/.codex/config.toml
model = "gpt-6.1-sol"              # default model
model_reasoning_effort = "medium"  # low | medium | high (levels depend on the model)
approval_policy = "on-request"     # ask before risky actions; "never" for unattended runs
sandbox_mode = "workspace-write"   # read-only | workspace-write | danger-full-access
web_search = "cached"              # cached (default) | live | disabled

What each one does:

TOML is picky: text values need straight double quotes ("gpt-6.1-sol", not gpt-6.1-sol), and a single mistake stops Codex from starting. The error tells you the line and column. See string values must be quoted.

Override settings for one run

codex --model gpt-6.1-sol
codex --config model_reasoning_effort='"high"'

The value after --config is TOML, which is why strings need the inner double quotes.

Profiles

Profiles are named sets of overrides. Since Codex 0.134.0, each one is a separate file. To create a deep-review profile:

# ~/.codex/deep-review.config.toml
model_reasoning_effort = "high"
approval_policy = "on-request"

codex --profile deep-review

Only put the keys that differ from your main config.toml. Write them at the top level, not under a [profiles.deep-review] header.

Custom providers and API gateways

Codex can send requests to any service that implements the OpenAI Responses API (/v1/responses). There are two ways to set it up.

Option 1: change the base URL of the built-in provider. This is the simplest if you only use one provider:

model = "gpt-6.1-sol"
openai_base_url = "https://api.foo/v1"

Then sign in with that provider's key:

printf 'sk-your-key' | codex login --with-api-key

Option 2: define a named provider. Use this to keep your ChatGPT sign-in as the default and switch to the provider only when you want to. Putting it in a profile file means plain codex stays on ChatGPT:

# ~/.codex/apifoo.config.toml
model = "gpt-6.1-sol"
model_provider = "apifoo"

[model_providers.apifoo]
name = "api.foo"
base_url = "https://api.foo/v1"
env_key = "APIFOO_API_KEY"

export APIFOO_API_KEY="sk-your-key"
codex --profile apifoo

The examples use api.foo, the API gateway that publishes these docs. Swap in your own provider's URL and key. To check the wiring before spending anything, we ran both options with a deliberately wrong key. Each request reached the gateway, and the gateway rejected the key:

model: gpt-6.1-sol
provider: apifoo
ERROR: unexpected status 401 Unauthorized: 无效的令牌 (request id: …), url: https://api.foo/v1/responses

The url in that error is the provider's address and the error text comes from the provider, which tells you the config works and only the key is wrong. (api.foo returns this message in Chinese by default. It means "invalid token".)

Things to get right:

• Include /v1 in the base URL. Codex appends /responses directly to it.
• Use a model name the provider actually offers.
• Provider settings only work in your user config or a profile. Codex ignores openai_base_url, model_provider and model_providers in a project's .codex/config.toml and prints a warning.
• env_key reads an environment variable. Apps launched from the macOS Dock, including VS Code, may not see variables set in ~/.zshrc. If the extension reports a missing variable, use Option 1.

Fix common errors

command not found: codex

The installer added ~/.local/bin to your PATH in ~/.zprofile, but terminal windows that were already open don't pick that up. Open a new one. On Linux with bash, make sure export PATH="$HOME/.local/bin:$PATH" is in ~/.bashrc or ~/.profile. For npm installs, the bin folder under npm config get prefix must be on PATH.

Two installs, wrong one runs

WARNING: Multiple managed Codex installs can be ambiguous because PATH order decides which one runs.

Run which -a codex (where.exe codex on Windows) to list them, then uninstall all but one. The install method line in codex doctor shows which one is running.

spawn … ENOENT

Error: spawn …/node_modules/@openai/codex/node_modules/@openai/codex-darwin-arm64/vendor/aarch64-apple-darwin/codex/codex ENOENT

We hit this ourselves on an old npm install: the platform binary inside the npm package was missing. Reinstalling the latest version fixed it:

npm install -g @openai/codex@latest

wire_api = "chat" is no longer supported

Error loading config.toml: `wire_api = "chat"` is no longer supported.
How to fix: set `wire_api = "responses"` in your provider config.

Delete the wire_api line, since responses is the default. If your provider then returns 404, it doesn't support the Responses API and won't work with current Codex.

--profile can't be used with a legacy [profiles] table

Error loading config.toml: --profile `apifoo` cannot be used while …/config.toml contains legacy `profile = "apifoo"` or `[profiles.apifoo]` config; move those settings into …/apifoo.config.toml and remove the legacy profile selector/table.

Move the keys from [profiles.apifoo] into ~/.codex/apifoo.config.toml at the top level, then delete the table and any profile = "…" line from config.toml.

Error loading config.toml: string values must be quoted

Error loading config.toml:
…/config.toml:1:9: string values must be quoted, expected literal string
  |
1 | model = gpt-6.1-sol
  |         ^^^^^^^^^^^

Add straight double quotes around the value. Curly quotes pasted from a web page or document cause the same error.

Missing environment variable: APIFOO_API_KEY

Your provider uses env_key, but Codex can't see that variable. Export it in your shell profile and open a new terminal. On Windows, run setx APIFOO_API_KEY "sk-…" and reopen PowerShell. For editor extensions, switch to Option 1 above.

401 Unauthorized

The request reached the provider but the key was rejected. Usually that's a missing character, a stray space, or a key from a different provider. Sign in again with codex login --with-api-key.

Update and uninstall

The standalone installer also adds a block to ~/.zprofile between # >>> Codex installer >>> and # <<< Codex installer <<<, which you can delete. Uninstalling never touches ~/.codex, where your config, credentials and chat history live. Delete that folder only if you want a clean slate.

Related

• How to install Claude Code