Codex CLI Installation Guide: macOS / Windows / Linux (2026)

Codex CLI is OpenAI's command-line AI coding tool that lets developers write, modify, and debug code using natural language directly in the terminal. However, for developers in regions with network restrictions, the installation process is often plagued by problems — npm install hanging indefinitely, GitHub Release downloads timing out, and successful installations failing to connect to the API. This guide provides a complete cross-platform walkthrough and shows how TeamoRouter resolves the network bottleneck in one step.

Why Installing Codex CLI Often Fails in China

Codex CLI's dependency fetching and API calls rely on overseas services. Under China's domestic network conditions, you'll encounter a few typical obstacles:

• npm registry throttling: The default registry at registry.npmjs.org is unreliable from within China — npm install -g @openai/codex can time out repeatedly.
• GitHub Release downloads are slow: Pre-compiled binaries are hosted on GitHub, where download speeds often drop to tens of KB/s.
• Inaccessible CDN dependencies: Codex CLI dynamically pulls JS runtime dependencies from CDNs like esm.sh and deno.land, which are also restricted.
• API connection failure after installation: The CLI connects to api.openai.com by default — direct connections from China often result in packet loss or ETIMEDOUT, rendering a successful install unusable.

These problems compound: you get it installed but can't connect, and setting up a proxy often conflicts with the CLI's local port. Let's fix them one by one, starting from the basics.

Prerequisites

Check if Node.js is installed

node --version
# Should output v18.x.x or higher
npm --version
# Should output 9.x.x or higher

If not installed, download the LTS version from nodejs.org.

macOS Installation

Method 1: npm Global Install (Recommended)

# Set npm registry mirror (essential for domestic networks)
npm config set registry https://registry.npmmirror.com

# Install Codex CLI globally
npm install -g @openai/codex

# Verify installation
codex --version

If npm install -g throws an EACCES permission error, fix the npm global path or use npx instead: npx @openai/codex --version.

Method 2: Homebrew

brew install openai/codex/codex

Configure Homebrew mirrors first in China:

export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.ustc.edu.cn/brew.git"
brew update
brew install openai/codex/codex

Method 3: GitHub Release

Download the appropriate .tar.gz from GitHub Releases, extract, and install:

# Example for codex-darwin-arm64.tar.gz
tar xzf codex-darwin-arm64.tar.gz
mv codex /usr/local/bin/
codex --version

Windows PowerShell Installation

Method 1: npm Global Install

# Set npm registry mirror
npm config set registry https://registry.npmmirror.com

# Global install
npm install -g @openai/codex

# Verify
codex --version

Method 2: Scoop

# Install Scoop if not already installed
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
irm get.scoop.sh | iex

# Add openai bucket
scoop bucket add openai https://github.com/openai/scoop-bucket

# Install Codex CLI
scoop install codex

Method 3: winget

winget install --id OpenAI.Codex

Linux / WSL2 Installation

Ubuntu / Debian

npm config set registry https://registry.npmmirror.com
npm install -g @openai/codex

# Or from GitHub Release
wget https://github.com/openai/codex/releases/latest/download/codex-linux-x64.tar.gz
tar xzf codex-linux-x64.tar.gz
sudo mv codex /usr/local/bin/

Arch Linux

yay -S codex-cli

WSL2 (Windows Subsystem for Linux)

WSL2 follows the same steps as a native Linux installation:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
nvm install 20
nvm use 20
npm install -g @openai/codex

npm vs Homebrew vs GitHub Release

Common Installation Errors

EACCES: permission denied

npm ERR! Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules/@openai/codex'

Fix:

# Option 1: Fix npm global path (recommended)
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

# Option 2: Use nvm
nvm install 20
nvm use 20

npm ERR! code ETIMEDOUT

npm ERR! code ETIMEDOUT
npm ERR! errno ETIMEDOUT
npm ERR! network request to https://registry.npmjs.org/@openai%2fcodex failed

Fix: Set npm mirror:

npm config set registry https://registry.npmmirror.com

SHA-256 Integrity Check Failed

# After downloading from GitHub Release
Error: integrity check failed

Fix: Re-download the archive, or switch to the npm installation method.

codex Command Not Found After Installation

npm bin -g
echo $PATH
# Ensure the global bin path is in your PATH

Recommended Network Config for Domestic Users

Installation is only half the battle — the CLI's API connections also need attention. Use TeamoRouter as an API gateway to resolve network issues in one step:

export OPENAI_BASE_URL="https://api.teamorouter.com/v1"
export OPENAI_API_KEY="sk-teamo-xxxxxxxx"

codex

Or persist the configuration:

echo 'export OPENAI_BASE_URL="https://api.teamorouter.com/v1"' >> ~/.zshrc
echo 'export OPENAI_API_KEY="sk-teamo-xxxxxxxx"' >> ~/.zshrc
source ~/.zshrc

FAQ

What Node.js version is required for Codex CLI?

Node.js v20 LTS or higher is recommended. v18 works but v20 offers better performance and stability.

npm install hangs at "sill idealTree buildDeps" — what now?

npm cannot reach the default registry. Set a mirror and retry:

npm config set registry https://registry.npmmirror.com
npm cache clean --force
npm install -g @openai/codex

Codex CLI is installed but shows "connection refused"?

Codex CLI connects to api.openai.com by default. Use TeamoRouter as a gateway:

export OPENAI_BASE_URL="https://api.teamorouter.com/v1"
export OPENAI_API_KEY="sk-teamo-xxxxxxxx"

Do I need to install Codex separately on WSL2 and Windows?

WSL2 is a self-contained Linux environment. If you develop primarily in WSL2, install Codex there once. Windows files can be accessed via \\wsl.localhost\.

Is there any difference between the GitHub Release and npm versions?

Functionally identical. The GitHub Release is a pre-compiled binary that runs without Node.js, while the npm version depends on the Node.js runtime.

Get Started

Once installed, pair Codex CLI with TeamoRouter and start coding immediately:

1. Sign up for TeamoRouter and get an API Key
2. Follow the Codex install guide to configure baseUrl and API Key
3. Run codex for interactive mode, or codex "your task" for one-shot tasks

Get Your Free Codex Setup →

Access Codex, Claude Code, and Gemini CLI stably through TeamoRouter.