"Codex CLI Installation Guide: Setup OpenAI's AI Coding Agent in Minutes"

OpenAI's Codex CLI is a terminal-based AI coding agent that reads your codebase, suggests edits, runs commands, and helps you ship code faster — all from the command line. If you've been looking for a way to bring AI-assisted development directly into your workflow without leaving the terminal, Codex CLI is worth your attention.

This guide walks you through installing Codex CLI on macOS, Linux, and Windows (via WSL), configuring your API key, and getting productive with it immediately.

What Is Codex CLI?#

Codex CLI is an open-source, lightweight coding agent built by OpenAI. Unlike browser-based AI assistants, it runs entirely in your terminal. You describe what you want in natural language, and Codex CLI:

• Reads and understands your project files
• Generates and applies code changes
• Runs shell commands on your behalf
• Handles multi-file edits in a single session

It's designed for developers who prefer keyboard-driven workflows and want AI assistance without context-switching to a browser.

System Requirements#

Before installing, make sure your system meets these requirements:

Step 1: Install Node.js#

Codex CLI requires Node.js v22+. Check your current version:

node --version

If you need to install or upgrade Node.js:

macOS (using Homebrew):

brew install node@22

Ubuntu/Debian:

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

Using nvm (recommended for version management):

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22

Step 2: Install Codex CLI#

With Node.js ready, install Codex CLI globally:

npm install -g @openai/codex

Verify the installation:

codex --version

You should see the version number printed. If you get a "command not found" error, make sure your npm global bin directory is in your PATH:

export PATH="$(npm config get prefix)/bin:$PATH"

Add this line to your ~/.bashrc or ~/.zshrc to make it permanent.

Step 3: Configure Your API Key#

Codex CLI needs an API key to communicate with the AI model. You have two options:

Option A: OpenAI API Key#

Set your OpenAI API key as an environment variable:

export OPENAI_API_KEY="sk-your-api-key-here"

Add it to your shell profile for persistence:

echo 'export OPENAI_API_KEY="sk-your-api-key-here"' >> ~/.bashrc
source ~/.bashrc

Option B: Use Crazyrouter as Your API Provider (Recommended)#

If you want access to multiple models (not just OpenAI) at lower prices, you can point Codex CLI to Crazyrouter:

export OPENAI_API_KEY="your-crazyrouter-api-key"
export OPENAI_BASE_URL="https://crazyrouter.com/v1"

This gives you access to 300+ models including Claude, Gemini, DeepSeek, and more — all through the same OpenAI-compatible API format. Pricing is typically 20-50% lower than going direct.

Step 4: Run Your First Command#

Navigate to a project directory and start Codex CLI:

cd your-project
codex

You'll enter an interactive session. Try a simple prompt:

> Add input validation to the signup form

Codex CLI will analyze your codebase, propose changes, and ask for confirmation before applying them.

Common Commands#

# Interactive mode (default)
codex

# Single prompt mode
codex "refactor the database connection to use connection pooling"

# Quiet mode (auto-approve safe operations)
codex --quiet "add TypeScript types to utils.js"

# Full auto mode (approve everything — use with caution)
codex --full-auto "write unit tests for auth module"

Step 5: Configure Approval Modes#

Codex CLI has three safety levels for approving actions:

For most development work, the default suggest mode is safest. Use --quiet when you trust the changes (like formatting or adding types), and reserve --full-auto for isolated test environments.

Codex CLI vs Alternatives#

How does Codex CLI compare to other AI coding tools?

All three are solid tools. Codex CLI's advantage is its open-source nature and tight integration with the OpenAI ecosystem. If you want to use multiple models, pairing any of these with Crazyrouter gives you flexibility to switch between providers without changing your workflow.

Pricing: Codex CLI API Costs#

Codex CLI itself is free and open source. You only pay for API usage. Here's what typical sessions cost:

A typical coding session (30-60 minutes) uses roughly 50K-200K tokens, costing $0.10-$1.60 depending on the model and task complexity.

Troubleshooting Common Issues#

"command not found: codex"#

Your npm global bin isn't in PATH. Fix it:

# Find where npm installs global packages
npm config get prefix

# Add to PATH (replace /usr/local with your prefix)
export PATH="/usr/local/bin:$PATH"

"Error: OPENAI_API_KEY is not set"#

Make sure your API key is exported in the current shell:

echo $OPENAI_API_KEY
# Should print your key. If empty:
export OPENAI_API_KEY="sk-your-key"

Node.js Version Too Old#

node --version
# If below v22, upgrade:
nvm install 22 && nvm use 22

Permission Errors on Linux#

# Don't use sudo with npm install -g. Instead, fix npm permissions:
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH="$HOME/.npm-global/bin:$PATH"
npm install -g @openai/codex

Slow Responses or Timeouts#

If you're experiencing latency, try using a closer API endpoint. Crazyrouter offers optimized routing that can reduce latency for users in Asia and Europe:

export OPENAI_BASE_URL="https://crazyrouter.com/v1"

Advanced Configuration#

Custom Model Selection#

# Use a specific model
codex --model gpt-4.1 "optimize this SQL query"

# Use a cheaper model for simple tasks
codex --model gpt-4.1-nano "add comments to this file"

Project-Level Configuration#

Create a .codex file in your project root:

{
  "model": "gpt-4.1",
  "approval_mode": "suggest",
  "ignore": ["node_modules", "dist", ".env"]
}

Integration with Git#

Codex CLI works well with Git workflows:

# Create a branch, make changes, commit
git checkout -b feature/add-validation
codex "add email validation to the registration endpoint"
git add -A && git commit -m "Add email validation"

FAQ#

Is Codex CLI free to use?#

Yes, Codex CLI is free and open source (Apache 2.0 license). You only pay for the API calls to the AI model provider. Using Crazyrouter can reduce these costs by 20-50%.

Can I use Codex CLI with models other than OpenAI?#

Yes. By setting OPENAI_BASE_URL to a compatible API endpoint like Crazyrouter, you can use Claude, Gemini, DeepSeek, and 300+ other models with the same Codex CLI interface.

Is Codex CLI safe to use on production code?#

In the default "suggest" mode, Codex CLI shows you every change before applying it. It won't modify files or run commands without your explicit approval. The --full-auto mode should only be used in sandboxed environments.

How does Codex CLI compare to GitHub Copilot?#

GitHub Copilot is an inline code completion tool integrated into editors. Codex CLI is a terminal-based agent that can make multi-file changes, run commands, and handle complex tasks. They complement each other — use Copilot for line-by-line suggestions and Codex CLI for larger refactoring tasks.

What's the best model to use with Codex CLI?#

GPT-4.1 offers the best balance of capability and cost for most coding tasks. For simple tasks (formatting, comments, renaming), GPT-4.1 nano is much cheaper. For complex architectural decisions, consider using Claude Opus or GPT-4.1 through Crazyrouter.

Summary#

Codex CLI brings AI-powered coding directly to your terminal with a simple npm install. The setup takes under 5 minutes, and you can start shipping code faster immediately.

For the best experience and lowest costs, pair Codex CLI with Crazyrouter — one API key gives you access to 300+ models including GPT-4.1, Claude, Gemini, and more, all at reduced pricing. Sign up at crazyrouter.com to get started.