Common Errors When Connecting Codex to Ollama Local Models: Tutorial, Troubleshooting, and FAQ

Once Codex can use local models, many developers want to route low-risk coding tasks to Ollama. It can save quota and keep some private work on local hardware. The first setup, however, often fails in small but confusing ways: Ollama runs, the model exists, yet Codex cannot connect or the output quality is disappointing.

This guide follows a simple path: make Ollama work first, connect Codex next, then troubleshoot by error type.

What local models are good for

Ollama-backed local models are useful for small code explanations, script drafts, README edits, configuration notes, and low-risk private text. They are not a perfect replacement for stronger cloud models when the task requires large refactors, deep repository reasoning, security-sensitive edits, or long autonomous execution.

Step 1: make sure Ollama works

Check the version:

1

ollama --version

Pull a coding model:

1

ollama pull qwen2.5-coder:7b

Run it once:

1

ollama run qwen2.5-coder:7b

If this fails, fix Ollama, model download, GPU/CPU resources, or network access before changing Codex.

Step 2: test the Ollama API

The default API address is usually:

1

http://localhost:11434

Test it with:

1

curl http://localhost:11434/api/tags

On Windows PowerShell:

1

Invoke-RestMethod http://localhost:11434/api/tags

If this fails, Codex will not be able to call the model either.

Step 3: configure Codex

The exact configuration depends on the Codex version, but you usually need to confirm three things:

The base_url points to the Ollama service.
The model name matches ollama list exactly.
The interface mode matches either Ollama native API or OpenAI-compatible API.

Small mistakes such as a missing port, a wrong model tag, or a WSL localhost mismatch are more common than model failures.

Minimal test prompt

Start with a read-only request:

1

Please explain the main purpose of README.md in this directory. Do not modify files.

Or:

1

Please inspect this function and list possible edge cases. Do not edit the code.

Do not start with a repository-wide refactor.

Error: connection refused

Typical messages:

1
2
3


connection refused
failed to connect
ECONNREFUSED 127.0.0.1:11434

Common causes:

Ollama is not running.
The port is not 11434.
Codex runs in WSL, a container, or a remote environment that cannot reach the host localhost.
A proxy or firewall blocks the local request.

Check from the same environment where Codex runs:

1

curl http://localhost:11434/api/tags

If Codex runs in WSL while Ollama runs on Windows, try the Windows host IP instead of localhost.

Error: model not found

Typical messages:

1
2
3


model not found
unknown model
pull model manifest: file does not exist

List local models:

1

ollama list

If the model is qwen2.5-coder:7b, configure exactly that. qwen2.5-coder, qwen-coder, or a different tag may fail.

1

qwen2.5-coder:7b

1

ollama pull qwen2.5-coder:7b

Error: 404 or wrong path

Ollama has native endpoints and OpenAI-compatible endpoints:

1
2
3
4
5


Ollama native:
http://localhost:11434/api/chat

OpenAI compatible:
http://localhost:11434/v1/chat/completions

If Codex expects an OpenAI-compatible provider, the base URL is often:

1

http://localhost:11434/v1

not:

1

http://localhost:11434/api

When you see 404, check the interface mode first.

Error: context length exceeded

Typical messages:

1
2
3


context length exceeded
prompt is too long
input exceeds context window

Local models often have tighter context budgets. Reduce the file scope, ask Codex to inspect only relevant files, trim logs, or switch to a model with a larger context window. For large refactors, use the local model for auxiliary analysis rather than the final edit.

Poor output quality

If the model connects but produces weak answers, the usual reasons are: the model is too small, it is not code-focused, the prompt is too broad, sampling is too aggressive, or Codex has too much irrelevant context.

Prefer narrow tasks:

1

Only read src/api/user.ts. Find possible null-handling issues. Do not modify files; list findings only.

This is much better than:

1

Optimize the whole project.

Slow responses

Speed depends on model size, CPU/GPU use, memory, and context length. Start with 7B before trying 14B or 32B. For Codex, stable and controllable responses are often more useful than the largest possible model.

1

ollama pull qwen2.5-coder:7b

Windows and WSL localhost issues

If Ollama runs on Windows and Codex runs in WSL, localhost inside WSL may refer to WSL itself. Test:

1

curl http://localhost:11434/api/tags

If it fails, inspect:

1

cat /etc/resolv.conf

Try the nameserver address as the Windows host:

1

curl http://<windows-host-ip>:11434/api/tags

Also ensure Ollama accepts non-localhost access if needed.

Proxy variables

Proxy settings can accidentally route local requests away from localhost.

1
2
3


echo $HTTP_PROXY
echo $HTTPS_PROXY
echo $NO_PROXY

PowerShell:

1
2
3


$env:HTTP_PROXY
$env:HTTPS_PROXY
$env:NO_PROXY

Add local addresses to NO_PROXY:

1

localhost,127.0.0.1

Include host IPs if WSL or LAN access is involved.

When not to use Ollama with Codex

Avoid local models for production-critical edits, large multi-file architecture changes, long autonomous tasks, weakly tested projects, or cases where the model already misunderstands the task. A practical split is: local model for drafts and simple checks, stronger cloud model for complex reasoning and final modifications.

Recommended task template

1
2
3
4
5
6


Please only inspect src/auth/session.ts.
Goal: find edge cases that may cause session loss.
Requirements:
1. Do not modify files.
2. Output only a list of issues.
3. For each issue, include trigger conditions and a suggested verification method.

For edits:

1
2
3
4
5
6


Please only modify src/utils/format.ts.
Goal: handle empty string and null.
Requirements:
1. Do not change function signatures.
2. Keep existing exports.
3. After editing, state which test should run.

FAQ

Can Codex with Ollama work fully offline?

Inference can be local if Codex, the model, and tools all run locally and no cloud provider is called. Verify with network monitoring or firewall rules if this matters.

Which model should I start with?

For code tasks, try qwen2.5-coder:7b or qwen2.5-coder:14b. Start small and move up only if the machine can handle it.

Why can a cloud model solve a task that the local model cannot?

The model size, training data, context window, and tool adaptation are different. Use narrower tasks and fewer files.

Can I give the whole repository to the local model?

Not at first. Start with a file, function, or error. Let Codex search first and pass only relevant snippets.

Does Ollama need to stay running?

Yes. If the service is closed, Codex will see connection errors or timeouts.

Do I still need an API key?

Usually not for local Ollama calls. But if other providers remain configured, check the actual routing.

Summary

Troubleshoot in order: Ollama process, HTTP API, Codex base URL, interface mode, model name, context length, and task scope. Local models are best for small, bounded work. They can be a low-cost assistant for Codex, but broad refactors and long autonomous tasks still need stronger models or tighter human control.