Codex CLI Deep Dive: Setup, Config, and 20+ Power User Tips

Most Codex CLI tutorials stop at “here are the commands.” They translate the docs and call it a day. This guide goes deeper — covering the configuration architecture, security model philosophy, real-world workflow patterns, and honest comparison with Claude Code that you won’t find in surface-level articles.

By the end, you’ll have:

• A production-ready Codex CLI configuration you can copy and use immediately
• Deep understanding of the sandbox security model and permission system
• 20+ battle-tested tips for daily development
• An objective Claude Code comparison to help you choose the right tool

What Is Codex CLI?

Codex CLI is not “ChatGPT in a terminal.” It’s OpenAI’s local AI coding agent that can:

• Read your entire codebase and understand project structure
• Edit files directly — not suggestions, actual changes
• Execute shell commands — run tests, install dependencies, manage Git
• Connect to external tools via MCP — Figma, Sentry, databases, and more
• Run everything in an OS-level sandbox — your system stays safe

Think of it as a senior developer sitting next to you. You describe what you need, and it writes the code, runs the tests, and fixes the bugs.

Architecture Overview

┌─────────────────────────────────────────┐
│           Codex CLI (TUI)               │
│  ┌─────────────┐  ┌──────────────────┐  │
│  │  Composer    │  │  Approval Engine │  │
│  │  (input UI)  │  │  (permissions)   │  │
│  └─────────────┘  └──────────────────┘  │
│  ┌─────────────────────────────────────┐ │
│  │         Sandbox (OS-level)          │ │
│  │  - File system isolation            │ │
│  │  - Network access control           │ │
│  │  - Process execution limits         │ │
│  └─────────────────────────────────────┘ │
│  ┌─────────────┐  ┌──────────────────┐  │
│  │  MCP Client │  │  Web Search      │  │
│  │  (tools)    │  │  (live/cached)   │  │
│  └─────────────┘  └──────────────────┘  │
└─────────────────────────────────────────┘
              │
              ▼
     OpenAI API (gpt-5.3-codex)

The key design decision: Codex CLI uses a local execution + cloud reasoning hybrid. Your code stays on your machine — only necessary context goes to OpenAI’s API. This differs from the cloud-based Codex Agent in ChatGPT, which runs in a remote sandbox.

Installation and Setup

Install Codex CLI

# macOS / Linux
npm install -g @openai/codex

# Or via Homebrew (macOS)
brew install openai-codex

# Verify installation
codex --version

Authentication: Two Methods

Most tutorials skip this, but the choice matters:

Method 1: ChatGPT Subscription (Default)

codex login
# Opens browser for OAuth authentication

Best for ChatGPT Plus/Pro/Enterprise users — usage is included in your subscription.

Method 2: API Key

# Edit ~/.codex/config.toml
preferred_auth_method = "apikey"

# Or switch temporarily
codex --config preferred_auth_method="apikey"

Best for precise cost control, CI/CD pipelines, or users without a ChatGPT subscription.

Pro tip: You can switch between methods anytime. A practical strategy: use your ChatGPT subscription for daily work, then switch to API key when your subscription quota runs out:

# Switch back to ChatGPT auth
codex --config preferred_auth_method="chatgpt"

API Pricing

If using API authentication, know the costs:

For the latest pricing, see OpenAI API Pricing.

Configuration Deep Dive

The Five-Layer Config System

This is something most guides completely miss — Codex CLI doesn’t have a single config file. It has a five-layer priority system:

CLI args & --config overrides      ← Highest priority
       │
Profile config (--profile)
       │
Project config (.codex/config.toml)
       │
User config (~/.codex/config.toml)
       │
System config (/etc/codex/config.toml)
       │
Built-in defaults                  ← Lowest priority

The Complete User Config

Here’s a production-ready ~/.codex/config.toml you can use as a starting point:

# ~/.codex/config.toml

# Default model
model = "gpt-5.3-codex"

# Approval policy
approval_policy = "on-request"

# Sandbox mode
sandbox_mode = "workspace-write"

# Web search
web_search = "live"    # "cached" | "live" | "disabled"

# Reasoning effort
model_reasoning_effort = "high"

# Communication style
personality = "pragmatic"    # "friendly" | "pragmatic" | "none"

# Feature flags
[features]
shell_snapshot = true
undo = true
web_search = true

# Trusted projects (skip trust prompt)
[projects."/Users/me/work/my-project"]
trust_level = "trusted"

Profiles: Better Than Aliases

Instead of shell aliases, use Codex’s built-in profile system:

# ~/.codex/config.toml

