I changed the model in config.toml but it has no effect — why?

config.toml is loaded once at startup. After editing the file you must fully exit your Codex session (Ctrl+C) and relaunch codex for the new model to take effect. To switch models mid-session without restarting, use the /model slash command — it won't be written back to the file.

My third-party API is throwing an error about wire_api — how do I fix it?

As of February 2026, Codex removed Chat Completions support. All providers — including third-party and local-model endpoints — must now use the Responses API. Change wire_api = "chat" to wire_api = "responses" in every [model_providers. ] section. If your third-party endpoint doesn't support the Responses API yet, it cannot currently be connected.

Codex CLI config.toml Complete Guide (2026)

Q: Where is config.toml on Windows?

On Windows the path is %USERPROFILE%\.codex\config.toml, which typically expands to C:\Users\yourname\.codex\config.toml. You can paste %USERPROFILE%\.codex directly into the Windows Explorer address bar to jump there.

Q: I broke config.toml — how do I reset to defaults?

Rename config.toml (e.g. to config.toml.bak) or delete it. Codex will start with its built-in defaults the next time you run it. Your authentication is stored separately in auth.json and won't be affected.

As of 2026: Chat Completions support was removed in February 2026. All providers must now use wire_api = "responses" (Responses API). See the wire_api section for details.

Where is the config file?

Codex automatically loads the config file from these paths at startup:

Platform	Path
macOS / Linux	`~/.codex/config.toml`
Windows	`%USERPROFILE%\.codex\config.toml`

A few things to keep in mind:

The CLI and the IDE extension (e.g. the VS Code Codex extension) share the same configuration layers — a change in this file applies everywhere.
The file is loaded once at startup; after editing it you need to exit and relaunch codex.
Authentication (your OAuth token or API key) is stored separately in ~/.codex/auth.json and is not touched when you edit config.toml.

✓

If the file doesn't exist, Codex starts fine using its built-in defaults — you only need to create it when you want to override something.

The keys you'll change most often

For day-to-day use, most people only need to care about three top-level keys:

Key	Type	Description
`model`	string	The model ID to use, e.g. `"gpt-5.3-codex"`. Must be a model ID supported by the selected provider.
`model_provider`	string	Which provider definition to use. Defaults to `"openai"` (built-in). When using a custom provider you must first define it under `[model_providers.<id>]`.
`model_context_window`	integer	Tells Codex how many context tokens the active model supports. Usually not needed; only set this when connecting a model whose context window differs from the built-in default.

~/.codex/config.toml — minimal config

# specify the model
model = "gpt-5.3-codex"

# use the built-in openai provider (this is the default — can be omitted)
model_provider = "openai"

The built-in provider "openai" uses the Responses API and requires no extra configuration. The built-in provider "oss" is for local models. The IDs openai, ollama, and lmstudio are reserved and cannot be overridden by a custom provider definition.

→

Not sure which model to pick? See the Codex CLI model selection guide — full comparison of o4-mini vs GPT-4.1 vs o3 with task-specific recommendations.

Custom model providers [model_providers]

When you need to connect a non-built-in endpoint — for example a company-internal model gateway or an inference service other than Ollama — you define a provider under [model_providers.<custom-id>]. Each provider block supports the following fields:

Field	Description
`base_url`	The root URL of the API endpoint (required for most setups).
`env_key`	The name of an environment variable. Codex reads that variable at runtime and sends its value as a Bearer token. The secret never lives in the config file.
`wire_api`	The wire protocol. As of 2026, only `"responses"` (Responses API) is supported.

~/.codex/config.toml — custom provider example

# top level: which model + which provider
model          = "gpt-5.3-codex"
model_provider = "myrelay"

# custom provider definition
[model_providers.myrelay]
base_url = "https://your-relay.example.com/v1"
env_key  = "MYRELAY_API_KEY"
wire_api = "responses"

Before launching Codex, export the corresponding environment variable in your shell:

terminal — set the API key environment variable

export MYRELAY_API_KEY="sk-..."
$ codex

Do not paste the API key value directly into config.toml. The env_key field holds only the variable name; the actual secret is passed in through the environment to keep it out of version control.

Connecting a third-party API (example)

To route Codex through a relay service or a compatible third-party endpoint, follow these steps:

Define a custom provider in config.toml: set base_url to the relay endpoint and env_key to the environment variable name that holds the API key for that service.
Set the top-level model_provider to your custom provider ID.
Before launching, export the corresponding environment variable in your terminal.

~/.codex/config.toml — third-party API example

model          = "gpt-5.3-codex"
model_provider = "myrelay"

[model_providers.myrelay]
base_url = "https://your-relay.example.com/v1"
env_key  = "MYRELAY_API_KEY"
wire_api = "responses"

Authentication details depend on the specific provider. The example above uses the most common approach — a Bearer token supplied via an environment variable (env_key). If your endpoint requires a different authentication method, consult that service's documentation.

wire_api and the 2026 change

wire_api controls which API protocol Codex uses when talking to a provider. As of February 2026, an important breaking change landed:

