Configuration with config.toml and profiles

Model and reasoning effort, approval and sandbox defaults, named profiles per workflow, project trust levels, and temporary overrides with -c.

The base configuration

# ~/.codex/config.toml
# Key names and available values change between releases.
# Confirm against the tool's own help output for your installed version.

model = "gpt-5-codex"
model_reasoning_effort = "medium"     # low | medium | high: cost against depth

approval_policy = "on-request"
sandbox_mode = "workspace-write"

# keep runs readable and logs available for the troubleshooting lesson
hide_agent_reasoning = false

[sandbox_workspace_write]
network_access = false
writable_roots = []

# register external tool servers; see the MCP lesson for what belongs here
# [mcp_servers.docs]
# command = "npx"
# args = ["-y", "@example/docs-mcp"]

• Reasoning effort is the main cost dial after the model itself. Low for mechanical edits, high for a task where the agent must reason about a subtle invariant.
• Keep the global file conservative. Per-task limits belong in a profile or on the command line, where the relaxation is visible in the run.
• Do not put credentials in config.toml. Use environment variables and the tool's own authentication, and keep the file free of anything you would not paste into a chat.
• Back up the file and treat edits as configuration changes: a typo in a key name can silently fall back to a default you did not intend.

Named profiles

# profiles let one file hold several working styles
[profiles.review]
model = "gpt-5-codex"
model_reasoning_effort = "high"
approval_policy = "untrusted"
sandbox_mode = "read-only"

[profiles.implement]
model = "gpt-5-codex"
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[profiles.ci]
model = "gpt-5-codex"
model_reasoning_effort = "low"
approval_policy = "never"
sandbox_mode = "workspace-write"
# only ever used inside a container with no credentials mounted

# select a profile for a run
codex --profile review "explain the retry logic in src/client.py and list its edge cases"
codex --profile implement "add exponential backoff to that retry loop"

# override a single key for one run without editing anything
codex -c model_reasoning_effort="high" "why does the nightly job occasionally double-process records?"
codex -c sandbox_mode="read-only" "summarise what changed in the last 20 commits"

# profiles are also usable from the environment for scripted runs
CODEX_PROFILE=ci codex exec "run the linter and report the failures"

Project trust and version drift

• Most agents ask you to confirm trust for a new directory before granting write access. Approving trust is a real decision: it decides whether a repository's own configuration files influence the run.
• Configuration keys move between releases. A key that no longer exists is usually ignored rather than rejected, so a silently ignored sandbox_mode can leave you running with a wider default than you intended.
• Record the tool version you validated your configuration against. After an upgrade, re-run your most sensitive workflow once and check which settings are still in force.
• Do not copy a configuration between machines without checking it. A profile written for a container is not appropriate on a laptop with your SSH keys and cloud credentials.

# capture the effective configuration for the record
codex --version > .codex-version.txt
codex --help > .codex-help.txt     2>&1

# verify a specific setting took effect by asking the agent to state it
codex -c sandbox_mode="read-only" "state your current sandbox mode and approval policy, then stop"

# after an upgrade, diff the help output against the recorded one
diff <(cat .codex-help.txt) <(codex --help 2>&1) | head -40

FAQ

Related

Approval modes and sandboxing Writing AGENTS.md project instructions

Last refreshed 2026-09-18.