# Default config (always applied)
model = "gpt-5.3-codex"
model_reasoning_effort = "high"
web_search = "live"

# Code review profile
[profiles.review]
sandbox_mode = "read-only"
approval_policy = "never"

# Quick mode profile
[profiles.quick]
model = "o4-mini"
model_reasoning_effort = "medium"
web_search = "disabled"

# Full auto profile (use with caution)
[profiles.auto]
approval_policy = "on-request"
sandbox_mode = "workspace-write"

Switch profiles on the fly:

codex --profile review   # Read-only code review
codex --profile quick    # Fast, cheap answers
codex                    # Default high-power config

Why profiles beat aliases: centralized management. Change one file instead of editing .zshrc.

Shell Aliases (If You Still Want Them)

# Add to ~/.zshrc or ~/.bashrc

# Daily development: high reasoning + web search
alias cx='codex -m gpt-5.3-codex -c model_reasoning_effort="high" --search'

# Code review: read-only, no approvals needed
alias cxr='codex -m gpt-5.3-codex --sandbox read-only --ask-for-approval never'

# Quick Q&A: lightweight model, save costs
alias cxq='codex -m o4-mini -c model_reasoning_effort="medium"'

# CI/CD script mode: non-interactive
alias cxci='codex exec'

Debug Your Config

When settings don’t seem to apply, use /debug-config to see the complete loading chain:

Config Layer 1: /etc/codex/config.toml (not found)
Config Layer 2: ~/.codex/config.toml (loaded)
Config Layer 3: /project/.codex/config.toml (loaded)
Config Layer 4: Profile "review" (active)
Config Layer 5: CLI overrides: model_reasoning_effort=high

Security Model: Sandbox and Permissions

Three Permission Modes

Fine-Grained Permission Control

Beyond the three presets, combine flags for precise control:

# Auto-edit, but approve untrusted commands
codex --sandbox workspace-write --ask-for-approval untrusted

# Read-only, never ask (pure analysis mode)
codex --sandbox read-only --ask-for-approval never

# Full auto with sandbox (reduced friction)
codex --full-auto

# Completely bypass everything (DANGEROUS - isolated environments only)
codex --dangerously-bypass-approvals-and-sandbox
# Alias: --yolo (yes, OpenAI really named it that)

–full-auto vs –yolo: Know the Difference

Many users confuse these two options. The distinction is critical:

Bottom line: --full-auto is for daily work with less friction. --yolo is for Docker containers and CI/CD pipelines. Never use --yolo on your main machine.

Approval Policy Levels

# untrusted: only untrusted commands need approval (default)
codex -a untrusted

# on-failure: approve only when a command fails
codex -a on-failure

# on-request: approve only when Codex explicitly asks
codex -a on-request

# never: never ask for approval
codex -a never

All 24 Slash Commands Explained

Codex CLI has 24 slash commands — far more than most guides cover. Here’s the complete reference, grouped by function:

Session Control

/fork is the most underrated command. Imagine you’re implementing a feature with approach A, halfway through you want to try approach B. Without /fork, you lose approach A’s progress or start fresh. With /fork, you branch off — both approaches preserved.

Model and Style

/plan best practice: For big tasks like “refactor the entire auth module,” always use /plan first. Let Codex outline the steps, review them, then proceed. Much safer than letting it charge ahead.

Permissions and Status

Files and Tools

Other

Session Recovery: Never Lose Progress

This feature alone makes Codex CLI worth using. When you close a session, you can come back to it later with full context:

Four Ways to Resume

# Interactive picker (recommended)
codex resume
# Shows recent sessions, select and press Enter

# Resume most recent session
codex resume --last

# Resume specific session
codex resume <SESSION_ID>

# Show sessions from all directories
codex resume --all

What Gets Preserved

When you resume a session, everything comes back:

• Full conversation history — what you said, what Codex responded
• Execution plans — strategies Codex outlined
• Approval records — previously approved operations
• File context — files referenced in the conversation

You can say “continue from where we left off, but change step 3” and Codex understands the full context.

Practical Scenarios

Scenario 1: Save progress before leaving

You: Refactor the auth module, start by analyzing the current structure
Codex: [analyzes files, outlines plan]
You: I need to go, we'll continue tomorrow
# Next day:
$ codex resume --last
You: Continue the refactor from step 2

Scenario 2: Juggle multiple tasks

# Task A: Auth refactor
codex    # Start task A, work on it...
# Ctrl+C to exit

# Task B: Fix a bug
codex    # Start task B, fix it, done

# Back to Task A
codex resume   # Select task A's session

This is something Claude Code doesn’t natively support — closing a Claude Code session means losing context.

Model Switching and Reasoning Levels

