# Codex model providers and config.toml, explained

AutoRouter · Oct 23, 2026 · 7 min read

Codex decides where each turn goes from two keys in ~/.codex/config.toml: model names the model, and model_provider names the provider, which is OpenAI's built-in openai provider unless you set another. To reach a different endpoint, you add a [model_providers.<id>] table with a name, a base_url, an env_key that names the environment variable holding the API key, and a wire_api, where responses is the only supported value (OpenAI config reference). AutoRouter, the Mac app for Codex and Claude Code, makes this edit for you: enabling it adds AutoRouter to config.toml after saving a copy of the file, and disabling it switches Codex back.

AutoRouter wrote this post. Every key, flag and example below is quoted from OpenAI's Codex configuration docs or, where marked, from Ollama's docs, as checked on October 22, 2026. OpenAI's Codex docs now live on learn.chatgpt.com, and the old developers.openai.com/codex links redirect there.

## Where does Codex read its model and provider settings?

Codex reads your personal settings from ~/.codex/config.toml, or from config.toml in the folder that CODEX_HOME names if you set that variable (OpenAI docs). OpenAI's Models page says "The ChatGPT desktop app, Codex CLI, and IDE extension use the same config.toml". The Codex app merged into the ChatGPT desktop app on July 9, 2026 (What's new).

When the same key is set in more than one place, Codex uses this order, highest first (Config basics):

1. CLI flags and --config overrides
2. Project .codex/config.toml files, where the one closest to your working directory wins (trusted projects only)
3. A profile file selected with --profile
4. Your user config, ~/.codex/config.toml
5. Cloud-managed defaults for your signed-in workspace
6. System config, /etc/codex/config.toml on Unix
7. Built-in defaults

Provider keys skip the project layer. Codex ignores model_provider, model_providers, openai_base_url, profile and profiles when they appear in a project's .codex/config.toml, so provider definitions belong in your user config (Configuration Reference).

## Which config.toml keys control the model and provider?

The keys below cover most provider setups. Descriptions follow OpenAI's Configuration Reference as of October 22, 2026; the fields from name down sit inside a [model_providers.<id>] table.

## How do you add a custom model provider to Codex?

Add a [model_providers.<id>] table to ~/.codex/config.toml, then set model_provider to that id and model to a model the provider serves. This is the first part of OpenAI's own example, which sends requests through a proxy (Advanced Configuration):

```toml
model = "gpt-6.1-sol"
model_provider = "proxy"
[model_providers.proxy]
name = "OpenAI using LLM proxy"
base_url = "http://proxy.example.com"
env_key = "OPENAI_API_KEY"
```

Codex reads the API key from the environment variable that env_key names. The reference also lists experimental_bearer_token for a token written into the file, marked "discouraged; use env_key", and an [model_providers.<id>.auth] table that runs a command to fetch a token, which you shouldn't combine with env_key. Because responses is the only wire_api value, the provider has to accept OpenAI's Responses API. For hosted providers' own Codex blocks and the keys they need, see Try a new model in Codex or Claude Code without another API key.

If you only want OpenAI traffic to pass through a proxy or router, OpenAI's docs say to set openai_base_url "instead of defining a new provider". It changes the base URL of the built-in openai provider. A [model_providers.openai] table won't work, because built-in provider ids can't be overridden.

```toml
openai_base_url = "https://us.api.openai.com/v1"
```

## How do profiles work in Codex now?

A profile is a separate file, ~/.codex/<name>.config.toml, that Codex layers over config.toml when you run codex --profile <name> (Advanced Configuration). The file uses top-level keys and only needs the values that differ from your base config. In Codex 0.134.0 and later, --profile no longer reads [profiles.<name>] tables from config.toml, and the top-level profile = "<name>" selector is gone, so guides that show those tables are out of date.

Ollama's Codex guide uses a profile to keep a local provider apart from your everyday setup (Ollama docs). Its profile file is ~/.codex/ollama-launch.config.toml:

```toml
model = "gpt-oss:120b"
model_provider = "ollama-launch"
model_catalog_json = "/Users/you/.codex/model.json"

[model_providers.ollama-launch]
name = "Ollama"
base_url = "http://localhost:11434/v1/"
wire_api = "responses"
```

