Daily-It

개발, AI, 인프라, 자동화와 일상 IT 제품 후기를 직접 써보며 정리하는 기술 블로그입니다.

How to Install Codex CLI: Start the OpenAI Coding Agent on macOS, Windows, and Linux

Summary

Codex CLI lets you run OpenAI’s coding agent from a terminal, but installing it in 2026 is no longer just a matter of copying an old npm install -g @openai/codex command. The current Korean source checks the official install script, npm package, Homebrew cask, GitHub Release binaries, login options, and the problems that usually waste time after installation: command not found, account permission, proxy/WebSocket, and environment-variable mismatches.

If you only need the shortest safe path: install with the official script or your package manager, verify codex --version, then run codex inside a test project before asking it to edit important files. If that fails, do not reinstall blindly; check PATH, authentication, network policy, and the shell environment first.

In this article

Background

Search results for Codex CLI still contain outdated instructions. Some pages mention requirements such as “Node.js 22 or later,” tell users to run codex --login, or show brew install codex. Those details may be stale or environment-dependent.

Based on the official README checked for the Korean article, Codex CLI can be installed on macOS, Linux, and Windows. The simplest route is the official install script. Developers who already manage Node.js can use the npm package. macOS users can also use the Homebrew cask, and locked-down environments can use a GitHub Release binary.

The important part is not just the install command. You need to know which authentication method you will use, whether the codex executable is actually on your terminal PATH, and whether your company, school, VPN, proxy, or security gateway blocks the network flow Codex needs.

What to check before installation

Start by checking the runtime and command paths you already have:

node -v
npm -v
which node
which npm
uname -m

If you install with npm, the npm package currently declares node >=16. In practice, a current LTS Node.js version is safer. If you use nvm, fnm, or volta, also check where global npm packages are installed:

npm config get prefix
which codex

On Windows, decide whether you will use PowerShell/Windows Terminal directly or run Codex inside WSL2. The two environments can have different PATH settings and authentication/config file locations.

Codex CLI installation methods

Method 1. Install with the official script

For macOS or Linux, the official README points to this command:

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

For Windows PowerShell:

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

This is usually the easiest first install. In a corporate environment where remote script execution is restricted, review the script first or use npm, Homebrew, or a release binary instead.

Method 2. Install with npm

If Node.js and npm are already part of your development setup, install the package globally:

npm install -g @openai/codex

Then verify both the version and executable path:

codex --version
which codex

As checked in the Korean source on June 16, 2026, the latest npm package version was 0.140.0. Global npm installation is convenient, but when you switch Node versions with nvm, the global package location can change. If which codex does not point where you expect, check PATH before reinstalling repeatedly.

Method 3. Install with Homebrew

On macOS, use the cask command from the official README:

brew install --cask codex

Be careful with older posts that say brew install codex. A Homebrew formula and a cask are not the same installation target.

Method 4. Install a GitHub Release binary

If package managers are not available, download the binary that matches your platform from GitHub Releases. The Korean source lists these examples:

  • Apple Silicon Mac: codex-aarch64-apple-darwin.tar.gz
  • Intel Mac: codex-x86_64-apple-darwin.tar.gz
  • Linux x86_64: codex-x86_64-unknown-linux-musl.tar.gz
  • Linux arm64: codex-aarch64-unknown-linux-musl.tar.gz

After extracting the archive, rename the executable to codex and move it to a directory on PATH:

chmod +x codex
sudo mv codex /usr/local/bin/codex
codex --version

Login and authentication

Running Codex for the first time usually starts the login flow:

codex

The official README recommends logging in with a ChatGPT account. Access can be tied to Plus, Pro, Business, Edu, or Enterprise plans.

API key usage is also possible, but it is not the same as saying “export OPENAI_API_KEY and every problem is solved.” Organization policy, billing, project permissions, model access, and Codex configuration can all matter.

If you use an environment variable, never put a real secret in a public document or committed config file:

export OPENAI_API_KEY="***"

PowerShell example:

$env:OPENAI_API_KEY="***"

Basic usage

The simplest mode is interactive:

codex

Run it from the project directory so Codex can inspect the files you actually want to work on:

cd my-project
codex

After installation and authentication, start with a read-only request rather than an edit:

Summarize this project structure.

If this works, move on to small edits, then verify with your own tests and Git diff.