Default Model

Codex CLI defaults to gpt-5.3-codex — OpenAI’s model specifically optimized for coding tasks, outperforming general-purpose GPT-5 on code benchmarks.

Switch at Runtime

# At launch
codex -m gpt-5.3-codex
codex --model gpt-5

# During a session
/model    # Interactive model/reasoning picker

Reasoning Effort Strategy

# In config.toml
model_reasoning_effort = "high"    # or "medium" / "low"

Cost-saving tip: Don’t run everything on high. Simple tasks like renaming a variable or formatting code work perfectly on low, saving significant tokens over time.

AGENTS.md: Your AI’s Onboarding Document

If Codex CLI is your “AI colleague,” AGENTS.md is its “onboarding handbook.” It’s not just documentation — it’s an instruction system designed specifically for AI agents.

File Discovery Order

Codex reads instruction files on startup (once per session) in this order:

1. ~/.codex/AGENTS.override.md   ← Global override (highest priority)
2. ~/.codex/AGENTS.md            ← Global defaults
3. <project-root>/AGENTS.override.md   ← Project override
4. <project-root>/AGENTS.md            ← Project defaults
5. <subdirectory>/AGENTS.override.md   ← Subdirectory override
6. <subdirectory>/AGENTS.md            ← Subdirectory defaults
   ... all the way to the current working directory

Files merge from global to local, with closer files taking higher priority.

A Real-World AGENTS.md Example

# Project Guidelines

## Code Standards
- Use TypeScript strict mode
- All functions must have JSDoc comments
- Test coverage must be at least 80%
- Use pnpm as package manager (no npm or yarn)

## Architecture
- Follow Clean Architecture layering
- Database operations only in the repository layer
- API routes use RESTful naming conventions

## Testing
- Unit tests: Vitest
- E2E tests: Playwright
- Run command: pnpm test

## Off-Limits
- Do NOT modify .github/workflows/ files
- Do NOT access the database directly — use the ORM
- Do NOT hardcode secrets in source code

Verify Your Instructions Load

codex --sandbox read-only --ask-for-approval never "Summarize the instructions you've loaded"

If instructions aren’t working, check:

• Is the file empty? (Empty files are ignored)
• Is an AGENTS.override.md overriding your file?
• Has the merged content exceeded project_doc_max_bytes (default 32KB)?

MCP Integration Guide

MCP (Model Context Protocol) transforms Codex CLI from a “code editor” into an agent that can operate your entire development toolchain.

Two Ways to Add MCP Servers

Method 1: CLI command (quick)

# Add Context7 documentation search
codex mcp add context7 -- npx -y @upstash/context7-mcp

# Add with environment variables
codex mcp add my-db --env DATABASE_URL=postgresql://... \
  -- npx -y @modelcontextprotocol/server-postgres

# List all MCP servers
codex mcp list

# Remove a server
codex mcp remove context7

Method 2: Config file (full control)

# ~/.codex/config.toml

# STDIO-based MCP server
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

