Integración de la API de Codex: guía de configuración completa

Conectar modelos externos a Codex es un proceso complejo. Esta guía usa la Kimi API como ejemplo práctico para guiarte a través de la configuración completa de la API de Codex en macOS y Windows.

¿Qué es Codex?

Codex es el agente de codificación de OpenAI para trabajo en repositorios y terminal. Puede:

• Escribir código: crear funciones, pruebas, scripts y funciones específicas.

• Entender bases de código desconocidas: buscar archivos, rastrear llamadas y explicar componentes.

• Revisar código: identificar posibles defectos, suposiciones riesgosas, pruebas faltantes y problemas de seguridad.

• Depurar y corregir problemas: reproducir errores, proponer cambios y ejecutar verificaciones.

• Automatizar tareas rutinarias: actualizar archivos y ejecutar flujos de trabajo documentados con tu aprobación.

Instala e inicia sesión en Codex

Parte 1: Instala Codex CLI

1. Abre Terminal en macOS o PowerShell en Windows.

2. Ejecuta el comando correspondiente a tu sistema operativo:

macOS:

Windows:

1. Espera a que termine la instalación y luego cierra y vuelve a abrir Terminal o PowerShell.

2. Ejecuta:

1. Selecciona Sign in with ChatGPT, completa el inicio de sesión en el navegador y regresa a Terminal o PowerShell.

Parte 2: Instala la aplicación de escritorio de Codex

1. Visita la página oficial de la aplicación de escritorio de Codex.

2. Descarga la aplicación de escritorio de ChatGPT para macOS o Windows.

3. Instala y abre la aplicación, luego inicia sesión con tu cuenta de ChatGPT.

4. Crea una tarea o abre un proyecto y selecciona Codex como modo de trabajo.

5. Escribe Say hello in one sentence. y envía el mensaje.

Modelos de IA integrados vs. APIs de LLM externas

Después de instalar Codex, puedes usar sus modelos de IA integrados o conectar una API de LLM externa compatible. La mejor opción depende de cuánta configuración, flexibilidad y gestión de cuentas quieras manejar.

Usa los modelos integrados de Codex

Los modelos integrados ofrecen la experiencia más simple. Puedes seleccionar un modelo disponible y empezar a programar sin ejecutar otro servicio ni configurar una clave de API por separado.

Ventajas:

• Configuración rápida, sin pasos adicionales.

• Integración directa con las herramientas y funciones de Codex

• Menos servicios y credenciales que administrar

Limitaciones:

• Solo puedes elegir entre los modelos disponibles para tu cuenta

• Menos flexibilidad si quieres usar un modelo de otro proveedor

• Requiere una suscripción a GPT, y el costo de uso es relativamente alto.

Usar una API de LLM externa

Una API externa te ofrece más opciones de modelos y te permite usar una cuenta existente con otro proveedor. Sin embargo, algunos modelos requieren configuración adicional o una herramienta de compatibilidad local antes de que Codex pueda usarlos.

Ventajas:

• Acceso a modelos de otros proveedores

• Más flexibilidad para diferentes tareas de codificación

• Control independiente sobre la cuenta y el uso de la API externa

• No requiere suscripción a GPT. Ideal para escenarios sensibles al costo.

Limitaciones:

• Requiere una clave de API y configuración adicional

• Puede requerir un enrutador local que debe permanecer en ejecución

• La facturación, la compatibilidad, la privacidad y la resolución de problemas dependen del proveedor externo

Si quieres la configuración más rápida, comienza con un modelo integrado. Si ya tienes una cuenta de API externa o quieres más opciones de modelos, continúa con la siguiente guía. Usa Kimi API como ejemplo práctico de cómo conectar un modelo externo a Codex.

Cómo conectar una API de LLM externa a Codex: ejemplo con Kimi

Configuración en macOS

Paso 1: Abre la Terminal A y verifica Node.js y npm

Dónde: Presiona Command+Space, escribe Terminal y presiona Enter. Trata esta primera ventana como la Terminal A.

