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.jsonand 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. |
# 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.
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. |
# 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:
export MYRELAY_API_KEY="sk-..."
$ codexDo 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_urlto the relay endpoint andenv_keyto the environment variable name that holds the API key for that service. - Set the top-level
model_providerto your custom provider ID. - Before launching,
exportthe corresponding environment variable in your terminal.
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"towire_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 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"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.