OpenAI Codex: Installation and Setup Guide: Features, Pricing, and Risks

OpenAI Codex is a cloud-native software engineering agent that parallelizes work across Git worktrees. Unlike terminal-based alternatives (Claude Code, Kimi), Codex operates through a command-center interface with real-time web dashboard for monitoring multiple simultaneous agents.

This guide covers installation across all supported platforms and basic configuration to get first tasks running.

Prerequisites

Before installing Codex, you need:

Git repository — Codex requires a Git-tracked project (worktrees are Git-native)
ChatGPT account — Plus ($20/mo), Pro ($200/mo), Team, or Enterprise
Node.js 18+ (for CLI installation) or macOS 12+ (for desktop app)

Important: Codex does not support “bring your own API key.” You must authenticate via ChatGPT account and purchase separate credits for Codex usage.

Installation Options

Option 1: CLI via NPM (Recommended for Developers)

The command-line interface provides maximum flexibility and integrates with existing terminal workflows.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
# Install globally
npm install -g @openai/codex

# Verify installation
codex --version
# Expected: 0.94.0 or higher

# Authenticate
codex auth login
# Opens browser to ChatGPT sign-in

Platforms: macOS (arm64/x86_64), Linux (arm64/x86_64), Windows (via WSL)

Option 2: CLI via Homebrew (macOS/Linux)

For macOS users preferring Homebrew over NPM:

1
2
3
4
5
6
7
8
# Install
brew install --cask codex

# Or (alternate tap)
brew install codex

# Verify
codex --version

Note: The --cask flag installs the desktop app; without it installs CLI only. Most developers want CLI.

Option 3: GitHub Releases (Binary Download)

For air-gapped environments or specific version pinning:

Visit github.com/openai/codex/releases
Download binary for your platform:
- codex-macos-arm64 (Apple Silicon)
- codex-macos-x86_64 (Intel Mac)
- codex-linux-arm64 (ARM Linux)
- codex-linux-x86_64 (x86 Linux)
Move to PATH: chmod +x codex-* && sudo mv codex-* /usr/local/bin/codex

Current stable: v0.94.0 (released February 2, 2026)

Option 4: macOS Desktop App

For users preferring GUI over terminal:

Download from openai.com/codex
Drag to Applications folder
Launch and authenticate with ChatGPT account
Grant accessibility permissions when prompted

Features:

Menu bar agent monitoring
Visual worktree dashboard
Drag-and-drop task creation
Native macOS notifications

Limitations: Cannot be used for remote/SSH development; local projects only.

JetBrains IDE Integration

Codex provides native JetBrains plugin support (IntelliJ IDEA, PyCharm, WebStorm, etc.).

Installation

Open JetBrains IDE → Preferences → Plugins
Search “OpenAI Codex” in Marketplace
Click Install → Restart IDE
Authenticate via Codex tool window (ChatGPT sign-in)

Configuration

Tool Window Setup:

View → Tool Windows → Codex
Dock alongside Project/Structure windows
Pin for persistent access

Keyboard Shortcuts:

Default: Cmd+Shift+C (macOS) / Ctrl+Shift+C (Linux/Windows)
Customize: Preferences → Keymap → search “Codex”

Editor Integration:

Inlay hints show agent status in code margins
Right-click → “Explain with Codex” for contextual queries
Right-click → “Refactor with Codex” for multi-file changes

AGENTS.md Configuration

Codex supports declarative agent configuration via AGENTS.md files in your repository root. This transforms generic assistants into organization-specific team members.

Basic Structure

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
# AGENTS.md — OpenAI Codex Agent Configuration
# Place in repository root

agents:
  BackendRefactor:
    model: gpt-5.2-codex
    reasoning: high
    skills: [$search, $test, $semgrep]
    scope: 
      - 'src/server/**/*.py'
      - 'src/models/**'
    constraints:
      - maintain_backward_compatibility: true
      - test_coverage_minimum: 90
      - allowed_imports: ['fastapi', 'pydantic', 'sqlalchemy']
    
  FrontendMigration:
    model: gpt-5.2-codex
    reasoning: medium
    skills: [$search, $imagegen]
    scope:
      - 'src/frontend/**/*.tsx'
      - 'src/components/**'
    constraints:
      - framework: react
      - styling: tailwind
      - accessibility_compliant: true

Key Configuration Options

Field	Description	Values
`model`	GPT model to use	`gpt-5.2-codex`, `gpt-5.1-codex-mini`
`reasoning`	Thinking depth	`low`, `medium`, `high`, `xhigh`
`skills`	Available tools	`$search`, `$test`, `$semgrep`, `$imagegen`, etc.
`scope`	File patterns agent can access	Glob patterns relative to repo root
`constraints`	Behavioral rules	Custom key-value pairs

Worktree Configuration

For parallel execution, Codex creates Git worktrees automatically. You can pre-configure worktree structure:

1
2
3
4
5
6
7
8
worktrees:
  base: main
  isolation: strict  # Each agent gets clean copy
  
agents:
  ApiV2Migration:
    worktree: feature/api-v2-migration
    dependencies: [BackendRefactor]

Basic Workflow Example

Step 1: Navigate to Git Repository

