# Configuration Precedence Order in Codex Plugin: User-Level vs. Project-Level `.codex/config.toml`

> Understand Codex Plugin configuration precedence. Learn how user-level and project-level .codex/config.toml files interact and which settings take priority for trusted projects.

- Repository: [OpenAI/codex-plugin-cc](https://github.com/openai/codex-plugin-cc)
- Tags: deep-dive
- Published: 2026-08-04

---

**Configuration settings are resolved in a two-layer precedence chain: user-level `~/.codex/config.toml` is loaded first, then project-level [`.codex/config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/.codex/config.toml) overrides those values if the project is trusted.**

The openai/codex-plugin-cc repository implements a predictable configuration hierarchy that balances personal defaults with project-specific requirements. Understanding this precedence order ensures you know exactly which settings apply when working across multiple repositories.

## How Configuration Files Are Loaded

The Codex plugin resolves configuration through a sequential merge process defined in `plugins/codex/scripts/lib/codex.mjs`. This loader implements two distinct tiers:

1. **User-level config** – `~/.codex/config.toml` serves as the foundation
2. **Project-level overrides** – [`.codex/config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/.codex/config.toml) in the current project root merges on top, but **only when the project is trusted**

This design lets developers maintain consistent personal preferences while allowing repositories to enforce project-specific requirements.

## Precedence Rules in Detail

### User-Level Configuration: The Default Layer

The user-level file at `~/.codex/config.toml` establishes baseline settings for all Codex interactions. This file is typically generated by the Codex CLI and contains your preferred defaults:

```toml

# ~/.codex/config.toml

model = "gpt-5.4-mini"
model_reasoning_effort = "medium"

```

These values apply universally unless a trusted project specifies alternatives.

### Project-Level Configuration: The Override Layer

When working in a trusted repository, the loader checks for [`.codex/config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/.codex/config.toml) in the project root (the directory where Codex was started). According to the README § Common Configurations (lines 80-85), this file merges last and takes precedence:

```toml

# .codex/config.toml (project-level, overrides user-level)

model = "gpt-5.4-mini"
model_reasoning_effort = "high"

```

The resulting effective configuration for `model_reasoning_effort` becomes **"high"**—the project value wins.

## Trust Verification Gates Project Overrides

A critical condition in the precedence chain is **project trust status**. The loader in `plugins/codex/scripts/lib/codex.mjs` only applies project-level overrides when the repository is explicitly trusted. Untrusted projects fall back entirely to user-level configuration, preventing potentially malicious project configs from executing automatically.

## Practical Configuration Management

To leverage this precedence order effectively:

- Store **personal preferences** in `~/.codex/config.toml` (preferred models, default reasoning effort)
- Place **project requirements** in repo-root [`.codex/config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/.codex/config.toml) (specific model versions, team-standard settings)
- Verify trust status when project overrides aren't applying as expected

## Summary

- **User-level `~/.codex/config.toml`** loads first as the default configuration layer
- **Project-level [`.codex/config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/.codex/config.toml)** merges second and overrides matching keys
- **Trust verification** is required for project-level overrides to take effect
- The loader implementation resides in `plugins/codex/scripts/lib/codex.mjs`
- Precedence behavior is documented in README.md, lines 80-85

## Frequently Asked Questions

### What happens if a project is not trusted?

The loader skips the project-level [`.codex/config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/.codex/config.toml) entirely. Only user-level settings apply, ensuring untrusted code cannot silently modify your Codex configuration.

### Can I disable project-level overrides for specific settings?

No selective disable mechanism exists. To prevent project overrides for a setting, ensure it is not defined in the project's [`.codex/config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/.codex/config.toml) file, or work with the repository untrusted.

### Where does the configuration loader prioritize environment variables?

Environment variables are not mentioned in the current precedence chain described in the source. The documented resolution order covers only TOML file sources: user-level first, then conditional project-level merge.

### Does the order of keys within a config file affect precedence?

No. Within each configuration file, key order is irrelevant. Precedence is determined entirely by **which file** provides the value, not by declaration sequence.