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.
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:
| Test | Command | Result | Time |
|---|---|---|---|
| Global config | codex exec "Reply with OK only" | model: gpt-6.1-terra, provider: aicodewith, replied OK | about 2.7 s |
| Profile overrides global | codex exec --profile deep "Reply with OK only" | model switched to gpt-6.1-sol, reasoning effort to high | about 4.5 s |
| CLI flags override profile | codex exec --profile deep -m gpt-6.1-terra -c model_reasoning_effort='"low"' ... | model back to gpt-6.1-terra, reasoning effort low | about 2.8 s |
| Small task | Ask Codex to fix a bug in calc.py, add a test and run it | 1 line changed, test_calc.py created, test passed | about 12.9 s |
| Provider in project config | model_provider and model_providers in the project's .codex/config.toml | ignore warning printed, request still used the global provider | about 4.2 s |
We sent the prompts in Chinese; they are translated in this table. Startup output of the global-config run, raw:
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
| Field | What it does | Example |
|---|---|---|
| model | Default model | model = "gpt-6.1-terra" |
| model_provider | Which provider to use, matching [model_providers.<id>] | model_provider = "aicodewith" |
| experimental_bearer_token | Key sent with requests, set inside the provider table | experimental_bearer_token = "sk-your-key" |
| model_reasoning_effort | Reasoning effort; allowed values depend on the model | model_reasoning_effort = "medium" |
| plan_mode_reasoning_effort | Separate reasoning effort for Plan mode | plan_mode_reasoning_effort = "high" |
| approval_policy | When Codex pauses to ask you | approval_policy = "on-request" |
| sandbox_mode | File and network access for commands | sandbox_mode = "workspace-write" |
| web_search | Web search mode | web_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:
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:
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:
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:
cp ~/.codex/config.toml ~/.codex/config.toml.backup
Windows 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:
# ~/.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:
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:
- CLI flags (-m / --model, -c / --config and so on);
- Project config files .codex/config.toml, loaded from the project root down to the current directory (closest wins), and only in trusted projects;
- The profile file ~/.codex/name.config.toml selected with --profile name;
- User config ~/.codex/config.toml;
- Cloud-managed defaults from a signed-in workspace, if any;
- System config /etc/codex/config.toml (Unix, if present);
- 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 started | model in startup output | reasoning effort |
|---|---|---|
| codex exec | gpt-6.1-terra | medium |
| codex exec --profile deep | gpt-6.1-sol | high |
| codex exec --profile deep -m gpt-6.1-terra -c model_reasoning_effort='"low"' | gpt-6.1-terra | low |
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>):
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:
# ~/.codex/deep.config.toml
model = "gpt-6.1-sol"
model_reasoning_effort = "high"
Usage:
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):
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:
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:
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:
[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):
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:
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:
{
"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 symptom | Usual cause | Fix |
|---|---|---|
| 401 Unauthorized ("please provide a valid API Key" in Chinese) | Wrong or expired key, or auth.json used without requires_openai_auth = true | Check experimental_bearer_token or auth.json; recreate the key if needed |
| Model xxx does not exist or is not available | Misspelled model or one the provider doesn't serve | Use an ID from the dashboard's model list, lowercase |
| Model metadata for xxx not found | Model ID not in Codex's bundled catalog, often a typo | Check the spelling; for new models, update Codex |
| Invalid value: 'ultra' | Reasoning effort the model doesn't support | Use 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 overrides | Drop the flags and check the project's .codex/config.toml |
| warning: Ignored unsupported project-local config keys | model_provider, model_providers etc. in project config | Move them to ~/.codex/config.toml |
| Project .codex/config.toml has no effect at all | Project not trusted | Trust the project; by default the folder containing .git is the root |
| --profile fails with a legacy config error | Old [profiles.xxx] table still in config.toml | Move 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"):
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):
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
- Run codex doctor --network-only to see which config.toml is loaded and whether it parses;
- Check the command for --model, --config or --profile;
- Check whether the project is trusted, whether it has a .codex/config.toml, and whether startup prints Ignored unsupported project-local config keys;
- Make sure the provider ID, base URL and model ID match;
- Check the key: experimental_bearer_token is correct, or the auth.json setup includes requires_openai_auth = true;
- 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);
- 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.
Related reading
- How to Configure a Codex API Key
- Codex Environment Variables
- Codex 401 Unauthorized
- Managing Multiple Codex Projects
- How to Use GPT-6.1 Terra in Codex and the API
- How to Use Codex



