"Codex CLI Installation Guide: Setup on macOS, Linux, Windows WSL and CI/CD"

Codex CLI Installation Guide: Setup on macOS, Linux, Windows WSL and CI/CD#

OpenAI's Codex CLI is a terminal-based AI coding agent that uses o4-mini to read, write, and execute code in your projects. Getting it installed correctly — especially in corporate environments with proxies, or in CI/CD pipelines — can be tricky.

This guide covers installation on every platform, common issues, and production deployment patterns.

What Is Codex CLI?#

Codex CLI is OpenAI's answer to Claude Code. It's a terminal agent that:

Reads your project files and understands context
Writes and modifies code across multiple files
Runs shell commands (build, test, lint)
Manages git operations
Uses o4-mini model for fast, cost-effective coding assistance

Key difference from Claude Code: Codex CLI is open source and uses o4-mini (cheaper, faster) rather than Opus 4 (more capable, expensive). It's better for routine tasks; Claude Code is better for complex architecture work.

Prerequisites#

Requirement	Minimum	Recommended
Node.js	18.0+	22.x LTS
npm	9.0+	10.x
OS	macOS 12+, Ubuntu 20.04+, Windows 10+ (WSL2)	Latest
RAM	4GB	8GB+
Disk	500MB	1GB

Installation by Platform#

macOS#

bash

# Option 1: npm (recommended)
npm install -g @openai/codex-cli

# Option 2: Homebrew
brew install openai-codex

# Option 3: Direct download
curl -fsSL https://cli.openai.com/install.sh | bash

# Verify installation
codex --version

macOS Troubleshooting#

bash

# Permission error on npm global install
sudo npm install -g @openai/codex-cli
# Better: fix npm permissions
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
npm install -g @openai/codex-cli

# Apple Silicon (M1/M2/M3) specific
# If you get architecture errors:
arch -arm64 npm install -g @openai/codex-cli

Linux (Ubuntu/Debian)#

bash

# Install Node.js if not present
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

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

# Verify
codex --version

# If you get EACCES errors:
sudo npm install -g @openai/codex-cli --unsafe-perm

Linux (RHEL/CentOS/Fedora)#

bash

# Install Node.js
curl -fsSL https://rpm.nodesource.com/setup_22.x | sudo bash -
sudo dnf install -y nodejs

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

Windows (WSL2)#

bash

# 1. Install WSL2 if not already done (PowerShell as Admin)
# wsl --install

# 2. Inside WSL2 (Ubuntu):
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

# 3. Install Codex CLI
npm install -g @openai/codex-cli

# 4. Verify
codex --version

# Note: Run Codex inside WSL2, not native Windows CMD/PowerShell

Docker#

dockerfile

FROM node:22-slim

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

# Set up workspace
WORKDIR /workspace

# Configure API key at runtime
ENV OPENAI_API_KEY=""

ENTRYPOINT ["codex"]

bash

# Build and run
docker build -t codex-cli .
docker run -it \
  -e OPENAI_API_KEY="your-key" \
  -v $(pwd):/workspace \
  codex-cli "explain this project"

Configuration#

API Key Setup#

bash

# Option 1: Environment variable (recommended)
export OPENAI_API_KEY="your-openai-api-key"

# Option 2: Use Crazyrouter for cheaper access
export OPENAI_API_KEY="your-crazyrouter-key"
export OPENAI_BASE_URL="https://crazyrouter.com/v1"

# Option 3: Config file
mkdir -p ~/.codex
cat > ~/.codex/config.json << 'EOF'
{
  "apiKey": "your-key",
  "baseUrl": "https://crazyrouter.com/v1",
  "model": "o4-mini",
  "maxTokens": 8192
}
EOF

# Add to shell profile for persistence
echo 'export OPENAI_API_KEY="your-key"' >> ~/.bashrc
echo 'export OPENAI_BASE_URL="https://crazyrouter.com/v1"' >> ~/.bashrc
source ~/.bashrc

Proxy Configuration#

For corporate environments behind a proxy:

bash

# HTTP proxy
export HTTP_PROXY="http://proxy.company.com:8080"
export HTTPS_PROXY="http://proxy.company.com:8080"
export NO_PROXY="localhost,127.0.0.1,.company.com"

# SOCKS proxy
export ALL_PROXY="socks5://proxy.company.com:1080"

# npm proxy (for installation)
npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080

# Then install
npm install -g @openai/codex-cli

Custom Certificate (Corporate SSL Inspection)#

bash

# If your company uses SSL inspection with custom CA
export NODE_EXTRA_CA_CERTS="/path/to/company-ca.pem"

# Or disable SSL verification (not recommended for production)
export NODE_TLS_REJECT_UNAUTHORIZED=0

CI/CD Integration#

GitHub Actions#

yaml

name: AI Code Review
on: [pull_request]

jobs:
  codex-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '22'

      - name: Install Codex CLI
        run: npm install -g @openai/codex-cli

      - name: Run AI Code Review
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
          OPENAI_BASE_URL: "https://crazyrouter.com/v1"
        run: |
          codex --once "Review the code changes in this PR. \
            Focus on bugs, security issues, and performance. \
            Output as markdown."

GitLab CI#

yaml

