Errores comunes al conectar Codex con modelos locales de Ollama: tutorial, diagnóstico y FAQ

Cuando Codex puede usar modelos locales, muchos desarrolladores quieren mover tareas sencillas a Ollama para ahorrar cuota y mantener parte del trabajo en local. Pero al configurarlo aparecen fallos pequeños: Ollama funciona, el modelo está descargado, pero Codex no conecta o la salida es pobre.

La forma más segura de depurar es: primero hacer funcionar Ollama, luego probar su API y después ajustar Codex.

Para qué sirve un modelo local

Es útil para explicar fragmentos pequeños, redactar scripts, editar README, revisar configuración y procesar texto privado de bajo riesgo. No sustituye necesariamente a modelos cloud potentes en refactors grandes, razonamiento profundo de repositorio, cambios sensibles o ejecución autónoma larga.

Paso 1: comprobar Ollama

1

ollama --version

Descarga un modelo para código:

1

ollama pull qwen2.5-coder:7b

Ejecútalo:

1

ollama run qwen2.5-coder:7b

Si esto falla, el problema aún no está en Codex.

Paso 2: probar la API de Ollama

La dirección habitual es:

1

http://localhost:11434

1

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

En PowerShell:

1

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

Si no ves la lista de modelos, Codex tampoco podrá llamar al servicio.

Paso 3: configurar Codex

Comprueba:

base_url apunta a Ollama.
El nombre del modelo coincide exactamente con ollama list.
El modo de API es el correcto: nativo de Ollama u OpenAI compatible.

Los fallos suelen ser un puerto incorrecto, un tag distinto o un localhost que apunta al entorno equivocado.

Prueba mínima

Empieza con una tarea de solo lectura:

1

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

1

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

connection refused

1
2
3


connection refused
failed to connect
ECONNREFUSED 127.0.0.1:11434

Posibles causas:

Ollama no está iniciado.
El puerto no es 11434.
Codex se ejecuta en WSL, contenedor o entorno remoto.
Proxy o firewall bloquea la conexión.

Prueba desde el mismo entorno donde corre Codex:

1

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

Si Codex está en WSL y Ollama en Windows, usa la IP del host Windows.

model not found

1
2
3


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

1

ollama list

Si el nombre es qwen2.5-coder:7b, usa exactamente ese nombre.

1

qwen2.5-coder:7b

1

ollama pull qwen2.5-coder:7b

404 o ruta equivocada

Ollama tiene endpoints nativos y compatibles con OpenAI:

1
2
3
4
5


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

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

Si Codex espera OpenAI compatible, normalmente usa:

1

http://localhost:11434/v1

No:

1

http://localhost:11434/api

context length exceeded

1
2
3


context length exceeded
prompt is too long
input exceeds context window

Reduce archivos, recorta logs y pasa solo fragmentos relevantes. Para refactors grandes, usa el modelo local como apoyo, no como responsable principal.

Mala calidad de salida

Las causas habituales son modelo pequeño, modelo no orientado a código, tarea demasiado abierta, sampling agresivo o demasiado contexto irrelevante.

Mejor:

1

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

Peor:

1

Optimize the whole project.

Respuestas lentas

Dependen del tamaño del modelo, CPU/GPU, memoria y longitud del contexto. Empieza con 7B antes de subir a 14B o 32B.

1

ollama pull qwen2.5-coder:7b

Windows y WSL

Si Ollama corre en Windows y Codex en WSL, localhost dentro de WSL puede apuntar al propio WSL.

1

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

Si falla:

1

cat /etc/resolv.conf

Prueba la IP del nameserver:

1

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

Variables de proxy

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

Añade:

1

localhost,127.0.0.1

Cuándo no conviene usar Ollama con Codex

Evita usarlo en rutas críticas de producción, cambios de arquitectura en muchos archivos, tareas largas autónomas, proyectos con pocas pruebas o tareas que el modelo ya ha malinterpretado.

Plantilla de tarea

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.

Para modificar:

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

¿Puede funcionar totalmente offline?

Sí, si Codex, el modelo y las herramientas se ejecutan localmente y no se llama a proveedores cloud. Verifícalo con firewall o monitorización de red si importa.

¿Qué modelo conviene probar primero?

Para código, qwen2.5-coder:7b o qwen2.5-coder:14b.

¿Por qué un modelo cloud resuelve algo que el local no?

Porque el tamaño, datos, contexto y adaptación a herramientas son distintos. Reduce el alcance.

¿Puedo pasarle todo el repositorio?

No al principio. Empieza por archivo, función o error.

¿Ollama debe estar siempre abierto?

Sí. Si el servicio se cierra, Codex verá errores de conexión.

Resumen

Revisa en orden: proceso de Ollama, API HTTP, base URL de Codex, modo de interfaz, nombre de modelo, contexto y alcance de la tarea. Los modelos locales funcionan mejor con tareas pequeñas, claras y de bajo riesgo.