Chat Completions support has been removed. Previously Codex supported both wire_api = "chat" (Chat Completions) and wire_api = "responses" (Responses API). The "chat" option was fully removed in February 2026.

All providers — including the built-in openai and oss providers, as well as any custom third-party or local-model provider — must now use wire_api = "responses".

If your config or a third-party endpoint still uses the old "chat" protocol, Codex will error immediately after the upgrade. To fix it:

Change every wire_api = "chat" to wire_api = "responses".
Confirm that your third-party endpoint supports the Responses API; endpoints that don't cannot be connected at this time.

A complete annotated config.toml

The example below covers the most common day-to-day scenarios. Take what you need and remove or comment out the rest.

~/.codex/config.toml — full annotated example

# ============================================================
# Codex CLI — config.toml full example (as of 2026)
# macOS / Linux: ~/.codex/config.toml
# Windows:       %USERPROFILE%\.codex\config.toml
# ============================================================

# The model ID to use
model = "gpt-5.3-codex"

# Which provider definition to use (default is "openai" — can be omitted)
model_provider = "openai"

# Optional: manually set the context window size (in tokens).
# Usually not needed; only set this when connecting a model whose
# context window differs from the built-in assumption.
# model_context_window = 128000

# ============================================================
# Custom provider example: relay / third-party API
# How to use:
#   1. Fill in base_url and the env-var name that holds your key
#   2. Change model_provider above to "myrelay"
#   3. Before launching: export MYRELAY_API_KEY="sk-..."
# ============================================================

[model_providers.myrelay]
base_url = "https://your-relay.example.com/v1"
env_key  = "MYRELAY_API_KEY"
# wire_api: as of 2026, only "responses" is supported.
# "chat" (Chat Completions) was removed in February 2026.
wire_api = "responses"

Approval policy: permission settings in config.toml

Beyond using /permissions to adjust permissions mid-session, you can set a default approval policy in config.toml so every new session starts with your preferred mode.

~/.codex/config.toml — approval policy

# Approval policy: when does Codex ask you before acting?
# "auto"            — fully automatic within sandbox limits (default)
# "untrusted-only"  — only asks for untrusted operations (recommended middle ground)
# "manual"          — every step needs confirmation, safest but slowest
approval_policy = "untrusted-only"

# Sandbox mode: what is Codex technically allowed to do?
# "workspace-write" — default, read/write within working directory only
# "read-only"       — read-only, no file modifications
# "danger-full-access" — no restrictions (use with caution!)
sandbox = "workspace-write"

Recommended config: approval_policy = "untrusted-only" + sandbox = "workspace-write". This lets Codex read and write files silently for routine work, but still asks before network requests, global package installs, or other "untrusted" operations. A good balance between speed and safety.

Project-level config: different settings per project

config.toml supports project-level overrides: create a .codex/config.toml inside any project directory. When Codex runs there, it merges both files — project-level fields override global fields with the same name.

Project structure example

~/
├── .codex/
│   └── config.toml       # Global default: model = "o4-mini"
└── my-project/
    ├── .codex/
    │   └── config.toml   # Project override: model = "gpt-4.1-mini" (saves cost)
    └── src/

my-project/.codex/config.toml

# This project has simple tasks — use the cheaper model
model = "gpt-4.1-mini"
approval_policy = "auto"   # Fully automatic for routine maintenance

Practical use cases:

Routine maintenance projects: gpt-4.1-mini + auto — fast and cheap
Active feature development: o4-mini + untrusted-only — quality and safety balanced
Security review projects: any model + read-only — analysis only, no code changes

✓

When committing a project-level config.toml to Git, consider adding it to .gitignore — it may contain test API keys or personal preferences that shouldn't be shared. For team-wide rules, use AGENTS.md instead.

FAQ

I changed the model but it has no effect — why?

config.toml is read once at startup. After editing the file, fully exit your session (Ctrl+C) and rerun codex for the new model to take effect.

To switch models without restarting, use the /model slash command inside a running session — that change won't be written back to config.toml.

My third-party API throws a wire_api error — how do I fix it?

Since February 2026, wire_api = "chat" is no longer accepted. Find every [model_providers.<id>] block in your config and change wire_api = "chat" to wire_api = "responses".

If your third-party endpoint doesn't support the Responses API yet, you'll need to wait for that service to update before you can connect it.

Where exactly is the file on Windows?

The path is %USERPROFILE%\.codex\config.toml, which typically expands to C:\Users\yourname\.codex\config.toml. You can paste %USERPROFILE%\.codex directly into the Windows Explorer address bar to open the folder.

I broke config.toml — how do I reset to defaults?

Rename the file (e.g. to config.toml.bak) or delete it. Codex will start with its built-in defaults the next time you launch it — the equivalent of a factory reset.

Your authentication is stored separately in auth.json and won't be affected, so you won't be logged out.

Codex CLI config.toml — Complete Guide

Where is the config file?

The keys you'll change most often

Custom model providers [model_providers]

Connecting a third-party API (example)

wire_api and the 2026 change

A complete annotated config.toml

Approval policy: permission settings in config.toml

Project-level config: different settings per project

FAQ