Codex config.toml Guide: Location, Provider, Model, and Precedence (October 2026, Tested on Codex 0.166)

Updated and tested on Codex CLI 0.166.0: where config.toml lives on each OS, a complete third-party provider config using a global experimental_bearer_token, profile files, model_reasoning_effort values and GPT-6.1 Terra, which of CLI flags, profiles and the global config wins, plus raw messages for 401, unknown model and legacy profiles errors and a troubleshooting order.

12 min read
Codex config.toml Guide: Location, Provider, Model, and Precedence (October 2026, Tested on Codex 0.166)
Updated 2026-10-31: re-tested end to end on Codex CLI 0.166.0 (the latest stable release, published 2026-10-30). Added a complete copy-paste config, a profile test, model_reasoning_effort values, how to set GPT-6.1 Terra, the new codex doctor --network-only in 0.166.0, and raw error messages.

When a Codex setting doesn't take effect, stop adding more fields to config.toml.

You may have edited the wrong layer, a command-line flag may be overriding it, or you may have put provider settings that only work at user level into a project directory. This guide first explains where the config file lives and what overrides what, then gives a complete config for AI Code With and a troubleshooting order. Fields and rules follow OpenAI's official Config basics, Advanced Configuration and Configuration Reference; every command here was actually run on Codex CLI 0.166.0 with one of our keys.

If Codex isn't installed yet, start with How to Use Codex. If you only need to know where the key goes, see How to Configure a Codex API Key.

Create an API Key →

