Codex es el producto de OpenAI para agentes de programación, disponible en varias formas: la herramienta de línea de comandos Codex CLI, la extensión para IDE y las tareas en la nube. Muchos equipos quieren conectarlo a su propio punto de acceso de API para usar una clave y una facturación unificadas, o para aprovechar los modelos que ofrece un gateway. Conviene aclarar algo desde el principio: Codex no tiene una «API de Codex» independiente; Codex CLI llama a la interfaz Responses de OpenAI. La llamada «API personalizada» consiste, en realidad, en cambiar la Base URL, la clave y el nombre del modelo de la solicitud por un endpoint compatible.

Este artículo toma como referencia las versiones habituales de octubre de 2026 y explica tres cosas: cómo instalar Codex CLI, cómo escribir config.toml y cómo verificar y solucionar problemas después de conectarlo a un gateway personalizado.

Nota: OpenAI y Codex son marcas de sus respectivos titulares; este artículo solo ofrece una explicación técnica de integración. Los requisitos de protocolo de Codex y las interfaces y nombres de modelos compatibles con el gateway pueden cambiar según la versión. Consulta la documentación oficial y los precios de modelos del sitio.

1. Distingue primero las tres formas de Codex

Forma Acceso ¿Permite clave personalizada?
Codex CLI Ejecutar codex en la terminal Sí, mediante config.toml
Extensión de IDE Barra lateral del editor Según la versión actual; suele depender del sistema de cuentas
Tareas en la nube Web Normalmente usa una cuenta de ChatGPT

Para la mayoría de los desarrolladores, el terreno principal de la API personalizada es Codex CLI. Esta herramienta lee código, modifica archivos y ejecuta comandos; el modelo solo se encarga del razonamiento. Al cambiar el endpoint del modelo, la cadena de herramientas sigue ejecutándose en local.

2. API Key y Base URL de Codex

El proveedor personalizado de Codex CLI necesita tres parámetros: Base URL, API Key y nombre del modelo. La dirección oficial predeterminada es https://api.openai.com/v1; si usas ZSQH AI Gateway, la dirección es https://ai.zhongshangqihang.com/v1.

Elemento Valor oficial predeterminado Gateway de ZSQH
Base URL https://api.openai.com/v1 https://ai.zhongshangqihang.com/v1
Autenticación API Key de OpenAI Clave creada en la consola del gateway
Protocolo API Responses Ofrece el endpoint /v1/responses; los modelos compatibles se indican en la documentación del sitio
Nombre del modelo ID oficial del modelo Según la página de precios del sitio

Aquí hay un cambio clave en 2026: el proveedor personalizado de Codex CLI solo acepta actualmente wire_api = "responses"; el antiguo wire_api = "chat" se ha eliminado. Es decir, el gateway debe poder reenviar el protocolo Responses. Si solo ofrece Chat Completions, necesitarás una capa intermedia que convierta el protocolo o cambiar de cliente. ZSQH AI Gateway ofrece el endpoint /v1/responses; los modelos concretos que admiten Responses se indican en la documentación y la página de precios del sitio.

3. Instalar Codex CLI

Elige un método según tu sistema:

# npm
npm install -g @openai/codex

# macOS Homebrew
brew install --cask codex

# Confirmar la versión tras la instalación
codex --version

Cuando termine la instalación, no te apresures a cambiar la configuración. Inicia sesión con una cuenta oficial y haz una primera prueba para confirmar que la herramienta funciona:

  1. Ejecuta codex en la terminal.
  2. Elige el método de inicio de sesión que se indique.
  3. Crea un directorio de prueba y pídele que lea un archivo.
  4. Confirma que responde correctamente antes de cambiar al proveedor personalizado.

4. Escribir config.toml

La configuración de usuario de Codex CLI se encuentra en ~/.codex/config.toml. El archivo .codex/config.toml dentro del directorio del proyecto no sobrescribe la definición del proveedor, lo que fácilmente hace pensar que la configuración no surte efecto.

# ~/.codex/config.toml
model = "your-model-id"
model_provider = "zsqh"

[model_providers.zsqh]
name = "ZSQH AI Gateway"
base_url = "https://ai.zhongshangqihang.com/v1"
env_key = "ZSQH_API_KEY"
wire_api = "responses"

Significado de los campos:

  • model: ID del modelo que se va a llamar; debe coincidir exactamente con el identificador de la página de precios del gateway.
  • model_provider: apunta al nombre del proveedor definido abajo; ambos deben coincidir.
  • base_url: dirección raíz compatible con OpenAI, normalmente termina en /v1.
  • env_key: nombre de la variable de entorno que contiene la clave; no escribas la clave directamente en el archivo de configuración.
  • wire_api: en la versión actual, usa responses.

Después, exporta la clave en la shell:

export ZSQH_API_KEY="sk-tu-clave"

En Windows PowerShell, usa $env:ZSQH_API_KEY="sk-tu-clave". Si quieres que se aplique de forma permanente, añade la variable al archivo de configuración de la shell o a las variables de entorno del sistema; no la incluyas en el repositorio de código.

5. Verificar la primera solicitud