Ejecuta:

Resultado esperado: Cada comando muestra una versión. Salidas como v22.x.x para Node.js y 10.x.x para npm son solo ejemplos, no requisitos mínimos.

Si no se encuentra un comando: Abre un navegador, visita https://nodejs.org/en/download, descarga el .pkg LTS para macOS, abre Descargas en Finder, haz doble clic en el paquete y acepta las opciones predeterminadas del instalador. Cierra la Terminal con Command+Q, vuelve a abrir la Terminal A y ejecuta ambos comandos de versión otra vez. No continúes hasta que ambos comandos devuelvan versiones.

Paso 2: Crea una clave de API de Kimi

Abre la plataforma de Kimi API. Crea una clave de API desde la consola y guárdala en un gestor de contraseñas o de secretos. Si la consola solo muestra la clave completa una vez, cópiala antes de salir de la página.

Paso 3: Configura MOONSHOT_API_KEY en la Terminal A

Dónde: Vuelve a la Terminal A.

Ejecuta:

Reemplaza solo YOUR_KIMI_API_KEY por tu clave real de Kimi. Mantén las comillas y el nombre de la variable MOONSHOT_API_KEY sin cambios.

Resultado esperado: El comando export no muestra ninguna salida. Verifica que exista un valor sin mostrarlo:

La terminal debería mostrar Kimi key is set.

Paso 4: Prueba Kimi directamente desde la Terminal A

Dónde: Sigue usando la Terminal A, donde ya está configurada MOONSHOT_API_KEY.

Ejecuta:

Resultado esperado: Aparece una respuesta JSON que contiene el texto generado en choices[0].message.content.

Paso 5: Abre la Terminal B e inicia el enrutador en la Terminal A

Dónde: Con la Terminal A activa, presiona Command+N para abrir una segunda ventana. Llama a la nueva ventana Terminal B. Regresa a la Terminal A antes de ejecutar el comando del enrutador.

Ejecuta en la Terminal A:

No reemplaces la URL base ni el modelo. $MOONSHOT_API_KEY debe seguir siendo la referencia de la variable, no una segunda copia pegada de la clave.

Posible mensaje en la primera ejecución: npx puede mostrar Need to install ... Ok to proceed? (y). Revisa primero el nombre del paquete y la fuente de terceros vinculada. Escribe y y presiona Enter solo si aceptas ese paquete. No se afirma aquí que se haya probado una versión exacta del paquete.

Resultado esperado: El proceso permanece en ejecución e informa que está escuchando en 127.0.0.1:8787. Deja abierta la Terminal A.

Si falla: Si npm no puede descargar el paquete, confirma el acceso a internet y vuelve a ejecutar node --version y npm --version. Si el puerto 8787 ya está en uso, detén el otro proceso local que usa ese puerto, o regresa a su terminal y presiona Ctrl+C, luego vuelve a ejecutar el comando del enrutador.

Paso 6: Prueba localhost desde la Terminal B

Dónde: Haz clic en la Terminal B.

Ejecuta:

Resultado esperado: La Terminal B imprime eventos de streaming similares a Responses, o una salida que contiene un saludo de una sola oración. La secuencia exacta de eventos puede variar según la versión del enrutador.

Si ves Connection refused: Revisa la Terminal A. Si el enrutador se detuvo, vuelve a ejecutar el comando del Paso 5 y déjalo abierto. Si la Terminal A muestra un 401 del proveedor, restablece MOONSHOT_API_KEY ahí y reinicia el enrutador.

Paso 7: Crea y edita la configuración de Codex en macOS

Dónde: Sigue usando la Terminal B.

Ejecuta:

Estos comandos crean el archivo de configuración a nivel de usuario si es necesario, respaldan un archivo existente y abren ~/.codex/config.toml en TextEdit.

Si el archivo está vacío

Pega la siguiente configuración completa:

Si el archivo ya contiene configuraciones

No pegues la configuración completa sobre el archivo existente. Conserva las configuraciones no relacionadas y actualiza las líneas necesarias de forma individual.

