Codex Installation Guide: Step-by-Step for macOS, Windows, and Linux

A hands-on walkthrough of installing Codex CLI on macOS, Windows, and Linux, plus fixes for common problems with npm, PATH, and first launch. Once installation is done, it points you on to API Key / Provider setup.

10 分钟阅读
Codex Installation Guide: Step-by-Step for macOS, Windows, and Linux

The most important part of installing Codex CLI isn't pasting one command into the terminal. It comes down to three things: confirming the command comes from the official source, making sure the system can find codex, and checking that both the version and help output print correctly. Once all three pass, you have a reliable starting point for logging in, configuring an API Key, and everyday use.

This tutorial is organized by operating system, with install commands, verification steps, and common issues for each. All install commands come from the OpenAI Codex CLI official documentationand the AI Code With Codex terminal documentation. If the commands here differ from what you see on the official pages, go with the official pages, because install methods change as versions are updated.

Haven't downloaded the installer yet? The official download link is in “Codex Download”. Once it's installed, see “How to Use Codex”.

Pick a Route Before You Install

OpenAI currently offers four install paths: a standalone install script for macOS/Linux, a standalone install script for Windows, npm, and Homebrew. They all install the same Codex CLI. The difference is what each one depends on and how you upgrade later.

Install methodBest forPrerequisitesUpgrade method
Official install script (macOS/Linux)Users who don't want to install Node.jscurl and a network that can reach the official addressRe-run the same install command
Official install script (Windows)First choice for Windows usersPowerShellRe-run the same install command
npmDevelopers already using Node.jsNode.js 18+ and npmnpm install -g @openai/codex
HomebrewmacOS users who prefer brewHomebrewbrew upgrade --cask codex

If you're on a network in mainland China, the official install script can be unreliable to download. In that case, npm with a China mirror is usually smoother. The AI Code With docs use the npm route and require Node.js 18 or later.

macOS Installation Steps

Option 1: Official install script

Open Terminal and run the standalone install command from the official docs:

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

When you need to upgrade, just run the same command again.

Option 2: Homebrew

If you already have Homebrew installed, you can use the cask the official docs provide:

bash
brew install --cask codex

The upgrade command is:

bash
brew upgrade --cask codex

Option 3: npm

First, confirm Node.js is installed and the version is 18 or higher:

bash
node --version
npm --version

If you don't have Node.js yet, install it with Homebrew, as the AI Code With docs do:

bash
brew install node

Then install Codex CLI. Users in China can add the mirror parameter:

bash
npm install -g @openai/codex
npm install -g @openai/codex --registry=https://registry.npmmirror.com/

Pick one of the two commands. The second one uses the China mirror.

Verifying the macOS install

After installation finishes, open a new terminal window, then check in order:

bash
command -v codex
codex --version
codex --help

The first command should print the path to codex, the second should print a version number, and the third should print the help text. If they do, the install succeeded. The bar for success isn't "the installer reported no errors." It's that all three commands produce normal output.

Windows Installation Steps

Option 1: Official PowerShell install script

The official OpenAI docs recommend that, from a newly opened PowerShell window, you run the following command:

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

Don't rely on PowerShell commands from old blog posts for long. The official install entry point gets updated, so check the official page for the current command before running it.

Option 2: npm

First download and install the LTS version from the Node.js website, then press Win + R, type powershell to open PowerShell, and check the version:

powershell
node --version
npm --version

Once you've confirmed Node.js is version 18 or higher, install Codex CLI:

powershell
npm install -g @openai/codex

Users in China can use the mirror instead:

powershell
npm install -g @openai/codex --registry=https://npmreg.proxy.ustclug.org

If PowerShell says "running scripts is disabled on this system," the AI Code With docs handle it this way: open PowerShell as administrator and run Set-ExecutionPolicy Unrestricted. This loosens the system's script execution policy, so make sure you understand the implications before doing it.

Verifying the Windows install

Close the current PowerShell window, open a new one, then check:

powershell
Get-Command codex
codex --version
codex --help

If Get-Command codex can't be found, don't reinstall yet. Read the section "Installed but can't find codex" below.

Linux Installation Steps

Option 1: Official install script

Linux uses the same standalone install command as macOS:

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

Option 2: npm

If Node.js isn't on your system yet, the AI Code With docs install it on Debian/Ubuntu like this (requires root):

bash
curl -fsSL https://deb.nodesource.com/setup_lts.x | bash -
apt-get install -y nodejs

After confirming the version, install Codex CLI:

bash
node --version
npm install -g @openai/codex --registry=https://registry.npmmirror.com/

On other distributions, install Node.js LTS with your own package manager, then run the same npm commands.

Verifying the Linux install

bash
command -v codex
codex --version
codex --help

If you're installing on a server with no GUI, the browser flow at the next login step may not work. How to handle that is covered in the common issues later on.

Why You Need to Reopen the Terminal Every Time

Many "installed but command not found" problems come down to a terminal that was never reopened. A terminal reads environment variables once at startup, so a new directory the installer adds to PATH only takes effect in terminal windows opened afterward. A window that's already open still uses the old PATH, so naturally it can't find the codex you just installed.

