Codex CLI config.toml: The Complete Guide to Models, Approvals, MCP and Layered Config

Codex CLI's behavior centers on ~/.codex/config.toml — one TOML file deciding which model it runs, what files it may touch, which tools it can call, and when it stops to ask. This guide maps the keys as defined by the ConfigToml struct in the codex-rs source rather than folklore.

1. File locations and layering

• User level: ~/.codex/config.toml — global defaults
• Project level: .codex/config.toml at the repo root — overrides same-named keys
• Admin level: requirements.toml — managed/mandatory constraints (e.g. allow_managed_hooks_only = true makes user and project hook configs inert, keeping only managed hooks)

The layering means: personal preferences go user-level, project rules go project-level (and into git), enterprise policy goes into requirements.toml.

2. Model and reasoning keys

model = "gpt-6-astra"
model_provider = "openai"
model_reasoning_effort = "high"
model_verbosity = "medium"

• model — the model name
• model_provider — a key into the [model_providers] table, which can register custom providers for alternate channels
• model_reasoning_effort — reasoning depth
• model_reasoning_summary / model_verbosity — reasoning summary style and output verbosity
• model_context_window / model_auto_compact_token_limit — context window and auto-compaction thresholds (rarely needed)

3. The two safety axes

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

sandbox_mode governs filesystem and network boundaries (read-only / workspace-write / external-sandbox / danger-full-access); approval_policy governs when the agent asks (on-request / on-failure / granular / never). See our sandbox guide for the full semantics — the point here is they are independent and combine; there is no single master switch.

4. MCP and profiles

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

[profiles.ci]
model = "gpt-6-astra"
approval_policy = "never"
sandbox_mode = "workspace-write"

• [mcp_servers.<name>] — declares an MCP server (full field list in our MCP guide)
• [profiles.<name>] — named config bundles for scenarios; select with profile = "ci" or --profile

Profiles are the most underused mechanism in config.toml — packaging "write code", "CI batch", "read-only review" into three profiles beats editing the file every time.

5. Common mistakes

• Writing requirements.toml keys into config.toml: allow_managed_hooks_only only works in the admin layer — misplaced, it silently does nothing
• Defining profiles but never selecting them: a [profiles.ci] block without --profile ci is dead config
• Plaintext secrets on disk: prefer the *_env_var forms for API keys — project-level files are committed to git
• Treating model_provider as a URL: it is a provider key; custom channels must be registered in [model_providers] first

6. Next steps

• Codex CLI Sandbox Modes: sandbox_mode and approval_policy Explained
• Codex CLI MCP Servers: The Full mcp_servers Config Field Guide
• Getting started with OpenAI Codex CLI: from install to daily use