codex-review:
  image: node:22-slim
  stage: review
  script:
    - npm install -g @openai/codex-cli
    - codex --once "Review recent changes for bugs and security issues"
  variables:
    OPENAI_API_KEY: $OPENAI_API_KEY
    OPENAI_BASE_URL: "https://crazyrouter.com/v1"
  only:
    - merge_requests

Jenkins Pipeline#

groovy

pipeline {
    agent { docker { image 'node:22-slim' } }
    environment {
        OPENAI_API_KEY = credentials('openai-api-key')
        OPENAI_BASE_URL = 'https://crazyrouter.com/v1'
    }
    stages {
        stage('AI Review') {
            steps {
                sh 'npm install -g @openai/codex-cli'
                sh 'codex --once "Analyze this build for potential issues"'
            }
        }
    }
}

Team Onboarding Script#

Create a setup script for your team:

bash

#!/bin/bash
# setup-codex.sh - Team onboarding script

set -e

echo "🤖 Setting up Codex CLI..."

# Check Node.js
if ! command -v node &> /dev/null; then
    echo "❌ Node.js not found. Installing..."
    curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
    sudo apt-get install -y nodejs
fi

NODE_VERSION=$(node --version | cut -d'v' -f2 | cut -d'.' -f1)
if [ "$NODE_VERSION" -lt 18 ]; then
    echo "❌ Node.js 18+ required. Current: $(node --version)"
    exit 1
fi

# Install Codex CLI
echo "📦 Installing Codex CLI..."
npm install -g @openai/codex-cli

# Configure
echo "⚙️ Configuring..."
mkdir -p ~/.codex

# Use team API gateway
cat > ~/.codex/config.json << 'EOF'
{
  "baseUrl": "https://crazyrouter.com/v1",
  "model": "o4-mini",
  "maxTokens": 8192,
  "confirmCommands": true
}
EOF

echo ""
echo "✅ Codex CLI installed successfully!"
echo ""
echo "Next steps:"
echo "  1. Set your API key: export OPENAI_API_KEY='your-crazyrouter-key'"
echo "  2. Add to ~/.bashrc for persistence"
echo "  3. Run 'codex' in any project directory"
echo ""
codex --version

Pricing: Direct vs Crazyrouter#

Usage Pattern	OpenAI Direct	Crazyrouter	Monthly Savings
Light (20 sessions/day)	$45/month	$18/month	$27 (60%)
Medium (50 sessions/day)	$112/month	$45/month	$67 (60%)
Heavy (100 sessions/day)	$225/month	$90/month	$135 (60%)
CI/CD (500 runs/month)	$150/month	$60/month	$90 (60%)

o4-mini pricing:

OpenAI Direct: $1.10/1M input,$ 4.40/1M output
Crazyrouter: $0.44/1M input,$ 1.76/1M output

Common Issues & Fixes#

"command not found: codex"#

bash

# Check npm global bin path
npm config get prefix
# Add to PATH if needed
export PATH="$(npm config get prefix)/bin:$PATH"

"ECONNREFUSED" or timeout errors#

bash

# Check if proxy is needed
curl -I https://api.openai.com
# If blocked, set proxy or use Crazyrouter
export OPENAI_BASE_URL="https://crazyrouter.com/v1"

"Insufficient quota" errors#

bash

# Check your balance
curl https://api.openai.com/v1/usage \
  -H "Authorization: Bearer $OPENAI_API_KEY"

# Switch to Crazyrouter for lower costs
export OPENAI_BASE_URL="https://crazyrouter.com/v1"

Slow performance#

bash

# Use streaming for faster perceived response
codex --stream "your prompt"

# Reduce context by excluding large files
echo "node_modules/\ndist/\n*.lock" > .codexignore

FAQ#

How do I install Codex CLI?#

Run npm install -g @openai/codex-cli with Node.js 18+. Set your API key with export OPENAI_API_KEY="your-key". Then run codex in any project directory.

Is Codex CLI free?#

The CLI tool itself is free and open source. You pay for API usage (o4-mini tokens). OpenAI charges $1.10/$ 4.40 per million tokens. Through Crazyrouter, it's $0.44/$ 1.76 — about 60% cheaper.

Can I use Codex CLI without an OpenAI account?#

Yes. You can point Codex CLI to any OpenAI-compatible API endpoint. Set OPENAI_BASE_URL to Crazyrouter or another provider that offers o4-mini access.

Does Codex CLI work on Windows?#

Not natively. Use WSL2 (Windows Subsystem for Linux) which provides a full Linux environment. Codex CLI works perfectly inside WSL2.

How is Codex CLI different from GitHub Copilot?#

Codex CLI is a terminal agent that can read/write files and run commands autonomously. Copilot is an editor plugin that suggests code inline. Codex CLI handles larger tasks (refactoring, debugging, feature implementation); Copilot helps with line-by-line completion.

Summary#

Codex CLI installation is straightforward on macOS and Linux (npm install -g @openai/codex-cli). For Windows, use WSL2. For corporate environments, configure proxy settings and custom certificates. For CI/CD, add it as a build step with your API key as a secret.

Use Crazyrouter as your API backend to cut Codex CLI costs by 60% while maintaining the same o4-mini model quality. One environment variable change (OPENAI_BASE_URL) is all it takes.

"Codex CLI Installation Guide: Setup on macOS, Linux, Windows WSL and CI/CD"