That's why the verification steps for every system in this article tell you to close the current window and open a new one before checking. If you installed from the built-in terminal in an editor like VS Code, you likewise need to quit the whole editor and reopen it. Opening a new terminal tab sometimes isn't enough.

Also, on Windows, if you switch between PowerShell, Command Prompt, and Git Bash, they may read different environment variables. Stick to PowerShell for both installing and using Codex, and troubleshooting gets much simpler.

Installed but can't find codex

This is the most common problem at the install stage. The cause usually isn't that it failed to install, but that the system PATH doesn't include the directory where Codex lives, or that the current terminal is still using old environment variables.

Check PATH first. On macOS / Linux:

bash
command -v codex
printf '%s\n' "$PATH"

On Windows:

powershell
Get-Command codex -ErrorAction SilentlyContinue
$env:Path -split ';'

The suggested order: reopen the terminal first. If that doesn't help, confirm which directory the executable actually landed in (on the npm route, you can use npm prefix -g to see the global install location). Finally, add only that one directory to PATH.Don't add a directory of unknown origin to your system PATH wholesale.

Files Created After Installation

After you install and log in, Codex uses a config directory in your home directory, which defaults to ~/.codex (you can move it elsewhere with the environment variable CODEX_HOME). Two files matter most for beginners:

  • config.toml: Codex's config file, where settings like model, Provider, and permissions live;
  • auth.json: the login cache. The official docs say Codex caches login info in this plaintext file, or stores it in the system credential store.

If you'd rather keep credentials in the system credential store than in a plaintext file, the official docs provide the cli_auth_credentials_store setting, and the possible values are file, keyring, auto, and ephemeral:file is stored in auth.json;keyring stores it in the system credential store, and errors out if the store is unavailable;auto prefers the credential store and falls back to auth.json if it's unavailable;ephemeral keeps it only in memory for the current process. The default is fine on a personal computer. On a shared machine, consider keyring.

Whichever route you take, keep this in mind: auth.json holds your access token, which makes it equivalent to a password. Don't commit it to a Git repository, paste it into a ticket, or post it in a group chat. When you share your configuration with teammates, send only config.toml, and first confirm that it doesn't contain any hardcoded keys.

Installing on a corporate network or behind a proxy

Many corporate networks route traffic through a TLS proxy or use a private root certificate. In that kind of environment, the install script may download fine, but the first login can fail with a certificate error. The officially documented fix is to set the environment variable CODEX_CA_CERTIFICATE to the path of the PEM certificate file provided by your company before logging in, and then run the login command:

bash
export CODEX_CA_CERTIFICATE=/path/to/corporate-root-ca.pem
codex login

If CODEX_CA_CERTIFICATE isn't set, Codex falls back to SSL_CERT_FILE. This certificate setting applies to login, regular HTTPS requests, and WebSocket connections, so setting it once covers all later calls. Ask your company's IT department for the certificate file, and don't download one from a random site.

Also, if you need a proxy to reach the outside internet, the npm route lets you configure npm's own proxy first, or switch to a regional mirror directly. That's usually less hassle than fiddling with system-wide proxy settings.

Uninstall the old version before switching install methods

If you started with npm and later want to switch to the official script or Homebrew, uninstall the old copy first. Otherwise, your PATH may find the old version first, and you'll end up in the situation where "I clearly upgraded, but the version number didn't change."

If you installed with npm, uninstall with npm:

bash
npm uninstall -g @openai/codex

If you installed with Homebrew, uninstall with Homebrew:

bash
brew uninstall --cask codex

After uninstalling, reopen your terminal and use command -v codex (on Windows, use Get-Command codex) to confirm the old command can no longer be found, then install with the new method. Uninstalling the CLI doesn't automatically delete the ~/.codex directory, so your configuration and login cache are still there and you can pick up right where you left off after reinstalling.

First launch and login

Go into a test project and start Codex:

bash
cd /你的/测试项目
codex

On first run, the official docs say you can choose Sign in with ChatGPT or another available login method. The two common ones are:

  • ChatGPT account login: Run codex login and finish signing in in the browser window that opens. This uses your subscription quota.
  • API Key login: The officially documented form is printenv OPENAI_API_KEY | codex login --with-api-key, which is billed at standard API prices.

After logging in, you can use codex login status to check which authentication method is currently in use. Login information is cached locally in ~/.codex/auth.json or in your system credential store. That file is effectively a password, so don't commit it to Git or send it to anyone.

Connecting Codex with an AICodeWith API Key

Once Codex is installed, if you want to use an AICodeWith key to call models, follow the integration guide. This article doesn't repeat the configuration steps:

See the guide to connecting Codex to AICodeWith →

Common errors at a glance