En modo interactivo, ejecuta codex directamente y plantea una pregunta de solo lectura dentro del directorio del proyecto, por ejemplo «explica el archivo de entrada de este directorio». Si solo quieres hacer una verificación no interactiva, puedes usar codex exec (si tu versión actual ofrece este subcomando, ejecuta primero codex exec --help para confirmarlo):

cd /path/to/your-project
codex exec "explica en tres puntos la estructura de directorios de este proyecto, sin modificar archivos"

Para rastrear el destino de las solicitudes, activa el registro de depuración:

codex --log-level debug

Fíjate sobre todo en si la URL de la solicitud apunta a tu Base URL, si la ruta es /responses y si el nombre del modelo se envía tal cual. Muchos casos de «la configuración no surte efecto» se deben en realidad a que la terminal no recargó las variables de entorno o a que se editó el archivo de configuración equivocado.

6. Cómo elegir el modelo

Las tareas de Codex se centran en comprender código, generar parches y ejecutar comandos. Al elegir un modelo, prioriza tres aspectos: longitud de contexto, estabilidad de las llamadas a herramientas y cumplimiento de instrucciones en tareas largas. No mires solo el precio unitario.

Escenario Recomendación Atención
Cambios de código diarios Modelo de chat general o de código Confirma que admite salida en streaming
Lectura de repositorios grandes Modelo de contexto largo Cuanto más largo es el contexto, mayor es el coste por solicitud
Tareas de varios pasos Modelo con llamadas a herramientas estables Valida primero con tareas pequeñas
Scripts por lotes Modelo de menor coste Limita los reintentos en caso de fallo

El ID del modelo se consulta en la página de precios del sitio. Copiar el nombre visible de la web directamente en model es uno de los errores más frecuentes: el nombre visible y el identificador de API no suelen ser lo mismo.

7. Errores habituales y cómo resolverlos

Síntoma Causa habitual Solución
401 Unauthorized La clave no se exportó o es incorrecta Abre una terminal nueva y confirma que la variable indicada en env_key tiene valor
404 Not Found La Base URL tiene /v1 de más o de menos, o el gateway no admite /responses Revisa la dirección y el alcance de las interfaces
Error con wire_api = "chat" Se está usando una configuración antigua Cambia a responses o actualiza Codex
model not found El ID del modelo no coincide con la página de precios Copia el identificador exacto de la página de precios
La solicitud se interrumpe Problema de red o tiempo de espera del streaming Revisa el proxy, los tiempos de espera y la configuración de reintentos
429 Límite de frecuencia o cuota insuficiente Consulta el uso en el gateway y reduce la concurrencia

Si el gateway solo admite Chat Completions y la versión actual de Codex solo reconoce Responses, lo más sensato es añadir una capa de conversión de protocolo (por ejemplo, un gateway como LiteLLM) en lugar de buscar versiones antiguas por todas partes. Las versiones antiguas acabarán quedando sin mantenimiento.

8. Lista de seguridad y costes

  1. Guarda la clave solo en variables de entorno o en un servicio de gestión de secretos; nunca en Git.
  2. Emite una clave independiente para Codex, así podrás limitar el uso y revocarla con facilidad.
  3. Configura presupuestos y límites de concurrencia en el gateway para evitar que un bucle del agente consuma la cuota.
  4. En repositorios grandes, excluye primero los artefactos de compilación, los directorios de dependencias y los archivos de secretos.
  5. Revisa periódicamente los informes de uso y separa los costes por proyecto.
  6. No pegues claves de producción, datos de clientes ni registros sin anonimizar en los prompts.

Preguntas frecuentes

¿La API de Codex y la suscripción a ChatGPT son lo mismo?

No. La suscripción a ChatGPT está orientada a la web y a los productos cliente; Codex CLI puede usar inicio de sesión con cuenta o configurarse con una API Key con facturación por uso. Los criterios de facturación son distintos, así que los equipos deben calcularlos por separado al comprar.

¿Puede Codex CLI usar la interfaz Chat Completions?

El proveedor personalizado de la versión actual solo admite el protocolo Responses; wire_api = "chat" se ha eliminado. Los endpoints que solo ofrecen Chat Completions necesitan una capa de conversión de protocolo.

¿Por qué no surte efecto el cambio en config.toml?

Primero confirma que editaste ~/.codex/config.toml y no un archivo de configuración dentro del proyecto; después, que model_provider coincide con el nombre de [model_providers.xxx]; por último, abre una terminal nueva para que las variables de entorno surtan efecto.

¿Debo poner el nombre visible o el identificador de API como nombre del modelo?

El identificador de API. El nombre visible solo se usa en la interfaz; si lo pones mal, normalmente obtendrás model not found. La forma exacta se consulta en los precios de modelos del sitio.

¿Puede un equipo compartir una sola clave?

No es recomendable. Emite claves por persona, proyecto o entorno: si surge un problema podrás localizarlo y, si alguien deja el equipo o la clave se filtra, podrás revocarla por separado.

Próximos pasos

La dificultad de integrar Codex no está en la instalación, sino en la compatibilidad de protocolos: primero confirma si el gateway admite Responses y después configura la Base URL, la clave y el modelo. Si necesitas un punto de acceso unificado y gestión de uso, puedes registrarte en ZSQH AI Gateway; los modelos y el alcance de las interfaces se indican en la página de precios de modelos.

Lecturas relacionadas: