Skip to main content
Codex CLI uses a configuration file located at ~/.codex/config.toml to customize behavior, model settings, approval policies, and integrations.

​
Configuration File Location

Codex looks for configuration in the following locations:
  • Global config: ~/.codex/config.toml - Your personal configuration
  • Project config: .codex/config.toml in your project root - Project-specific settings
  • Environment variables: Override config values using environment variables
Configuration files are merged with project settings taking precedence over global settings.

​
Basic Structure

Here’s a minimal config.toml example: 
# Model selection
model = "o4-mini"

# Approval policy for command execution
approval_policy = "on-request"

# Sandbox mode for safety
sandbox_mode = "workspace-write"

# Enable desktop notifications
[tui]
notifications = true

​
Configuration Sections

Codex configuration is organized into several sections:

​
Core Settings

  • Model configuration - Select AI models and providers
  • Approval policies - Control when Codex asks for permission
  • Sandbox mode - Define execution boundaries
  • Authentication - API keys and login methods

​
Advanced Features

  • MCP servers - Connect to Model Context Protocol servers
  • Custom instructions - Personalize agent behavior
  • Profiles - Switch between different configuration sets
  • Network permissions - Control network access for tools

​
UI & Experience

  • TUI settings - Customize terminal interface
  • Notifications - Desktop notification preferences
  • History - Conversation history settings
  • Analytics - Usage data collection preferences

​
Quick Start

If you don’t have a config file yet, Codex will create one automatically on first run. To create or edit your configuration: 
# Create the config directory
mkdir -p ~/.codex

# Edit your config file
$EDITOR ~/.codex/config.toml

​
Configuration Schema

Codex includes a JSON schema for config.toml validation at: 
codex-rs/core/config.schema.json
This schema documents all available configuration options and is kept in sync with the codebase.

​
Next Steps

Basic Configuration

Learn about essential configuration options

Advanced Configuration

Explore advanced features and customization

Custom Providers

Configure alternative AI providers

MCP Servers

Integrate Model Context Protocol servers

​
Configuration Layers

Codex merges configuration from multiple sources in this order (later sources override earlier ones):
  1. Built-in defaults
  2. Global config (~/.codex/config.toml)
  3. Project config (.codex/config.toml)
  4. Profile overrides (when using --profile)
  5. CLI flags (e.g., --model, --approval-policy)
  6. Environment variables
This layering allows you to set defaults globally while customizing behavior per-project or per-invocation.