Codex se distribuye con modelos de OpenAI por defecto, pero no te ata a ellos. La CLI tiene un modo OSS incorporado para tiempos de ejecución locales como Ollama y LM Studio, además de un sistema de proveedor personalizado que apunta al agente a cualquier endpoint compatible que definas en un archivo TOML. Esto significa que puedes ejecutar gpt-oss en tu portátil, impulsar Codex con una API de DeepSeek o Qwen alojada, o cambiar entre proveedores por proyecto.
Esta guía detalla toda la configuración: qué hace el modo OSS, las claves de configuración exactas, las recetas por modelo y las compensaciones que aceptas al sustituir los modelos de OpenAI. Todo lo que aquí se presenta proviene de la documentación oficial de configuración avanzada de Codex. Cuando la documentación es ambigua, lo indico en lugar de adivinar.
Una nota antes de empezar. Una vez que tu modelo está funcionando dentro de Codex, el modelo es solo la mitad del flujo de trabajo. La otra mitad es verificar las API que tu agente construye y llama. Ahí es donde Apidog encaja, y cubriremos la combinación cerca del final.
En resumen
El modo OSS de Codex es una característica de la CLI. Ejecuta codex --oss y Codex se comunicará con un servidor local de Ollama o LM Studio en lugar de OpenAI. Establece oss_provider = "ollama" en ~/.codex/config.toml para que sea el valor predeterminado, y pasa -m <model> para elegir qué modelo local se ejecuta. Para modelos de código abierto alojados (DeepSeek, Qwen, GLM a través de sus API), define un bloque [model_providers.<id>] con una base_url y env_key, luego selecciónalo con model_provider. La trampa: la referencia de configuración actual enumera responses como el único valor wire_api compatible, por lo que tu endpoint debe hablar el protocolo de la API de Responses.
Qué es el modo OSS
El modo OSS es el atajo de Codex para ejecutarlo contra servidores de modelos de código abierto locales. La documentación describe dos proveedores locales compatibles:
- Ollama, el popular tiempo de ejecución de modelos local
- LM Studio, la aplicación de escritorio con un servidor local integrado
Lo activas con el flag --oss. De la referencia de comandos de desarrollador de Codex:
--oss: Utiliza un proveedor de modelo de código abierto local. Codex utiliza--local-provider, tuoss_providerconfigurado, o te pide que elijas entre LM Studio y Ollama.
Existe un flag complementario, --local-provider, que acepta lmstudio u ollama y anula tu configuración predeterminada para una única ejecución. Si no estableces un flag ni un valor predeterminado en la configuración, la CLI interactiva te pedirá que elijas. El comando no interactivo codex exec no pide; sale con un error. Por lo tanto, para scripts y CI, siempre establece el proveedor explícitamente.
Una nota de honestidad sobre las interfaces: la documentación cubre el modo OSS y los proveedores personalizados bajo el sistema config.toml de la CLI. La extensión de IDE y la nube de Codex no se mencionan como compatibles con proveedores locales en ninguna parte de la documentación de configuración. [VERIFICAR: si la extensión de IDE de Codex lee model_providers de config.toml de la misma manera que la CLI; la documentación no lo indica de ninguna manera.] Considera esto como un flujo de trabajo de CLI hasta que OpenAI documente lo contrario.
Por qué ejecutar un modelo de código abierto dentro de Codex
Buena pregunta, ya que Codex es el propio agente de OpenAI. Algunas razones reales:
- Control de costes. La inferencia local a través de Ollama no cuesta nada por token. Si estás agotando los límites de uso en sesiones largas del agente, un modelo local se encarga del trabajo pesado mientras guardas las llamadas alojadas para problemas difíciles.
- Privacidad y trabajo en entornos aislados. Algunas bases de código no pueden salir de la máquina. Un modelo local Kimi, GLM o gpt-oss mantiene cada token en tu hardware. Nuestra guía sobre cómo ejecutar Kimi K3 localmente cubre lo que esto implica en la práctica.
- Preferencia de modelo. Los modelos de código abierto han cerrado la mayor parte de la brecha de codificación. Las API alojadas de DeepSeek y Qwen tienen precios más bajos que OpenAI, mientras que obtienen resultados similares en los benchmarks de codificación, y simplemente puede que te guste cómo un modelo específico escribe código.
- Un arnés de agente, muchos modelos. La UX de terminal de Codex, el sandboxing y el flujo de aprobación son buenos. La configuración del proveedor te permite mantener ese arnés y cambiar el cerebro.
Dónde reside la configuración
Codex almacena el estado bajo CODEX_HOME, que por defecto es ~/.codex. Tu configuración a nivel de usuario es ~/.codex/config.toml, y un repositorio puede llevar anulaciones a nivel de proyecto en .codex/config.toml. Todo lo que sigue se incluye en uno de esos dos archivos.
Inicio rápido: Codex con Ollama
El camino más rápido para usar un modelo de código abierto en Codex es Ollama.
- Instala Ollama desde ollama.com e inícialo. Sirve una API compatible con OpenAI en el puerto 11434.
- Descarga un modelo. La propia versión de peso abierto de OpenAI es una primera elección natural; la página de la biblioteca gpt-oss tiene las variantes 20b y 120b. Hemos cubierto la configuración independiente en cómo ejecutar gpt-oss usando Ollama.
ollama pull gpt-oss:20b
- Ejecuta Codex en modo OSS y nombra el modelo:
codex --oss -m gpt-oss:20b
El flag -m/--model anula el modelo configurado, y combinado con --oss selecciona qué modelo local se ejecuta. Para uso no interactivo:
codex exec --oss --local-provider ollama -m gpt-oss:20b "add input validation to the signup route"
- Hazlo el valor predeterminado para que puedas omitir los flags. En
~/.codex/config.toml:
# Proveedor local predeterminado usado con `--oss`
oss_provider = "ollama" # o "lmstudio"
Esa es toda la funcionalidad para los modelos locales. Sin clave API, sin bloque de proveedor personalizado. LM Studio funciona de la misma manera: carga un modelo en la aplicación, inicia su servidor local y ejecuta codex --oss --local-provider lmstudio. Consulta lmstudio.ai para la configuración del servidor.
Proveedores personalizados: apunta Codex a cualquier endpoint compatible
El modo OSS cubre Ollama y LM Studio. Para todo lo demás, API alojadas de DeepSeek o Qwen, un proxy, un servidor vLLM en tu LAN, Codex tiene proveedores de modelos personalizados. La documentación define un proveedor como "cómo Codex se conecta a un modelo (URL base, API de conexión, autenticación y encabezados HTTP opcionales)".
El patrón de la documentación oficial:
model = "gpt-5.6-terra"
model_provider = "proxy"
[model_providers.proxy]
name = "OpenAI using LLM proxy"
base_url = "http://proxy.example.com"
env_key = "OPENAI_API_KEY"
[model_providers.local_ollama]
name = "Ollama"
base_url = "http://localhost:11434/v1"
[model_providers.mistral]
name = "Mistral"
base_url = "https://api.mistral.ai/v1"
env_key = "MISTRAL_API_KEY"
Las claves importantes:
| Clave | Qué hace |
|---|---|
model_provider | Qué ID de proveedor usa Codex (predeterminado: openai) |
model | El nombre del modelo enviado a ese proveedor |
name | Nombre de visualización para el proveedor |
base_url | URL base de la API |
env_key | Variable de entorno que contiene la clave API |
wire_api | Protocolo usado por el proveedor |
query_params | Parámetros de consulta adicionales adjuntos a las solicitudes |
http_headers / env_http_headers | Encabezados estáticos, o encabezados llenados desde variables de entorno |
También está disponible la optimización de red por proveedor: request_max_retries (predeterminado 4), stream_max_retries (predeterminado 5) y stream_idle_timeout_ms (predeterminado 300000). El hardware local lento se beneficia de un tiempo de espera inactivo más largo, ya que un modelo de 120b en un portátil puede permanecer inactivo durante un tiempo entre tokens.
Dos reglas que la documentación destaca directamente. Primero, los IDs openai, ollama y lmstudio están reservados; no puedes anular los proveedores incorporados. Para cambiar la URL base del proveedor OpenAI incorporado, establece openai_base_url en lugar de crear [model_providers.openai]. Segundo, y esto lo define todo: la referencia de configuración establece que para wire_api, "responses es el único valor compatible, y es el predeterminado si se omite."
Esa es una limitación real. Las versiones anteriores de Codex aceptaban wire_api = "chat" para los endpoints de Chat Completions, y la página de descripción general de los modelos aún dice que puedes apuntar Codex a proveedores que admiten "las API de Chat Completions o de Responses". La referencia y la descripción general no concuerdan. [VERIFICAR: si wire_api = "chat" todavía funciona en la versión actual de la CLI; la referencia de configuración dice que solo acepta responses, la página de modelos implica que chat todavía funciona. Probar contra un endpoint de solo chat antes de publicar.] Si solo se admiten responses, tu proveedor necesita un endpoint de API de Responses, que la mayoría de los servidores compatibles con OpenAI ahora exponen, pero algunas API alojadas todavía no.
Recetas modelo por modelo
Cada receta a continuación es un bloque de configuración más el comando para ejecutar. Establece la variable de entorno de la clave API antes de iniciar.
DeepSeek (API alojada)
DeepSeek añadió soporte para la API de Responses junto con su beta V4 Flash, que es exactamente lo que el protocolo de conexión de Codex requiere. Cubrimos ese lanzamiento en DeepSeek V4 Flash, la API de Responses y Codex.
model = "deepseek-chat"
model_provider = "deepseek"
[model_providers.deepseek]
name = "DeepSeek"
base_url = "https://api.deepseek.com"
env_key = "DEEPSEEK_API_KEY"
export DEEPSEEK_API_KEY="sk-..."
codex
Consulta la documentación de la API de DeepSeek para conocer los IDs de modelo actuales. [VERIFICAR: la ruta base_url exacta que DeepSeek documenta para el acceso al protocolo de Responses; la ruta /v1 chat puede diferir de la ruta de Responses.]
Qwen (alojado a través de Model Studio)
Model Studio (DashScope) de Alibaba expone un modo compatible con OpenAI para la familia Qwen 3.8. Históricamente, el endpoint en modo compatible ha tenido forma de Chat Completions. [VERIFICAR: si el modo compatible de DashScope ahora sirve el protocolo Responses; de lo contrario, esta receta depende de la pregunta anterior sobre wire_api = "chat".]
model = "qwen3.8-max"
model_provider = "qwen"
[model_providers.qwen]
name = "Qwen via Model Studio"
base_url = "https://dashscope-intl.aliyuncs.com/compatible-mode/v1"
env_key = "DASHSCOPE_API_KEY"
Nuestra guía de la API de Qwen 3.8 cubre claves, IDs de modelos y precios para la ruta alojada.
Kimi, GLM y otros modelos de código abierto (local a través de Ollama)
Cualquier cosa que puedas integrar en Ollama funciona a través del modo OSS simple, sin necesidad de un bloque de proveedor:
ollama pull <model>
codex --oss -m <model>
Esto cubre los modelos de código abierto GLM y Qwen, además de Kimi K3 si tu hardware lo soporta (los pesos de K3 son 594 GB en MXFP4, por lo que la mayoría de la gente debería leer ejecutar Kimi K3 localmente antes de intentarlo). Para máquinas de tamaño medio, gpt-oss:20b o una compilación cuantificada de Qwen coder es la opción práctica.
vLLM autoalojado o un servidor LAN
Un servidor vLLM o similar compatible con OpenAI en otra máquina es un proveedor personalizado, no el modo OSS:
model_provider = "lan_vllm"
[model_providers.lan_vllm]
name = "vLLM on the workstation"
base_url = "http://192.168.1.50:8000/v1"
env_key = "VLLM_API_KEY"
Perfiles: cambia de "cerebro" por tarea
No tienes que elegir una sola configuración. Los perfiles de Codex son archivos TOML separados en ~/.codex/<profile-name>.config.toml, que se superponen a tu configuración base cuando pasas --profile. Un perfil de modelo local se ve así:
# ~/.codex/oss-local.config.toml
oss_provider = "ollama"
model = "gpt-oss:20b"
codex --profile oss-local
codex exec --profile oss-local "write unit tests for utils/dates.ts"
Mantén tu configuración predeterminada en los modelos de OpenAI para refactorizaciones difíciles y activa --profile oss-local para correcciones de lint, andamiaje de pruebas y pases de documentación. Las anulaciones puntuales también funcionan sin perfil: codex -c model='"deepseek-chat"' -c model_provider='"deepseek"'.
Compensaciones frente a los modelos de OpenAI
Sé honesto contigo mismo sobre lo que estás sacrificando:
- Capacidad. gpt-oss:20b no es gpt-5.6-terra. Los modelos locales fallan con más frecuencia en ediciones largas de múltiples archivos, y los bucles del agente amplifican la debilidad del modelo porque cada paso se basa en el anterior.
- Velocidad. Las API alojadas transmiten datos rápidamente. Un modelo local grande en hardware de consumo puede ser lo suficientemente lento como para cambiar tu forma de trabajar.
- Fidelidad de las herramientas. Las instrucciones y la llamada a herramientas de Codex están ajustadas para los modelos de OpenAI. Los modelos de código abierto varían en la fiabilidad con la que emiten llamadas a herramientas, y el protocolo de conexión de solo respuestas limita qué endpoints son elegibles.
- Superficie de soporte. El modo OSS es una ruta de CLI documentada, pero los proveedores de terceros dependen de ti: los IDs de modelo, los límites de velocidad y las peculiaridades del protocolo son una cuestión entre tú y el proveedor.
La división pragmática: modelos locales o alojados baratos para trabajos de gran volumen y bajo riesgo, modelos de vanguardia para las tareas donde una ejecución fallida te cuesta una tarde.
Verifica las API que tu agente toca
Cualquiera que sea el modelo que se ejecute dentro de Codex, la salida suele ser código que llama o define API, y los modelos de código abierto a menudo alucinan endpoints y esquemas más que los de vanguardia. Detecta eso en la capa de la API en lugar de en producción.
Apidog cubre esa parte del flujo de trabajo. Apunta el servidor Apidog MCP a tu proyecto y tu agente Codex podrá leer la especificación real de la API mientras escribe código, en lugar de inventar nombres de campos. Luego, usa Apidog CLI dentro de Codex para permitir que el agente ejecute tus escenarios de prueba desde la terminal después de cada cambio: edita, prueba, tú revisas un diff que pasa. Ese bucle importa más, no menos, cuando un modelo más pequeño escribe el código. Descarga Apidog para configurarlo; la CLI y el servidor MCP funcionan con cualquier modelo que hayas configurado.
Solución de problemas
codex execfalla inmediatamente en modo OSS. No configuraste un proveedor. Las ejecuciones no interactivas nunca piden, así que pasa--local-provider ollamao estableceoss_provideren la configuración.- Conexión rechazada en el puerto 11434. Ollama no está ejecutándose, o está enlazado a una dirección diferente. Inicia la aplicación o
ollama serve, y confirma concurl http://localhost:11434/v1/models. - Errores 404 o de protocolo de un proveedor alojado. Forma incorrecta de
base_url, o el endpoint no habla el protocolo Responses. Verifica si el proveedor documenta una ruta compatible con Responses. - Fallos de autenticación.
env_keynombra una variable de entorno; Codex lee la clave de tu entorno de shell al iniciar. Exporértala en el mismo shell, y recuerda que los shells de launchd o CI pueden no cargar tus dotfiles. - Los streams se detienen a mitad de generación en un modelo local lento. Aumenta
stream_idle_timeout_msystream_max_retriesen el bloque del proveedor. - Ediciones de configuración ignoradas. Verifica si hay un
.codex/config.tomla nivel de proyecto que anule tu configuración de usuario, y recuerda que los perfiles se superponen a ambos.
Preguntas frecuentes
¿Funciona el modo OSS de Codex en la extensión de IDE o en la nube de Codex?
La documentación cubre el modo OSS y los proveedores personalizados como parte del sistema de configuración de la CLI. El soporte de IDE o nube para proveedores locales no está documentado, así que trátalo como una característica de la CLI. [VERIFICA antes de depender del soporte de IDE.]
¿Qué modelos funcionan mejor con Codex en modo OSS?
Cualquier cosa que Ollama o LM Studio puedan servir en tu hardware. gpt-oss:20b es el valor predeterminado de baja fricción. Las opciones potentes de codificación de peso abierto incluyen la familia Qwen 3.8 y GLM; para los modelos gigantes como Kimi K3, consulta primero los cálculos de hardware en nuestra guía local de Kimi K3.
¿Puedo usar OpenRouter u otro agregador con Codex?
Cualquier agregador que exponga un endpoint compatible se ajusta al patrón [model_providers.<id>]: establece base_url y env_key, luego selecciónalo con model_provider. La pregunta abierta es el protocolo: la referencia de configuración enumera responses como el único wire_api compatible, así que confirma que tu agregador sirva la API de Responses.
¿Necesito una clave API de OpenAI para ejecutar Codex con un modelo de código abierto?
No se necesita ninguna clave para el modo OSS con un servidor local de Ollama o LM Studio. Los proveedores alojados personalizados utilizan su propia clave a través de env_key. Aún así, debes iniciar sesión en Codex como de costumbre para cualquier cosa que involucre los servicios de OpenAI.
Ejecuta la configuración que se adapte a la tarea. Un gpt-oss local para los bucles económicos, DeepSeek o Qwen cuando quieras velocidad alojada a menor coste, y los modelos de frontera de OpenAI cuando el problema sea difícil. La configuración de Codex hace que los tres estén a un solo flag de distancia, y con Apidog manejando la verificación en el lado de la API, el modelo se convierte en una parte intercambiable en lugar de un compromiso.