# Codex model providers and config.toml, explained Authors: AutoRouter Published: 2026-10-23T02:20:01.306Z Reading time: 7 min Canonical: https://autorouter.com/blog/codex-model-providers Publisher: AutoRouter, the Mac app for Codex and Claude Code (https://autorouter.com) > Codex picks its model from the model key and its endpoint from the model_provider key in ~/.codex/config.toml, and each custom provider is a [model_providers.] table with a base URL, an environment variable for its API key and the Responses wire API. Profiles are separate files loaded with --profile, -c overrides one key for one run, and --oss runs a local Ollama or LM Studio model. Enabling AutoRouter, the Mac app for Codex and Claude Code, adds it to config.toml after saving a copy of the file, and disabling it switches Codex back. 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.]` 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](https://learn.chatgpt.com/docs/config-file/config-reference)). [AutoRouter, the Mac app for Codex and Claude Code](https://autorouter.com), 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](https://learn.chatgpt.com/docs/config-file/config-advanced#config-and-state-locations)). OpenAI's [Models page](https://learn.chatgpt.com/docs/models) 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](https://learn.chatgpt.com/docs/whats-new)). When the same key is set in more than one place, Codex uses this order, highest first ([Config basics](https://learn.chatgpt.com/docs/config-file/config-basic#configuration-precedence)): 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](https://learn.chatgpt.com/docs/config-file/config-reference#configtoml)). ## Which config.toml keys control the model and provider? The keys below cover most provider setups. Descriptions follow OpenAI's [Configuration Reference](https://learn.chatgpt.com/docs/config-file/config-reference) as of October 22, 2026; the fields from `name` down sit inside a `[model_providers.]` table. | Key | What it does | Default | | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------- | | `model` | The model to use, for example `gpt-6.1-sol` | A recommended model | | `model_provider` | Provider id from `model_providers` | `openai` | | `openai_base_url` | Base URL override for the built-in `openai` provider | Not set | | `[model_providers.]` | A custom provider definition; `openai`, `ollama` and `lmstudio` are reserved ids | Not set | | `name` | Display name for the provider | Not set | | `base_url` | API base URL for the provider | Not set | | `env_key` | Environment variable that supplies the provider's API key | Not set | | `wire_api` | Protocol the provider uses; `responses` is the only supported value | `responses` | | `http_headers`, `env_http_headers`, `query_params` | Static headers, headers filled from environment variables, and extra query parameters on each request | Not set | | `request_max_retries`, `stream_max_retries`, `stream_idle_timeout_ms` | HTTP retries, streaming retries and the stream idle timeout | 4, 5 and 300000 ms | | `[model_providers..auth]` | A command that prints a bearer token, for providers that need one fetched | Not set | | `oss_provider` | Default local provider for `--oss`: `ollama` or `lmstudio` | Codex asks | ## How do you add a custom model provider to Codex? Add a `[model_providers.]` 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](https://learn.chatgpt.com/docs/config-file/config-advanced#custom-model-providers)): ```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..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](/blog/try-new-models-in-codex-and-claude-code). 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/.config.toml`, that Codex layers over `config.toml` when you run `codex --profile ` ([Advanced Configuration](https://learn.chatgpt.com/docs/config-file/config-advanced#profiles)). 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.]` tables from `config.toml`, and the top-level `profile = ""` 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](https://docs.ollama.com/integrations/codex)). 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](https://learn.chatgpt.com/docs/developer-commands?surface=cli)). `-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](https://learn.chatgpt.com/docs/config-file/config-advanced#one-off-overrides-from-the-cli)): ```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](https://learn.chatgpt.com/docs/config-file/config-advanced#oss-mode-local-providers)). 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](https://docs.ollama.com/integrations/codex)). ## 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](https://autorouter.com/setup.md) 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](/blog/how-autorouter-picks-a-model) 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](https://autorouter.com/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.]` tables or the `profile = ""` selector. Move the table's keys to the top level of `~/.codex/.config.toml`, delete the old table and selector from `config.toml`, and run `codex --profile `. ### 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..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](/blog/claude-code-model-settings) covers that app's own model options. ## Sources - [OpenAI: Config basics](https://learn.chatgpt.com/docs/config-file/config-basic) - [OpenAI: Advanced Configuration](https://learn.chatgpt.com/docs/config-file/config-advanced) - [OpenAI: Configuration Reference](https://learn.chatgpt.com/docs/config-file/config-reference) - [OpenAI: Developer commands, CLI](https://learn.chatgpt.com/docs/developer-commands?surface=cli) - [OpenAI: Models](https://learn.chatgpt.com/docs/models) - [OpenAI: What's new](https://learn.chatgpt.com/docs/whats-new) - [Ollama: Codex CLI](https://docs.ollama.com/integrations/codex) - [AutoRouter](https://autorouter.com) - [AutoRouter agent setup guide](https://autorouter.com/setup.md) - [AutoRouter privacy](https://autorouter.com/privacy) ## Read next - [Which model to use for which coding task](https://autorouter.com/blog/which-model-for-which-task.md): Use a frontier model such as Claude Opus 5.5 or GPT-6 Astra for multi-file refactors, hard bugs and UI built from a design. Use a strong model such as Claude Sonnet 5.5 or GPT-6.1 Sol for tests and code review, and a fast model such as Claude Haiku 5.5 or GPT-6 Luna for renames, commit messages and one-line shell commands. AutoRouter, the Mac app for Codex and Claude Code, makes that choice on every turn. - [Try a new model in Codex or Claude Code without another API key](https://autorouter.com/blog/try-new-models-in-codex-and-claude-code.md): Every manual way to try a new model in Codex or Claude Code needs an API key: one per provider, or one gateway key such as OpenRouter's. Claude Code reaches another provider through environment variables, and Codex through a custom provider in config.toml. AutoRouter, the Mac app for Codex and Claude Code, adds 20+ models to both apps' model pickers with no keys or endpoints to set up, and new models show up there right away. - [Every way to choose a model in Claude Code](https://autorouter.com/blog/claude-code-model-settings.md): Claude Code takes its model from, in order of priority, the /model command, the --model flag, the ANTHROPIC_MODEL environment variable, the model key in settings.json and the ANTHROPIC_DEFAULT_MODEL variable. Aliases such as opus, sonnet, haiku, fable and opusplan stand for the current model in each family, and subagents take their model from their own model field, CLAUDE_CODE_SUBAGENT_MODEL or the main session. AutoRouter, the Mac app for Codex and Claude Code, adds one more choice to /model that picks a model for each turn while it is selected. Tags: [Codex](https://autorouter.com/blog/tags/codex.md), [Guides](https://autorouter.com/blog/tags/guides.md), [Models](https://autorouter.com/blog/tags/models.md) Drafted with AI from the sources linked above, then checked and edited by the AutoRouter team.