# HTTP-based MCP server
[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"

Advanced MCP Configuration

[mcp_servers.my-server]
command = "node"
args = ["my-server.js"]
cwd = "/path/to/server"
enabled = true                     # Toggle without removing
required = true                    # Abort Codex if startup fails
startup_timeout_sec = 15           # Default: 10s
tool_timeout_sec = 120             # Default: 60s
enabled_tools = ["tool_a", "tool_b"]   # Whitelist
disabled_tools = ["dangerous_tool"]     # Blacklist

Recommended MCP Servers

For a comprehensive guide on MCP servers, see Best MCP Servers for Claude Code — most servers work with Codex CLI too.

Web Search: Three Modes

# Cached search (default): uses OpenAI's index cache
web_search = "cached"

# Live search: fetches latest web data
web_search = "live"

# Disabled
web_search = "disabled"

Enable at launch:

codex --search    # Enable live search

Important security distinction: --search only lets Codex query through OpenAI’s search API — it can’t access arbitrary URLs. Full Access mode allows curl, wget, and direct network access. For most cases, --search is sufficient and safer.

Keyboard Shortcuts and Interaction Tips

Essential Shortcuts

Ctrl+G: The Underrated Long-Text Editor

When you need to write a detailed prompt, the tiny terminal input box is painful. Press Ctrl+G to open your configured editor (defaults to $EDITOR) — write your prompt in Vim, VS Code, or any editor, save and close, and it auto-sends.

–add-dir: Cross-Directory Work

# Give Codex write access to additional directories
codex --add-dir /path/to/shared-library

Essential for monorepos or projects that depend on local shared libraries.

Codex CLI vs Claude Code: Honest Comparison

As someone who uses both tools daily, here’s an objective comparison:

Feature Comparison

When to Use Which

Codex CLI wins when you need:

• Strict sandbox isolation (enterprise security)
• Session recovery for long-running tasks
• CI/CD automation (codex exec + JSON output)
• Cost control with precise token management

Claude Code wins when you need:

• Deep reasoning and complex multi-step tasks
• UI development and frontend work
• Interactive development with real-time feedback
• Richer MCP ecosystem
• Multi-agent orchestration

The Pragmatic Approach

You don’t have to choose one. Here’s what works in practice:

• Daily coding, bug fixes → Codex CLI (fast, cost-effective)
• Complex architecture, major refactors → Claude Code (deeper reasoning)
• Automated code review → Codex CLI’s GitHub App
• Frontend development → Claude Code (better UI understanding)
• CI/CD integration → Codex CLI’s codex exec

Scripting and CI/CD Integration

The exec Command

exec is Codex CLI’s non-interactive mode, built for scripts and pipelines:

# Basic usage
codex exec "Fix all ESLint errors"

# JSON output (for script parsing)
codex exec --json "Analyze this repo for security vulnerabilities"

# Pipe with other tools
codex exec "List all TODO comments" | grep "FIXME"

GitHub Actions Example

# .github/workflows/codex-review.yml
name: Codex Code Review
on: [pull_request]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Codex CLI
        run: npm install -g @openai/codex
      - name: Run Code Review
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: |
          codex exec --json \
            --config preferred_auth_method="apikey" \
            "Review code changes in this PR for security and performance issues"

Git Hook Integration

# .git/hooks/pre-commit
#!/bin/bash
codex exec "Check staged code for obvious security issues or bugs"
if [ $? -ne 0 ]; then
    echo "Codex found potential issues. Please review before committing."
    exit 1
fi

Performance and Cost Optimization

Token Optimization

1. Match reasoning level to task complexity — use low for simple tasks, high only when needed
2. Use /compact proactively — compress context before hitting limits
3. Reference files with @ — reduces unnecessary file searching
4. Disable search when not needed — set web_search = "disabled" for offline work

Response Speed Tips

1. Use --no-alt-screen — disables fullscreen mode, faster rendering on some terminals
2. Minimize MCP servers — each server adds startup time. Only configure what you actually use
3. Set reasonable timeouts — don’t set startup_timeout_sec too high

Troubleshooting

“Re-connecting” on startup

Usually a network or auth issue:

# Re-authenticate
codex logout
codex login

# If using a proxy
export HTTPS_PROXY=http://127.0.0.1:7890

# Check API key
codex --config preferred_auth_method="apikey"

MCP server won’t connect

# Test the command manually
npx -y @upstash/context7-mcp

# Verify environment variables
echo $MY_ENV_VAR

# Increase startup timeout in config.toml
[mcp_servers.my-server]
startup_timeout_sec = 30

Context exhaustion (Codex starts hallucinating)

# Option 1: Compress context
/compact

# Option 2: Start fresh with a concise summary
/new

# Option 3: Break the task into smaller pieces
# Don't cram too many tasks into one session

Notifications and Hooks

Set up desktop notifications for long-running tasks:

# ~/.codex/config.toml

# macOS notification
[notification_hook]
command = "osascript"
args = ["-e", "display notification \"Task complete\" with title \"Codex CLI\""]

For fancier notifications on macOS with terminal-notifier:

[notification_hook]
command = "terminal-notifier"
args = ["-title", "Codex CLI", "-message", "Task complete", "-sound", "default"]

Compare this to Claude Code’s Hooks system, which offers more granular event triggers but requires more setup.

Key Takeaways

1. Profiles over aliases — centralized config management beats scattered shell aliases
2. Understand the security model — balance convenience and safety with the right sandbox + approval combo
3. Use session recovery — it’s a killer feature that prevents context loss
4. MCP is the force multiplier — it transforms Codex from “code editor” to “full development agent”
5. Write a proper AGENTS.md — it directly determines how well Codex understands your project
6. Don’t choose between Codex CLI and Claude Code — use each where it excels

Related Reading

• Claude Code Complete Guide 2026 — Master Claude Code’s full feature set
• Claude Code vs ChatGPT Codex: Detailed Comparison — Opus 4.6 vs GPT-5.3 deep dive
• MCP Protocol Explained — The universal standard both tools use
• Claude Code vs Cursor: Which Wins? — Another key tool comparison
• CLAUDE.md Guide — The Claude Code equivalent of AGENTS.md
• Best MCP Servers for Claude Code — MCP servers that work with both tools