1. Busca la línea que comienza con model = y reemplaza toda la línea con:

1. Busca la línea que comienza con model_provider = y reemplaza toda la línea con:

1. Busca la línea que comienza con model_context_window = y reemplaza toda la línea con:

1. Busca la línea que comienza con model_supports_reasoning_summaries = y reemplaza toda la línea con:

Si alguna de estas cuatro configuraciones no existe todavía, agrega la línea faltante cerca del inicio del archivo.

1. Busca y elimina cualquier línea completa que comience con:

También busca y elimina cualquier línea completa que comience con:

1. Agrega la siguiente sección:

No elimines otras secciones de proveedores, como [model_providers.openai].

Conserva las configuraciones existentes no relacionadas, incluidas las preferencias de notify, aprobación, sandbox, proyecto e interfaz. No copies la línea notify de otro usuario, ya que puede contener una ruta absoluta específica de ese equipo.

Presiona Command+S para guardar el archivo y luego cierra TextEdit.

Paso 8: Reinicia Codex y ejecuta la prueba completa en macOS

Dónde: Mantén el enrutador en ejecución en la Terminal A. En la Terminal B, cierra cualquier sesión existente de Codex con Ctrl+C y luego prepara una carpeta desechable.

Ejecuta en la Terminal B:

Prueba: Escribe hello. y presiona Enter. Una respuesta de una sola oración confirma una ruta de solicitud básica.

Configuración en Windows

Usa dos ventanas independientes de PowerShell. PowerShell A almacena la clave de Kimi de la sesión actual y ejecuta el enrutador. PowerShell B prueba localhost, edita la configuración e inicia Codex. La variable de usuario persistente sirve para futuras ventanas; la asignación de la sesión actual hace que la clave esté disponible de inmediato en PowerShell A.

Paso 1: Abre PowerShell A y verifica Node.js y npm

Dónde: Presiona la tecla Windows, escribe PowerShell y abre Windows PowerShell. Llama a esta ventana PowerShell A.

Ejecuta:

Resultado esperado: Ambos comandos muestran versiones. Valores como v22.x.x y 10.x.x son solo ejemplos, no requisitos mínimos.

Si no se reconoce un comando: Abre un navegador y visita https://nodejs.org/en/download. Descarga el instalador LTS .msi para Windows, abre Descargas en el Explorador de archivos, haz doble clic en el instalador, acepta las opciones predeterminadas y asegúrate de que el instalador conserve la opción de agregar Node.js al PATH. Cierra todas las ventanas de PowerShell, vuelve a abrir PowerShell A y vuelve a ejecutar ambos comandos.

Paso 2: Crea una clave de la API de Kimi

Abre la plataforma de la API de Kimi. Crea una clave de API desde la consola y guárdala en un administrador de contraseñas o de secretos. Si la consola solo muestra la clave completa una vez, cópiala antes de salir de la página.

Paso 3: Configura variables persistentes y de la sesión actual en PowerShell A

Dónde: Vuelve a PowerShell A.

Ejecuta:

Reemplaza únicamente YOUR_KIMI_API_KEY en ambas líneas con la misma clave de Kimi. Deja MOONSHOT_API_KEY, User, las comillas y la puntuación sin cambios. La primera línea guarda el valor para procesos futuros. La segunda línea lo pone disponible de inmediato en PowerShell A.

Resultado esperado: Ambos comandos no devuelven salida. Verifica su presencia sin imprimir la clave:

PowerShell debería mostrar True.

Si muestra False: Vuelve a ejecutar la asignación de la sesión actual con comillas rectas. Si la escritura en User fue bloqueada por una política, continúa con el valor de la sesión actual para este recorrido y consulta a tu administrador cómo deben almacenarse las variables de entorno de usuario. Revoca cualquier clave expuesta en registros o texto compartido.

Paso 4: Prueba Kimi directamente desde PowerShell A

Las referencias de la API pueden mostrar POST URL, pero nunca escribas POST https://... solo en PowerShell. Usa Invoke-RestMethod -Method Post como se muestra aquí.

