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.

1. 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

2. 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.

3. 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

4. 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.

5. 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

6. 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