Codex CLI Installation, Configuration, Usage, and Authentication Guide

Codex CLI is a localized AI programming assistant launched by OpenAI that runs in the terminal and can read, write, and execute code in directories you specify. It is open-source, written in Rust, and supports macOS and Linux, with experimental support for Windows.

I. Introduction and Features

• Open-source: Code is in openai/codex, written in Rust with a focus on performance
• Local operation: Runs in the terminal, can read, modify, and execute code in specified local directories
• Full-screen TUI: Provides a terminal full-screen interface for real-time viewing of operations, editing, and command execution
• ChatGPT subscription binding: Included with ChatGPT Plus, Pro, Business, Edu, and Enterprise plans; can also use API Key for pay-as-you-go billing
• Multimodal: Supports attaching screenshots or design diagrams (-i) as input
• MCP support: Supports Model Context Protocol, can connect to third-party tools and contexts
• Approval mode: Can configure approval strategies (untrusted / on-request / never) before executing commands or editing
• Sandbox: Can restrict permissions for model-generated commands (read-only / workspace-write / danger-full-access)

II. Installation

System Requirements

• macOS and Linux are officially supported
• Windows has experimental support; it's recommended to use WSL for a better experience

Installation Methods

# npm global installation
npm install -g @openai/codex

# Homebrew (macOS / Linux)
brew install codex
# or
brew install --cask codex

You can also download the corresponding platform binary from GitHub Releases (macOS Apple Silicon/x86_64, Linux x86_64/arm64).

Login / Authentication

After installation, you need to complete authentication for first-time use:

# Use ChatGPT account to log in (recommended, associated with Plus/Pro/Business/Edu/Enterprise subscriptions)
codex login
# Select "Sign in with ChatGPT" and follow the prompts in the browser to complete

# Or use API Key (billed at API pricing, no subscription quota)
export OPENAI_API_KEY="your-api-key"
# You can also set OPENAI_API_KEY in the .env file at the project root, and the CLI will automatically read it

III. Authentication Methods

Method 1: Sign in with ChatGPT (Recommended)

• Associated with ChatGPT Plus, Pro, Team, Edu, Enterprise, etc. subscriptions, using the Codex quota included in each plan
• No need to manage API Key separately; execute codex login in the CLI and select "Sign in with ChatGPT" to complete OAuth
• You can check current quota and usage on the Codex usage page

Method 2: API Key

• Suitable for scenarios where you only need pay-as-you-go usage and don't rely on ChatGPT subscriptions
• Set the environment variable OPENAI_API_KEY or configure it in the .env file at the project root
• Billed at OpenAI API pricing, no fixed subscription quota; does not include cloud Code Review, Slack, and other integrated features

IV. Basic Usage

Interactive Mode (TUI)

# Start interactive terminal interface
codex

# Start with initial instruction
codex "Add unit tests for this project"

# Attach image (screenshot, design draft, etc.)
codex -i screenshot.png "Implement this interface based on the screenshot"

Models and Reasoning

• By default, models like GPT-5.3-Codex can be used; switch models or adjust reasoning levels via /model in TUI
• Command line override: codex --model gpt-5.3-codex "your prompt"

Non-interactive Mode (Script / Automation)

# Single task, stream output to stdout or JSONL
codex exec "List and briefly explain all TypeScript files in the src directory"

# Read prompt from stdin
echo "Add README section: Installation instructions" | codex exec -

# Alias
codex e "your prompt"

Session Recovery and Branching

# Resume most recent session
codex resume
codex resume --last

# Resume by session ID
codex resume <session-id>

# Fork a new session from a previous session (preserve original conversation, open new branch)
codex fork

Common Subcommands Overview

Command	Description
codex	Start interactive TUI, optional initial prompt or -i image
codex exec / codex e	Non-interactive execution of single task
codex login	Log in using ChatGPT or API Key
codex logout	Clear local authentication information
codex resume	Restore historical session
codex fork	Fork new session from current session
codex apply / codex a	Apply latest diff generated by Codex Cloud task to local
codex completion	Generate Shell completion (Bash/Zsh/Fish/PowerShell)
codex features	View/enable/disable feature switches (write to config.toml)
codex mcp	Manage MCP servers (list, add, delete, authenticate)

