Herramientas de IA

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

Guía práctica para conectar Codex con modelos locales de Ollama, con configuración, errores de conexión, nombres de modelos, límites de contexto, calidad de salida, Windows/WSL 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.

O:

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.

Error: Codex no está usando Ollama

Si Codex sigue pidiendo login o API key, probablemente no está en modo local provider.

1

codex --help

Busca opciones relacionadas con local provider, OSS mode u Ollama. Revisa también la configuración global, la del proyecto y las variables de entorno.

Error: unknown option

El tutorial puede estar escrito para otra versión de Codex.

1
2

codex --version
codex --help

Usa la ayuda de tu instalación como referencia. Actualiza Codex si hace falta.

Error: 401, API key o autenticación

Ollama local normalmente no requiere una clave de OpenAI. Si ves errores de API key, Codex puede seguir usando un provider en la nube.

1
2

$env:OPENAI_API_KEY
$env:OPENAI_BASE_URL

Para una ejecución local pura, limpia variables y configuración que apunten a otro provider.

Error: la solicitud se queda colgada

Los modelos locales pueden ser lentos, sobre todo en CPU, con modelos grandes o prompts largos.

Empieza con un modelo pequeño y una tarea mínima. Si una pregunta corta ya tarda en ollama run, también tardará dentro de Codex.

Error: llamadas a herramientas inestables

Muchos modelos locales escriben código, pero no siempre siguen bien un flujo agentic con herramientas. Pueden inventar comandos, ignorar salidas o romper JSON.

Úsalos para cambios pequeños, explicación, refactor sencillo y documentación. Para revisiones complejas, seguridad o depuración larga, conviene un modelo más fuerte.

Flujo estable recomendado 

1
2
3
4
5

ollama pull qwen2.5-coder:7b
ollama run qwen2.5-coder:7b
curl http://localhost:11434/api/tags
codex --help
codex --oss --local-provider ollama

Prueba con una tarea pequeña:

1

Read this single file and suggest one safe refactor. Do not edit yet.

Luego amplía a ediciones, pruebas y tareas más largas.

Plantilla para pedir ayuda 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

OS:
PowerShell or shell version:
Codex version:
Ollama version:
Model name:
Command used:
Exact error:
Does ollama run work:
Does curl http://localhost:11434/api/tags work:
Are you using WSL, Docker, or remote SSH:

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.