Error or symptomCommon causeFix
command not found: codex / Get-Command not foundThe install directory isn't in PATH, or the terminal wasn't reopenedReopen the terminal; use npm prefix -g to find the install location, and add only that one directory to PATH
npm: command not foundNode.js isn't installed, or Node.js isn't in PATHInstall Node.js LTS first, then confirm that node --version and npm --version both print output
Startup error after npm install; Node version too oldThe AI Code With docs require Node.js 18+Upgrade Node.js to an LTS version and reinstall
PowerShell says "running scripts is disabled on this system"Windows script execution policy restrictionIn an administrator PowerShell, run Set-ExecutionPolicy Unrestricted (change it only after you understand the implications)
npm downloads are very slow or time outThe official npm registry is unreliable to reachAdd --registry=https://registry.npmmirror.com/ and other domestic mirrors
On a server, codex login can't open a browserNo GUI, or the local callback port localhost:1455 is blockedUse codex login --device-auth device-code login, or forward port 1455 over SSH
Certificate errors when logging in on a corporate networkAn enterprise TLS proxy or a private root certificateBefore logging in, set CODEX_CA_CERTIFICATE to point to a PEM certificate file
First launch shows "this folder is not version controlled"The current directory isn't a Git repository, and Codex is confirming permissionsIn a test directory, you can follow the prompt. For a real project, run git init first, then use

If you hit a 401 or 429 after installation, that's not an install problem. See "How to Fix Codex 401 Unauthorized" and "How to Fix Codex 429 Too Many Requests" respectively.

FAQ

Does installing Codex CLI require Node.js?

Not necessarily. The official standalone install scripts (on macOS/Linux, install.sh; on Windows, install.ps1) don't depend on Node.js. You only need it if you go the npm route, and the AI Code With docs require Node.js 18 or later.

Which install method should I use on Windows?

Use the official PowerShell install script first. If you already work with Node.js, or the official script downloads unreliably, you can switch to npm with a domestic mirror. Both methods give you the same Codex CLI.

How do I upgrade Codex CLI?

Upgrade the same way you installed: rerun the install script, or for npm, run npm install -g @openai/codex again; for Homebrew, use brew upgrade --cask codex. After upgrading, run codex --version to confirm the version number changed.

Installation worked, but it asks me to log in on launch. Which option should I pick?

If you have a ChatGPT subscription, choose ChatGPT login, which uses your subscription quota. If you want pay-as-you-go billing or need to use it in CI, use an API Key. If you want to use an AI Code With key, sign up for an account first, then write the Provider configuration following the Codex configuration docs.

How do I log in on a Linux server with no GUI?

The officially recommended way is device-code login. Run codex login --device-auth, open the link on another device that has a browser, and enter the one-time code. You can also log in locally and copy ~/.codex/auth.json to the same location on the server.

Can I install multiple versions at the same time?

Not recommended. Mixing npm, Homebrew, and the install script makes it easy for PATH to find an old version first. Pick one method, uninstall the others, and then use command -v codex to confirm which one is actually being called.

Next Steps

Once it's installed, we suggest continuing in this order:

See the Codex and AICodeWith integration tutorial →

Sources

相关文章

What is the UI SDK, and how do you use it? Vercel and shadcn's behavior library for agents, installed and tested in Claude Code / Codex / Cursor (0.1.0-beta.1)

What is the UI SDK, and how do you use it? Vercel and shadcn's behavior library for agents, installed and tested in Claude Code / Codex / Cursor (0.1.0-beta.1)

The UI SDK is Vercel's behavior library for agents, released on 12 November 2026 as 0.1.0-beta.1. Behaviors live in the framework-free @ui-sdk/core package and are rendered by adapters for React, Vue, Svelte, Solid, and Web Components. This guide follows the official docs on what it is, how to install it, and how to add the skill for Claude Code, Codex, and Cursor, and it records the commands, timings, and output from our test machine.

What Is AWS Emulator and How Do You Install It? Test AWS Apps Locally with Claude Code and Codex (Tested on 1.0.322)

What Is AWS Emulator and How Do You Install It? Test AWS Apps Locally with Claude Code and Codex (Tested on 1.0.322)

AWS Emulator is AWS's official local emulator of its service APIs, generally available since November 11, 2026 (US time). It has no additional service fee, its source is open, it needs no AWS account, and it covers more than 200 services. We tested version 1.0.322 on Debian 13. This guide covers the install commands, pointing the AWS CLI at the local endpoint to create an S3 bucket and a DynamoDB table, the errors we hit, and how to let Claude Code, Codex and Cursor write and test code against the emulator.

What Is T3 Code and How Do You Install It? Connect Claude Code and Codex, Use a Third-Party API Key, Fix Common Errors (Tested on 0.1.9)

What Is T3 Code and How Do You Install It? Connect Claude Code and Codex, Use a Third-Party API Key, Fix Common Errors (Tested on 0.1.9)

T3 Code is pingdotgg's open-source control surface for coding agents. It ships no model of its own; it drives the Claude Code, Codex, Cursor and other CLIs already on your machine. We tested T3 Code 0.1.9 on Linux. This guide covers the install commands, how to point Claude Code and Codex at an AICodeWith API Key so T3 Code can drive them, a full run of both agents with the t3 thread command, and the errors we hit along the way with their fixes.