Daily-It

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

Summary

Codex CLI is a tool that runs OpenAI’s coding agent in your terminal. In the past npm install -g @openai/codexJust explaining it alone would have been enough, but now the options have expanded to include official installation scripts, Homebrew cask, npm, and GitHub Release binaries. In this article, we summarize the Codex CLI installation method and login method as of June 2026, as well as installation/authentication/terminal problems that often occur.

Table of Contents

Background

When you search to install Codex CLI, you still find many old articles. especially Node.js 22 이상 필요, codex --login 실행, brew install codexLike this, there is a mixture of content that is not accurate by current standards or may operate differently depending on the environment.

Based on the current official README, Codex CLI can be installed on macOS, Linux, and Windows, and there are several installation methods. The simplest way is to use the official installation script, and if you are a developer who already uses npm, @openai/codex You can also install it as a package.

What’s important is that the installation command What authentication method to use, in my terminal codex Is the command actually caught?, Check if the network is blocked in a company/school/proxy environment.no see. In fact, most of the blockages come from here.

What to Check Before Installation

First, check your current environment.

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

When installing with npm, the npm package engines The standard is now node >=16no see. However, in actual use, it is safer to use the latest LTS series Node.js. already nvm, fnm, volta If you use the same Node version manager, you should also check where the global npm installation location is.

npm config get prefix
which codex

On Windows, it is recommended to install PowerShell or Windows Terminal and decide in advance whether development work will be done in WSL2 or Windows native. The PATH and authentication file locations may be different for the two.

Codex CLI Installation Methods

Method 1. Install with official installation script

On macOS or Linux, the official README guides you through the commands below.

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

In Windows PowerShell, use the following command:

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

If you are a first-time installer, this method is the simplest. However, in environments where remote script execution is restricted due to company security policy, checking the script contents first or using the npm/Homebrew/GitHub Release method may be more appropriate.

Method 2. Install with npm

If you are already using Node.js and npm, you can also install npm globally.

npm install -g @openai/codex

Check after installation.

codex --version
which codex

As of check on June 16, 2026, npm @openai/codex The latest version is 0.140.0no see. npm global installation is simple, nvmIn an environment using , global packages may be installed in a different location if you change the Node version. In this case which codex If the results are not as expected, you should check your PATH first.

Method 3. Install with Homebrew

macOS also provides the Homebrew cask method.

brew install --cask codex

Often seen in existing articles brew install codexPlease be careful as it may be different. The official README is --cask We guide you through installation.

Method 4. Install with GitHub Release binary

If you find it difficult to use the package manager, you can get the binary appropriate for your platform from GitHub Release.

  • 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 unzipping, change the executable file name to codexJust change it to and move it to a location in your PATH.

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

Login and Authentication Methods

When you first run Codex CLI, it usually starts with a login flow.

codex

According to the official README, Log in with your ChatGPT accountThis is the recommended method. This is because Codex usage rights can be linked to Plus, Pro, Business, Edu, and Enterprise plans.

It can also be used as an API Key, but in this case separate settings are required. Just like the previous post OPENAI_API_KEYYou should not assume that all authentication issues are over once you export. This may vary depending on organizational policy, account permissions, model access, and how Codex is set up.

When using environment variables, you do not leave the actual key directly in the post or configuration file.

export OPENAI_API_KEY="****"

In PowerShell, you can set it like this:

$env:OPENAI_API_KEY = "****"

Basic Usage

The most basic one is interactive execution.

codex

When run from a project folder, Codex works based on the files in the current directory.

cd my-project
codex

Once installation and authentication are complete, first check operation with a simple request.

이 프로젝트 구조를 요약해줘.

It is safer to start with read-oriented requests rather than having the file be modified right away.

Failure Cases and Fixes

Case 1. codex: command not foundWhen comes out

The installation is complete, but this message may appear in the terminal.

codex: command not found

First, check where the executable file is installed.

npm config get prefix
which codex

I installed npm globally. which codexIf is empty, the npm global bin path is most likely not in your PATH.

npm bin -g

Also check which shell you are using.

echo $SHELL

If you use zsh ~/.zshrc, if you use bash ~/.bashrc or ~/.bash_profile View your PATH settings. In environments where nvm is used, global packages may appear to have disappeared after changing the Node version, so reinstalling with the current Node version is also an option.

npm install -g @openai/codex

Case 2. When installed with Homebrew, but the command is guided differently

Some articles provide guidance as follows.

brew install codex

However, as per the official README, the installation instructions are:

brew install --cask codex

Homebrew formula and cask have different installation targets and management methods. If installation fails, first check the latest commands in the official README, and if there are any packages that you have already installed incorrectly, clean them and install them again.

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

Depending on the environment brew uninstall codexmay not be able to find the item. In that case, the actual installed item name is brew list --caskConfirm with .

brew list --cask | grep -i codex

Case 3. If you log in but cannot use it due to permission or plan issues

Codex CLI is not a simple installation tool; it is tied to account permissions. If you are unable to use ChatGPT even after logging in, check below first.

  • Is your ChatGPT account correct?
  • Are your personal accounts and work/school workspaces mixed?
  • Is the plan authorized to use Codex?
  • If the API Key method is used, are the project/organization/payment settings correct?

