OpenAI Codex CLI: Complete Setup Guide (2026)

OpenAI Codex CLI: Complete Setup Guide for 2026

OpenAI's Codex CLI is a command-line AI coding agent that can read your codebase, write and edit files, run shell commands, and iteratively solve programming tasks. Think of it as an AI pair programmer that lives in your terminal. Unlike IDE-based tools, Codex CLI operates through a text interface, which makes it fast, scriptable, and works over SSH.

This guide covers everything from installation to advanced usage patterns.

What Is Codex CLI?

Codex CLI is OpenAI's open-source terminal-based coding agent. It uses OpenAI's models (primarily o4-mini and GPT-4o) to understand your codebase and execute multi-step tasks. Key features include:

• File reading and writing -- It can navigate your project and modify files
• Shell command execution -- It can run tests, install packages, and execute build commands
• Multi-step reasoning -- It plans and executes complex tasks across multiple files
• Sandboxed execution -- Commands run in a sandboxed environment for safety
• Conversation context -- It maintains context throughout a session

Prerequisites

Before installing Codex CLI, make sure you have:

Requirement	Minimum Version	Check Command
Node.js	22+	node --version
npm	9+	npm --version
Git	2.0+	git --version
OpenAI API key	--	platform.openai.com/api-keys

Installation

Install via npm

npm install -g @openai/codex

Verify Installation

codex --version

Set Up Your API Key

Codex CLI requires an OpenAI API key. Set it as an environment variable:

# Add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
export OPENAI_API_KEY="sk-proj-xxxxxxxxxxxxxxxxxxxx"

Reload your shell:

source ~/.zshrc  # or ~/.bashrc

Verify the key is set:

echo $OPENAI_API_KEY

Basic Usage

Interactive Mode

Start Codex CLI in interactive mode in your project directory:

cd /path/to/your/project
codex

You will see a prompt where you can type natural language instructions:

> Fix the failing tests in the auth module

Codex will analyze the test failures, read the relevant files, and propose fixes.

One-Shot Mode

Run a single instruction without entering interactive mode:

codex "add input validation to the signup endpoint"

Piping Input

Pipe content into Codex for analysis:

cat error.log | codex "explain these errors and suggest fixes"
git diff HEAD~3 | codex "write a changelog entry for these changes"

Configuration

Config File

Create a configuration file at ~/.codex/config.json:

{
  "model": "o4-mini",
  "approval_mode": "suggest",
  "sandbox": "docker"
}

Project-Level Configuration

Create a codex.md file in your project root to give Codex context about your project:

# Project: MyApp

## Tech Stack
- TypeScript, React, Next.js
- PostgreSQL with Prisma ORM
- Tailwind CSS

## Conventions
- Use functional components with hooks
- Use `pnpm` as the package manager
- Tests go in `__tests__/` directories next to source files
- Use kebab-case for file names

## Important
- Never modify files in the `migrations/` directory directly
- Always run `pnpm test` after making changes
- Environment variables are in `.env.local` (do not commit)

Codex reads this file automatically and uses it as context for every interaction.

Approval Modes

Codex CLI has three approval modes that control how much autonomy the agent has:

Mode	File Edits	Shell Commands	Best For
suggest	Requires approval	Requires approval	Learning, reviewing
auto-edit	Automatic	Requires approval	Trusted file changes
full-auto	Automatic	Automatic	Scripting, CI pipelines

Set the mode at startup:

# Suggest mode (safest, default)
codex --approval-mode suggest "refactor the auth module"

# Auto-edit mode (approves file changes, asks for commands)
codex --approval-mode auto-edit "add unit tests for the User model"

# Full-auto mode (approves everything)
codex --approval-mode full-auto "fix all ESLint errors"

Practical Examples

Example 1: Fix Failing Tests

codex "run the tests, identify failures, and fix them"

Codex will:

1. Run your test suite to identify failures
2. Read the failing test files and source files
3. Analyze the root cause
4. Make targeted fixes
5. Re-run the tests to verify

Example 2: Add a New Feature

codex "add a rate limiting middleware to the Express API using express-rate-limit. \
Limit to 100 requests per 15 minutes per IP. Add tests."

Example 3: Refactor Code

