OpenAI Codex CLI: The Open-Source Coding Agent Guide

OpenAI shipped something unusual in 2025: an open-source terminal coding agent. Not a chat wrapper. Not an autocomplete engine bolted onto VS Code. A legitimate agentic coding tool written in Rust that reads your repo, edits files, runs commands, and iterates on its own work -- all from your terminal.

It's called Codex CLI, and it occupies a fascinating position in the AI coding landscape. It's open-source (Apache 2.0 licensed), it runs locally on your machine, and it's backed by OpenAI's Codex-optimized models that have been steadily climbing the benchmarks. If you've been watching the terminal-agent space dominated by Claude Code, Codex CLI is OpenAI's answer -- with some fundamentally different design choices.

This guide covers the practical setup, configuration, and daily workflows. No surface-level "install it and type hello" walkthrough. We're going from zero to productive.

🛠️ What You'll Need

• An OpenAI account -- either a ChatGPT subscription (Plus, Pro, Team, or Enterprise) or an OpenAI API key with credits
• Node.js 22+ -- Codex CLI is distributed via npm (the CLI itself is Rust, but the package manager is npm)
• A terminal -- Bash, Zsh, or Fish on macOS, Linux, or WSL on Windows
• A real project -- Codex CLI is most useful on actual codebases, not empty directories
• Git -- Codex integrates deeply with Git workflows for reviewing and committing changes

📦 Installation and First Run

Codex CLI gives you two installation paths. Pick whichever matches your setup.

npm (all platforms)

npm install -g @openai/codex

Homebrew (macOS)

brew install --cask codex

Verify the installation

codex --version

Authentication

On first run, Codex will prompt you to sign in. You have two options:

Option 1: ChatGPT account -- Sign in with your existing ChatGPT subscription. This gives you access to the latest Codex models and your subscription's credit allocation.

Option 2: API key -- Set your OpenAI API key as an environment variable:

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

Add that to your ~/.zshrc or ~/.bashrc to persist it across sessions.

Launch your first session

Navigate to your project directory and start Codex:

cd your-project
codex

You'll land in a full-screen terminal UI (TUI) -- a conversational interface where you can type natural language instructions. Codex reads your repository structure, understands the codebase, and starts working.

⚙️ Configuration: config.toml Deep Dive

Codex stores configuration in TOML files at two levels:

• User-level: ~/.codex/config.toml -- your personal defaults across all projects
• Project-level: .codex/config.toml in any repo -- project-specific overrides (check this into Git for team sharing)

Here's a practical starter configuration:

# ~/.codex/config.toml

# Model selection -- GPT-5.3-Codex is the current best for coding tasks
model = "gpt-5.3-codex"

# Approval policy: "suggest" (ask before every action), "auto-edit" (auto-approve edits, ask for commands), "on-request", or "never"
approval_policy = "on-request"

# Sandbox mode: "read-only", "workspace-write", or "danger-full-access"
sandbox_mode = "workspace-write"

[sandbox_workspace_write]
# Network access inside the sandbox (off by default for security)
network_access = false

# Additional writable directories beyond the workspace
# writable_roots = ["/tmp/build-output"]

Profiles

Define named profiles for different workflows:

[profiles.review]
model = "gpt-5.3-codex"
approval_policy = "suggest"
sandbox_mode = "read-only"

[profiles.ship]
model = "gpt-5.3-codex"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

Then launch with a profile:

codex --profile review

This keeps your "reviewing someone else's PR" workflow separate from your "build this feature" workflow.

Project-level config

Drop a .codex/config.toml in your repo root for team-wide settings:

# .codex/config.toml (checked into Git)
model = "gpt-5.3-codex"
sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = false

Codex walks from the project root to your current working directory and loads every .codex/config.toml it finds, so monorepo teams can have per-package overrides.

🔒 Sandbox Modes and Autonomy

This is where Codex CLI gets interesting -- and where the design philosophy diverges sharply from other agents. Codex gives you two independent security layers: sandbox mode (what Codex can do) and approval policy (when Codex asks first).

