Most Codex CLI tutorials simply translate the official documentation. This article is different—it delves into the design philosophy of the configuration system, the underlying logic of the security model, real-world workflows, and an objective comparison with Claude Code—insights you won’t find elsewhere.

By the end of this article, you will gain:

• A production-ready Codex CLI configuration you can use directly.
• An in-depth understanding of the sandbox security model and permission system.
• Over 20 practical tips validated by experts.
• An objective analysis comparing Claude Code, helping you choose the right tool.

What is Codex CLI?

Codex CLI is not “ChatGPT in the terminal”; it is a local AI programming agent launched by OpenAI, capable of:

• Reading your entire codebase and understanding project structure.
• Directly modifying files—not just suggesting, but making actual changes.
• Executing Shell commands—running tests, installing dependencies, managing Git.
• Connecting external tools through MCP—like Figma, Sentry, databases, etc.
• Running all operations in an OS-level sandbox—keeping your system secure.

You can think of it as a seasoned developer sitting next to you: you state your requirements, and it writes code, runs tests, and fixes bugs.

Architecture Overview

┌─────────────────────────────────────────┐
│           Codex CLI (TUI)               │
│  ┌─────────────┐  ┌──────────────────┐  │
│  │  Composer    │  │  Approval Engine │  │
│  │  (Input UI)  │  │  (Permission Approval) │  │
│  └─────────────┘  └──────────────────┘  │
│  ┌─────────────────────────────────────┐ │
│         Sandbox (OS-level)            │ │
│  - File system isolation                │ │
│  - Network access control               │ │
│  - Process execution limits             │ │
│  └─────────────────────────────────────┘ │
│  ┌─────────────┐  ┌──────────────────┐  │
│  │  MCP Client  │  │  Web Search      │  │
│  │  (Tool Extension) │  │  (Real-time/Cached)  │  │
│  └─────────────┘  └──────────────────┘  │
└─────────────────────────────────────────┘
              │
              ▼
     OpenAI API (gpt-5.3-codex)

The core design philosophy: Codex CLI adopts a hybrid architecture of local execution + cloud inference. Code always stays on your machine, with only necessary context sent to OpenAI’s API. This is entirely different from the Codex Agent running in the cloud sandbox within ChatGPT.

Installation and Setup

Installing Codex CLI

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

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

# Verify installation
codex --version

Authentication Methods: Two Options

Most tutorials skip this point, but choosing the authentication method is crucial:

Option 1: ChatGPT Subscription (default)

codex login
# A browser will open for OAuth authentication

Suitable for ChatGPT Plus/Pro/Enterprise users—usage is included in the subscription.

Option 2: API Key

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

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

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

Practical Tip: You can switch between the two methods at any time. A smart strategy is to use the ChatGPT subscription for daily development and switch to the API Key when the quota is exhausted:

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

API Pricing

If using API authentication, be aware of the costs:

For the latest pricing, please check OpenAI API Pricing.

In-Depth Analysis of the Configuration System

Five Layers of Configuration Priority

This is something most tutorials completely overlook—Codex CLI does not just have one configuration file; it has a five-layer priority system:

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

Complete User Configuration

Here’s a ready-to-use ~/.codex/config.toml to start with:

# ~/.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"

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

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

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

Profile: A Better Solution than Shell Aliases

Instead of maintaining a bunch of Shell aliases, use the built-in Profile system in Codex:

# ~/.codex/config.toml

# Default configuration (always effective)
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 Q&A Profile
[profiles.quick]
model = "o4-mini"
model_reasoning_effort = "medium"
web_search = "disabled"

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

Switch profiles anytime:

codex --profile review   # Read-only mode for code review
codex --profile quick    # Quick cost-saving mode
codex                    # Default high-performance configuration

Profiles are better than aliases because of centralized management. Change one file, and you don’t have to modify .zshrc everywhere.

Shell Aliases (if you still want to use 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 approval needed
alias cxr='codex -m gpt-5.3-codex --sandbox read-only --ask-for-approval never'

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

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

Troubleshooting Configuration Issues

When configurations seem ineffective, use /debug-config to view 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

In addition to the three presets, you can combine parameters for precise control:

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

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

# Fully automatic + sandbox protection (reduce friction)
codex --full-auto

# Completely bypass all protections (dangerous! only for isolated environments)
codex --dangerously-bypass-approvals-and-sandbox
# Alias: --yolo (yes, OpenAI really named it that)

Difference Between –full-auto and –yolo

Many confuse these two options, but the distinction is crucial:

Conclusion: –full-auto is suitable for daily development to minimize interruptions. –yolo is for Docker containers and CI/CD pipelines. Never use –yolo on your main machine.

Approval Policy Levels

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

# on-failure: only approve if the command execution fails
codex -a on-failure

# on-request: approve only when Codex actively requests it
codex -a on-request

# never: never approve
codex -a never

All 24 Slash Commands Explained

Codex CLI has 24 slash commands—far more than most tutorials introduce. Here they are grouped by functionality:

Session Control

/fork is the most underrated command. Imagine you’re implementing a feature using approach A, and halfway through, you want to try approach B. Without /fork, you either lose progress on approach A or have to start over. With /fork, you can branch out directly—both approaches are preserved.

Models and Styles

Best Practice for /plan: For large tasks like “refactoring the entire authentication module,” always start with /plan. Let Codex list the steps, review them, and then execute. It’s much safer than diving straight in.

Permissions and Status

Files and Tools