OpenAI Codex CLI

Codex CLI is OpenAI’s official command-line AI coding agent. It lets you complete code generation, refactoring, debugging, file editing, and system command execution directly from your terminal using natural language. Compared to other AI coding tools, Codex CLI features full sandbox isolation and fine-grained permission control.

Installation

Check Node.js Version

node -v

Requires Node.js 22+.

Install Codex CLI

npm install -g @openai/codex

Configure ePhone AI

Codex CLI uses model_providers to define custom API providers, and the top-level model_provider key to specify which provider to use by default.

Set the API Key Environment Variable

Mac / Linux (zsh)

echo 'export OPENAI_API_KEY="sk-your-api-key"' >> ~/.zshrc
source ~/.zshrc

Mac / Linux (bash)

echo 'export OPENAI_API_KEY="sk-your-api-key"' >> ~/.bash_profile
source ~/.bash_profile

Windows (PowerShell)

[Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "sk-your-api-key", "User")

Create the Configuration File

mkdir -p ~/.codex

Add the following to ~/.codex/config.toml:

# ~/.codex/config.toml

model = "gpt-4o"
model_provider = "ephone"       # Required: set the default provider
disable_response_storage = true

[model_providers.ephone]
name = "ePhone AI"
base_url = "https://api.ephone.ai/v1"
env_key = "OPENAI_API_KEY"      # Name of the env var (not the key itself)
wire_api = "responses"          # Responses API protocol (only supported value)

Three critical settings — all are required:

model_provider = "ephone" — without this, Codex routes known model names like gpt-4o directly to OpenAI’s servers
wire_api = "responses" — the only protocol supported by Codex, using the Responses API
env_key = "OPENAI_API_KEY" — this is the name of the environment variable, not the API key value itself

Getting Started & Approval Modes

codex

On first launch, choose an approval mode that controls how Codex handles permissions:

Mode	Config Value	Description
Suggest	`untrusted`	Default. Codex can only read files — all writes and commands require your confirmation
Auto Execute	`on-request`	Safe sandbox operations run automatically; only privilege escalation requires confirmation
Full Auto	`never`	No confirmation needed. Codex acts autonomously — best for trusted dev environments

Set the default approval mode in config.toml:

approval_policy = "on-request"

Common Commands

CLI Launch Options

Command	Description
`codex`	Start an interactive session
`codex "task description"`	Run a one-off task directly
`codex --model gpt-4o "task"`	Run a task with a specific model
`codex --image screenshot.png "fix this bug"`	Attach an image as context
`codex --search "task description"`	Enable web search for the task
`codex --profile fast "quick task"`	Use a preset configuration profile

In-Session Commands

Use these slash commands during an interactive session:

Command	Description
`/status`	View current model, token usage, and config info
`/model`	Switch the active model
`/approvals`	Adjust the approval policy for the current session
`/compact`	Compress conversation history to free context window
`/clear`	Clear the current conversation history
`/init`	Create an `AGENTS.md` template in the current directory
`/feedback`	Submit feedback

Recommended Models

Use Case	Recommended Model	Notes
Everyday coding	`gpt-4o`	Good balance of speed and capability
Complex refactoring	`o4-mini`	Strong reasoning for deep analysis tasks
Quick lightweight tasks	`gpt-4o-mini`	Fast response, lower cost

Use the /model command to switch models mid-session without restarting.

Project Configuration: AGENTS.md

Codex automatically reads AGENTS.md files on startup as project context instructions, similar to Claude Code’s CLAUDE.md. Through layered configuration, you can set different rules for different projects and directories.

Discovery Order

Global: ~/.codex/AGENTS.md — shared defaults for all projects
Project root: <project-root>/AGENTS.md — project-level rules
Subdirectories: <subdir>/AGENTS.md — subdirectory overrides

Each level also supports AGENTS.override.md, which takes priority over AGENTS.md in the same directory.

Global Configuration Example

# ~/.codex/AGENTS.md

