Codex · Capítulo 5
Integración de modelos de terceros como DeepSeek
3 minutos de lectura
📚 Navegación de la serie: El artículo anterior (04 · Suscripción y facturación) aclaró las cuentas de Codex: si es más conveniente la suscripción o el pago por uso. Este capítulo continúa con la "optimización de costes" abordando un enfoque más alternativo: reemplazar el cerebro detrás de Codex por modelos de terceros como DeepSeek.
⚠️ Advertencia inicial (característica experimental sujeta a cambios, basada en pruebas reales): Codex es un producto propio de OpenAI, y su documentación oficial no contempla en absoluto la integración de DeepSeek. Conectar modelos de terceros a Codex es una alternativa desarrollada por la comunidad aprovechando un mecanismo oficial: los proveedores de modelos personalizados (
model_providers). El éxito y la fluidez de esta integración dependen de los protocolos de interfaz que admita el modelo de terceros, que suele ser el principal origen de problemas (detallado en la sección 03). En este capítulo, los elementos de configuración y comportamientos documentados oficialmente indican su fuente de procedencia; la integración de DeepSeek se basa principalmente en pruebas prácticas y soluciones de la comunidad. Las direcciones de las APIs, los nombres de los modelos y la compatibilidad de protocolos pueden cambiar en cualquier momento, rigiéndose siempre por los canales oficiales de DeepSeek y Codex.
Compañeros, permítanme compartir una conversación real que mantuve hace poco:
Colega: "Lograste ahorrar bastante integrando DeepSeek en Claude Code, ¿por qué no haces lo mismo con Codex?" Yo: "Yo también pensé que sería igual... pero tras dos horas intentándolo, con la configuración correcta, la petición devolvía un error 400." Colega: "¿Ah, sí? ¿No es solo cuestión de cambiar la
base_url?" Yo: "Codex y Claude Code no siguen el mismo patrón. Parecen similares por fuera, pero su funcionamiento interno es muy diferente."
A decir verdad, este es el capítulo de toda la serie de Codex en el que más quiero llamar tu atención. Si buscas "integrar DeepSeek en Codex" en internet, encontrarás multitud de tutoriales, pero el 90% de ellos no aclara un aspecto crítico: la integración de terceros en Codex y en Claude Code, sigue una lógica subyacente completamente diferente. Si intentas replicar la experiencia de Claude Code, lo más probable es que experimentes fallos de protocolo. En este capítulo analizaremos este problema a fondo.
Al terminar este artículo, obtendrás:
- La diferencia fundamental en una frase sobre cómo integran terceros Codex y Claude Code (ahorrándote horas de pruebas)
- Una tabla comparativa para evaluar si te conviene o no conectar modelos de terceros a Codex antes de actuar
- Comparativa de ventajas e inconvenientes de las dos vías de integración (edición manual de
config.tomlfrente a herramientas de proxy de terceros) y perfiles recomendados - Una plantilla de configuración de
model_providers, metodologías de verificación y resolución de errores comunes.
01 Comprende la diferencia: cambiar el modelo en Codex no es igual que en Claude Code
La conclusión primero: Claude Code cambia de modelo mediante variables de entorno, mientras que Codex lo hace editando el "proveedor de modelos" en su archivo de configuración; además, Codex exige protocolos específicos para APIs de terceros y no es compatible con cualquier interfaz genérica.
Analicemos los pasos:
Codex es en esencia un cliente que se ejecuta en la terminal; se encarga de leer el código, invocar herramientas y gestionar el contexto, pero no procesa el razonamiento por sí mismo, sino que delega cada petición en un modelo de lenguaje. El modelo predeterminado es el GPT de OpenAI (actualmente se recomienda gpt-5.5, fuente: documentación oficial de Codex, sección Models).
La integración de terceros consiste en redirigir estas peticiones desde OpenAI a otro proveedor. Codex ofrece oficialmente esta opción; la documentación recoge:
También puedes configurar Codex para apuntar a cualquier modelo y proveedor que admita Chat Completions y Responses API, con el fin de adaptarlo a tus necesidades específicas. (Documentación oficial de Codex, sección Models)
Analogía: El formato del enchufe. Claude Code funciona como un adaptador universal: si un tercero diseña una API compatible con el formato de Anthropic, la conexión es inmediata. Codex es diferente y se asemeja a un electrodoméstico que solo admite enchufes específicos: solo reconoce los formatos de OpenAI (Chat Completions y Responses API). Modelos como DeepSeek ofrecen comúnmente APIs "compatibles con OpenAI", es decir, enchufes con el formato de OpenAI, por lo que en teoría deberían funcionar. Sin embargo, existe una limitación oculta:
La documentación oficial de Codex detalla que el soporte para Chat Completions API está obsoleto y se eliminará en versiones futuras (fuente: sección Models). Esto significa que Codex está priorizando Responses API, que es un protocolo propio relativamente nuevo de OpenAI y no ha sido implementado completamente por la mayoría de proveedores de modelos de terceros.
Este es el motivo de mi bloqueo previo: asumí que la compatibilidad con OpenAI de DeepSeek sería suficiente, pero el proceso falló debido a las restricciones de protocolo.
💡 Resumen en una frase: Claude Code cambia de modelo mediante variables de entorno y reconoce el protocolo de Anthropic; Codex lo hace editando los proveedores de modelos en
config.tomly reconoce el protocolo de OpenAI (priorizando Responses API). Evita aplicar la experiencia de Claude Code directamente en Codex.
02 ¿Deberías integrar modelos de terceros en Codex? Evaluación previa
Una recomendación honesta: para la integración de terceros, Codex resulta mucho más complejo de configurar que Claude Code. Esta es una conclusión práctica basada en mi experiencia de uso.
Los motivos principales son tres:
- La tasa de éxito de integración de terceros en Codex es inferior a la de Claude Code, limitada por la compatibilidad de protocolos analizada.
- Las capacidades de programación de
gpt-5.5en Codex son excelentes; para tareas complejas o refactorizaciones extensas, los modelos de terceros no alcanzan su rendimiento, por lo que el ahorro económico reduce la calidad del resultado. - Las suscripciones de OpenAI (Plus o Pro) ya incluyen la cuota de uso de Codex. Si ya pagas la suscripción, consumir APIs de terceros supone un coste duplicado.
| Dimensión | GPT oficial (predeterminado de Codex) | Modelos de terceros (como DeepSeek) |
|---|---|---|
| Coste | Elevado; el pago por consumo en uso intensivo incrementa la factura | Económico; suele ser un orden de magnitud inferior |
| Acceso a red | Requiere proxies o VPNs en redes restringidas | Conexión directa compatible (sin restricciones locales) |
| Complejidad de integración | Configuración inmediata tras iniciar sesión | ⚠️ Riesgo de incompatibilidad de protocolos |
| Capacidad de programación | gpt-5.5 excelente; óptimo en flujos extensos | Adecuado para tareas comunes; fallos en arquitectura compleja |
| Soporte oficial | Integración nativa preferente | Experimental; sin soporte oficial ante incidencias |
| Estabilidad de configuración | Actualizaciones gestionadas de forma nativa | ⚠️ Requiere reconfiguración ante cambios de API o nombres del modelo |
La diferencia es clara: a diferencia de lo concluido para Claude Code, donde las APIs de terceros son la mejor opción de optimización de costes, en Codex la integración introduce el riesgo de incompatibilidad de protocolos, reduciendo su viabilidad.
¿Para qué perfiles se recomienda probarlo? Mi opinión:
- Recomendado para: Usuarios con un consumo elevado de API que realicen tareas sencillas de edición de código y busquen reducir costes; usuarios con restricciones de red que requieran conexión directa; o perfiles que deseen experimentar con la configuración técnica.
- No recomendado para: Suscriptores activos de planes de OpenAI (supone un coste duplicado); desarrolladores centrados en arquitecturas complejas o depuraciones avanzadas (donde el rendimiento de
gpt-5.5es necesario); o usuarios principiantes que prefieran evitar complejidades de configuración.
Mi conclusión es la siguiente: utilizo DeepSeek con Claude Code para tareas comunes, pero con Codex empleo de forma exclusiva la vía oficial de OpenAI. No por limitaciones de DeepSeek, sino porque la integración de terceros en Codex no es lo suficientemente estable y es más eficiente centrarse en el uso nativo.
💡 Resumen en una frase: La integración de terceros en Codex introduce el riesgo de compatibilidad de protocolos; evita realizarla si eres suscriptor activo, abordas desarrollos complejos o prefieres configuraciones sencillas. Consiente que es una alternativa experimental.
03 Dos alternativas de integración: edición manual frente a herramientas de proxy
Si tras evaluar los riesgos deseas proceder, ten en cuenta que existen dos vías alternativas de integración con diferentes requisitos.
Ambas alternativas persiguen el mismo fin, pero deben superar la validación de protocolos, que constituye la barrera principal en Codex.
Vía 1: Edición manual de config.toml (mecanismo oficial)
Codex gestiona sus parámetros en el archivo de configuración de usuario ~/.codex/config.toml (fuente: Configuration Reference oficial). Permite definir proveedores de modelos personalizados.
Analogía: Crear un nuevo contacto en tu agenda. Tu agenda solo incluye por defecto el contacto de OpenAI; si deseas realizar llamadas a DeepSeek, debes registrar una nueva entrada: asignar un nombre, la dirección de llamada (base_url) y la credencial de acceso (obtenida de una variable de entorno). Tras registrarlo, configuras Codex para que realice las llamadas a este nuevo contacto.
Los parámetros clave de configuración son los siguientes (fuente: Configuration Reference; los primeros cuatro se definen en la sección model_providers, los últimos dos son directivas globales):
| Parámetro | Definición oficial |
|---|---|
model_providers.<id>.name | Nombre visible del proveedor personalizado |
model_providers.<id>.base_url | Dirección base de la API del proveedor |
model_providers.<id>.env_key | Variable de entorno que almacena la clave de API |
model_providers.<id>.wire_api | Protocolo utilizado; el único valor admitido oficialmente es responses, que se aplica por defecto |
model_provider (global) | Proveedor activo; el valor por defecto es openai |
model (global) | Modelo de procesamiento activo |
Presta atención al parámetro wire_api: la documentación detalla explícitamente que responses es el único valor admitido (responses is the only supported value). Este es el obstáculo principal de la edición manual: si el proveedor de terceros solo implementa la interfaz Chat Completions y carece de compatibilidad con Responses API, esta vía de integración no será compatible.
⚠️ DeepSeek ofrece una API "compatible con OpenAI" orientada a Chat Completions. La compatibilidad real con el protocolo
responsesde Codex depende del estado actual de las implementaciones; no es posible garantizar su funcionamiento previo. Valida este aspecto realizando pruebas locales de acuerdo con la documentación vigente de ambos servicios. Si funciona, es una ventaja; si falla, es el comportamiento esperable.
Vía 2: Integración mediante herramientas de proxy de terceros (solución de la comunidad)
Dado que las restricciones de protocolo son la barrera principal, la comunidad ha diseñado una alternativa: levantar un servicio de proxy local en tu máquina que actúe como traductor de protocolos —Codex envía la petición en formato de OpenAI al proxy local, este traduce la petición al formato de DeepSeek y realiza la redirección, traduciendo de vuelta la respuesta obtenida. Codex opera asumiendo que se comunica directamente con OpenAI.
La herramienta de código abierto CC Switch (github.com/farion1231/cc-switch) implementa esta solución: levanta un proxy local y redirige de forma transparente las peticiones de Codex al proveedor seleccionado, incluyendo plantillas preconfiguradas para plataformas como DeepSeek.
Analogía: Contratar un intérprete. Si tú (Codex) solo hablas inglés (protocolo de OpenAI) y tu interlocutor (DeepSeek) solo entiende chino, la Vía 1 confía en que el interlocutor aprenda inglés (compatibilidad nativa con Responses API); la Vía 2 introduce un intérprete (el proxy local) para traducir las comunicaciones en tiempo real.
Ambas alternativas se comparan a continuación:
| Criterio | Vía 1: Edición manual de config.toml | Vía 2: Herramienta de proxy (como CC Switch) |
|---|---|---|
| Vía oficial | Sí, utiliza las directivas oficiales de configuración | No, herramienta de terceros desarrollada por la comunidad |
| Compatibilidad de protocolos | ⚠️ Depende de la compatibilidad del proveedor con responses | Gestionada automáticamente por el proxy local; mayor tasa de éxito |
| Complejidad de configuración | Requiere edición manual de archivos TOML; riesgo de erratas | Panel visual sencillo; accesible para principiantes |
| Transparencia | Las directivas se configuran de forma directa y visible | Introduce un intermediario; diagnóstico de fallos más complejo |
| Alternancia de proveedores | Requiere edición de archivos ante cada cambio | Selección rápida de diferentes proveedores en el panel |
| Perfiles recomendados | Usuarios técnicos que busquen comprender el flujo interno | Perfiles orientados a resultados que prefieran evitar edición manual |
Mi recomendación: si deseas comprender cómo Codex descarga e integra terceros, utiliza la Vía 1; aunque falle, te familiarizarás con las directivas internas. Si tu objetivo es utilizar la herramienta sin implicaciones técnicas, utiliza la Vía 2 para delegar la gestión de protocolos.
💡 Resumen en una frase: La Vía 1 es la configuración nativa (transparente pero sujeta a la compatibilidad del protocolo); la Vía 2 es una herramienta de proxy (intermediaria pero con mayor éxito). Elige la herramienta de proxy si prefieres comodidad o la edición manual si buscas comprender el funcionamiento, pero ambas dependen de la compatibilidad de protocolos final.
04 Práctica: plantilla básica de configuración en config.toml
En esta sección se detalla la plantilla de configuración para la Vía 1. Se define como plantilla debido a la compatibilidad del protocolo: la sintaxis TOML es la oficial y válida; el funcionamiento real con DeepSeek dependerá de tus pruebas locales.
Rutas del sistema: el archivo ~/.codex/config.toml se localiza en ~/.codex/ en macOS/Linux y en C:\Users\TuUsuario\.codex\ en Windows (~ corresponde al directorio personal del usuario). Si el archivo no existe, créalo manualmente.
Paso 1: Obtener una clave de API de DeepSeek
- Accede al panel de desarrolladores de DeepSeek e inicia sesión.
- Genera una nueva clave de API, cópiala y guárdala de forma segura (con formato
sk-xxxxxxxx).
🔑 La clave de API es la credencial de acceso a tu saldo de facturación; nunca la subas a Git, ni la expongas en chats ni la configures directamente en el archivo TOML. La gestionaremos mediante variables de entorno para evitar su filtración en los archivos.
Paso 2: Declarar la clave como variable de entorno
Declara la credencial en una variable de entorno personalizada (por ejemplo, DEEPSEEK_API_KEY), de forma que la configuración solo referencie la variable sin exponer la clave.
macOS/Linux:
export DEEPSEEK_API_KEY=<tu_clave_de_API>Windows (PowerShell):
$env:DEEPSEEK_API_KEY="<tu_clave_de_API>"Estas declaraciones solo tienen vigencia en la sesión de terminal activa. Para configuraciones persistentes, añádelas a ~/.zshrc en macOS, ~/.bashrc en Linux (y ejecuta source correspondientemente) o agrégalas como variables de usuario en las propiedades del sistema en Windows.
Paso 3: Configurar el proveedor en config.toml
Edita tu archivo ~/.codex/config.toml y añade la siguiente estructura (siguiendo las directivas oficiales):
# Directivas globales: configuran el proveedor personalizado y modelo activos
model_provider = "deepseek"
model = "<nombre_del_modelo_de_DeepSeek>"
# Registro del proveedor de modelos personalizado con identificador "deepseek"
[model_providers.deepseek]
name = "DeepSeek"
base_url = "<direccion_base_de_la_API_de_DeepSeek>"
env_key = "DEEPSEEK_API_KEY" # Referencia a la variable de entorno
# wire_api se aplica como "responses" por defecto si se omiteExplicación detallada de las directivas:
model_provider = "deepseek": Indica a Codex que ignore el proveedoropenaipredeterminado y utilicedeepseek.model = "...": Define el identificador del modelo; consulta la documentación oficial de DeepSeek para obtener los nombres de modelo vigentes.[model_providers.deepseek]: Define el registro del nuevo proveedor, cuyo identificador coincide conmodel_provider.base_url: Dirección base de la API del proveedor de acuerdo con las especificaciones oficiales.env_key = "DEEPSEEK_API_KEY": Variable de entorno que almacena la clave de API declarada en el Paso 2.
⚠️ Los valores de
modelybase_urlse muestran como marcadores de posición. Esto se debido a que las direcciones y nombres de modelo oficiales de DeepSeek están sujetos a cambios; además, el funcionamiento de esta vía nativa depende de la compatibilidad del protocoloresponsesde la API de terceros. Comprueba su vigencia mediante pruebas locales. La sintaxis TOML es la correcta, pero el funcionamiento depende de la compatibilidad de protocolos final.
Nota: Los identificadores de proveedor integrados (
openai,ollamaylmstudio) están reservados y no se pueden sobreescribir (fuente: Configuration Reference), por lo que debes evitar usarlos para tus proveedores personalizados.
💡 Resumen en una frase: La edición manual consiste en declarar la clave en una variable de entorno, registrar la sección
model_providersenconfig.tomly definir las directivas globales correspondientes. La sintaxis es válida y el funcionamiento depende del protocolo.
05 Verificación: comprobar el estado de la integración
Una vez configurado, realiza las siguientes comprobaciones para verificar que las peticiones se redirijan correctamente antes de trabajar.
Paso 1: Verificar el modelo activo
Inicia Codex y escribe el comando de barra /model en la sesión, que permite alternar el modelo utilizado en el hilo activo (fuente: sección Models oficial). Confirma que el panel liste el modelo personalizado y no el GPT nativo de OpenAI.
codexIn-app command:
/modelTambién puedes iniciar el servicio forzando un modelo con el parámetro
-m(por ejemplo,codex -m <nombre_del_modelo>, fuente: sección Models).
Paso 2: Ejecutar una petición de prueba
Para asegurar el funcionamiento del protocolo, envía una petición de prueba de baja complejidad:
Hola, confirma en una sola frase si puedes responder correctamente.Tres posibles respuestas según el caso:
| Síntoma | Causa probable | Resolución |
|---|---|---|
| Respuesta en texto coherente | 🎉 Integración correcta | Listo para su uso |
| Error 401 / Fallo de autenticación | Clave de API incorrecta o variable de entorno no declarada | Revisa la directiva env_key, declara la variable de entorno de nuevo y reinicia la terminal |
| Error 400 / Fallo de protocolo o formato | Incompatibilidad de protocolo (restricciones de Responses API) | La Vía 1 no es compatible con el proveedor; utiliza la Vía 2 o cambia de modelo |
| Error de modelo no encontrado | Identificador del modelo incorrecto o actualizado por el proveedor | Revisa la documentación oficial de DeepSeek para obtener el identificador vigente |
Presta especial atención al Error 400 (Fallo de protocolo): si lo experimentas, no asumas que cometiste una errata en la sintaxis. Confirma la incompatibilidad descrita en el apartado 03: Codex requiere el protocolo responses de OpenAI y el proveedor de terceros no lo implementa. Ante esta situación, te sugerimos utilizar la Vía 2 (traducción de protocolos mediante proxy) o cambiar de modelo.
💡 Resumen en una frase: Comprueba la asignación con
/modely ejecuta una petición de prueba; el error 401 suele deberse a la credencial de acceso y el 400 a incompatibilidad de protocolo. Cambia de alternativa si experimentas fallos de protocolo.
06 Tras la integración: ajustar el esfuerzo de razonamiento
Si la integración es exitosa, ten en cuenta la siguiente directiva práctica: Codex permite ajustar el esfuerzo de razonamiento del modelo para optimizar el consumo de tokens o la calidad de la respuesta.
El parámetro oficial model_reasoning_effort admite los niveles minimal (reflexión mínima), low, medium, high y xhigh (sujeto a compatibilidad del modelo; fuente: Configuration Reference). Se configura en config.toml así:
model_reasoning_effort = "medium"Analogía: Estrategia de examen. El nivel low es como responder preguntas de opción múltiple rápidamente: respuestas veloces pero imprecisas; high o xhigh es como desarrollar problemas matemáticos complejos: requiere reflexión profunda, garantizando exactitud a costa de lentitud y mayor consumo de tokens. Configurar el esfuerzo máximo de forma permanente incrementará los costes considerablemente.
Mi recomendación es: mantén el valor predeterminado en medium para optimizar el rendimiento y coste diario; auméntalo a high de forma puntual ante tareas de refactorización complejas o depuración avanzada. Asignar el nivel máximo por defecto va en contra de la optimización de costes perseguida al integrar proveedores de terceros.
Nota de compatibilidad: algunas características nativas del ecosistema de OpenAI no estarán disponibles al utilizar proveedores de terceros ; por ejemplo, la búsqueda web basada en caché (web_search en modo cached, fuente: Configuration Reference) depende directamente de los índices mantenidos por OpenAI. Esto confirma el carácter experimental de la integración analizado en el apartado 02: aunque no afecte a la programación diaria, debes tenerlo en cuenta.
💡 Resumen en una frase: Ajusta el esfuerzo de razonamiento mediante
model_reasoning_effort(usamediumpor defecto y sube ahighde forma justificada) para evitar costes excesivos, y ten en cuenta las limitaciones de las características exclusivas de OpenAI.
07 Resumen
En este capítulo hemos analizado la integración de modelos de terceros como DeepSeek en Codex, detallando sus implicaciones y el carácter experimental de la configuración.
Resumen de puntos clave:
| Fases | Conceptos y acciones clave |
|---|---|
| Diferencias de protocolo | Codex reconoce de forma exclusiva la especificación de OpenAI (priorizando Responses API); evita aplicar la lógica de Claude Code |
| Evaluación de viabilidad | Evita la integración si dispones de una suscripción activa, realizas desarrollos avanzados o prefieres configuraciones sencillas |
| Alternativas de integración | Edición manual de config.toml para comprender el flujo interno, o herramientas de proxy (CC Switch) para simplicidad |
| Configuración del proveedor | Definición de model_providers y asignación global de proveedor y modelo, gestionando las claves en variables de entorno |
| Verificación de la API | Comprobación del modelo activo mediante /model y petición de prueba; el error 400 confirma incompatibilidad de protocolo |
| Optimización de uso | Ajuste del esfuerzo de razonamiento con model_reasoning_effort para controlar el consumo de tokens |
A partir de ahora dispones de los criterios necesarios para: evaluar la conveniencia de la integración, seleccionar la alternativa de integración adecuada, configurar las directivas TOML de proveedores de modelos personalizados y diagnosticar fallos de compatibilidad de protocolos.
Un consejo para concluir: el factor crítico al integrar terceros en Codex no es la exactitud de tu archivo de configuración, sino la compatibilidad de protocolos del proveedor. Tener esto presente te ahorrará horas de pruebas infructuosas.
En el próximo capítulo (06 · Ejecución de la primera tarea) concluiremos la fase de configuración e iniciaremos la práctica de desarrollo. Te invitamos a ejecutar una tarea real completa con Codex (ya sea con el modelo nativo o de terceros) para familiarizarte con la dinámica de programación autónoma. Una pequeña reflexión antes de empezar: ¿cuál será la primera tarea que le encargues: solucionar un bug, programar una función menor o pedirle que analice el repositorio completo?