Skip to content

OpenAI Codex CLI: Official Description & Setup Guide (Updated 2026-02)

Updated 2026-02-25 | Codex CLI v0.104.0

Target Audience

Developers and platform engineers who want a single entry point for Codex CLI setup, authentication, approval modes, sandbox behavior, and troubleshooting.

Key Points

  • Codex CLI is OpenAI's terminal-first coding agent for local codebase automation
  • ChatGPT authentication, approval modes, sandboxing, and network policy shape daily use
  • This guide links out to specialized articles for /goal, review Skills, automation, pricing, and recovery

What is Codex CLI?

Codex CLI is OpenAI's official command-line tool for AI-powered coding automation. This terminal-based coding agent runs locally on your machine, reads your codebase, suggests or automatically implements changes, and executes commands—all while maintaining security through OS-level sandboxing.

Key Features: - Official OpenAI tool with direct ChatGPT Plus/Pro integration
- Local execution with three safety levels (Read Only/Auto/Full Access) - Zero additional cost when using ChatGPT authentication - Cross-platform sandbox security (macOS Seatbelt, Linux Landlock)

Compare with: Claude Code | GitHub Copilot CLI | AI Development Tools

What Changed & Where People Get Stuck

Codex CLI has evolved from Node.js to Rust, authentication now works via ChatGPT Plus/Pro/Team or API key, and the sandbox blocks network by default. Most issues fall into four categories: approval prompts that won't stop, network access denied, sandbox errors on WSL/macOS, and authentication loops.

Quick Start: 3 Commands

npm i -g @openai/codex   # Install
codex                     # Launch (browser auth or set OPENAI_API_KEY)
codex --full-auto "Run tests and fix failures"

If you hit a wall, jump to Troubleshooting Top 5 Issues below. For approval-free automation, see Approval Modes Guide. For plan or diff review with a separate Codex session, see Second-Pass Review. For network fixes, see Network Restrictions Solution.

Installation

npm i -g @openai/codex

Homebrew (macOS/Linux)

brew install --cask codex

Verify Installation

codex --version

Authentication (ChatGPT vs API Key)

Choose one of two methods:

codex   # Opens browser for authentication
  • No additional charges beyond your ChatGPT subscription
  • Access to latest models including GPT-5.3-Codex

Option 2: API Key

export OPENAI_API_KEY="sk-..."
codex
  • Pay-as-you-go pricing
  • Suitable for CI/CD and headless environments

Remote/SSH Authentication

ssh -L 1455:localhost:1455 user@your-server
codex   # Authenticate via local browser

Approval Modes (Read Only / Auto / Full Access)

Codex CLI uses three safety levels:

ModeCommandFile EditingCommand ExecutionUse Case
Read Onlycodex -s read-onlySuggest onlySuggest onlySafe verification, learning
Auto (default)codexAuto-executeApproval requiredDaily development
Full Accesscodex --full-autoAuto-executeAuto-executeComplete automation
# Daily development (default: Auto mode)
codex

# Full automation
codex --full-auto "Run unit tests"

# Full automation (CI environments only)
codex --dangerously-bypass-approvals-and-sandbox "Deploy"

For detailed approval configuration, see Approval Modes: Disable Prompts.

Sandbox & Network Configuration

OS-Level Isolation

PlatformTechnology
macOSApple Seatbelt
LinuxLandlock + seccomp

Network Access

Network is blocked by default in sandbox mode. To enable:

# Option 1: Config override
codex -c 'sandbox_workspace_write.network_access=true' "Install packages"

# Option 2: Full access (less safe)
codex -s danger-full-access "Run gh commands"

Configuration File

# ~/.codex/config.toml
model = "gpt-5.3-codex"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = true  # Enable when needed

Troubleshooting Top 5 Issues

1. Approval Prompts Won't Stop

Symptom: Codex keeps asking for confirmation even with --full-auto.

Fix: 

# Check current settings
codex /status

# Restart with explicit flags
codex -a never -s workspace-write "Your task"

If settings reset after reconnect, use a profile in config.toml.

2. Network Access Denied

Symptom: gh, curl, or package install commands fail.

Fix: 

# Enable network while keeping sandbox
codex -a never -s workspace-write \
  -c 'sandbox_workspace_write.network_access=true' \
  "npm install && npm test"

3. Sandbox Errors on macOS

Symptom: sandbox-exec ENOENT or similar errors.

Fix: - Verify Xcode Command Line Tools: xcode-select --install - Check directory permissions - Try running from a different working directory

4. Sandbox Errors on Linux/WSL

Symptom: Landlock/seccomp unsupported failure.

Fix: - Update WSL2 to latest version - Consider running inside a container - Use --dangerously-bypass-approvals-and-sandbox in isolated environments only

5. Authentication Loops

Symptom: Browser opens repeatedly, auth never completes.

Fix: 

# Clear cached auth (or run `codex logout`)
rm -f ~/.codex/auth.json

# Use API key instead
export OPENAI_API_KEY="sk-..."
codex

Practical Use Cases

Fixing Broken Builds

codex --full-auto "Fix failing tests and make npm test pass"

Large-Scale Refactoring

codex "Rename processData to processUserData across the repo"

CI/CD Integration

# .github/workflows/codex.yml
- name: Run Codex
  run: |
    npm i -g @openai/codex
    codex exec --full-auto "Update CHANGELOG"
  env:
    OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

Using AGENTS.md

Place project context at repository root:

# AGENTS.md
## Build Instructions
- `npm run build` to build
- `npm test` to run tests

Codex CLI vs Claude Code

AspectCodex CLIClaude Code
LicenseApache-2.0 (OSS)Source Available (Restricted License)
Installnpm i -g @openai/codexnpm i -g @anthropic-ai/claude-code
AuthChatGPT Plus/Pro/Team or APIAnthropic API / AWS / GCP
SandboxOS-level (Seatbelt/Landlock)Tool whitelist + permissions
IDETerminal-firstVS Code/JetBrains integration
CostNo extra charge with ChatGPT authAPI billing or Max plan

🧭 Related Guides

GuideWhat It Solves
Approval Modes: Disable PromptsSkip approval with --full-auto, -a never, or --dangerously-bypass-approvals-and-sandbox
Network Restrictions SolutionFix gh, curl, and package install failures behind proxies
Context Window Error RecoveryResolve "ran out of room" stalls
Reconnecting Issue PlaybookStop codex re-connecting… loops
Codex CLI Best PracticesGit workflow, alias tips, and AGENTS.md setup
Second-Pass Review with Independent SessionsUse codex-review / codex-impl-review to review plans or diffs in a separate Codex session
What Is Codex /goal?Replace repeated "keep going" prompts with objective retention, automatic continuation, and completion audit
How to Use Codex /goalEnable the feature, use the TUI command, and write objective examples with verification and Stop rules
Practical Codex Automations Use CasesDesign recurring briefs, decision memos, AI news candidates, and workflow audits
Codex CLI vs Claude CodeDetailed feature comparison

FAQ

Which approval mode is safest?

Read Only (-s read-only) for audits, Auto (default) for daily dev, --full-auto for full automation. Use --dangerously-bypass-approvals-and-sandbox only in isolated CI environments.

Why does Codex still ask for approval after I set --full-auto?

Check /status in the TUI. A reconnect or profile mismatch can reset approval_policy. Restart with your profile and re-apply settings.

Why is network blocked by default?

The sandbox isolates the agent for security. Enable network via -c 'sandbox_workspace_write.network_access=true' or switch to danger-full-access when needed.

📚 Related Articles

🔗 OpenAI Codex Series

🤖 ChatGPT & OpenAI Related

🔗 Reference Links