Dónde: Permanece en PowerShell A, donde $env:MOONSHOT_API_KEY está configurado.

Ejecuta:

No reemplaces el endpoint, el modelo ni el nombre de la variable. PowerShell lee la clave desde $env:MOONSHOT_API_KEY.

Resultado esperado: La última línea imprime un saludo de una frase proveniente de choices[0].message.content.

Si recibes 401: Confirma que la clave provenga de la consola global .ai, revócala y vuelve a crearla si es necesario, vuelve a ejecutar ambas asignaciones del Paso 3 e inténtalo de nuevo. Si el modelo es rechazado, confirma que el ID sea exactamente kimi-k2.7-code y revisa el acceso al modelo en la consola de Kimi.

Paso 5: Abre PowerShell B e inicia el router en PowerShell A

Dónde: Presiona la tecla Windows otra vez, escribe PowerShell y abre una segunda ventana de Windows PowerShell. Llámala PowerShell B. Vuelve a PowerShell A para el comando del router.

Ejecuta en PowerShell A:

Deja $env:MOONSHOT_API_KEY sin cambios; no pegues la clave directamente en el comando.

Posible mensaje en la primera ejecución: npx puede mostrar Need to install ... Ok to proceed? (y). Revisa el paquete y la fuente de terceros. Escribe y y presiona Enter solo si lo aceptas. No se afirma que se haya probado una versión exacta del paquete.

Resultado esperado: El proceso permanece abierto e informa que está escuchando en 127.0.0.1:8787. Mantén PowerShell A abierto.

Si falla: Ejecuta node --version y npm --version en PowerShell A. Si alguno falla, repite el Paso 1. Si el puerto 8787 está ocupado, detén el otro router con Ctrl+C en su ventana y luego vuelve a ejecutar el comando.

Paso 6: Prueba localhost desde PowerShell B

Dónde: Haz clic en PowerShell B. No detengas el router en PowerShell A.

Ejecuta:

No reemplaces la URL de localhost. Apunta al router en PowerShell A.

Resultado esperado: PowerShell devuelve un objeto similar a Responses o una salida que contiene el saludo. Los campos exactos pueden variar según la versión del router.

Si se rechaza la conexión: Revisa PowerShell A y reinicia el comando del Paso 5 si el router se cerró. Si PowerShell A muestra un error de autenticación con el servicio de origen, presiona Ctrl+C, restablece $env:MOONSHOT_API_KEY y reinicia el router. No agregues un encabezado de autorización local para el inicio rápido predeterminado de @codeproxy/cli.

Paso 7: Crea y edita la configuración de Codex para Windows

Dónde: Sigue usando PowerShell B. La configuración del proveedor pertenece a $HOME\.codex\config.toml, no dentro de una carpeta de proyecto.

Ejecuta:

Los comandos crean el directorio de usuario, respaldan una configuración existente, crean el archivo si no existe y lo abren en el Bloc de notas.

En el Bloc de notas: Pega esta configuración predeterminada completa, eliminando claves duplicadas y en conflicto de modelo o proveedor si el archivo ya las contiene:

No reemplaces kimi-proxy, la URL de localhost ni responses. Presiona Ctrl+S y cierra el Bloc de notas.

Confirma el nombre del archivo: Ejecuta:

Resultado esperado: Name es exactamente config.toml, no config.toml.txt, y Length es mayor que cero.

Si el Bloc de notas agregó .txt: En el Bloc de notas, elige Archivo → Guardar como, establece Guardar como tipo en Todos los archivos, escribe config.toml y guárdalo en $HOME\.codex. Vuelve a ejecutar Get-Item. Si Codex ignora el proveedor, verifica que hayas editado la ruta a nivel de usuario y elimina las claves TOML duplicadas.

Paso 8: Reinicia Codex y ejecuta la prueba completa en Windows

