How to troubleshoot local models in Codex

Local model failures in Codex usually trace to the selected provider, the model ID, or the local provider API. A prompt can fail even when the local model app is open if Codex is routed to the wrong backend or asks for a model name that the backend does not expose.

The Codex CLI enters local-provider mode with --oss, selects Ollama or LM Studio with --local-provider, and sends the model value from -m to that provider. The model value must match the identifier returned by the provider, not a display name copied from a download page or another model catalog.

A working local provider should expose a model list and answer the OpenAI-compatible POST /v1/responses endpoint that Codex uses for local runs. If /v1/models works but /v1/responses fails, update the local server before changing Codex configuration; Codex can also reject an Ollama server version that is older than the minimum it expects for local OSS setup.

Steps to troubleshoot local models in Codex:

Identify the provider that should answer the failing prompt.

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

Related: How to use Ollama models with Codex
Related: How to use LM Studio models with Codex

List the models exposed by the selected provider.

$ curl --silent 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 Codex command.

Post the same prompt directly to the provider's /v1/responses endpoint.

$ curl --silent --request POST http://localhost:11434/v1/responses \
--header "Content-Type: application/json" \
--data '{"model":"gpt-oss:20b","input":"Return OK."}'
{"id":"resp_407876","object":"response","status":"completed","model":"gpt-oss:20b"
##### snipped #####
"content":[{"type":"output_text","text":"OK","annotations":[],"logprobs":[]}]}

LM Studio uses port 1234 by default. If the model list works but this request fails, update the provider before changing Codex flags.

Check the Ollama API version when Codex says the server is too old.
```
$ curl --silent http://localhost:11434/api/version
{"version":"0.13.4"}
```
Ollama documents /v1/responses support as added in version 0.13.3, but Codex CLI 0.139.0 rejected 0.13.3 during OSS setup in validation. Use 0.13.4 or newer when this error appears.
Run a minimal Codex probe from the repository that should own the task.
```
$ codex exec --oss --local-provider ollama -m gpt-oss:20b "Return OK."
OK
```
If this returns OK, local model routing works and the original failure is usually in the prompt, workspace trust boundary, or a later tool call rather than the provider connection.

Related: How to fix the Codex trusted-directory error

Match a missing-model error to the model ID layer.

$ 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

Use the exact id from the model list, then pull or load the model in the provider if it is absent.

Match an Ollama server error to the provider layer.

$ codex exec --oss --local-provider ollama -m gpt-oss:20b "Return OK."
Error: OSS setup failed: No running Ollama server detected. Start it with: `ollama serve`.

This error means Codex selected the Ollama route, but no Ollama server answered on the expected local port.

Match an LM Studio server error to the provider layer.

$ codex exec --oss --local-provider lmstudio -m openai/gpt-oss-20b "Return OK."
Error: OSS setup failed: OSS setup failed: LM Studio is not responding. Install from https://lmstudio.ai/download and run 'lms server start'.

This error means Codex selected the LM Studio route, but no server answered on the expected local port.

Re-run the minimal probe after correcting the provider, model ID, or local server.
```
$ codex exec --oss --local-provider ollama -m gpt-oss:20b "Return OK."
OK
```