Codex CLI config.toml: where it lives and what to set

Codex CLI reads ~/.codex/config.toml for your own settings, and .codex/config.toml inside a repository for that project's, though only after you've trusted the project. When the two disagree, the project file wins. A profile picked with --profile sits between them, and a -c key=value flag beats everything.

OpenAI's config basics page is where the keys and that order come from; we read it on 23 October 2026 and again on 25 October 2026. Codex changes often, so check it there when a key doesn't behave.

Where the Codex config files live#

Signing in to a ChatGPT workspace can add one more layer, cloud-managed defaults, and they rank below your own file. The IDE extension edits the same file as the CLI: gear icon › Codex Settings › Open config.toml.

If you mark a project untrusted, Codex skips everything under its .codex/ folder: the project config, its hooks and its rules. Your own and the system config still load.

Which setting wins#

OpenAI lists the order from highest to lowest:

1. Command-line flags and -c / --config overrides
2. Project .codex/config.toml files, from the project root down to the folder you're in (the closest wins; trusted projects only)
3. The profile file chosen with --profile
4. Your ~/.codex/config.toml
5. Cloud-managed defaults for your signed-in workspace
6. /etc/codex/config.toml
7. Codex's built-in defaults

A project file can therefore override your personal default model without telling you. When one repository behaves differently from the rest, look for a .codex/ folder there first.

On a managed machine there can be one more layer, requirements.toml, where your organisation sets limits rather than defaults. OpenAI's examples are disallowing approval_policy = "never" or sandbox_mode = "danger-full-access".

The keys worth setting first#

model = "gpt-6.1-sol"
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"

• model is the default model. The value above is the example OpenAI's page uses; run /model in Codex to see what your plan offers. To run Codex on a model served by Ollama or LM Studio, see Codex CLI with local models.
• model_reasoning_effort sets how much the model reasons, where the model supports it.
• approval_policy is when Codex stops to ask you: on-request or never. OpenAI's approvals page says the old untrusted value is retired and can stop Codex from starting, so delete it if an old config still has it.
• sandbox_mode is what Codex may touch: read-only, workspace-write or danger-full-access. Which pair suits which job is in the approval modes guide.
• web_search takes "cached" (the default, OpenAI's own index of results), "indexed", "live" (the same as --search) or "disabled".

Network access is off inside workspace-write by default. To allow it:

[sandbox_workspace_write]
network_access = true

MCP servers go in [mcp_servers.<name>] tables in the same file (add an MCP server to Codex CLI has the commands and keys). If one won't start, Codex MCP server failed to start explains each error message.

Less common keys from the same page#

Change a setting for one run#

For one run, pass -c (or --config). It outranks every file:

codex -c model_reasoning_effort="high"

For a whole setup you come back to, such as a careful one for production repositories, use a profile:

1. Create ~/.codex/careful.config.toml with only the keys that differ, for example sandbox_mode = "read-only".
2. Start Codex with codex --profile careful.

Everything else still comes from config.toml, which is the split OpenAI recommends: shared defaults there, differences in the profile.

A project file the whole team shares#

Everyone who trusts the repository gets what a committed .codex/config.toml sets. Two things are worth putting in it:

• sandbox_mode and approval_policy, so Codex has the same boundary for every person in that repo.
• [sandbox_workspace_write] with network_access = true, if the test suite needs the network.

Leave model out. It's a personal choice, and the project file would override it for everyone.

When you also run Claude Code#

Claude Code doesn't read this file. Its MCP servers live in ~/.claude.json and in a project's .mcp.json, so a server added to Codex has to be added there too. Shuriken keeps one list of MCP servers and hands it to every Codex and Claude Code chat when the chat starts. Doing it by hand on the Claude side takes claude mcp add --scope user, covered in set up MCP servers once for every project.