# Codex CLI config.toml: where it lives and what to set > Codex reads ~/.codex/config.toml, a trusted project's .codex/config.toml, a profile and -c flags. Flags win, then the closest project file. Source: https://shuriken.sh/guides/codex-cli-config-toml Codex reads ~/.codex/config.toml, a trusted project's .codex/config.toml, a profile and -c flags. Flags win, then the closest project file. By Shuriken Updated 27 October 2026 4 min read **Contents** 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](https://learn.chatgpt.com/docs/config-file/config-basic) 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 # | File | Scope | Notes | | --- | --- | --- | | ~/.codex/config.toml | You, every project | The one to edit first | | .codex/config.toml in a repository (or a subfolder) | That project | Read only when the project is trusted | | ~/.codex/.config.toml | A profile | Loaded with codex --profile | | /etc/codex/config.toml | The machine (Unix) | Usually left alone | 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: - Command-line flags and -c / --config overrides - Project .codex/config.toml files, from the project root down to the folder you're in (the closest wins; trusted projects only) - The profile file chosen with --profile - Your ~/.codex/config.toml - Cloud-managed defaults for your signed-in workspace - /etc/codex/config.toml - 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 # toml 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](https://shuriken.sh/guides/codex-cli-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](https://shuriken.sh/guides/codex-cli-approval-modes). - 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: toml [sandbox_workspace_write] network_access = true MCP servers go in [mcp_servers.] tables in the same file ([add an MCP server to Codex CLI](https://shuriken.sh/guides/codex-cli-mcp-servers) has the commands and keys). If one won't start, [Codex MCP server failed to start](https://shuriken.sh/guides/codex-mcp-server-failed-to-start) explains each error message. ## Less common keys from the same page # | Key | What it does | | --- | --- | | personality = "none" | Drops the Personality section from the model's built-in instructions. friendly and pragmatic no longer pick a style, and /personality is gone | | [tui.keymap.global] , .composer , .chat | Rebind terminal keys, e.g. open_transcript = "ctrl-t" ; an empty list unbinds | | [shell_environment_policy] | Which environment variables reach the commands Codex runs. ignore_default_excludes defaults to true , which skips filtering names containing KEY , SECRET or TOKEN ; false filters them | | log_dir | Moves the logs and turns on the plaintext codex-tui.log there | | default_permissions | A permission profile: built-in :read-only , :workspace , :danger-full-access , or your own [permissions.] | | [features] | Optional parts. multi_agent , hooks , shell_snapshot default to true ; memories is experimental and false . codex --enable turns one on from the command line | Shuriken runs Claude Code, Codex, Gemini CLI and 64 more agents side by side, with your own sign-ins. [Download](https://shuriken.sh/download) ## Change a setting for one run # For one run, pass -c (or --config). It outranks every file: bash 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: - Create ~/.codex/careful.config.toml with only the keys that differ, for example sandbox_mode = "read-only". - 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](https://shuriken.sh/guides/mcp-servers-across-all-projects). Share [X](https://x.com/intent/post?url=https%3A%2F%2Fshuriken.sh%2Fguides%2Fcodex-cli-config-toml&text=Codex%20CLI%20config.toml%3A%20where%20it%20lives%20and%20what%20to%20set)[LinkedIn](https://www.linkedin.com/sharing/share-offsite/?url=https%3A%2F%2Fshuriken.sh%2Fguides%2Fcodex-cli-config-toml)[Hacker News](https://news.ycombinator.com/submitlink?u=https%3A%2F%2Fshuriken.sh%2Fguides%2Fcodex-cli-config-toml&t=Codex%20CLI%20config.toml%3A%20where%20it%20lives%20and%20what%20to%20set)[Reddit](https://www.reddit.com/submit?url=https%3A%2F%2Fshuriken.sh%2Fguides%2Fcodex-cli-config-toml&title=Codex%20CLI%20config.toml%3A%20where%20it%20lives%20and%20what%20to%20set)[E-mail](mailto:?subject=Codex%20CLI%20config.toml%3A%20where%20it%20lives%20and%20what%20to%20set&body=https%3A%2F%2Fshuriken.sh%2Fguides%2Fcodex-cli-config-toml) ## Sources - [OpenAI: Codex config basics](https://learn.chatgpt.com/docs/config-file/config-basic) (accessed 25 October 2026) - [OpenAI: Agent approvals and security](https://learn.chatgpt.com/docs/agent-approvals-security) (accessed 23 October 2026) - [OpenAI: Model Context Protocol in Codex](https://learn.chatgpt.com/docs/extend/mcp?surface=cli) (accessed 23 October 2026) ## Frequently asked questions **Where is the Codex config file?** Your own settings are in ~/.codex/config.toml. A project can add .codex/config.toml in the repository, which Codex reads only when you trust the project. **Does the Codex IDE extension use the same config.toml?** Yes for MCP servers: OpenAI's MCP page says the ChatGPT desktop app, the Codex CLI and the IDE extension share the same configuration in ~/.codex/config.toml. **How do I change one setting for a single run?** Pass it with -c, for example codex -c model_reasoning_effort="high". Command-line flags and -c overrides win over every file. **Is approval_policy = "untrusted" still valid?** No. OpenAI's approvals page says untrusted is retired and can stop Codex from starting. Use on-request or never. Every coding agent 67 coding agents, one harness. Run Claude Code, Codex, Gemini CLI and the rest on your own computers, with the sign-ins you already have. [Download](https://shuriken.sh/download) [Other platforms](https://shuriken.sh/download#main) ## Keep reading - [Codex usage limits explained (2026): Guide 27 Oct 2026 5 min read How Codex limits work on ChatGPT Plus and Pro: the 5-hour and weekly windows, the 2026 changes, checking yours with /status, and using several accounts.](https://shuriken.sh/guides/codex-usage-limits) - [Claude Code vs Codex CLI (2026): Comparison 27 Oct 2026 6 min read Claude Code and Codex CLI side by side from each vendor's docs: plans, limits, MCP, platforms and licence. No made-up benchmarks, and how to run both.](https://shuriken.sh/compare/claude-code-vs-codex) - [Codex CLI on Windows: native PowerShell or WSL?: Guide 27 Oct 2026 7 min read Codex CLI runs natively in PowerShell inside its own Windows sandbox. In WSL2 it uses the Linux sandbox, needs bubblewrap and no longer runs on WSL1.](https://shuriken.sh/guides/codex-cli-on-windows) ## Free tools - [Claude limit reset tracker](https://shuriken.sh/tools/limit-resets/claude) - [Codex limit reset tracker](https://shuriken.sh/tools/limit-resets/codex)