Codex config.toml: File Location, Settings & Examples

Need a working Codex configuration? Put user settings at ~/.codex/config.toml, set model, model_provider, and model_reasoning_effort, then save the API key with codex login --with-api-key. Verify the result with /status and use /debug-config to see which configuration precedence layer supplied each value. The same configuration layers are shared by Codex CLI and the Codex IDE extension. If you set CODEX_HOME, look for config.toml in that directory instead.

Official OpenAI documentation reviewed 2026-10-21. Field notes were collected against Codex CLI 0.146.0. The recommended template was rechecked on 2026-09-14 with 0.154.0 (strict config check plus a live test through this gateway). Repeat the validation at the end of this page after you upgrade. The install guide defaults to gpt-6.1-sol; the example below uses the flagship gpt-6-astra and keeps the sandbox at workspace-write. For installation, start with Codex Setup. For the editor extension, continue with VS Code setup.

Keep API keys and bearer tokens out of config.toml, source control, documentation, and shell history.

Copy-paste Codex setup

This example connects Codex to I Code Easy using an I Code Easy account and API key. Before signing up, check current prices and payment availability, supported model capabilities, and how API data is handled. If you already use another provider, keep its provider ID, model IDs, Base URL, and credentials when applying the settings below.

1. Create an account and copy a key from API Keys.
2. Create ~/.codex/config.toml. On Windows, ~ is your user profile directory.
3. Paste this configuration:

model_provider = "icodeeasy"
model = "gpt-6-astra"
model_reasoning_effort = "xhigh"
plan_mode_reasoning_effort = "xhigh"
cli_auth_credentials_store = "file"

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

[model_providers.icodeeasy]
name = "I Code Easy"
base_url = "https://api.icodeeasy.cc"
wire_api = "responses"
requires_openai_auth = true

The example selects gpt-6-astra. Choose a model supported by your account from the model capability catalog and check current pricing before your first request.

Do not append /v1 to this Codex Provider Base URL. If the primary domain is slow or unreachable from your network, change only base_url to https://jp.icodeeasy.cc or https://sg.icodeeasy.cc. You can compare the currently available domains on Endpoints.

1. Save the API key without writing it into config.toml.

Linux and macOS:

read -s OPENAI_API_KEY
printf '\n'
printf '%s' "$OPENAI_API_KEY" | codex login --with-api-key
unset OPENAI_API_KEY
codex login status

PowerShell:

$secureKey = Read-Host "API Key" -AsSecureString
$plainKey = [System.Net.NetworkCredential]::new("", $secureKey).Password
$plainKey | codex login --with-api-key
$plainKey = $null
codex login status

Codex writes the credential to ~/.codex/auth.json. Do not create or edit that file manually.

Verify the configuration

Start Codex inside a project:

codex

Then run:

/status
/debug-config

The important /status lines should identify the selected model and destination:

Model:              gpt-6-astra (reasoning xhigh)
Model provider:     I Code Easy - https://api.icodeeasy.cc
Account:            API key configured

Verification checklist:

• codex login status confirms that a login is stored.
• /status shows gpt-6-astra, reasoning xhigh, and the intended Provider URL.
• /debug-config shows which file or CLI override supplied each effective value.
• A real prompt returns text and completes its stream; an HTTP response alone is not a complete configuration check.

If the Provider URL or model is wrong, fix the highest-precedence configuration layer instead of editing every file you can find.

Quick answers for common config.toml questions

Configuration location and precedence

The user-level file is:

~/.codex/config.toml

Higher-precedence values override lower-precedence values in this order:

1. CLI flags and -c / --config overrides;
2. .codex/config.toml files from the trusted project root down to the current directory;
3. the selected $CODEX_HOME/<name>.config.toml profile;
4. user configuration at ~/.codex/config.toml;
5. cloud-managed default configuration, when supplied;
6. system configuration;
7. Codex defaults.

A trusted project can provide project-local configuration, hooks, and rules. It still cannot override provider routing, authentication, or profile selection. Codex ignores model_provider, [model_providers.<id>], openai_base_url, and profile-related keys in project-local configuration. Keep those settings in ~/.codex/config.toml or the selected $CODEX_HOME/<name>.config.toml profile file.

Top-level TOML keys must appear before the first table:

model = "gpt-6-astra"
model_reasoning_effort = "xhigh"

[model_providers.icodeeasy]
name = "I Code Easy"

After a table header, later keys belong to that table until another table begins.

Model and reasoning settings

model

To set the default model for future sessions, add a top-level model entry to your user configuration, before any [table] header:

model = "gpt-6-astra"

For one session, override the default from the command line:

codex --model gpt-6-astra

The command-line flag does not rewrite config.toml. If the selected model still differs from your saved default, check CLI overrides, the active profile, and trusted project configuration with /debug-config, then confirm the effective model with /status.

The model ID must be available from the active Provider. A configuration check alone does not verify model access, tool calls, streaming completion, or usage reporting.

model_reasoning_effort

model_reasoning_effort = "xhigh"

Available values depend on both the model and the client release. The current reference also includes examples such as max and ultra; those are not supported by every model or provider. Use a value documented for your selected model and confirm it in /status. A value accepted by TOML parsing can still be rejected when the request reaches the Provider.

plan_mode_reasoning_effort

plan_mode_reasoning_effort = "xhigh"