V. Configuration

Configuration File Locations

• User-level: ~/.codex/config.toml
• Project-level (trusted projects): .codex/config.toml, can override user-level configuration

For example, here's a configuration file example:

model = "gpt-5.3-codex"
model_provider = "azure"
model_reasoning_effort = "medium"

[model_providers.azure]
name = "azure"
base_url = "https://ai-gateway.dmall.com/openai/v1"
env_key = "DMALL_API_KEY"
wire_api = "responses"

[projects."/Users/zhijunio/development/personal"]
trust_level = "trusted"

[mcp_servers.playwright]
args = ["@playwright/mcp@latest"]
command = "npx"

Command Line Overrides

Use --config / -c to temporarily override configuration items, for example:

codex -c "model_provider=\"oss\"" "Explain this code"
# or
codex -c features.web_search=true

Use --profile / -p to specify a configuration profile in ~/.codex/config.toml:

codex -p my-profile

Common Command Line Options

Option	Description
--model, -m	Override model in configuration (e.g., gpt-5.3-codex)
--sandbox, -s	Sandbox policy: read-only / workspace-write / danger-full-access
--ask-for-approval, -a	Approval timing: untrusted / on-request / never
--full-auto	Shortcut: on-request + workspace-write, suitable for local low-friction use
--cd, -C	Specify working directory
--add-dir	Add additional directory to context (can be used multiple times)
--exclude	Exclude path patterns (e.g., "**/*.log")
--no-history	Disable session history recording
--json	Output in JSON format (non-TUI)
--verbose	Show detailed logs

VI. Subscription and Usage

Subscription Inclusions

• ChatGPT Plus: Includes basic Codex CLI usage rights with fixed monthly quota
• ChatGPT Pro: Higher quota and more advanced features
• ChatGPT Business / Enterprise: Team-level management, higher quota, and SLA

Usage Management

• Check current usage on the Codex usage page
• API Key method is billed at OpenAI API pricing
• After exceeding subscription quota, you can choose to upgrade your subscription or switch to API Key for pay-as-you-go billing

VII. Common Issues and Troubleshooting

Authentication Failure

• Confirm network connection is normal and can access OpenAI services
• Check if the API Key is correct and not expired
• Try re-executing codex login to complete the OAuth process

Model Call Failure

• Check network connection and proxy settings
• Confirm the model name is correct and included in the current subscription
• Check if Codex usage has been exhausted

Permissions and Sandbox

• To execute commands, ensure sandbox policy is set to workspace-write or danger-full-access
• Setting approval mode to never can improve流畅度 but reduces security

Performance Optimization

• For large projects, use --exclude to exclude irrelevant directories
• Adjust model_reasoning_effort to balance speed and quality
• Local model caching can improve response speed (requires additional configuration)

VIII. Advanced Features

MCP Integration

Connect to third-party tools through MCP (Model Context Protocol):

# Add MCP server
codex mcp add playwright npx @playwright/mcp@latest

# List added MCP servers
codex mcp list

Custom Tools

Define custom tools in the configuration file:

[tools.my_tool]
name = "My Tool"
description = "Execute custom operations"
command = "python"
args = ["/path/to/tool.py"]

Batch Operations

Implement batch processing with shell commands:

# Perform the same operation on multiple files
for file in src/*.ts; do
  codex exec "Optimize the performance of $file"
done

IX. Summary

Codex CLI is a powerful local AI programming assistant that provides code understanding, generation, and execution capabilities through the terminal. It can be used either with ChatGPT subscription binding or via API Key for pay-as-you-go billing. Reasonable configuration of sandbox policies and approval modes can balance security and fluency.

Through this guide, you should be able to successfully install, configure, and use Codex CLI to improve programming efficiency.