Configuration

You authenticated, launched Codex, and it immediately tried to run rm -rf node_modules without asking. Or worse, it asked permission for every single ls command before doing anything useful. The difference between these experiences is one file: config.toml. Get it right, and Codex feels like a trusted senior colleague. Get it wrong, and it is either reckless or paralyzed.

What You’ll Walk Away With

A ~/.codex/config.toml configured with your preferred model, approval policy, and sandbox level
Project-level overrides in .codex/config.toml for team-specific settings
A clear understanding of the configuration precedence order
Feature flags enabled for the capabilities you want
Web search mode tuned for your security requirements

The Configuration File

Codex reads configuration from TOML files. Your personal defaults live at ~/.codex/config.toml, and project-specific overrides go in .codex/config.toml at the root of your repository.

Both the CLI and IDE extension share the same config layers. The App reads them too. Configure once, use everywhere.

Configuration Precedence

Codex resolves settings in this order, from highest to lowest priority:

CLI flags and --config overrides — codex -a never beats everything.
Profile values — From --profile <name> if you use named profiles.
Project config — .codex/config.toml files, ordered from the project root down to your current working directory. Closest directory wins. Only loaded for trusted projects.
User config — ~/.codex/config.toml.
System config — /etc/codex/config.toml on Unix (if present).
Built-in defaults — Codex’s factory settings.

This means your team can commit a .codex/config.toml to the repo that sets project-specific approval policies, and individual developers can override with their own ~/.codex/config.toml preferences.

Essential Settings

Here is a production-ready ~/.codex/config.toml with the settings most developers change first.

# Model selection -- GPT-5.3-Codex is the default and best for coding tasks
model = "gpt-5.3-codex"

# Approval policy -- controls when Codex pauses to ask before running commands
# Options: "on-request" (ask for everything), "on-failure" (auto-approve,
#          ask on errors), "never" (full autonomy -- the "yolo mode")
approval_policy = "on-failure"

# Sandbox mode -- controls filesystem and network access
# Options: "workspace-write" (default, scoped to project), "danger-full-access"
sandbox_mode = "workspace-write"

# Web search mode
# Options: "cached" (default, pre-indexed results), "live" (real-time),
#          "disabled" (no web search)
web_search = "cached"

# Reasoning effort -- how much the model thinks before responding
# Options: "low", "medium", "high"
model_reasoning_effort = "high"

# Credential storage
cli_auth_credentials_store = "auto"

Approval Modes Deep Dive

The approval policy is the single most impactful setting. Here is what each mode actually does.

Codex pauses and asks permission before every file edit and command execution. This is the safest mode but creates the most friction.

approval_policy = "on-request"

Use when: Working in unfamiliar codebases, running Codex for the first time, or operating in production environments.

Codex auto-approves actions but pauses and asks when something fails. This is the sweet spot for most development work — Codex flows smoothly on happy paths but checks in with you when errors occur.

approval_policy = "on-failure"

Use when: Day-to-day development in trusted projects.

Codex runs everything without asking. File edits, shell commands, Git operations — all autonomous. This is the fastest mode but requires high trust. You can also use the --full-auto CLI flag for the same effect with sandboxing.

approval_policy = "never"

Use when: Working in containerized environments, disposable branches, CI/CD pipelines, or when you want uninterrupted flow and can easily revert.

Prompt to test your approval mode:

With on-failure mode, try this in the CLI:

codex "Create a file called test-approval.txt with the text 'hello' and then run cat test-approval.txt"

Codex should create the file automatically (no prompt) but ask permission before running cat. If that matches, your approval mode is working correctly.

Project-Level Overrides

For team settings, create .codex/config.toml in your repository root:

# .codex/config.toml -- committed to the repo

# Team-standard approval policy
approval_policy = "on-failure"

# Sandbox scoped to workspace
sandbox_mode = "workspace-write"

# Team prefers high reasoning for this complex codebase
model_reasoning_effort = "high"

When a developer clones the repo and trusts the project, these settings apply automatically. Their personal ~/.codex/config.toml still takes precedence for settings they override explicitly.

Feature Flags

Optional capabilities live under the [features] table:

[features]
# Speed up repeated commands by snapshotting your shell environment
shell_snapshot = true

# Enable undo via per-turn git ghost snapshots (on by default)
undo = true

# Enable smart approvals that suggest prefix rules
request_rule = true

Key feature flags:

Flag	Default	What it does
`shell_snapshot`	false	Caches shell environment for faster repeated commands
`undo`	true	Creates per-turn Git snapshots so you can roll back
`request_rule`	true	Smart approvals suggest reusable permission rules
`unified_exec`	false	Uses a unified PTY-backed exec tool (beta)
`remote_compaction`	true	Compacts context remotely (ChatGPT auth only)

Enable from the CLI without editing config:

codex --enable shell_snapshot

Communication Style

Codex supports an experimental communication style setting:

# Options: "friendly", "pragmatic", "none"
model_personality = "pragmatic"

You can also change this per-session with /personality in the TUI.

Environment Variable Forwarding

Control which environment variables Codex passes to spawned commands:

[shell_environment_policy]
include_only = ["PATH", "HOME", "NODE_ENV", "DATABASE_URL"]

This is critical for security. Without this policy, Codex forwards your entire shell environment to any command it runs, which could leak secrets.

Prompt to inspect your current configuration:

Run this in the CLI to see your effective settings:

codex "What are my current configuration settings? List model, approval policy, sandbox mode, and web search mode."

CLI Quick Overrides

You do not always need to edit config.toml. The CLI accepts one-off overrides:

# Override model for this session
codex -c model=gpt-5.2

# Override approval policy
codex -a never

# Enable a feature flag
codex --enable shell_snapshot

# Combine multiple overrides
codex -c model=gpt-5.2 -c model_reasoning_effort=low

When This Breaks

“Untrusted project” warning and project config ignored: Codex asks you to trust a project the first time you open it. If you declined, project-level .codex/config.toml files are skipped. Re-run Codex in the project and accept the trust prompt.

Approval mode seems wrong: Check the precedence. A CLI flag overrides everything. Run codex without flags to test the config file settings in isolation.

Feature flag not taking effect: Some flags require restarting Codex. Close the App, exit the CLI, and reopen. Feature flags are read at startup, not hot-reloaded.

“sandbox_mode not allowed” error: Your organization may enforce constraints via requirements.toml. Contact your admin if managed policies block your preferred sandbox mode.

Environment variables missing in commands: If Codex runs npm test and it fails because DATABASE_URL is missing, check your [shell_environment_policy]. Either add the variable to include_only or remove the policy to forward everything.

What’s Next

Set Up AGENTS.md Give Codex real context about your project conventions and expectations