Sandbox Modes

The default workspace-write mode is the sweet spot for most work. Codex can read your entire filesystem for context but can only write files and execute commands within your project directory. Network access is off by default, which prevents Codex from curl-ing random things or npm install-ing packages without your knowledge.

Approval Policies

Convenience Shortcuts

Instead of setting both sandbox and approval separately, Codex provides presets:

# Full auto: workspace-write sandbox + on-request approval
codex --full-auto

# Interactive and cautious
codex --sandbox read-only

# Unrestricted (only in containers!)
codex --sandbox danger-full-access --ask-for-approval never

You can also switch approval modes mid-session by typing /permissions inside the TUI.

Adding Extra Writable Directories

Need Codex to write to a build output directory outside your workspace? Use --add-dir instead of escalating to full access:

codex --add-dir /tmp/build-output --add-dir ~/shared-libs

This is the safer approach -- grant access to specific directories rather than everything.

🚀 Daily Workflows and Slash Commands

Codex ships with built-in slash commands that cover the most common developer workflows. These aren't just aliases -- they're specialized prompts backed by Codex's understanding of your repo.

/review -- Pre-commit Code Review

Type /review in the TUI and pick from:

• Review against a base branch -- Codex finds the merge base, diffs your work, and highlights risks before you open a PR
• Review uncommitted changes -- Inspects staged, unstaged, and untracked files for issues before you commit

The reviewer runs in a separate context, so it won't pollute your working session. It produces prioritized, actionable findings without touching your working tree.

> /review

Codex: Which review mode?
  1. Review against base branch (main)
  2. Review uncommitted changes

> 1

Codex: Reviewing 3 commits against main...

## Findings (prioritized)

1. **HIGH** - SQL injection risk in `api/search.py:47`
   The `query` parameter is interpolated directly into the SQL string.
   Fix: Use parameterized queries via Django ORM.

2. **MEDIUM** - Missing error handling in `utils/email.py:23`
   The SMTP connection failure is unhandled. This will crash silently in production.

3. **LOW** - Unused import `datetime` in `models/user.py:3`

/fork -- Parallel Exploration

Type /fork to clone your current conversation into a new thread. The original stays untouched, and you get a fresh branch to explore an alternative approach. This is incredibly useful when you're debating between two implementation strategies.

Custom Slash Commands

This is where Codex gets really powerful for teams. You can create custom prompts as Markdown files that become slash commands.

Create a file at ~/.codex/prompts/test-coverage.md:

Analyze the test coverage for the file at $1.
Identify untested code paths, edge cases, and missing assertions.
Generate tests that would bring coverage to at least 90%.
Run the tests to verify they pass.

Now invoke it:

> /test-coverage src/api/handlers.py

The $1 placeholder expands to whatever argument you provide. You can use $1 through $9 for positional arguments, or named placeholders like $FILE and $TICKET_ID with KEY=value syntax.

Non-Interactive Mode

Run Codex as a one-shot command for scripting and CI/CD:

# Stream results to stdout
codex -q "Find and fix all TypeScript type errors in src/"

# Output as JSONL for pipeline processing
codex --output-format jsonl -q "List all TODO comments with file paths"

The -q (quiet) flag runs non-interactively and streams the result. Combine with --full-auto for unattended operation in containers.

🤖 Models and What They Cost

Codex CLI's model lineup has evolved rapidly. Here's what's available in 2026 and what each one is best for.

Available Models

Switch models mid-session with /model:

> /model gpt-5.3-codex-spark

Pricing

Codex CLI uses a credit system that draws from your subscription or API balance. The cost per message varies based on task complexity, context size, and reasoning depth -- it's not a fixed per-message price.

For API usage, the codex-mini-latest model runs at approximately $1.50 per 1M input tokens and $6 per 1M output tokens, with a 75% discount for cached prompts. The flagship models cost more but handle complex reasoning tasks that cheaper models struggle with.

