Conectar modelos de terceros como DeepSeek
📚 Navegación de la serie: El artículo anterior 04 · Suscripción y facturación detalló los costes de Codex y la conveniencia de los diferentes planes. Este artículo continúa con la optimización de costes explorando una opción más avanzada: sustituir el modelo en segundo plano de Codex por modelos alternativos de terceros como DeepSeek.
📌 Advertencia inicial (uso experimental sujeto a cambios, guíate por tus pruebas locales): Codex es un producto diseñado por OpenAI, por lo que su documentación oficial no contempla el soporte para conectar a DeepSeek u otros proveedores. La conexión a modelos de terceros es una funcionalidad desarrollada por la comunidad basándose en el punto de extensión de proveedores de modelos personalizados (
model_providers) expuesto por la CLI. Que este flujo funcione y sea estable depende de la compatibilidad del protocolo del proveedor seleccionado, siendo este el punto donde más errores ocurren (ver detalles en la sección 03). Las configuraciones y directivas documentadas oficialmente se indican con su fuente; el apartado dedicado a DeepSeek se basa en soluciones validadas por la comunidad, teniendo en cuenta que las URLs de la API, nombres de modelos y compatibilidad de protocolos pueden cambiar, por lo que te aconsejamos consultar las actualizaciones directamente en los sitios de DeepSeek y Codex.
Permíteme compartir una conversación real que mantuve con un compañero recientemente:
Compañero: «¿No habías conectado Claude Code a DeepSeek para ahorrar bastante? ¿Por qué no haces lo mismo con Codex?» Yo: «Eso mismo pensé... pero tras configurar todo y verificarlo durante dos horas, recibí un error 400 en la primera petición.» Compañero: «¿Ah, sí? ¿No bastaba con cambiar la
base_url?» Yo: «Codex no sigue el mismo esquema de configuración que Claude Code. Parecen similares, pero en el fondo trabajan de forma muy distinta.»
A decir verdad, este es uno de los capítulos en los que más me interesa ponerte sobre aviso en todo el manual de Codex. En internet abundan guías sencillas para conectar Codex a DeepSeek, pero casi ninguna menciona un detalle técnico crítico: conectar Codex a modelos externos sigue un esquema lógico completamente diferente al de Claude Code, y pretender aplicar la misma configuración solo provocará que te quedes atascado por problemas de protocolo de la API. Analicemos este problema a fondo.
Al leer este artículo, obtendrás:
- La explicación técnica sobre la diferencia fundamental entre Claude Code y Codex al conectar proveedores externos (ahorrándote horas de depuración).
- Una tabla de ventajas y desventajas para evaluar si te conviene conectar modelos de terceros en Codex.
- Comparación de los dos métodos de integración (edición directa del archivo
config.tomlvs herramientas de proxy locales). - Una plantilla base de configuración para
model_providers, junto con el proceso de verificación y resolución de errores comunes.
01 Concepto fundamental: Cambiar de modelo en Codex difiere de Claude Code
Para ir directo al grano, esta es la regla principal: en Claude Code se cambian los modelos modificando variables de entorno, mientras que en Codex se realiza editando el apartado de proveedores de modelos en el archivo de configuración; además, Codex exige que los proveedores de terceros implementen protocolos de API específicos, no siendo compatible con cualquier API estándar.
Vayamos paso a paso.
La CLI de Codex que instalaste actúa como un cliente local que gestiona el contexto, lee archivos y ejecuta comandos, pero no realiza el procesamiento cognitivo por sí misma, delegando cada paso en un modelo en segundo plano. Por defecto, este modelo es de la serie GPT de OpenAI (la versión recomendada actualmente es gpt-5.5, ver documentación de modelos de Codex).
Asociar un proveedor externo significa redirigir las consultas de la CLI fuera de los servidores de OpenAI. Codex expone esta posibilidad en su configuración, describiéndola así:
Puedes configurar Codex para apuntar a cualquier modelo o proveedor compatible con la API de Chat Completions o Responses API para adaptarlo a tus necesidades específicas. (Documentación de modelos de Codex)
Analogía: El formato del enchufe de alimentación. Claude Code es como un cargador universal: mientras el proveedor de API de terceros implemente una interfaz compatible con el protocolo de Anthropic, se conectará inmediatamente. Codex, por el contrario, requiere formatos de enchufe muy específicos: solo acepta las dos interfaces de OpenAI (Chat Completions y Responses API). Modelos alternativos como DeepSeek suelen ofrecer APIs compatibles con OpenAI (es decir, el mismo formato de enchufe), por lo que técnicamente se pueden conectar. Sin embargo, hay un inconveniente importante:
La documentación oficial especifica que el soporte para la API de Chat Completions está «obsoleto y se eliminará en futuras versiones» (ver documentación de modelos de Codex). Codex está migrando su arquitectura hacia la nueva interfaz de Responses API. Dado que Responses API es un protocolo de API de OpenAI reciente, muchas plataformas y proveedores de API de terceros aún no lo han implementado de forma completa.
Esta es la razón por la que mi configuración falló al principio: asumí que al ser «compatible con la API de OpenAI» funcionaría inmediatamente con DeepSeek, pero la petición chocó contra la falta de soporte para la Responses API.
💡 Resumen en una frase: En Claude Code se modifica el modelo mediante variables de entorno bajo el protocolo de Anthropic; en Codex se modifica el apartado de proveedores en
config.tomlbajo los protocolos de OpenAI (priorizando Responses API). Evita aplicar los pasos de Claude Code directamente en Codex.
02 ¿Te conviene conectar modelos de terceros en Codex?
A decir verdad, el uso de modelos de terceros en Codex ofrece menos ventajas y más complicaciones que en Claude Code. Esta es mi valoración tras usarlo de forma regular.
Las razones se resumen en tres puntos:
- La tasa de éxito al conectar proveedores externos en Codex es menor debido a las exigencias de compatibilidad con la Responses API explicadas anteriormente.
- Las capacidades de generación de código de GPT-5.5 en Codex son excelentes, sobre todo para tareas complejas y refactorizaciones largas. Usar modelos de terceros menos capaces para ahorrar costes puede comprometer la calidad del código generado.
- El coste de Codex ya está cubierto en tu plan de ChatGPT Plus o Pro (como calculamos en el capítulo 04). Si ya pagas la suscripción mensual, consumir APIs de pago adicionales de terceros supone un gasto redundante.
Consulta la tabla comparativa de capacidades:
| Parámetro | GPT oficial (Codex por defecto) | Modelos de terceros (como DeepSeek) |
|---|---|---|
| Coste | Mayor coste; el pago por uso en tareas intensivas consume más cuota | ✅ Coste significativamente menor; suele ser un orden de magnitud más barato |
| Acceso regional | Requiere una conexión de red estable y sin restricciones | ✅ Acceso directo local sin restricciones de red en múltiples regiones |
| Facilidad de conexión | Configurado por defecto | ⚠️ Riesgo de incompatibilidad por diferencias de protocolo |
| Capacidades de agente | ✅ GPT-5.5 en la primera categoría; estable en tareas largas | Adecuado para tareas cotidianas; puede fallar en lógica de sistemas complejos |
| Soporte oficial | ✅ Integrado y mantenido oficialmente | ❌ Soporte experimental; sin garantías en caso de fallos |
| Persistencia de configuración | Actualizaciones gestionadas de forma transparente | ⚠️ Requiere ajustes manuales si cambian los nombres de modelos o APIs |
Como puedes ver, a diferencia de Claude Code (donde el uso de modelos de terceros es una recomendación clara para optimizar costes), en Codex añadir proveedores externos introduce el riesgo de fallos por incompatibilidad de protocolos, lo que resta atractivo a esta opción.
¿Para quiénes está recomendada esta opción?
- ✅ Recomendado para: usuarios intensivos con facturas de API elevadas que realicen tareas sencillas y rutinarias; usuarios con problemas de conexión persistentes a los servidores de OpenAI que busquen una alternativa local estable; y desarrolladores interesados en probar configuraciones de sistemas.
- ❌ No recomendado para: usuarios con planes de ChatGPT activos (coste redundante e ineficiente); desarrolladores que trabajen en arquitecturas de sistemas complejos o depuraciones avanzadas (donde las capacidades de GPT-5.5 son indispensables); y usuarios que busquen configuraciones sencillas que funcionen inmediatamente sin realizar ajustes técnicos.
Mi criterio de uso: empleo DeepSeek con Claude Code para tareas genéricas y prototipos rápidos, y utilizo la configuración oficial con GPT para Codex. No por falta de capacidades de DeepSeek, sino porque la integración técnica en Codex es inestable y prefiero centrar mi tiempo en el desarrollo del proyecto.
💡 Resumen en una frase: Conectar modelos de terceros en Codex introduce el riesgo de incompatibilidades del protocolo; evítalo si dispones de planes de ChatGPT activos, trabajas en lógica de código compleja o prefieres configuraciones sin mantenimiento técnico.
03 Dos métodos de integración: configuración directa vs proxy local
Si decides realizar la conexión de todos modos, ten en cuenta que existen dos métodos de integración y elegir el adecuado te ahorrará tiempo de depuración.
El diagrama muestra ambas rutas de integración: ambas son válidas, pero el factor determinante en el éxito de la conexión es la compatibilidad del protocolo de la API de destino, que es el cuello de botella técnico de Codex.
Método 1: Edición manual de config.toml (vía oficial)
Codex reúne sus parámetros en el archivo de configuración de usuario ~/.codex/config.toml (ver guía de referencia de configuración). El sistema permite registrar en este archivo proveedores de modelos personalizados en el apartado model_providers.
Analogía: Añadir un contacto en la agenda de tu teléfono. Por defecto, tu agenda solo contiene a OpenAI; si quieres realizar llamadas a DeepSeek, debes registrar una nueva entrada con su nombre, la dirección de acceso (base_url) y el identificador de acceso (la variable de entorno de tu API key). Una vez registrado, le indicas a Codex que realice las llamadas a este nuevo contacto.
Los parámetros de configuración requeridos en el archivo TOML (según la guía de referencia de configuración; los cuatro primeros dentro del subapartado model_providers, y los dos últimos en la raíz del archivo):
| Parámetro | Significado técnico |
|---|---|
model_providers.<id>.name | Nombre identificador del proveedor personalizado |
model_providers.<id>.base_url | Dirección URL de acceso a la API del proveedor |
model_providers.<id>.env_key | Nombre de la variable de entorno que contiene la API Key |
model_providers.<id>.wire_api | Protocolo a utilizar; solo se admite responses y se aplica por defecto |
model_provider (raíz) | Proveedor activo de la sesión; por defecto, openai |
model (raíz) | Nombre del modelo activo a utilizar |
Presta atención al parámetro wire_api: la documentación oficial indica de forma explícita que responses es el único valor admitido. Este es el principal obstáculo del método 1: si la API del proveedor de terceros solo es compatible con Chat Completions y no soporta Responses API, este método de conexión fallará.
⚠️ DeepSeek dispone de una API compatible con OpenAI, orientada principalmente al protocolo de Chat Completions. La compatibilidad de esta API con el protocolo
responsesde Codex depende de las actualizaciones de servicio de ambos proveedores; te aconsejamos validar su funcionamiento localmente. Si la conexión falla por problemas de protocolo, se considera un comportamiento esperado debido a las restricciones de Codex.
Método 2: Uso de herramientas de proxy local (solución de la comunidad)
Para resolver las diferencias de protocolo, la comunidad desarrolló una solución intermedia: ejecutar un servicio de proxy local en tu máquina que traduzca los protocolos. Codex envía las peticiones en formato Responses API de OpenAI al puerto local del proxy, y este las traduce al formato Chat Completions de OpenAI que acepta DeepSeek, gestionando el retorno de la misma manera. Desde la perspectiva de la CLI de Codex, la comunicación sigue el protocolo nativo de OpenAI de forma transparente.
La herramienta CC Switch (una utilidad gráfica de código abierto y multiplataforma disponible en GitHub en github.com/farion1231/cc-switch) implementa este esquema: levanta un proxy local y redirige de forma transparente las peticiones de Codex al proveedor seleccionado, incluyendo perfiles preconfigurados para plataformas comunes como DeepSeek.
Una vez instalada la herramienta, abre la interfaz y haz clic en «Add Provider» (o en el icono de agregar «+») para configurar el proveedor de API.
El panel muestra el asistente de configuración: selecciona el agente que deseas configurar en el panel izquierdo (en este caso, Codex) y en el panel derecho se mostrará la sección de configuración del proveedor; selecciona el backend que vas a asociar (DeepSeek, etc.), introduce la API key y guarda los cambios para que CC Switch gestione la traducción de protocolos.
El menú muestra los perfiles de los proveedores de API integrados (como DeepSeek u OpenRouter), lo que evita tener que configurar manualmente las URLs y los detalles del protocolo; basta con seleccionar el proveedor e introducir la API key.
Analogía: Contratar a un traductor. Tú (Codex) solo hablas inglés (protocolo de OpenAI) y tu interlocutor (DeepSeek) solo entiende chino. El método 1 asume que tu interlocutor aprenderá a hablar inglés (que la API de terceros implemente Responses API); el método 2 sitúa a un traductor (el proxy local) en medio para gestionar la comunicación. Si el traductor realiza su trabajo, la conversación fluirá de forma estable.
Comparativa de los dos métodos de integración:
| Criterio | Método 1: Configuración en config.toml | Método 2: Proxy local (ej. CC Switch) |
|---|---|---|
| Tipo de integración | ✅ Implementación nativa de la CLI de Codex | ❌ Dependencia de herramientas de terceros de la comunidad |
| Compatibilidad | ⚠️ Limitada por el soporte del proveedor a responses | ✅ El proxy gestiona la traducción de protocolos, aumentando la tasa de éxito |
| Complejidad | Requiere edición manual de archivos TOML | Interfaz gráfica sencilla de configurar, adecuada para perfiles no técnicos |
| Auditoría | Configuración local transparente y visible | Añade un intermediario en la comunicación local |
| Flexibilidad | Requiere edición manual para cambiar de modelo | Permite alternar entre proveedores con un clic |
| Perfil recomendado | Desarrolladores que busquen integraciones limpias y comprender el flujo | Usuarios que busquen una solución rápida y sin edición de archivos |
Mi recomendación: si quieres comprender el funcionamiento del sistema de proveedores de Codex, utiliza el método 1; si este método falla por incompatibilidad de protocolos, habrás verificado el comportamiento del sistema. Si prefieres una solución directa sin depurar archivos, utiliza el método 2 para delegar la traducción en el proxy local.
💡 Resumen en una frase: El método 1 es la configuración nativa de la CLI (sencilla pero sensible a la compatibilidad del protocolo), mientras que el método 2 recurre a un proxy local (añade una dependencia local pero asegura mayor compatibilidad); selecciona el método según tu perfil técnico y necesidades de desarrollo.
04 Práctica: Configuración manual de config.toml
A continuación mostramos la estructura de configuración base para aplicar el método 1. Considera esta plantilla como una guía de referencia técnica, teniendo en cuenta que la viabilidad del flujo con DeepSeek dependerá de la compatibilidad del protocolo de la API del proveedor.
La ubicación del archivo de configuración ~/.codex/config.toml varía según el sistema operativo: en macOS y Linux se encuentra en ~/.codex/config.toml y en Windows en C:\Users\TuUsuario\.codex\config.toml. Crea el directorio y el archivo si no existen en tu sistema.
Paso 1: Obtener una API key de DeepSeek
- Accede a la plataforma de desarrollo de DeepSeek e inicia sesión con tu cuenta.
- Genera una API Key y guárdala en un lugar seguro (tiene el formato
sk-xxxxxxxx).
🔑 Protege tus API keys como contraseñas. No las integres directamente en el archivo de configuración ni las subas a repositorios Git. Utilizaremos variables de entorno para cargarlas de forma segura.
Paso 2: Configurar la variable de entorno
Asocia tu API key a una variable de entorno local (utilizaremos el identificador DEEPSEEK_API_KEY), de modo que el archivo de configuración apunte al nombre de la variable en lugar de contener la clave en texto plano.
macOS y Linux (Terminal):
export DEEPSEEK_API_KEY=<tu_API_key_de_DeepSeek>Windows (PowerShell):
$env:DEEPSEEK_API_KEY="<tu_API_key_de_DeepSeek>"Estas declaraciones de variables de entorno solo tienen validez en la ventana activa de la terminal. Para hacerlas permanentes, añádelas al archivo de configuración de tu shell (como ~/.zshrc en macOS o ~/.bashrc en Linux y aplica cambios con source); en Windows, añade el identificador en las «Variables de entorno» de tu configuración de usuario y reinicia la terminal.
Paso 3: Editar el archivo config.toml
Edita el archivo ~/.codex/config.toml e introduce la siguiente estructura de parámetros (respetando la nomenclatura oficial):
# Parámetros raíz: definen el proveedor y el modelo activos de la sesión
model_provider = "deepseek"
model = "<nombre_de_modelo_oficial_de_DeepSeek>"
# Configuración del proveedor personalizado con identificador "deepseek"
[model_providers.deepseek]
name = "DeepSeek"
base_url = "<URL_base_de_la_API_de_DeepSeek>"
env_key = "DEEPSEEK_API_KEY" # Nombre de la variable de entorno configurada en el paso 2
# wire_api se aplica como "responses" de forma predeterminada si no se especificaDetalle técnico de los parámetros:
model_provider = "deepseek": indica a la CLI de Codex que debe desviar las peticiones al proveedor con identificadordeepseeken lugar de usaropenai.model = "...": indica el nombre del modelo. Consulta los nombres de modelos vigentes en la documentación de la API de DeepSeek, ya que cambian con las actualizaciones de servicio.[model_providers.deepseek]: inicia el bloque de configuración del proveedor personalizado con identificadordeepseek.base_url: indica la URL de destino de las peticiones a la API, provista por el proveedor de servicio.env_key = "DEEPSEEK_API_KEY": la CLI leerá el token de la variable de entorno con este nombre al autenticar las peticiones.
⚠️ Los valores para
modelybase_urlse muestran como marcadores en la plantilla para evitar que dependas de valores estáticos que puedan quedar obsoletos. La conexión de este bloque TOML con DeepSeek dependerá de que la API de destino acepte el protocoloresponsesde Codex. La estructura es correcta técnicamente, pero la viabilidad del flujo depende del soporte de API del proveedor de destino.
Nota: Los identificadores de proveedores integrados (
openai,ollama,lmstudio) están reservados por el sistema (ver guía de referencia de configuración); evita utilizarlos como identificadores para tus proveedores personalizados.
💡 Resumen en una frase: Configurar el proveedor requiere exportar la API key como variable de entorno, registrar la estructura
model_providersenconfig.tomly definir los parámetros raíz de modelo y proveedor; la sintaxis es estándar pero el éxito del flujo depende de la compatibilidad del protocolo.
05 Verificación de la conexión
Una vez guardados los archivos de configuración, verifica el estado de la conexión antes de continuar con tu flujo de trabajo ordinario.
La validación se realiza en dos fases:
Fase 1: Validar la asignación del modelo
Inicia Codex y ejecuta el comando /model en la terminal; este comando te mostrará el modelo activo de la sesión (ver documentación de modelos de Codex). Confirma que la CLI detecta el modelo configurado en tu archivo TOML y que no se mantiene en el modelo GPT predeterminado.
codexEn la línea de comandos de Codex, escribe:
/modelTambién puedes especificar el modelo al iniciar la CLI con el parámetro
-m, por ejemplocodex -m <nombre_modelo>.
Fase 2: Realizar una petición básica de prueba
Confirma que la comunicación es fluida enviando una consulta sencilla que no requiera analizar archivos del proyecto:
Confirma que la comunicación funciona respondiendo con una única frase corta.Comportamiento de la respuesta:
| Resultado | Causa probable | Solución recomendada |
|---|---|---|
| Respuesta fluida del modelo de terceros | ✅ Conexión operativa | Puedes comenzar a programar |
| Error 401 / Fallo de autenticación | La variable de entorno de la API key no es accesible | Comprueba el nombre de la variable en env_key y que la variable esté cargada en la terminal activa |
| Error 400 / Error de formato o protocolo | Falta de compatibilidad del protocolo de la API (restricciones de Responses API) | La API de destino no soporta el protocolo nativo de Codex; utiliza el método 2 de proxy local o asocia un proveedor compatible |
| Error indicando que el modelo no existe | El nombre del modelo en el parámetro model es incorrecto | Consulta los modelos de la API actualizados en la web de DeepSeek |
Si recibes un error 400 de protocolo, es un comportamiento esperado debido a las limitaciones de Responses API detalladas en la sección 03. En este escenario, no intentes corregir los archivos de configuración; utiliza el método 2 de proxy local para delegar la traducción de protocolos en lugar de forzar la conexión directa en config.toml, optimizando tu tiempo de desarrollo.
💡 Resumen en una frase: Comprueba la asignación del modelo con
/modely realiza una pregunta sencilla para validar la conexión; los errores 401 apuntan a la configuración de la clave y los errores 400 indican incompatibilidad del protocolo, requiriendo en este caso usar un proxy local.
06 Gestión de la profundidad de razonamiento
Si la conexión se ha completado correctamente, puedes ajustar el nivel de procesamiento del modelo para controlar el consumo de tokens.
Codex expone el parámetro model_reasoning_effort, que admite los niveles minimal / low / medium / high / xhigh (la disponibilidad de xhigh depende del modelo asociado; ver guía de referencia de configuración). Configura el parámetro en tu archivo config.toml:
model_reasoning_effort = "medium"Analogía: Estrategia de resolución de un examen. El nivel low es como responder preguntas de opción múltiple sencillas: respuesta rápida pero sin análisis profundo; los niveles high o xhigh equivalen a resolver problemas complejos de desarrollo, donde el modelo analiza más variantes y se toma más tiempo. Usar el nivel máximo de forma continuada incrementará notablemente el consumo de tokens y el tiempo de respuesta.
Mi recomendación: aplica el nivel medium para el trabajo diario para equilibrar velocidad y coste; cambia a high solo para tareas complejas que involucren lógica modular. Dado que el objetivo de usar modelos de terceros es reducir costes, forzar el nivel máximo de razonamiento para tareas sencillas consumirá tokens innecesariamente, anulando las ventajas del cambio.
Consideración técnica: al usar modelos de terceros, ciertas funcionalidades nativas de Codex estrechamente integradas con los servicios de OpenAI podrían verse afectadas o no estar disponibles (por ejemplo, las búsquedas web del parámetro
web_searchse procesan sobre índices mantenidos por OpenAI). Ten esto en cuenta al cambiar de proveedor.
💡 Resumen en una frase: Controla el procesamiento del modelo de terceros con el parámetro
model_reasoning_effort(usamediumpor defecto yhighsolo para lógicas complejas), evitando malgastar tokens; ten en cuenta que las funciones nativas en la nube de OpenAI no estarán disponibles con otros proveedores.
07 Resumen
En este capítulo hemos analizado la integración de modelos de terceros en Codex:
| Apartado | Detalle clave |
|---|---|
| Protocolos | Codex requiere el protocolo Responses API de OpenAI en segundo plano; no apliques los métodos de Claude Code directamente |
| Criterio de uso | Útil para optimizar costes de API en tareas sencillas; evítalo si usas planes de ChatGPT, necesitas lógicas complejas o prefieres sistemas sin mantenimiento técnico |
| Métodos | Configuración nativa en config.toml (método 1, requiere compatibilidad de API de destino) o uso de proxies locales de la comunidad como CC Switch (método 2, traduce protocolos localmente) |
| Estructura TOML | Registro del proveedor en model_providers asociando la variable de entorno de la API key |
| Validación | Comprobación de modelo activo con /model y prueba de comunicación; resolución de errores 401 (autenticación) y 400 (protocolo) |
| Optimización | Ajuste del nivel de procesamiento con model_reasoning_effort en nivel medium por defecto |
La regla técnica a recordar: el éxito de la conexión nativa con modelos de terceros depende de la compatibilidad del proveedor de API con el protocolo Responses API de Codex. Comprender esta limitación te ayudará a seleccionar el método de integración adecuado y a evitar demoras de configuración en tu entorno local.
Una vez analizada la configuración y los proveedores de modelos, el próximo capítulo 06 · Ejecutar la primera tarea te guiará para poner a trabajar al agente en tu base de código local, aplicando modificaciones reales de código de principio a fin para comprender el comportamiento de la herramienta.