How to troubleshoot local models in Codex

Local model failures in Codex usually come from a provider mismatch, a missing model identifier, or a local server that is running in the wrong mode. A short diagnostic sequence isolates the failing layer before the prompt run is retried.

The Codex CLI uses --oss to route a run to a local provider, while --local-provider selects Ollama or LM Studio and -m must match the exact model ID exposed by that provider. The fastest check is to query the provider's OpenAI-compatible endpoint and then run a one-line codex exec probe against the same provider and model.

Current Codex local-model runs depend on the provider exposing the modern /v1/responses API as well as a model list, so older compatibility layers or stale local-server builds can fail even when a model appears loaded. Wrong-provider errors and missing-model errors usually read clearly, and reusing the same minimal prompt for every test keeps the diagnosis specific.

Steps to troubleshoot local models in Codex:

Determine which local provider should answer the prompt before testing anything else.

Ollama normally listens on http://localhost:11434 and LM Studio normally listens on http://localhost:1234. Keep --local-provider aligned with the server that is actually running.

Related: How to use Ollama models with Codex
Related: How to use LM Studio models with Codex
Query the selected provider's model list and copy the exact model ID that Codex must use.
```
$ curl -s http://localhost:11434/v1/models
{"object":"list","data":[{"id":"gpt-oss:20b","object":"model","created":1765244842,"owned_by":"library"}]}
```
For LM Studio, replace port 11434 with 1234 and use the returned id value in the next step.
Run a minimal Codex probe against the same provider and model ID.
```
$ codex exec --oss --local-provider ollama -m gpt-oss:20b "Return OK."
OK
```
If this succeeds, local model routing is working and the original failure is usually caused by the prompt, the workspace trust boundary, or a later tool call rather than the provider connection itself.

Related: How to fix Codex trusted directory error

Post the same model directly to the provider's /v1/responses endpoint when the Codex probe still fails.

$ curl -s -X POST http://localhost:11434/v1/responses \
-H "Content-Type: application/json" \
-d '{"model":"gpt-oss:20b","input":"Return OK."}'
{"id":"resp_968540","object":"response","status":"completed","model":"gpt-oss:20b"
##### snipped #####
"output":[{"type":"message","status":"completed","role":"assistant","content":[{"type":"output_text","text":"OK"}]}]}

If the direct /v1/responses call works but codex exec does not, the remaining fault is usually the selected provider, a Codex option, or the working directory context rather than the local model server.

Read the first error literally before changing providers, models, or config.
```
$ codex exec --oss --local-provider ollama -m missing-model "Return OK."
Pulling model missing-model...
Error: OSS setup failed: OSS setup failed: Pull failed: pull model manifest: file does not exist
```
Pull failed: pull model manifest: file does not exist means the value passed with -m is not available from the selected provider
LM Studio is not responding means Codex is pointed at LM Studio but nothing is listening on port 1234
Built-in providers are ollama and lmstudio, so do not override them with custom provider definitions
Re-run the same minimal probe after correcting the provider, model ID, or local server issue.
```
$ codex exec --oss --local-provider ollama -m gpt-oss:20b "Return OK."
OK
```