Where to Find Codex CLI Configuration Documentation: The Complete Guide

You can find Codex CLI configuration documentation in three official locations: the basic configuration guide for quick-start settings, the advanced guide for MCP servers and notification hooks, and the auto-generated JSON schema at codex-rs/core/config.schema.json that serves as the canonical reference.

The openai/codex repository provides a flexible command-line interface that supports complex customization through layered configuration files. Understanding the authoritative sources for Codex CLI configuration ensures you can properly configure everything from simple API credentials to advanced Model Context Protocol (MCP) server integrations.

Official Documentation Sources

The configuration system is documented across three tiers, ranging from quick-start guides to machine-readable specifications.

Basic Configuration Guide

The basic configuration guide covers essential setup instructions for the ~/.codex/config.toml file. This resource explains environment variable overrides and demonstrates how to use the -c flag for per-run customizations without editing persistent files. It is the appropriate starting point for configuring API credentials, default models, and basic behavior flags.

Advanced Configuration Guide

For production deployments and complex workflows, the advanced configuration guide documents specialized TOML sections including [mcp] for MCP server WebSocket connections, [apps] for app connector defaults, [notify] for notification hooks, [sqlite] for state database paths, and [plan_mode] for reasoning effort controls. Each section includes validated configuration snippets that demonstrate proper syntax for settings like plan_mode_reasoning_effort = "high" or custom notification scripts.

Reference Documentation

The canonical reference documentation provides an exhaustive list of every configuration key, its type, and default value. According to the openai/codex source code, this reference is generated from codex-rs/core/config.schema.json, which the CLI uses at runtime to validate your config.toml against strict type definitions before applying settings.

Practical Configuration Examples

Define persistent settings by creating or editing ~/.codex/config.toml:

# ~/.codex/config.toml

[mcp]

# Connect to a custom MCP server.

url = "wss://my-mcp.example.com"

[apps]

# Enable the "github" connector by default.

default = ["github"]

[notify]

# Run a script after each turn finishes.

hook = "~/.codex/notify.sh"

[sqlite]

# Store state DB under a custom directory.

sqlite_home = "~/.codex/state"

[plan_mode]

# Override the default reasoning effort for Plan mode.

plan_mode_reasoning_effort = "high"

Override any setting temporarily for a single execution using the -c flag with key=value syntax:

# Run a single turn with a different SQLite location.

codex -c sqlite.sqlite_home=~/tmp/codex-db run "Write a short poem"

The -c flag accepts multiple key=value pairs and supersedes file-based configuration for that specific run.

Configuration System Architecture

The configuration loader is implemented in Rust within the codex-rs/core crate, utilizing a layered architecture that merges settings from multiple sources.

In codex-rs/core/src/config_loader/mod.rs, the load_config_layers_state function implements the core logic that combines default values, file-based configurations, and CLI overrides into a final ConfigLayerStack. This design allows directory-specific settings to override global home directory configurations while maintaining type safety throughout the merge process.

Human-readable documentation originates from docs/config.md in the repository root, while codex-rs/core/src/config_loader/README.md details the precise loading precedence: system defaults → home directory ~/.codex/config.toml → current working directory overrides → CLI -c arguments. The machine-readable schema at codex-rs/core/config.schema.json validates all layers before they reach the runtime configuration.

Summary

• Three documentation tiers exist: basic guides for quick starts, advanced guides for complex integrations, and auto-generated schema references for canonical definitions.
• Configuration file location is ~/.codex/config.toml, supporting TOML sections like [mcp], [sqlite], [notify], and [plan_mode].
• Runtime overrides use the -c flag to pass key=value pairs that temporarily supersede file settings for single executions.
• Validation relies on codex-rs/core/config.schema.json, which ensures type safety for all configuration keys before runtime application.
• Layered loading via load_config_layers_state merges defaults, files, and CLI arguments into a ConfigLayerStack with predictable precedence.

Frequently Asked Questions

Where is the default Codex CLI configuration file located?

The default configuration file is located at ~/.codex/config.toml in your home directory. You can create this file manually if it does not exist, and the CLI will validate it against the JSON schema at codex-rs/core/config.schema.json before applying any settings.

How do I temporarily override a configuration setting without editing the file?

Use the -c flag followed by a key=value pair when invoking the codex command. For example, codex -c sqlite.sqlite_home=~/tmp/codex-db run "prompt" temporarily changes the SQLite storage directory for that single execution, superseding the value defined in your persistent config file.

What configuration sections support MCP server integration?

The [mcp] section in ~/.codex/config.toml handles Model Context Protocol server connections, including the url key for WebSocket endpoints like wss://my-mcp.example.com. The advanced configuration guide documents additional options for authentication and reconnection behavior specific to MCP integrations.

How does the CLI validate my configuration file?

The Codex CLI validates config.toml using the machine-generated schema located at codex-rs/core/config.schema.json. This schema defines every valid key, its expected data type, and default values, ensuring strict type safety before the load_config_layers_state function merges your settings into the runtime ConfigLayerStack.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}