1
2
3
4
5
cd /path/to/your-project

# Verify Git tracking
git status
# Should show clean working directory or tracked files

Step 2: Initialize Codex Session

1
2
3
4
5
# Start with default agent
codex plan "Migrate authentication from JWT to OAuth2"

# Or use pre-configured agent from AGENTS.md
codex plan "Migrate authentication from JWT to OAuth2" --agent BackendRefactor

Output:

Task decomposition displayed in terminal
Dependency analysis
Proposed worktree allocation
Estimated credit cost

Step 3: Review and Execute

1
2
3
4
5
6
7
8
# Review the plan
codex review

# Approve and execute
codex execute

# Or approve with modifications
codex execute --scope src/auth/** --exclude src/auth/legacy/**

Step 4: Monitor Progress

Terminal: Real-time streaming output from active agents

Web Dashboard: Open https://codex.openai.com/dashboard (automatically launched on codex execute)

Visual progress bars per agent
File change diffs
Test execution status
Credit consumption tracking

Step 5: Review and Merge

1
2
3
4
5
6
7
8
9
# Review changes
codex diff

# Run tests
codex test

# Merge to main
git checkout main
git merge feature/oauth-migration

Authentication and Credits

ChatGPT Account Linking

1
2
3
4
5
6
7
8
9
# Login (opens browser)
codex auth login

# Verify linked account
codex auth status
# Shows: plan (Plus/Pro/Team), remaining credits, rate limits

# Logout
codex auth logout

Credit Management

Critical: Codex requires credit purchases separate from subscription fees.

1
2
3
4
5
6
7
8
# Check credit balance
codex credits balance

# Purchase credits (opens browser)
codex credits purchase

# View usage history
codex credits history --last-30-days

Credit Consumption (approximate):

Local task with GPT-5.2-Codex: ~5 credits
Local task with GPT-5.1-Codex-Mini: ~1 credit
Cloud task (parallel agents): ~10-50 credits depending on complexity

Rate Limits by Tier:

Tier	Local Msgs/5h	Cloud Tasks/5h	Credits/Month
Plus ($20)	45-225	10-60	Purchase separately
Pro ($200)	300-1500	50-400	Purchase separately
Enterprise	Unlimited	Unlimited	Custom billing

Troubleshooting

“Not a Git repository” Error

Cause: Codex requires Git initialization.

Fix:

1
2
3
git init
git add .
git commit -m "Initial commit"

Authentication Failures

Symptoms: codex auth login hangs or returns error.

Fixes:

Clear browser cookies for openai.com
Run codex auth logout && codex auth login
Check ChatGPT subscription status at chatgpt.com
Verify no corporate VPN blocking OAuth

Rate Limit Errors

Symptoms: “Rate limit exceeded” during heavy usage.

Solutions:

Upgrade to Pro tier (6x higher limits)
Switch to GPT-5.1-Codex-Mini (4x higher rate limits)
Wait for 5-hour rolling window to reset
Purchase additional credits (does not increase rate limits)

Worktree Conflicts

Symptoms: “Worktree already exists” or merge conflicts.

Fix:

1
2
3
4
5
6
7
8
# List active worktrees
git worktree list

# Remove stale worktree
git worktree remove .git/worktrees/feature-name

# Or force cleanup
codex cleanup --force

Credit Depletion Mid-Task

Critical: Tasks halt if credits deplete. There is no “pay later” option.

Prevention:

1
2
3
4
5
# Check before large tasks
codex credits balance

# Set low-credit warning (in AGENTS.md)
credit_warning_threshold: 50

Advanced Configuration

Custom Skills Development

Extend Codex with organization-specific skills:

1
2
3
4
5
6
7
8
9
# AGENTS.md
skills:
  custom:
    - name: internal_api
      endpoint: https://api.yourcompany.com/codex-skill
      auth: bearer_token
    
    - name: compliance_check
      script: ./scripts/compliance.sh

Integration with CI/CD

1
2
3
4
5
6
7
8
# GitHub Actions example
- name: Run Codex Refactoring
  run: |
    npm install -g @openai/codex
    codex auth login --token ${{ secrets.OPENAI_TOKEN }}
    codex plan "Update dependencies to latest versions"
    codex execute
    codex test

Note: Codex CLI is designed for interactive use. CI integration requires careful handling of authentication and credits.

Security Best Practices

Repository Scope: Configure tight scope patterns in AGENTS.md to limit file access
Review Mode: Use codex review before codex execute for high-risk operations
Test Constraints: Set test_coverage_minimum and require passing tests before merge
Secret Exclusion: Ensure .env files and secrets directories are in .gitignore and excluded from scope
Audit Logging: Enterprise tier includes 7-year audit retention; lower tiers have limited logging

See detailed security analysis: /risks/codex/cloud-dependency-risks/

Migration from Other Tools

From Claude Code

Key differences:

Claude Code: Terminal-native, API billing, transparent reasoning
Codex: Cloud dashboard, credit system, parallel agents

Migration:

1
2
3
4
5
6
7
# Install Codex alongside Claude Code (they coexist)
npm install -g @openai/codex

# Convert existing project
cd your-project
codex init --from-claude-project
# Imports context from Claude's project settings

From Kimi k2.5