Short answer

  • User-level config is ~/.codex/config.toml (%USERPROFILE%\.codex\config.toml on Windows).
  • For a third-party service, put model_provider and [model_providers.aicodewith] in the global config.toml, put the key in experimental_bearer_token, and set name = "aicodewith". These fields are ignored in a project's .codex/config.toml.
  • Precedence in one line: CLI flags > profile > global config.toml (a trusted project's .codex/config.toml sits between CLI flags and the profile).
  • A profile is now a separate file, ~/.codex/name.config.toml, selected with --profile name; a legacy [profiles.xxx] table in config.toml makes --profile fail.
  • The allowed model_reasoning_effort values depend on the model. Calling the API directly, gpt-6.1-terra accepts none, minimal, low, medium, high, xhigh and max.

Test setup and results

On a clean Linux machine we installed @openai/codex@0.166.0 with npm; codex --version printed codex-cli 0.166.0. With a separate CODEX_HOME holding the complete config below, we ran codex exec for each case:

TestCommandResultTime
Global configcodex exec "Reply with OK only"model: gpt-6.1-terra, provider: aicodewith, replied OKabout 2.7 s
Profile overrides globalcodex exec --profile deep "Reply with OK only"model switched to gpt-6.1-sol, reasoning effort to highabout 4.5 s
CLI flags override profilecodex exec --profile deep -m gpt-6.1-terra -c model_reasoning_effort='"low"' ...model back to gpt-6.1-terra, reasoning effort lowabout 2.8 s
Small taskAsk Codex to fix a bug in calc.py, add a test and run it1 line changed, test_calc.py created, test passedabout 12.9 s
Provider in project configmodel_provider and model_providers in the project's .codex/config.tomlignore warning printed, request still used the global providerabout 4.2 s

We sent the prompts in Chinese; they are translated in this table. Startup output of the global-config run, raw:

text
OpenAI Codex v0.166.0
--------
model: gpt-6.1-terra
provider: aicodewith
approval: never
sandbox: workspace-write [workdir, /tmp, $TMPDIR]
reasoning effort: medium
reasoning summaries: none
--------
user
只回复:OK
codex
OK

Quick reference: the most used config.toml fields

FieldWhat it doesExample
modelDefault modelmodel = "gpt-6.1-terra"
model_providerWhich provider to use, matching [model_providers.<id>]model_provider = "aicodewith"
experimental_bearer_tokenKey sent with requests, set inside the provider tableexperimental_bearer_token = "sk-your-key"
model_reasoning_effortReasoning effort; allowed values depend on the modelmodel_reasoning_effort = "medium"
plan_mode_reasoning_effortSeparate reasoning effort for Plan modeplan_mode_reasoning_effort = "high"
approval_policyWhen Codex pauses to ask youapproval_policy = "on-request"
sandbox_modeFile and network access for commandssandbox_mode = "workspace-write"
web_searchWeb search modeweb_search = "cached"

A misspelled field name doesn't always cause an error; Codex may silently ignore it, so check the official reference before writing.

Where config.toml lives

From the official docs: "User-level configuration lives in ~/.codex/config.toml. You can also add project-scoped overrides in .codex/config.toml files." Source: Configuration Reference.

macOS

The user-level path is ~/.codex/config.toml, i.e. /Users/your-name/.codex/config.toml. .codex is a hidden folder; if Finder doesn't show it, open it from the terminal:

bash
ls -la ~/.codex
open -e ~/.codex/config.toml

Windows

The user-level config is %USERPROFILE%\.codex\config.toml, for example C:\Users\your-name\.codex\config.toml. View and edit it in PowerShell:

powershell
Get-ChildItem "$env:USERPROFILE\.codex"
notepad "$env:USERPROFILE\.codex\config.toml"

When saving from Notepad, make sure the encoding is UTF-8 so Codex can read the file.

Linux

The path is also ~/.codex/config.toml:

bash
ls -la ~/.codex
nano ~/.codex/config.toml

On Unix, if /etc/codex/config.toml exists, it is read as system-level config with lower priority than your user config.

If you set CODEX_HOME

CODEX_HOME defaults to ~/.codex. If you point it elsewhere, config.toml, profile files and auth.json all have to live in the new directory. The quickest check is the network diagnostic added in 0.166.0, which prints the config.toml actually loaded (see "Run codex doctor first" below).

Back up before editing

macOS / Linux:

bash
cp ~/.codex/config.toml ~/.codex/config.toml.backup

Windows PowerShell:

powershell
Copy-Item "$env:USERPROFILE\.codex\config.toml" "$env:USERPROFILE\.codex\config.toml.backup"

If the file doesn't exist, start with a minimal config rather than a long template. The more fields you have, the harder it is to tell which line caused a problem.

Complete copy-paste config (AI Code With)

Put the whole block below into the global ~/.codex/config.toml and replace sk-your-key with your own key:

toml
# ~/.codex/config.toml
model_provider = "aicodewith"
model = "gpt-6.1-terra"
model_reasoning_effort = "medium"

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

[model_providers.aicodewith]
name = "aicodewith"
base_url = "https://api.aicodewith.ai/chatgpt/v1"
wire_api = "responses"
experimental_bearer_token = "sk-your-key"

Then check four things:

  • model_provider matches the ID in [model_providers.xxx] exactly; here both are aicodewith;
  • base_url comes from the provider's current docs, not from memory;
  • experimental_bearer_token holds the full key with no spaces around it;
  • model is a model ID the provider actually serves, in lowercase.

Run one minimal request:

bash
codex exec "Reply with OK only"

If the startup output shows provider: aicodewith and your model, and the reply is OK, the config works. Then check the request time and model in the dashboard's usage log.

From the official docs: model_provider is "Provider id from model_providers (default: openai)"; for wire_api, "responses is the only supported value, and it is the default when omitted". Source: Configuration Reference.

A few more official rules:

  • A custom provider can't use the reserved built-in IDs openai, ollama and lmstudio. Since 0.165.0 there is also a built-in Google Cloud Vertex AI provider (model_provider = "gcp", per the rust-v0.165.0 release), so don't use that name for your own provider either;
  • If you only want to point the built-in OpenAI provider at a proxy, openai_base_url is enough; no new provider needed;
  • The provider and key only work in the global ~/.codex/config.toml; in a project's .codex/config.toml they are ignored (see the next section).

For what wins when environment variables and this file disagree, see Codex Environment Variables.

Precedence: what overrides what

For everyday use, remember one line: CLI flags > profile > global config.toml. The full resolution order in the official docs, highest first:

  1. CLI flags (-m / --model, -c / --config and so on);
  2. Project config files .codex/config.toml, loaded from the project root down to the current directory (closest wins), and only in trusted projects;
  3. The profile file ~/.codex/name.config.toml selected with --profile name;
  4. User config ~/.codex/config.toml;
  5. Cloud-managed defaults from a signed-in workspace, if any;
  6. System config /etc/codex/config.toml (Unix, if present);
  7. Built-in defaults.

We tested this order with one global config (gpt-6.1-terra, medium) and one profile file (gpt-6.1-sol, high):

How Codex was startedmodel in startup outputreasoning effort
codex execgpt-6.1-terramedium
codex exec --profile deepgpt-6.1-solhigh
codex exec --profile deep -m gpt-6.1-terra -c model_reasoning_effort='"low"'gpt-6.1-terralow

So when "I changed config.toml and nothing happened", first check whether the command includes --model, --config or --profile, then check whether the current project has a .codex/config.toml overriding it.

Project config can't change provider, base URL or auth

From the official docs: "Codex ignores the following keys in project-local .codex/config.toml and prints a startup warning when it sees them: openai_base_url, chatgpt_base_url, apps_mcp_product_sku, model_provider, model_providers, notify, profile, profiles, experimental_realtime_ws_base_url, and otel." Source: Advanced Configuration · Project config files.

We tested it again on 0.166.0. In a trusted project's .codex/config.toml we set model = "gpt-6.1-sol", a non-existent model_provider, and a rewritten base_url and key for the aicodewith table (all wrong values). The model change applied (switched to gpt-6.1-sol); the provider, URL and key were all ignored, the request succeeded with the global config, and this warning was printed at startup (path replaced with <project>):

text
warning: Ignored unsupported project-local config keys in <project>/.codex/config.toml: model_provider, model_providers. If you want these settings to apply, manually set them in your user-level config.toml.

The upside: keys never get committed with the repo, and a teammate who clones it won't end up on someone else's service.

Profiles: different configs for different jobs

With --profile name, Codex loads ~/.codex/config.toml first and then layers ~/.codex/name.config.toml on top. A profile file contains top-level fields, only the ones that differ from the base config. For example, a deep profile for large changes:

toml
# ~/.codex/deep.config.toml
model = "gpt-6.1-sol"
model_reasoning_effort = "high"

Usage:

bash
codex --profile deep
codex exec --profile deep "review this change"
From the official docs: "In Codex 0.134.0 and later, --profile no longer reads [profiles.profile-name] from config.toml, and the top-level profile = "profile-name" selector is no longer supported." Source: Advanced Configuration · Profiles.

If config.toml still contains a legacy [profiles.old] table, --profile old exits with an error on 0.166.0. The raw message (path replaced with ~/.codex):

text
Error loading config.toml: --profile `old` cannot be used while ~/.codex/config.toml contains legacy `profile = "old"` or `[profiles.old]` config; move those settings into ~/.codex/old.config.toml and remove the legacy profile selector/table. See https://developers.openai.com/codex/config-advanced#profiles for more information.

Move each legacy profile into its own ~/.codex/name.config.toml and delete the old table. For different models and keys per project, see Managing Multiple Codex Projects.

What to put in model and model_reasoning_effort

Model ID

model must be a model ID the provider really serves, in lowercase, for example gpt-6.1-terra or gpt-6.1-sol. According to the rust-v0.165.0 and rust-v0.166.0 release notes, GPT-6.1 Terra has been added to Codex's bundled model catalog. On 0.166.0, setting gpt-6.1-terra produced no "Model metadata not found" warning at startup. For choosing between Terra and Sol and calling it through the API, see How to Use GPT-6.1 Terra in Codex and the API.

To try another model temporarily without editing the file, use a CLI flag:

bash
codex --model gpt-6.1-sol
codex --config model='"gpt-6.1-sol"'
From the official docs: "--config values are parsed as TOML. When in doubt, quote the value so your shell doesn't split it on spaces." Source: Advanced Configuration.

So the string needs double quotes, wrapped in single quotes so the shell doesn't split it.

Reasoning effort values

The official reference describes model_reasoning_effort as "Reasoning effort advertised by the selected model, such as low, medium, high, xhigh, max, or ultra. Available levels depend on the model and client." Source: Configuration Reference. In other words, the model decides which values are valid.

Calling our API directly with ultra for gpt-6.1-terra returned 400, and the error listed every accepted value:

text
Invalid value: 'ultra'. Supported values are: 'none', 'minimal', 'low', 'medium', 'high', 'xhigh', and 'max'.

In Codex 0.166.0, setting xhigh, max and ultra with -c all replied OK in 2 to 3 seconds. Since ultra is not in the API's list, stick to the values above in your config file. Keep medium for everyday small edits and raise it to high or xhigh for cross-file refactors or hard bugs; higher effort is usually slower and uses more tokens. Since 0.165.0, supported models let you change reasoning effort mid-conversation (per the rust-v0.165.0 release), so you don't need to restart for that.

Common experience settings

approval_policy: when Codex asks you

Options are on-request (ask when needed), never (no prompts), or a granular table. The old approval_policy = "untrusted" is retired and on-failure is deprecated; if your file still has either, follow the official migration notes. Beginners should keep on-request.

sandbox_mode: how far commands can reach

Options are read-only, workspace-write and danger-full-access. The one with danger in its name is only for isolated environments where you fully understand the consequences.

web_search: which search mode

Options are disabled, cached, indexed and live; the default is cached. Treat web results as untrusted content.

shell_environment_policy: which variables reach subprocesses

ignore_default_excludes defaults to true, which means variables with KEY, SECRET or TOKEN in their names are not filtered automatically. To filter them, set it to false:

toml
[shell_environment_policy]
ignore_default_excludes = false

Run codex doctor first

0.166.0 added codex doctor --network-only for focused configuration, connectivity and WebSocket checks (per the rust-v0.166.0 release). With the complete config above, the key lines were (path replaced with ~/.codex):

text
Codex Doctor v0.166.0

Configuration
  ✓ config       loaded
      model                    gpt-6.1-terra · aicodewith
      config.toml              ~/.codex/config.toml
      config.toml parse        ok
Connectivity
  ✓ network      no proxy env vars
  ✓ websocket    Responses WebSocket is not enabled for the active provider
  ✓ reachability active provider endpoints are reachable over HTTP
4 ok · 0 warn · 0 fail ok

It confirms three things: which config.toml is loaded, whether the TOML parses, and whether the active provider's endpoint is reachable. It does not prove the key is valid: with the same config, the probe lines under reachability showed HTTP 401 while real requests succeeded. To check the key, run codex exec "Reply with OK only".

Alternative: key in auth.json

The AI Code With dashboard's Codex (terminal) guide uses another approach: the key goes in ~/.codex/auth.json and config.toml uses requires_openai_auth = true. Pick one of the two. config.toml:

toml
model_provider = "aicodewith"
model = "gpt-6.1-terra"

[model_providers.aicodewith]
name = "aicodewith"
base_url = "https://api.aicodewith.ai/chatgpt/v1"
wire_api = "responses"
requires_openai_auth = true

~/.codex/auth.json in the same folder:

json
{
  "OPENAI_API_KEY": "sk-your-key"
}
Don't drop requires_openai_auth = true. Without it Codex sends requests without the key and gets a 401.

Splitting config across a team

  • User-level ~/.codex/config.toml: provider, base URL, key, personal reasoning effort. These differ per person and include secrets, so never commit them.
  • Project-level .codex/config.toml: settings everyone on the project should share, such as model and approval policy. Even if someone writes a provider or key there by mistake, Codex ignores it and prints a warning.
  • Project rules such as code style, test commands and folder conventions belong in AGENTS.md.

Common errors and fixes

Error or symptomUsual causeFix
401 Unauthorized ("please provide a valid API Key" in Chinese)Wrong or expired key, or auth.json used without requires_openai_auth = trueCheck experimental_bearer_token or auth.json; recreate the key if needed
Model xxx does not exist or is not availableMisspelled model or one the provider doesn't serveUse an ID from the dashboard's model list, lowercase
Model metadata for xxx not foundModel ID not in Codex's bundled catalog, often a typoCheck the spelling; for new models, update Codex
Invalid value: 'ultra'Reasoning effort the model doesn't supportUse a value listed in the error, such as high or xhigh
Edited config.toml, model unchanged--model / --config / --profile on the command, or project config overridesDrop the flags and check the project's .codex/config.toml
warning: Ignored unsupported project-local config keysmodel_provider, model_providers etc. in project configMove them to ~/.codex/config.toml
Project .codex/config.toml has no effect at allProject not trustedTrust the project; by default the folder containing .git is the root
--profile fails with a legacy config errorOld [profiles.xxx] table still in config.tomlMove it to ~/.codex/name.config.toml

On 0.166.0, a 401 first prints Reconnecting five times and exits after about 9 seconds. The last line, raw (cf-ray and request id removed; the server message is in Chinese and means "please provide a valid API Key in the request"):

text
ERROR: unexpected status 401 Unauthorized: {"error":"请在请求中提供有效的 API Key。"}, url: https://api.aicodewith.ai/chatgpt/v1/responses

More 401 cases: Codex 401 Unauthorized.

With a misspelled model (we used gpt-6.1-terr on purpose), 0.166.0 does not retry and exits in under a second. Raw output (request id removed; the server message says the model does not exist or is not available and points to the model list):

text
warning: Model metadata for `gpt-6.1-terr` not found. Defaulting to fallback metadata; this can degrade performance and cause issues.
ERROR: {"error":"模型 gpt-6.1-terr 不存在或未上线,请前往 https://aicodewith.ai/zh/dashboard/pricing 查看可用模型列表"}

Per the rust-v0.165.0 release, since 0.165.0 Codex stops retrying when a provider reports that a model was not found and keeps the original message, so fix the model name right away.

Troubleshooting order when config doesn't apply

  1. Run codex doctor --network-only to see which config.toml is loaded and whether it parses;
  2. Check the command for --model, --config or --profile;
  3. Check whether the project is trusted, whether it has a .codex/config.toml, and whether startup prints Ignored unsupported project-local config keys;
  4. Make sure the provider ID, base URL and model ID match;
  5. Check the key: experimental_bearer_token is correct, or the auth.json setup includes requires_openai_auth = true;
  6. In the interactive UI, open /config to see current values and which changes need a restart (available since 0.163.0, per the rust-v0.163.0 release);
  7. Finally send codex exec "Reply with OK only" and check the usage log.

FAQ

Where is Codex's config.toml by default?

In config.toml under CODEX_HOME, which defaults to ~/.codex. On Windows that is %USERPROFILE%\.codex\config.toml. If unsure, run codex doctor --network-only; it prints the actual path.

Which wins: CLI flags, a profile, or config.toml?

CLI flags first, then a trusted project's .codex/config.toml, then the profile file selected with --profile, and finally the global config.toml. We tested this order on 0.166.0.

Can I put the API key directly in config.toml?

Yes. Put experimental_bearer_token = "sk-your-key" in the provider table of the global ~/.codex/config.toml; this is the recommended setup for AI Code With. You can also follow the dashboard guide and put the key in auth.json with requires_openai_auth = true in the provider table. Either way, keep it in the global config only, never in a project folder or repo.

Can model_reasoning_effort be ultra?

It depends on the model. Calling the API directly, gpt-6.1-terra rejects ultra and accepts only none, minimal, low, medium, high, xhigh and max. Pick one of these in your config file.

Do the CLI and the IDE extension share the same config?

Yes, Codex CLI and the IDE extension share the same config layers.

How do I recover a broken config?

If you made a backup, copy config.toml.backup back. If not, cut the file down to the complete config above, get it working, then add fields back one by one.

Create an API Key for Codex →

Related reading

Sources

Related articles

What is the UI SDK, and how do you use it? Vercel and shadcn's behavior library for agents, installed and tested in Claude Code / Codex / Cursor (0.1.0-beta.1)

What is the UI SDK, and how do you use it? Vercel and shadcn's behavior library for agents, installed and tested in Claude Code / Codex / Cursor (0.1.0-beta.1)

The UI SDK is Vercel's behavior library for agents, released on 12 November 2026 as 0.1.0-beta.1. Behaviors live in the framework-free @ui-sdk/core package and are rendered by adapters for React, Vue, Svelte, Solid, and Web Components. This guide follows the official docs on what it is, how to install it, and how to add the skill for Claude Code, Codex, and Cursor, and it records the commands, timings, and output from our test machine.

What Is AWS Emulator and How Do You Install It? Test AWS Apps Locally with Claude Code and Codex (Tested on 1.0.322)

What Is AWS Emulator and How Do You Install It? Test AWS Apps Locally with Claude Code and Codex (Tested on 1.0.322)

AWS Emulator is AWS's official local emulator of its service APIs, generally available since November 11, 2026 (US time). It has no additional service fee, its source is open, it needs no AWS account, and it covers more than 200 services. We tested version 1.0.322 on Debian 13. This guide covers the install commands, pointing the AWS CLI at the local endpoint to create an S3 bucket and a DynamoDB table, the errors we hit, and how to let Claude Code, Codex and Cursor write and test code against the emulator.

What Is T3 Code and How Do You Install It? Connect Claude Code and Codex, Use a Third-Party API Key, Fix Common Errors (Tested on 0.1.9)

What Is T3 Code and How Do You Install It? Connect Claude Code and Codex, Use a Third-Party API Key, Fix Common Errors (Tested on 0.1.9)

T3 Code is pingdotgg's open-source control surface for coding agents. It ships no model of its own; it drives the Claude Code, Codex, Cursor and other CLIs already on your machine. We tested T3 Code 0.1.9 on Linux. This guide covers the install commands, how to point Claude Code and Codex at an AICodeWith API Key so T3 Code can drive them, a full run of both agents with the t3 thread command, and the errors we hit along the way with their fixes.