This is a Plan-mode-specific override. Remove it to use Codex's built-in Plan-mode preset.

Context window: set it to 1M

The Codex models served here (e.g. gpt-6.1-sol) are verified in production to accept roughly 1M tokens of context (successful requests beyond 830K tokens), while Codex's model catalog defaults to only ~258K, so long sessions auto-compact far earlier than necessary. Set it explicitly:

model_context_window = 1000000
model_auto_compact_token_limit = 900000

Once a single turn's input exceeds 500K tokens, the request is billed at the long-context tier and the usage detail shows "Long context". An input of exactly 500K or less stays at the standard price.

Provider ID, Base URL, and authentication

model_provider = "icodeeasy"

[model_providers.icodeeasy]
name = "I Code Easy"
base_url = "https://api.icodeeasy.cc"
wire_api = "responses"
requires_openai_auth = true

Changing only name does not change routing, authentication, latency, or billing. The Provider ID is also stored in session metadata. If you rename or remove it, an older session may fail to resume with:

failed to load configuration: Model provider `icodeeasy` not found

Restore the original Provider definition to resume the session.

Authentication

The copy-paste configuration uses:

cli_auth_credentials_store = "file"
requires_openai_auth = true

The official reference supports file, keyring, and auto for cli_auth_credentials_store. file stores credentials in ~/.codex/auth.json; keyring uses the operating-system credential store; auto uses the OS store when available and otherwise falls back to the file.

With requires_openai_auth = true, Codex can use an API key saved by codex login --with-api-key, and it ignores a Provider-level env_key. These are alternative authentication methods, not two settings to combine.

For a provider-specific environment variable instead, remove requires_openai_auth = true and use:

[model_providers.example]
name = "Example Provider"
base_url = "https://example.com"
env_key = "EXAMPLE_API_KEY"
wire_api = "responses"

Do not use both methods for one Provider. Run codex login --with-api-key again to rotate the saved key, or codex logout to remove the current login.

Project trust and profiles

Trust only repositories you control:

[projects."/absolute/path/to/repository"]
trust_level = "trusted"

An untrusted project skips project-scoped .codex/ configuration, hooks, and rules. User and system configuration still load.

Current Codex profiles are separate files next to the user configuration. Keep only the differences in each profile:

# ~/.codex/quick.config.toml
model_reasoning_effort = "medium"
plan_mode_reasoning_effort = "high"

codex --profile quick

Keep the stable Provider ID in the base user configuration so saved sessions can still find it.

Fix 401, 429, and connection errors

401 Unauthorized

A 401 normally means Codex sent no usable credential or the saved key is invalid.

1. Run codex login status.
2. Copy an active key from API Keys.
3. Run codex login --with-api-key again.
4. Confirm that requires_openai_auth = true is present and that you did not also rely on env_key.
5. Restart the failed Codex session and check /status.

Do not paste the key into config.toml while debugging.

429 Too Many Requests

A 429 is not a TOML syntax error. Check account balance and model availability, then retry with lower concurrency. If only one model fails, test another available model before changing authentication. Use Endpoints to compare access domains and Recharge when the account needs more balance.

Connection failed or timed out

1. Confirm that base_url has no /v1 suffix and no trailing path.
2. Try https://jp.icodeeasy.cc or https://sg.icodeeasy.cc as the Base URL.
3. Check whether a VPN, corporate proxy, DNS filter, or local firewall can reach the selected domain.
4. Run /status again to prove that Codex loaded the URL you changed.

If the URL in /status did not change, another configuration layer has higher precedence.

Provider not found after resume

If an old session names a Provider ID that is no longer defined, restore the matching [model_providers.<id>] table. Do not edit Codex session files by hand.

Unknown configuration field

Start Codex with strict configuration checking after changing fields:

codex --strict-config

Fix the first reported field, then start it again. Use /debug-config to inspect the loaded configuration and /status to check the effective settings. You can exit without sending a prompt when you only want to inspect configuration. A field from an old blog post or issue may no longer be recognized by your running client.

Codex is ignoring an unrecognized configuration setting

If the warning names features.thread_tools or features.code_mode_tool_description_first, the running client is ignoring that entry. These names are not listed in the current public configuration reference; do not add them just to match an older configuration example.

1. Read the field name and source shown in the warning.
2. Use /debug-config to find the configuration layer supplying the value.
3. Remove the unsupported entry from that source, then restart Codex and check the warning.

If the source is session-flags, also check the launcher or integration that starts Codex. Editing ~/.codex/config.toml will not remove a value supplied by a different source. An unrecognized-field warning does not by itself indicate a bad API key or an unavailable model.

Obsolete fields and validation

Do not add this old field to Codex CLI 0.145.0:

disable_response_storage = true

The current public configuration reference does not list it. A local strict check reports unknown configuration field disable_response_storage; that proves only that the tested Codex version rejects the setting. It does not make a claim about service-side retention.

Next steps

• New to the product? Create an account and then open API Keys.
• Checking whether the service fits your project? Review pricing and payment availability and model capabilities.
• Already have a key? Compare Endpoints, paste the configuration, and verify it with /status.
• Need installation or Windows steps? Follow Codex Setup.
• Using the IDE extension? Continue with VS Code setup.

Official references

• Codex configuration basics
• Codex Configuration Reference
• Codex Advanced Configuration
• Codex Authentication
• Codex CLI command reference