Codex config.toml Setup, Settings & Fixes

Need a working Codex configuration? Put the file at ~/.codex/config.toml, paste the provider setup below, save your API key with codex login --with-api-key, and verify the result with /status. The same file is shared by Codex CLI and the Codex IDE extension.

Official OpenAI documentation reviewed 2026-08-17; strict configuration behavior tested with codex-cli 0.145.0. Codex changes quickly, so repeat the validation steps after an upgrade. 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

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-5.6-sol"
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

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-5.6-sol (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-5.6-sol, 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. system configuration;
6. 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-5.6-sol"
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

model = "gpt-5.6-sol"

The model name is sent to the active Provider. Verify the selected model, tool calls, streaming completion, and usage reporting with a real request.

model_reasoning_effort

model_reasoning_effort = "xhigh"

The official reference lists minimal, low, medium, high, and xhigh. xhigh remains model-dependent. A value accepted by TOML parsing can still be unsupported by the selected model, so confirm the effective value in /status.

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.

Avoid hard-coding model_context_window or model_auto_compact_token_limit unless the active model's real limit has been verified.

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

Run a strict validation after changing fields:

codex --strict-config mcp-server </dev/null

Fix the first reported field, then run the command again. A field from an old blog post or issue may no longer be part of the current public contract.

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.
• 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