Dónde: Deja PowerShell A y su enrutador en ejecución. Cierra por completo cualquier app o sesión de Codex. Cierra PowerShell B, vuelve a abrirlo con la tecla Windows → escribe PowerShell → abre Windows PowerShell, y crea una carpeta desechable.

Ejecuta en la ventana reabierta de PowerShell B:

Prueba: Escribe hello. y presiona Enter. Una respuesta de una sola oración confirma una ruta de solicitud básica.

Usa Kimi en la app de escritorio de Codex

Antes de continuar, completa los pasos 1 a 7 de la configuración de macOS o Windows para el enrutador local y config.toml. No es necesario completar primero la prueba de la CLI, pero el enrutador debe seguir en ejecución mientras usas Kimi en la app de escritorio.

Paso 1: Mantén en ejecución el enrutador local

Mantén abierto Terminal A o PowerShell A con @codeproxy/cli en ejecución en:

Paso 2: Confirma la configuración del proveedor

Abre el archivo de configuración de Codex a nivel de usuario.

En macOS, ejecuta:

En Windows, ejecuta:

Confirma que el archivo contenga estos ajustes de nivel superior:

Paso 3: Reinicia por completo la app de escritorio

En macOS, presiona Command+Q para cerrar por completo la app de escritorio. No basta con cerrar solo la ventana.

En Windows, cierra todas las ventanas de la app de escritorio y confirma que la app ya no se esté ejecutando en la bandeja del sistema.

Vuelve a abrir la app de escritorio y abre una carpeta de proyecto.

Paso 4: Mantén seleccionado el modelo Custom

El selector de modelos de la app de escritorio puede mostrar Custom en lugar de Kimi K2.7 Code. Esto es normal.

Los proveedores personalizados definidos en config.toml no siempre se muestran por nombre en la lista de modelos de la app de escritorio. No selecciones un modelo de OpenAI, como GPT-5.6 Sol, cuando quieras usar el proveedor Kimi. Mantén seleccionado Custom.

También podrías ver esta advertencia:

Esto es una advertencia, no un fallo de conexión. Los siguientes ajustes ya proporcionan la información importante del modelo necesaria para el uso normal:

Paso 5: Verifica la ruta de solicitud de la app de escritorio

Envía este prompt en la app de escritorio:

Observa Terminal A o PowerShell A mientras la app de escritorio responde. Si la ventana de Terminal A recibe una nueva solicitud y la app de escritorio devuelve una respuesta, significa que la app de escritorio está usando la ruta local de Kimi.

Solución de errores comunes de integración

zsh: command not found: POST

POST URL es una notación de la documentación de la API, no un comando. En macOS, copia el ejemplo completo de curl. En Windows, copia el ejemplo completo de Invoke-RestMethod -Method Post.

Conexión rechazada en el puerto 8787

Vuelve a Terminal A o PowerShell A. Si no hay ningún proceso del enrutador en ejecución, establece la variable de Kimi de la sesión actual y vuelve a ejecutar el comando documentado npx @codeproxy/cli .... Mantén esa ventana abierta y repite la prueba de localhost en la ventana B.

Una respuesta 401

Revisa la ventana del enrutador para identificar el salto que falla. Un 401 proveniente de Kimi suele significar que MOONSHOT_API_KEY no es válida, fue revocada o corresponde a la cuenta regional incorrecta. Revoca la clave en la consola global .ai, crea una nueva, restablece la variable de la sesión actual y reinicia el enrutador. La ruta predeterminada del enrutador no tiene verificación de token de autorización entrante. Un 401 local con otro adaptador puede significar que su CODEX_KIMI_PROXY_KEY opcional falta o no es válida.

Errores de parámetro o herramienta no compatibles

Es posible que el enrutador esté reenviando un campo que Kimi no acepta. Los campos de muestreo deben permanecer sin definir; si se envían, deben usar los valores fijos aceptados. Confirma que tool_choice sea auto o none y que el adaptador conserve reasoning_content. Si la prueba de varios pasos sigue fallando, deja de usar esa versión del enrutador y elige o actualiza una que tenga compatibilidad explícita con Kimi.