## Working Agreements
- Prefer pnpm when installing dependencies
- Run relevant tests after modifying code
- Follow Conventional Commits for commit messages
- Ask for confirmation before adding production dependencies

Project Configuration Example

# AGENTS.md

## Project Info
This is a full-stack project using Go + React.

## Development Standards
- Backend uses Go 1.22+, follow standard project layout
- Frontend uses TypeScript, no any types allowed
- All user-facing strings must use i18n
- Run make build after backend changes
- Run npm run lint after frontend changes

## Testing Requirements
- New APIs must include unit tests
- Test command: go test ./... -v

Subdirectory Override Example

# services/payments/AGENTS.override.md

## Payment Service Rules
- Use make test-payments instead of the default test command
- All monetary calculations must use decimal types
- Never operate directly on the production database

Configuration Profiles

Profiles let you quickly switch between different configuration sets — ideal for different projects or scenarios:

# ~/.codex/config.toml

# Use the fast profile by default
profile = "fast"

[profiles.fast]
model_provider = "ephone"
model = "gpt-4o-mini"
approval_policy = "never"

[profiles.careful]
model_provider = "ephone"
model = "o4-mini"
approval_policy = "on-request"
model_reasoning_effort = "high"

Switch profiles at launch with --profile:

codex --profile careful "refactor the error handling in this module"

Each profile needs model_provider = "ephone" — otherwise switching profiles may fall back to the default OpenAI provider.

MCP Server Integration

Codex CLI supports MCP (Model Context Protocol) to connect external tools, significantly extending its Agent capabilities.

# ~/.codex/config.toml

[mcp_servers.context7]
command = "npx"
args = ["-y", "@context7/mcp"]

[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_PERSONAL_ACCESS_TOKEN = "ghp_xxx" }

Once configured, Codex can query documentation, interact with GitHub, and more — without manually providing context.

Reasoning Control

For models that support reasoning (e.g., o4-mini), you can control reasoning depth:

model_reasoning_effort = "high"    # minimal | low | medium | high
model_reasoning_summary = "auto"   # auto | concise | detailed | none

Higher reasoning effort means deeper thinking but higher token usage. Use medium for daily tasks and high for complex refactoring.

Web Search

Codex supports web search during conversations to fetch the latest documentation and information:

web_search = "cached"   # disabled | cached | live

cached: Uses an OpenAI-maintained index (default, fast)
live: Fetches live web pages (most current info)
disabled: Turns off search entirely

You can also enable search at launch with --search:

codex --search "find the latest React 19 API changes"

Sandbox & Security

Codex provides three sandbox levels to protect your system:

Mode	Description
`read-only`	Read-only mode — cannot modify files or run write commands
`workspace-write`	Can modify files within the workspace directory (default)
`danger-full-access`	Full access with no restrictions (use with caution)

sandbox_mode = "workspace-write"

Usage Examples

Code Refactoring

codex "convert all error handling in utils/helpers.go to use wrapped errors"

Bug Fixing with Screenshots

codex --image bug-screenshot.png "this button doesn't respond when clicked, help me locate and fix the issue"

Project Scaffolding

codex "create a Go + Gin REST API project scaffold with CRUD, middleware, and Docker config"

Git Operations

codex "review recent commit history, find the commit that introduced this bug, then fix it"

Code Review

codex "review recently modified files in src/services/, identify potential security issues and performance concerns"

Full Configuration Reference

# ~/.codex/config.toml

# Default model and provider (required)
model = "gpt-4o"
model_provider = "ephone"

# Approval policy
approval_policy = "on-request"

# Sandbox mode
sandbox_mode = "workspace-write"

# Reasoning control
model_reasoning_effort = "medium"

# Web search
web_search = "cached"

# Disable API response storage (required for third-party providers)
disable_response_storage = true

# Conversation history
[history]
persistence = "save-all"

# ePhone AI Provider
[model_providers.ephone]
name = "ePhone AI"
base_url = "https://api.ephone.ai/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"