🆚 How Codex CLI Compares

The terminal coding agent space now has three serious contenders. Here's how they stack up in practice, not benchmarks.

When to use each

Choose Codex CLI when:
- You want an open-source tool you can inspect, fork, and customize
- Sandbox isolation matters to your security team
- You're already paying for ChatGPT and want terminal-agent capabilities at no extra cost
- Your team wants to standardize on shared config.toml files

Choose Claude Code when:
- You need the deepest code reasoning and multi-file understanding
- CLAUDE.md project instructions and hooks are critical to your workflow
- You're doing complex refactors where getting it right matters more than speed
- Read our Claude Code Workflow Guide for the full picture

Choose GitHub Copilot Agent Mode when:
- You live in VS Code and don't want to leave your IDE
- You need tight integration with GitHub Issues, PRs, and Actions
- Inline suggestions + agent mode in one tool is your ideal workflow
- See our GitHub Copilot Agent Mode Guide for setup details

For a comprehensive breakdown of all the major AI coding tools, check our AI Coding Agents Compared article.

🐛 Troubleshooting

"Could not resolve host" or network errors in sandbox

The default workspace-write sandbox blocks network access. If your task requires downloading packages or hitting APIs:

# Option 1: Enable network in config.toml
# Under [sandbox_workspace_write], set network_access = true

# Option 2: One-time override
codex --sandbox danger-full-access

But think twice before enabling network. Often the better approach is to install dependencies yourself, then let Codex work offline.

Sandbox mode stuck on read-only

A known issue: sometimes the config.toml setting gets overridden. Force it from the command line:

codex --sandbox workspace-write --ask-for-approval on-request

If that works but config.toml doesn't, check for conflicting project-level configs. Codex loads configs hierarchically, and a .codex/config.toml deeper in your directory tree overrides the user-level one.

Authentication failures

# Re-authenticate
codex auth login

# Or reset and start fresh
rm -rf ~/.codex/auth
codex

If you're using an API key, make sure OPENAI_API_KEY is exported in your current shell session, not just defined in a file that hasn't been sourced.

High credit consumption

Codex credits scale with task complexity and context size. To reduce consumption:

• Use gpt-5.3-codex-spark or gpt-5.1-codex-mini for simple tasks
• Keep your working directory focused -- don't run Codex from your home directory
• Use /model to switch to a lighter model for straightforward edits

Windows sandbox errors

Windows users may see "sandbox setup refresh failed with status exit code: 1." This is typically a permissions issue:

# Run your terminal as Administrator
# Or use WSL for a more reliable experience
wsl
npm install -g @openai/codex
codex

WSL is the recommended path for Windows users -- the Linux sandbox is more mature and better tested.

🔮 What's Next

Once you're up and running with Codex CLI:

• Build custom slash commands -- Turn your team's repetitive workflows into reusable Markdown prompts in ~/.codex/prompts/
• Connect MCP servers -- Add your databases, issue trackers, and monitoring tools via config.toml so Codex can query them directly
• Set up shell completions -- Run codex completion zsh >> ~/.zshrc (or bash/fish) for tab completion of commands and flags
• Explore multi-agent workflows -- Use /fork to run parallel exploration threads, or pipe Codex's JSONL output into other tools
• Contribute upstream -- It's open source at github.com/openai/codex. The issue tracker is active, and community PRs are welcome

The terminal coding agent space is moving fast. In 2025 there was basically one serious option. In 2026 there are three, each with a different philosophy about how much autonomy an AI should have over your codebase. Codex CLI's bet -- open-source, sandboxed, configurable -- is a compelling one, especially for teams that need to audit and control exactly what their AI tools can do.

Whether Codex CLI becomes your primary agent or a complement to your existing setup, having an open-source option in your toolkit is worth the fifteen minutes it takes to install.

Exploring AI coding tools? Read our AI Coding Agents Compared for the full landscape, or dive into The Rise of the AI Engineer to understand where these tools fit in the bigger career picture.