Codex ignora el proveedor

Abre el archivo de usuario directamente: ejecuta open -e "$HOME/.codex/config.toml" en macOS o notepad "$HOME\.codex\config.toml" en Windows. Confirma que haya un único model_provider = "kimi-proxy" de nivel superior, una sola tabla de proveedor, la URL base de localhost y wire_api = "responses". Guarda, cierra Codex por completo y vuelve a iniciarlo. No coloques la selección de proveedor únicamente en un .codex/config.toml de proyecto.

npx no puede iniciar el router

Ejecuta node --version y npm --version en la ventana A del router. Si alguno de los comandos falla, instala el paquete LTS de Node.js desde nodejs.org/download, cierra y vuelve a abrir la terminal, y vuelve a intentarlo. Si npx pide permiso para descargar el paquete, revisa el paquete y su origen antes de escribir y.

Beneficios de usar la API de Kimi

Usar Kimi en flujos de trabajo de la API de Cursor puede mejorar tareas de programación, depuración y desarrollo. Sus capacidades avanzadas ayudan a generar respuestas precisas, manejar instrucciones complejas y resolver problemas con mayor rapidez. Estos son los principales beneficios de usar Kimi en los flujos de trabajo de Cursor para aumentar la productividad y la eficiencia.

• Comprensión de código con contexto largo

Kimi puede procesar grandes cantidades de código e información a la vez. Reconoce con más eficacia las relaciones entre distintos archivos y secciones del proyecto. Como resultado, trabajar con bases de código grandes o complejas se vuelve mucho más sencillo.

• Mejor análisis de documentación y repositorios

Con Kimi es posible revisar rápidamente documentos del proyecto, notas técnicas y repositorios. Es más fácil encontrar detalles importantes sin tener que revisar cada archivo manualmente. Los desarrolladores pueden obtener una comprensión más clara de todo el proyecto en menos tiempo.

• Desarrollo con IA a un costo razonable

Kimi ofrece una opción práctica y económica para manejar muchas tareas de desarrollo. Se dispone de soporte de IA potente sin depender por completo de modelos más costosos. Los equipos pueden mejorar la productividad general manteniendo mejor control de los gastos.

• Recuperación de conocimiento más rápida

La información útil puede localizarse rápidamente en bases de código, conjuntos de datos y archivos de proyecto grandes. Se dedica menos tiempo a buscar respuestas o referencias entre los recursos disponibles. Se puede prestar más atención a la programación, las pruebas y la mejora del proyecto.

• Automatización mejorada del flujo de trabajo

Las tareas de desarrollo repetitivas se vuelven más fáciles de manejar y completar con Kimi. Puede ayudar con la generación de código, la revisión de contenido y las actividades rutinarias del proyecto. Los flujos de trabajo diarios se mantienen organizados, eficientes y más productivos con el tiempo.

Cómo Codex mejora el flujo de trabajo de desarrollo

Un flujo de trabajo configurado de la API de Codex CLI conecta la inspección del repositorio, la edición, los comandos y la revisión en un mismo contexto. Codex puede estructurar archivos, explicar módulos poco conocidos, reproducir fallas, proponer pruebas y ejecutar verificaciones aprobadas. El soporte de proveedores externos añade opciones de modelo, pero no elimina la responsabilidad de revisión.

Comienza cada tarea con un objetivo acotado. Pide a Codex que inspeccione antes de editar, revisa los cambios que propone, aprueba solo los comandos que entiendes, ejecuta las pruebas del repositorio e inspecciona el diff final. Trata el código generado como una contribución no confiable hasta que pase la revisión y la verificación.

Conclusión

Un uso confiable de la API de Codex se logra probando cada capa en orden: autenticar Codex, llamar directamente a Kimi, iniciar y probar localhost, guardar la configuración de proveedor a nivel de usuario, ejecutar un prompt de solo lectura y completar una tarea de archivos y herramientas. Conserva la clave real de Kimi junto con el router, mantén los secretos fuera de archivos compartidos y detén el router cuando termines.