codex "refactor the database queries in src/services/ to use the repository pattern. \
Keep the existing tests passing."

Example 4: Code Review

git diff main | codex "review this diff for bugs, security issues, and style problems"

Example 5: Documentation

codex "generate JSDoc comments for all exported functions in src/utils/"

Example 6: Debugging

codex "the /api/users endpoint returns 500 when the email contains a plus sign. \
Find and fix the bug."

Advanced Usage

Using with CI/CD

Codex CLI can run in non-interactive mode for CI/CD pipelines:

# .github/workflows/codex-fix.yml
name: Auto-fix lint errors
on:
  push:
    branches: [main]

jobs:
  fix:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
      - run: npm install -g @openai/codex
      - run: codex --approval-mode full-auto "fix all ESLint errors and format with Prettier"
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
      - run: git diff
      - uses: stefanzweifel/git-auto-commit-action@v5
        with:
          commit_message: "fix: auto-fix lint errors via Codex CLI"

Custom System Prompts

Override the default system prompt for specialized tasks:

codex --system-prompt "You are a security auditor. Review code for vulnerabilities only." \
  "audit the authentication flow"

Model Selection

Choose the model based on task complexity:

# Fast, cheap tasks
codex --model o4-mini "fix the typo in the README"

# Complex reasoning tasks
codex --model o3 "redesign the caching layer to handle cache stampedes"

Sandboxing Options

Codex supports different sandboxing strategies:

# Docker sandbox (recommended for full-auto mode)
codex --sandbox docker "install dependencies and run the test suite"

# Network-disabled sandbox
codex --sandbox network-disabled "refactor the parser module"

# No sandbox (use with caution)
codex --sandbox none "run the deployment script"

Codex CLI vs Other CLI Tools

Feature	Codex CLI	Claude Code	Aider
Provider	OpenAI	Anthropic	Multi-provider
Default Model	o4-mini	Claude Sonnet	Configurable
File Editing	Yes	Yes	Yes
Shell Commands	Yes (sandboxed)	Yes	Limited
Approval Modes	3 modes	Per-tool	Auto/manual
Open Source	Yes	No	Yes
MCP Support	No	Yes	No
Git Integration	Basic	Advanced	Advanced
Price	API usage	API usage	Free (BYOK)

Cost Management

Codex CLI charges based on OpenAI API token usage. Here is a rough cost guide:

Task Type	Estimated Cost	Model
Simple fix (1-2 files)	$0.01-0.05	o4-mini
Feature addition (3-5 files)	$0.05-0.20	o4-mini
Complex refactor (10+ files)	$0.20-1.00	o4-mini
Architecture redesign	$1.00-5.00	o3

Tips to Reduce Costs

1. Be specific in your prompts. Vague instructions cause more back-and-forth
2. Use o4-mini for most tasks. It handles 90% of coding tasks well
3. Break large tasks into smaller ones. Each task starts with fresh context
4. Use the codex.md file. Good project context reduces exploratory reads

Troubleshooting

"Command not found: codex"

# Check if it is installed
npm list -g @openai/codex

# Reinstall
npm install -g @openai/codex

# Check your PATH
echo $PATH

"Invalid API key"

# Verify your key
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  | head -c 200

Codex Makes Incorrect Changes

• Use suggest mode so you can review before applying
• Add more context to your codex.md project file
• Be more specific in your instructions
• Break complex tasks into smaller, focused steps

Docker Sandbox Issues

# Make sure Docker is running
docker ps

# Pull the Codex sandbox image
docker pull openai/codex-sandbox:latest

Building AI-Powered Applications

Codex CLI is excellent for writing code, but if your application needs to generate images, videos, audio, or avatars, you will need media generation APIs alongside your code. Hypereal AI offers a unified API for AI media generation that you can integrate into projects built with Codex CLI, giving you both intelligent code generation and AI-powered media creation in one workflow.

Summary

OpenAI Codex CLI is a powerful terminal-based coding agent. Install it with npm install -g @openai/codex, set your OPENAI_API_KEY, and create a codex.md file in your project for context. Use suggest mode when learning, auto-edit for trusted changes, and full-auto for scripting and CI pipelines. For most tasks, o4-mini provides the best balance of speed, quality, and cost.