Codex CLI Configuration

Codex CLI can be customized through configuration files. This section describes the structure of configuration files, the various configuration options, and how to adjust them according to your needs.

Configuration File Location

Codex's configuration file is located in the user's home directory under~/.codex/config.toml：

~/.codex/config.toml

If the file does not exist, you need to create it manually. Codex will create a default configuration file on first startup.

After modifying the configuration, you need to restart Codex for it to take effect.

Configuration File Structure

A complete configuration file may include the following sections:

Codex CLI 配置结构图
Figure: Codex CLI Configuration Structure

Full Configuration Example

# ~/.codex/config.toml

# Basic settings
[model]
default = "o4-mini" # Default model to use

# TUI settings
[tui]
alternate_screen = "auto" # Alternate screen mode: auto/always/never

# Skills configuration
[skills]
enabled = true

# Feature toggles
[features]
js_repl = false # Whether to enable JavaScript REPL

# MCP server configuration
[mcp_servers]

# Notification settings
[notify]
enabled = false

Model Configuration

Codex supports multiple models; you can choose based on task requirements:

Configuration ItemTypeDescription
model.defaultstringDefault model used
model.reasoning_effortstringReasoning effort: low/medium/high

Available Models

The models available in Codex CLI include:

  • o4-mini- Fast and efficient, suitable for simple tasks
  • o4-mini-high- High-reasoning version of o4-mini
  • o3- Strong reasoning capabilities
  • o3-pro- Professional version of o3

Different models have different speeds and prices; choosing the right model can optimize user experience and cost.

TUI Configuration

Relevant settings for the terminal user interface:

Configuration ItemTypeDescriptionDefault Value
tui.alternate_screenstringAlternate screen mode: auto/always/neverauto
tui.widthnumberTerminal Width0 (automatic)
tui.heightnumberTerminal Height0 (automatic)

Alternate Screen Mode Explanation

  • auto- Auto-detect, automatically disabled in terminal multiplexers such as Zellij
  • always- Always use alternate screen (default experience)
  • never- Never use alternate screen (preserve scroll history)

Runtime Override

You can override these settings at runtime via command-line arguments:

Command Line Override Configuration

# Disable alternate screen mode
codex --no-alt-screen

Skills Configuration

Skills are Codex's extension mechanism that allows you to customize workflows:

Configuration ItemTypeDescription
skills.enabledbooleanWhether to enable the skills system
skills.directorystringSkills file directory

Custom Skills Directory

Configure Skills Directory

[skills]
enabled = true
directory = "~/my-codex-skills"

MCP Server Configuration

MCP (Model Context Protocol) servers allow Codex to integrate with external tools and services:

Configure MCP Server

[mcp_servers.docs]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "./docs"]

# Tool permission configuration
[mcp_servers.docs.tools.search]
approval_mode = "approve"

MCP Tool Permissions

You can set permissions individually for each MCP server's tools:

  • approve- Auto-approve, no prompting
  • deny- Auto-reject
  • ask- Ask before each execution (default)

Be careful when configuring MCP servers; only enable tools you trust.

Feature Toggles

Enable or disable specific Codex features:

Configuration ItemTypeDescription
features.js_replbooleanEnable JavaScript REPL
features.js_repl_tools_onlybooleanRestrict to only the js_repl tool

JavaScript REPL Configuration

Enable JavaScript REPL

[features]
js_repl = true

You can also specify the Node.js path:

Specify Node.js Path

js_repl_node_path = "/usr/local/bin/node"

Notification Configuration

Codex can send notifications when tasks complete:

Configuration ItemTypeDescription
notify.enabledbooleanEnable notifications

Configure Notification Hooks

You can configure custom notification scripts through environment variables:

CODEX_NOTIFY_HOOK=/path/to/your/notify-script.sh

SQLite State Database

Codex uses SQLite to store internal state:

Environment VariableDescriptionDefault Value
CODEX_SQLITE_HOMESQLite database directorySame as CODEX_HOME

Configure SQLite Directory

export CODEX_SQLITE_HOME=/path/to/sqlite
codex

Logging Configuration

Codex uses Rust's env_logger; you can configure the log level:

Configure Log Output

# View logs
tail -f ~/.codex/log/codex-tui.log

# Set log level
RUST_LOG=codex_core=info,codex_tui=info,codex_rmcp_client=info codex
Log LevelDescription
errorShow errors only
warnShow warnings and errors
infoShow general info, warnings, and errors
debugShow debug information
traceShow detailed trace information

By default, the log level in TUI mode is info, and the default level in non-interactive (exec) mode is error.

Plan Mode Configuration

Configure Codex's behavior in Plan Mode:

Configure Plan Mode

# Set the default reasoning effort for Plan Mode
# Optional values: low/medium/high/none
plan_mode_reasoning_effort = "medium"

Common Configuration Examples

Basic Configuration

Minimal Configuration

# Use default settings
# Codex already provides reasonable defaults

High Performance Configuration

Performance Optimization Configuration

[model]
default = "o4-mini"

[tui]
alternate_screen = "always"

[features]
js_repl = true

Developer Configuration

Developer Configuration

[model]
default = "o4-mini"
reasoning_effort = "high"

[tui]
alternate_screen = "never"

[skills]
enabled = true
directory = "~/codex-skills"
Other extensions