Failure cases and fixes

Case 1. codex: command not found

This usually means the executable is not on PATH, or it was installed under a different Node version than the one your shell is using.

npm config get prefix
which codex
npm bin -g
echo $SHELL

For zsh, check ~/.zshrc. For bash, check ~/.bashrc or ~/.bash_profile. If you use nvm, switch to the Node version you actually use for the project and reinstall there:

npm install -g @openai/codex

Case 2. Homebrew instructions differ

If an article tells you to run this:

brew install codex

compare it with the official README, which currently uses:

brew install --cask codex

If you already tried an old command, inspect what is installed before removing anything:

brew list | grep -i codex
brew list --cask | grep -i codex

Then uninstall the incorrect item if it exists and install the cask.

Case 3. Login succeeds, but Codex still cannot be used

Codex CLI is tied to account permissions, not just local installation. Check these before reinstalling:

  • Are you logged in with the intended ChatGPT account?
  • Are personal and company/school workspaces mixed up?
  • Does the selected plan include Codex access?
  • If using an API key, are project, organization, billing, and model permissions correct?

On machines used with multiple OpenAI accounts, logout/login and account switching often matter more than reinstalling the CLI.

Case 4. WebSocket reconnect or timeout messages behind a corporate network

GitHub issues referenced by the Korean source include cases where Codex tries a WebSocket connection, times out or is closed by policy, and falls back to HTTPS. Users may see messages such as Reconnecting... or Request timed out.

First, try the same command on a different network:

codex

Then check in this order:

  • Update Codex CLI to the latest version.
  • Test without a corporate VPN or through another network.
  • Ask whether the proxy, firewall, or SSL inspection layer blocks chatgpt.com or OpenAI-related connections.
  • If it continues, compare with GitHub issues for the same Codex version.
npm install -g @openai/codex@latest
codex --version

Case 5. Environment variables are visible in the terminal but missing inside Codex

Some users feel that commands launched from Codex do not inherit the exact same environment as their shell. Check presence, not the secret value itself:

printenv OPENAI_API_KEY

Inside a command executed by Codex, use a masked existence check:

printenv OPENAI_API_KEY >/dev/null && echo "set" || echo "missing"

The safest fix depends on the project. Make required environment variables explicit, keep real secrets out of Git, and avoid writing actual API keys into Codex settings or project documentation.

Case 6. macOS blocks helper tools

Some reported macOS cases look like a Codex installation failure, but the blocked component is a helper executable such as rg. Gatekeeper, quarantine attributes, or local security policy may be involved.

codex --version
codex doctor

If your version provides codex doctor, use its output to identify what is blocked. Update first, then confirm whether the same failure still reproduces.

npm install -g @openai/codex@latest

Best practices

Start with explanation and inspection tasks before asking Codex to edit files:

Explain this repository structure.
Find how to run the tests.
List likely causes of this error log.

Before file edits, make sure Git is clean:

git status

After Codex changes code, verify it yourself:

npm test
npm run build

For work code or sensitive projects, check your organization’s policy. Do not paste API keys, customer data, production passwords, or internal tokens into prompts or committed config files.

Common mistakes

Judging the problem only by the Node version

The npm package currently requires node >=16, but many failures are caused by global npm path, PATH configuration, or switching Node versions with nvm.

Copying old install commands

Codex CLI changes quickly. Check the official README and latest GitHub Release before trusting an old blog command.

Mixing up API key authentication and ChatGPT login

The README recommends ChatGPT login, while API key usage has its own setup and permission checks. Authentication problems are easy to misread as installation problems.

Not verifying Codex changes

Codex can edit code, but it does not guarantee the result matches your project intent. Always review the diff and run tests or builds.

Conclusion

Installing Codex CLI is usually straightforward: macOS and Linux can use the official script, npm, Homebrew cask, or a release binary; Windows can use the PowerShell install script. The slow part is normally PATH, authentication, account permissions, network policy, or shell environment differences.

For a first install, try:

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

If your npm environment is already clean, this is also fine:

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

If either path fails, search by the exact symptom: command not found, login permission, WebSocket/proxy timeout, missing environment variable, or macOS security block.

References

Original Korean version: This article is based on the Korean version and lightly adapted for English readers. Read the original Korean post.
Please show some love to Korean, too.