# Where to Find Codex CLI Configuration Documentation: The Complete Guide

> Find Codex CLI configuration documentation in three official locations including a basic guide, advanced guide, and auto-generated JSON schema. Get the complete guide here.

- Repository: [OpenAI/codex](https://github.com/openai/codex)
- Tags: documentation
- Published: 2026-03-06

---

**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`](https://github.com/openai/codex/blob/main/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`](https://github.com/openai/codex/blob/main/codex-rs/core/config.schema.json), which the CLI uses at runtime to validate your [`config.toml`](https://github.com/openai/codex/blob/main/config.toml) against strict type definitions before applying settings.

## Practical Configuration Examples

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

```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:

```bash

# 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`](https://github.com/openai/codex/blob/main/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`](https://github.com/openai/codex/blob/main/docs/config.md) in the repository root, while [`codex-rs/core/src/config_loader/README.md`](https://github.com/openai/codex/blob/main/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`](https://github.com/openai/codex/blob/main/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`](https://github.com/openai/codex/blob/main/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`](https://github.com/openai/codex/blob/main/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`](https://github.com/openai/codex/blob/main/config.toml) using the machine-generated schema located at [`codex-rs/core/config.schema.json`](https://github.com/openai/codex/blob/main/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`.