Then codex --profile ollama-launch starts Codex with that provider, and plain codex keeps using your base config. Ollama's own ollama launch codex command uses a dedicated Codex profile and refreshes the model catalog for you; --config sets it up without launching, and --restore removes the profile and the generated catalog.

## How do you change the model or provider for one run?

Pass --model (or -m) for the model and -c (or --config) for any other key; both apply to that run only and outrank every config file (Command line options). -c values are parsed as TOML, a value that can't be parsed is treated as a string, and nested keys use dot notation. These are OpenAI's examples (Advanced Configuration):

```bash
codex --model gpt-6.1-sol
codex --config model='"gpt-6.1-sol"'
```

## What does codex --oss do?

--oss runs Codex against a local open-source model provider, Ollama or LM Studio (Advanced Configuration). Choose one for a single run with --local-provider, or set a default in config.toml:

```toml
# Default local provider used with `--oss`
oss_provider = "ollama" # or "lmstudio"
```

With neither set, the interactive CLI asks you to choose, and codex exec exits with an error. Ollama's guide adds the model with -m, as in codex --oss -m gpt-oss:120b, and recommends a context window of at least 64k tokens for Codex (Ollama docs).

## What does AutoRouter change in Codex's config.toml?

Enabling Codex in AutoRouter adds AutoRouter to config.toml after saving a copy of the file, and your other settings stay as they are. Once it is enabled, config.toml points at api.autorouter.com. AutoRouter's agent setup guide confirms the Codex connection with this check:

```sh
grep -q 'api.autorouter.com' "${CODEX_HOME:-$HOME/.codex}/config.toml" && echo "Codex: connected"
```

Disabling Codex in AutoRouter's settings switches it back. You don't write a provider table, export a key or set an endpoint. AutoRouter adds 20+ models to the Codex model menu under the message box, beside the models already there, plus AutoRouter itself, which picks a model for each turn. In Codex, OpenAI models run on your ChatGPT plan.

Choosing a specific model in the menu sends your turns straight to it; AutoRouter routes only while AutoRouter is the model selected. How AutoRouter picks a model for each turn explains the order it follows. AutoRouter runs on macOS 14 or later, is in beta, and sends requests through its servers on their way to each provider (AutoRouter privacy).

## Questions

### Can a project's .codex/config.toml set the model provider?

No. Codex ignores model_provider, model_providers and openai_base_url in a project's .codex/config.toml, so provider definitions go in ~/.codex/config.toml. Project files load only when you trust the project.

### Why did my [profiles.name] table stop working?

Codex 0.134.0 and later no longer reads [profiles.<name>] tables or the profile = "<name>" selector. Move the table's keys to the top level of ~/.codex/<name>.config.toml, delete the old table and selector from config.toml, and run codex --profile <name>.

### Can I point the built-in openai provider at another URL?

Yes. Set openai_base_url, which changes the base URL of the built-in openai provider without a new provider table. You can't define [model_providers.openai], because openai, ollama and lmstudio are reserved ids.

### Where should a custom provider's API key go?

Put it in an environment variable and name that variable in env_key. OpenAI's reference marks experimental_bearer_token, a token written into config.toml, as discouraged. For short-lived tokens, [model_providers.<id>.auth] runs a command that prints one, and Codex refreshes it every 300000 ms unless you change refresh_interval_ms.

### Do I need a model_providers entry to use AutoRouter in Codex?

No. Enabling Codex in AutoRouter adds AutoRouter to config.toml after saving a copy of the file, and its models appear in the Codex model menu with no keys or endpoints to set up. AutoRouter makes the same kind of change to Claude Code's settings.json; Claude Code model settings covers that app's own model options.

## Sources

• - OpenAI: Config basics
• - OpenAI: Advanced Configuration
• - OpenAI: Configuration Reference
• - OpenAI: Developer commands, CLI
• - OpenAI: Models
• - OpenAI: What's new
• - Ollama: Codex CLI
• - AutoRouter
• - AutoRouter agent setup guide
• - AutoRouter privacy