Guide
How to Install Codex CLI
OpenAI's Codex CLI puts a coding agent in your terminal. Installation is a single command once you know the correct package name — and getting that wrong is the most common first mistake, because an unrelated package occupies the obvious name on npm.
Install With npm
The standard route, and the one that works on macOS, Linux, and Windows alike:
npm install -g @openai/codexNode.js 22 or later is required. Check with node --version before installing — an older Node produces errors that look unrelated to the version.
@openai/codex, with the scope. The unscoped codex package on npm is an unrelated project from 2012. Installing it gives you something that is not a coding agent, which is a confusing few minutes.Install With Homebrew (macOS)
brew install --cask codexConvenient if you already manage tools with Homebrew. One caveat worth knowing: if you later replace the binary manually to pick up a newer release, brew upgrade loses track of what is actually installed. Pick one method and stay with it.
Install From a Release Binary
For machines without Node, download the binary for your platform from the Codex GitHub releases page, make it executable, and put it somewhere on your PATH:
chmod +x codex
sudo mv codex /usr/local/bin/Signing In
Codex offers two authentication paths. Run:
codex loginOption 1: ChatGPT account (recommended)
This opens a browser for OAuth. Sign in with an OpenAI account on a ChatGPT Plus, Pro, Team, Edu, or Enterprise plan and usage draws against that plan. There is no API key to manage or rotate, which is the easier path for day-to-day interactive work.
Option 2: API key
Authenticate with an OpenAI API key instead. This suits automated workflows, CI, or anyone who prefers usage-based API billing to a subscription. Usage bills to the API account rather than a ChatGPT plan.
Headless machines and browser problems
On a server with no browser, or when the browser handoff fails, use the device-code flow:
codex login --device-authCodex prints a URL and a one-time code. Open the URL on any device, paste the code, and the CLI completes sign-in. This is the reliable path for remote and containerised environments.
Verify the Install
codex --version
codexRunning codex with no arguments in a project directory starts an interactive session. If the version prints and a session opens, you are set up.
Fixing “command not found”
This is a PATH problem rather than a failed install. The global npm bin directory is not on your PATH. Find it and add it:
npm config get prefix
# add "<that path>/bin" to your PATH, e.g. in ~/.zshrc:
export PATH="$(npm config get prefix)/bin:$PATH"Open a new shell afterwards. If npm install -g itself failed with a permissions error, avoid fixing it with sudo — use a Node version manager, or point npm's prefix at a directory you own.
Other Common Problems
Installed but behaves oddly, or commands are missing
Check you installed the scoped package. Run npm ls -g --depth=0 and look for @openai/codex. If you see a bare codex entry, uninstall it and install the scoped one.
Node version errors
Codex CLI needs Node 22 or later. On a system Node that is older, install a current version with nvm, fnm, or your package manager rather than forcing the install.
Sign-in loops or a stale session
Run codex logout and sign in again, preferring --device-auth if the browser flow keeps failing.
Codex in the Terminal vs an Always-On Assistant
Codex CLI is a coding agent for your machine — it reads your repository, edits files, and runs commands in a session you drive. It is not a service, and it stops when you close the terminal.
If what you want instead is an assistant that stays online and answers from Telegram, Discord, WhatsApp, or WeChat, that is a different tool. OpenClaw Launch deploys one in about 30 seconds, and if you have a ChatGPT subscription you can connect it so your assistant uses your existing plan — see the OpenClaw and Codex guide. Plenty of people run both: Codex CLI for hands-on coding, a deployed assistant for everything that should keep working when the laptop is shut.