oss_provider

oss_provider is the default local backend Codex uses when you launch with the --oss flag and don’t spell out a provider on the command line. It only understands two values, and it does nothing on its own. It’s the answer to the “which local runner?” question that --oss would otherwise ask you interactively.

Values

Value	Backend	Notes
ollama	Ollama	Talks to the local daemon at http://localhost:11434/v1
lmstudio	LM Studio	The other reserved built-in runner
(unset)	none	Default. Codex prompts you to pick on every --oss run

The docs describe it as the “Default local provider used when running with --oss (defaults to prompting if unset)” (config reference). Both ollama and lmstudio are reserved built-in provider IDs, so you don’t have to hand-write a [model_providers.<id>] block for them. The built-in knows its own base URL.

# ~/.codex/config.toml
oss_provider = "ollama"       # or "lmstudio"; unset = Codex asks every time

# gpt-oss needs a real window and the local backend won't report one,
# so set it by hand. At least 64k is the documented floor.
model_context_window = 65536

Run codex --oss after that and it goes straight to your local runner (default model gpt-oss:20b) instead of stopping to ask.

When to change it

• You run local models through one backend day to day and you’re tired of answering the picker on every --oss launch.
• You’re scripting or running codex --oss in CI, where an interactive prompt would just hang.
• Your team standardized on LM Studio (or Ollama) and you want the config to match without anyone passing flags.

Gotchas

• It only fires on --oss. If you set model_provider to a custom or cloud provider instead, oss_provider sits there doing nothing. The two are separate paths.
• Two legal values, full stop. lmstudio and ollama are it; there’s no mlx value here even though MLX shows up in local-model guides.
• It does not set your context window. Ollama defaults to a small window, and Codex wants at least 64k tokens, so you have to set model_context_window yourself or the model quietly truncates (Ollama docs). This is the single most common way a local setup “works but forgets everything.”
• Wiring up non-OpenAI providers has been a rough edge for a while (see the 32-comment thread on issue #987). That report predates the move to config.toml, so ignore its JSON snippets, but the demand is real.

Related settings

• model_provider: the general provider selector. oss_provider is the --oss-only shortcut to the local ones.
• model_context_window: the one you almost always have to set alongside this for a local model.
• model: pick which local model runs (e.g. gpt-oss:120b) instead of the gpt-oss:20b default.