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.

The ChatGPT desktop app, CLI, and VS Code-family IDE extension share the same local config layers when they use the same CODEX_HOME. Codex Cloud has separate environment and workspace configuration; local config.toml settings do not automatically sync to cloud tasks.

Tip

Prompt to open your config file from the IDE:

In the Codex IDE extension, click the gear icon in the top-right corner, then select Codex Settings > Open config.toml. This opens your user-level config file directly.

Configuration Precedence

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

1. CLI flags and --config overrides — for example, codex -a on-request beats file-based defaults.

2. 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.

3. Profile file — $CODEX_HOME/<name>.config.toml, selected with --profile <name>.

4. User config — ~/.codex/config.toml.

5. System config — /etc/codex/config.toml on Unix (if present).

6. Built-in defaults — Codex’s factory settings.

This means a trusted repo’s .codex/config.toml overrides profile and user defaults. Use a CLI flag or -c key=value for a one-off override; use managed requirements.toml when an administrator must constrain allowed values.

Caution

If you mark a project as untrusted, Codex skips all .codex/ layers (including project config) and falls back to user, system, and built-in defaults. This is a security feature — untrusted repos cannot change your sandbox settings.

Essential Settings

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

Choose a model your plan exposes

Codex model availability is plan- and workspace-dependent: Free and Go expose GPT-5.6 Terra; eligible Plus, Pro, Business, and Enterprise accounts can choose Sol, Terra, or Luna. A managed-workspace admin can restrict models by role. The explicit Terra setting below is a portable, balanced choice — it is not a claim that every Codex product surface has the same default.

The API model cards list a 1,050,000-token context window and 128,000 maximum output tokens for Sol, Terra, and Luna. Those are API limits, not a promise that every Codex surface exposes the full window to a thread.

GPT-5.6 also adds max in Codex settings for every user with model access, while ultra is available in Codex on Plus and higher plans. These are product controls: the current config.toml reference still documents model_reasoning_effort only through xhigh, so do not put max or ultra in this key unless your installed schema explicitly accepts it.

~/.codex/config.toml

# Model selection -- choose the GPT-5.6 tier by workload.
# Sol: frontier quality; Terra: balanced; Luna: high-volume efficiency.
model = "gpt-5.6-terra"

# Approval policy -- controls when Codex asks to cross a permission boundary
# Use "on-request" for interactive work. Reserve "never" for explicitly
# trusted unattended runs; it does not weaken the sandbox.
approval_policy = "on-request"

# Sandbox mode -- controls filesystem and network access
# Options: "read-only", "workspace-write" (default), "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: "minimal", "low", "medium", "high", "xhigh" (xhigh is model-dependent)
model_reasoning_effort = "high"

# Credential storage
cli_auth_credentials_store = "auto"

Approval Modes Deep Dive

Approval policy and sandbox mode are separate axes: the sandbox defines what a command can technically access, while the approval policy defines whether Codex may ask to cross that boundary. Changing one does not silently change the other.

on-request (Interactive)

Codex works autonomously inside the active sandbox and asks when it needs to cross that boundary, for example to write outside the workspace or use blocked network access. It does not ask before every routine edit or command that already fits the sandbox.

approval_policy = "on-request"

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

never (Unattended)

Codex never opens an approval prompt. It makes a best effort inside the configured sandbox, and an action outside that boundary fails instead of being approved. Use it only for explicitly trusted unattended automation, preferably with workspace-write or a stricter sandbox.

approval_policy = "never"

Use when: A reviewed CI job or isolated automation runner must not wait for a person. Do not combine it with danger-full-access unless the runner itself provides an equivalent isolation boundary.

Tip

Prompt to test your approval mode:

With on-request and workspace-write, try this in the interactive CLI:

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

Codex should create and read the file inside the workspace without an approval prompt. A request to write outside the workspace should trigger approval. That distinction verifies both axes.

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-request"

# 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. Project config takes precedence over profile and personal config; only CLI flags/-c sit above it.

Feature Flags

Optional capabilities live under the [features] table:

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

# Persisted goals and automatic continuation are stable and on by default.
goals = true

Key feature flags:

Flag	Default	What it does
shell_snapshot	true	Stable; snapshots the shell environment for faster repeated commands
unified_exec	true except Windows	Stable PTY-backed execution; Windows keeps it off by default
goals	true	Stable persisted goals and automatic continuation

Enable from the CLI without editing config:

codex features list

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.

Tip

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.6-sol

# Override approval policy for an interactive session
codex -a on-request

# Inspect current feature state
codex features list

# Combine multiple overrides
codex -c model=gpt-5.6-sol -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.

Requested GPT-5.6 model is unavailable: Check your plan and workspace role before changing model IDs. Free and Go use Terra; eligible Plus, Pro, Business, and Enterprise users can select all three tiers, unless an admin policy narrows access.

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