In this case, rather than blindly reinstalling, log out/relogin, switch accounts, and check permissions first. This can be confusing, especially if you have multiple OpenAI accounts on the same computer.

Case 4. Repeated WebSocket reconnection messages in corporate network

A GitHub issue reports a case where Codex CLI attempts a WebSocket connection and falls back to HTTPS after a timeout or policy termination. The user Reconnecting..., Request timed out You will see the same message.

First, try running the same command on a different network.

codex

WebSockets may be blocked in environments with corporate VPNs, proxies, security gateways, and SSL inspection. Officially, this is not a problem that has the same solution in all environments, so in this case it is safer to check in the following order:

  1. Update Codex CLI to the latest version
  2. Check if it reproduces with corporate VPN turned off or on another network
  3. In proxy/firewall chatgpt.com and check if OpenAI-related connections are blocked
  4. If the problem persists, check the GitHub issue for a case of the same version.

If it is an npm installation, the update is done as follows.

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

Case 5. When environment variables are not visible in Codex

There are cases where I feel that Codex does not fully capture the user’s terminal environment when executing commands. For example, in the terminal it looks like SENTRY_API_TOKEN, OPENAI_API_KEY The same value is not visible in the Codex execution environment, and so on.

First check in a regular terminal.

printenv OPENAI_API_KEY

Next, check whether the commands executed within Codex see the same environment. Do not print out sensitive information as is; only check whether it exists.

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

The solution varies from environment to environment. The safest direction is to explicitly set the environment variables needed for the project, and secret values .envis not uploaded to Git. You should avoid writing actual keys in Codex configuration files or project documentation.

Case 6. Assistant tools are blocked due to security policy on macOS

GitHub issue on macOS rg There are also reported cases where the same secondary executable file is blocked by security policy. Although this may seem like a problem with Codex’s own installation, it may actually be caused by macOS Gatekeeper, quarantine properties, or security settings.

First, check the Codex version and diagnostic information.

codex --version
codex doctor

codex doctorIf the version is available, check the diagnostic results to see which executable file is blocked. Rather than blindly expanding permissions, it is better to first check whether the same problem recurs after updating to the latest version.

npm install -g @openai/codex@latest

Best Practices

When using Codex CLI for the first time, it is better to start with a focus on reading and explanation rather than relying on automatic correction.

이 저장소의 구조를 설명해줘.
테스트 실행 방법을 찾아줘.
이 에러 로그의 원인을 후보별로 정리해줘.

When requesting a file modification, make sure your Git status is clean first.

git status

After making modifications, do not just rely on the explanations in the Codex, but test them yourself.

npm test
npm run build

When using it in corporate code or sensitive projects, you should also check the security policy. We recommend that you avoid pasting API Keys, customer data, operational passwords, and in-house tokens directly into the Codex prompt or configuration file.

Common Mistakes

Determining installation issues by only looking at the Node version

The current npm package standard is node >=16no see. Problems are more often caused by differences in npm global install path, PATH, and global package location due to nvm transitions than with Node versions.

Just following the old installation commands

Codex CLI is a rapidly changing tool. You should look at the official README and GitHub Release for the most up-to-date information before the installation instructions in the blog post.

Understanding the mixture of API Key method and ChatGPT login method

The official README recommends logging into your ChatGPT account. The API Key method is also possible, but separate settings and permission confirmation may be required. Mistaking an authentication issue for an installation issue can cost you a lot of time.

Codex does not verify the results of modifications

Codex allows code modifications, but the results of modifications may not always match the project’s intent. Testing, building, and diff checking must be done by the user.

Conclusion

Installing Codex CLI itself is not difficult. For macOS and Linux, you can use the official installation script, npm, or Homebrew cask, and for Windows, you can use the PowerShell installation script.

However, the part that actually takes up time is not the installation command, but differences in PATH, authentication, account permissions, network, and terminal environment. So the Codex CLI article is more than a simple installation procedure. command not found, it is much more practical to look at failure cases together, such as login permission issues, WebSocket/proxy issues, and environment variable issues.

If you are installing for the first time, please follow the steps below.

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

If you already have an npm environment organized, the following approach should suffice:

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

References

  • OpenAI Codex GitHub README: https://github.com/openai/codex
  • Codex CLI npm package: https://www.npmjs.com/package/@openai/codex
  • Codex latest GitHub Release: https://github.com/openai/codex/releases/latest
  • OpenAI Codex certification document: https://developers.openai.com/codex/auth
  • OpenAI Codex CLI feature documentation: https://developers.openai.com/codex/cli/features
  • OpenAI Codex configuration document: https://developers.openai.com/codex/config-basic
  • GitHub issue: WebSocket timeout/fallback example: https://github.com/openai/codex/issues/28503
  • GitHub issue: On macOS rg Blocking case: https://github.com/openai/codex/issues/28190
  • GitHub issue: Case related to environment variable inheritance: https://github.com/openai/codex/issues/3064