Errores comunes al usar Codex con modelos locales en Ollama: orden de diagnóstico y soluciones

Cuando Codex falla al usar un modelo local con Ollama, el error parece de Codex. Muchas veces la causa es más simple: Ollama no está activo, el nombre del modelo no coincide, Codex sigue usando un proveedor en la nube, localhost apunta al entorno equivocado o el modelo local no puede con la tarea.

Lo mejor es depurar por capas: primero Ollama, luego la conexión HTTP, después el provider de Codex y finalmente la capacidad del modelo.

Confirma primero la forma correcta de conexión

La ruta típica tiene tres partes:

Ollama ejecuta el modelo local.
Codex se conecta a Ollama como provider local.
Codex envía la tarea de programación a ese modelo.

Prueba primero Ollama:

1
2
3


ollama serve
ollama pull qwen2.5-coder:7b
ollama run qwen2.5-coder:7b

Después inicia Codex con las opciones compatibles con tu versión:

1

codex --oss --local-provider ollama

Si esas opciones no existen, revisa la ayuda local:

1
2


codex --help
codex --version

Orden mínimo de diagnóstico

1
2
3
4
5
6


ollama --version
ollama list
ollama run qwen2.5-coder:7b
curl http://localhost:11434/api/tags
codex --version
codex --help

Si falla ollama run, arregla Ollama. Si falla curl, arregla el servicio o la red. Si Codex no muestra opciones de provider local, actualiza Codex o usa el método de configuración que soporte tu versión.

Error: no se encuentra el comando ollama

Ollama no está instalado o no está en PATH.

En Windows:

1
2


where.exe ollama
ollama --version

Si sigue sin aparecer después de instalarlo, abre una nueva ventana de PowerShell o reinicia Windows.

Error: el servicio de Ollama no está iniciado

Comprueba el API local:

1

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

Si no responde:

1

ollama serve

En Windows, la app de escritorio de Ollama puede gestionar el servicio. Evita levantar dos instancias que compitan entre sí.

Error: model not found

El nombre del modelo debe coincidir exactamente.

1
2
3


ollama list
ollama pull qwen2.5-coder:7b
ollama run qwen2.5-coder:7b

No adivines el tag. qwen2.5-coder y qwen2.5-coder:7b pueden no significar lo mismo en tu máquina.

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: localhost apunta al lugar equivocado

Es común al mezclar WSL, Docker, terminales remotas y apps de Windows.

Prueba desde el mismo entorno donde corre Codex:

1

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

Si funciona en Windows PowerShell pero no en WSL, el problema es de red, no del modelo.

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: context length exceeded

Codex puede enviar archivos, diffs, logs e instrucciones. Un modelo local con poco contexto se queda corto rápido.

Reduce la tarea:

pide revisar un solo archivo;
elimina logs grandes;
divide el trabajo;
usa un modelo con más contexto;
evita enviar todo el repositorio.

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.

Problemas comunes en Windows

1
2
3


where.exe ollama
where.exe codex
$PSVersionTable.PSVersion

No pegues comandos Bash directamente:

1

export OLLAMA_HOST=...

En PowerShell:

1

$env:OLLAMA_HOST = 'http://localhost:11434'

Si la ruta tiene espacios o caracteres no ASCII, usa comillas y -LiteralPath con cmdlets de PowerShell.

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:

FAQ

¿Codex queda totalmente offline al usar Ollama?

No necesariamente. Depende del provider, del modo de Codex y de otros servicios activos.

¿Puedo configurar Ollama como OpenAI API base_url?

Depende de la herramienta. Usa el modo que soporte tu versión de Codex.

¿Los modelos locales sirven para todas las tareas de Codex?

No. Son útiles para privacidad, coste y tareas pequeñas; los flujos largos con herramientas pueden necesitar modelos más fuertes.

¿Por qué el modelo responde bien en Ollama y mal en Codex?

Conversar es más fácil que programar con herramientas, archivos y comandos.

¿Necesito una OpenAI API key?

Para Ollama local puro, normalmente no. Para cloud, fallback o configuraciones mixtas, sí.

¿Hay que reiniciar Codex al cambiar de modelo?

Es recomendable para evitar estado antiguo de provider o modelo.

Resumen

La mayoría de errores de Codex con Ollama vienen del servicio, el nombre del modelo, el provider, la red o los límites del modelo local. Revisa capa por capa: Ollama, localhost, provider de Codex y capacidad del modelo.