# Fast profile
[profiles.fast]
model_provider = "ephone"
model = "gpt-4o-mini"
approval_policy = "never"
model_reasoning_effort = "minimal"

# Deep thinking profile
[profiles.think]
model_provider = "ephone"
model = "o4-mini"
approval_policy = "on-request"
model_reasoning_effort = "high"

Troubleshooting

401 Unauthorized — still connecting to api.openai.com

Cause: Missing model_provider = "ephone" in config. Codex routes known model names (like gpt-4o) to the built-in OpenAI provider.Fix: Ensure model_provider = "ephone" is set at the top level of config.toml.If you previously logged into Codex via ChatGPT, also clear cached credentials:

rm -f ~/.codex/auth.json

WebSocket connecting to api.openai.com

Cause: Missing model_provider configuration, causing Codex to route WebSocket connections to OpenAI’s servers instead of ePhone AI.Fix: Ensure model_provider = "ephone" is set at the top level of config.toml. This routes connections to wss://api.ephone.ai/v1/responses.

env_key not working

Cause: env_key should contain the name of the environment variable (e.g., "OPENAI_API_KEY"), not the API key value itself.Fix: Set env_key = "OPENAI_API_KEY" and make sure the variable is exported via export OPENAI_API_KEY="sk-...".

Switching profiles falls back to OpenAI

Cause: The profile doesn’t include model_provider, so it reverts to the default OpenAI provider.Fix: Add model_provider = "ephone" to every profile section.

Important Notes

Codex CLI’s autonomous mode calls the model frequently and executes system commands — token usage is much higher than regular chat. We recommend using a Tier 2 account to avoid hitting rate limits.

Set disable_response_storage = true to disable API response storage — required for third-party providers
Use the /compact command to compress overly long conversation history and prevent context window limits
Log files are located at ~/.codex/log/ — check them for troubleshooting

Official Codex Docs

OpenAI developer documentation

GitHub Repository

Source code & issues

AGENTS.md Spec

Project configuration spec

Development Tools & Platforms

Translation Tools

Integration Applications

Installation

Configure ePhone AI

Getting Started & Approval Modes

Common Commands

CLI Launch Options

In-Session Commands

Recommended Models

Project Configuration: AGENTS.md

Discovery Order

Global Configuration Example

Project Configuration Example

Subdirectory Override Example

Configuration Profiles

MCP Server Integration

Reasoning Control

Web Search

Sandbox & Security

Usage Examples

Code Refactoring

Bug Fixing with Screenshots

Project Scaffolding

Git Operations

Code Review

Full Configuration Reference

Troubleshooting

Important Notes

Official Codex Docs

GitHub Repository

AGENTS.md Spec

​Installation

​Configure ePhone AI

​Getting Started & Approval Modes

​Common Commands

​CLI Launch Options

​In-Session Commands

​Recommended Models

​Project Configuration: AGENTS.md

​Discovery Order

​Global Configuration Example

​Project Configuration Example

​Subdirectory Override Example

​Configuration Profiles

​MCP Server Integration

​Reasoning Control

​Web Search

​Sandbox & Security

​Usage Examples

​Code Refactoring

​Bug Fixing with Screenshots

​Project Scaffolding

​Git Operations

​Code Review

​Full Configuration Reference

​Troubleshooting

​Important Notes

​Related Resources

Official Codex Docs

GitHub Repository

AGENTS.md Spec

Installation

Configure ePhone AI

Getting Started & Approval Modes

Common Commands

CLI Launch Options

In-Session Commands

Recommended Models

Project Configuration: AGENTS.md

Discovery Order

Global Configuration Example

Project Configuration Example

Subdirectory Override Example

Configuration Profiles

MCP Server Integration

Reasoning Control

Web Search

Sandbox & Security

Usage Examples

Code Refactoring

Bug Fixing with Screenshots

Project Scaffolding

Git Operations

Code Review

Full Configuration Reference

Troubleshooting

Important Notes

Related Resources