Usar Apexnova AI Hub con Codex CLI
Codex es el asistente de programación de línea de comandos oficial de OpenAI y solo habla la API Responses. La plataforma sirve /v1/responses en la misma base URL, así que basta con añadir un proveedor personalizado a config.toml para mover Codex con cualquier modelo de texto de aquí.
Los detalles del endpoint están en la referencia de la API Responses. La traducción ocurre en la plataforma: las peticiones salen en el formato nativo del modelo de destino, con streaming, llamadas a herramientas y contenido de razonamiento intactos. Autenticación, límites, descuentos, conmutación por error y facturación funcionan igual que en el resto de endpoints.
Antes de empezar
- Node.js 18 o superior instalado en tu equipo.
- Una API key creada en API Keys dentro de la consola. El valor sk- completo solo se muestra una vez, guárdalo en ese momento.
- Un modelo de chat elegido en el catálogo de modelos: anota su Public Model Name. Codex depende mucho de las llamadas a herramientas, así que elige un modelo que las admita.
- Saldo positivo en la cuenta. Sin saldo la API devuelve HTTP 402.
1. Instalar Codex CLI
Instala la CLI oficial de forma global con npm:
# Requires Node.js 18 or newer npm install -g @openai/codex codex --version
2. Configurar config.toml
Añade un proveedor personalizado al archivo de configuración de Codex y ponlo por defecto:
# ~/.codex/config.toml model_provider = "apexnova" model = "glm-4.6" # a Public Model Name on this platform [model_providers.apexnova] name = "Apexnova AI Hub" base_url = "https://api.apexnova-consulting.com/v1" env_key = "APEXNOVA_API_KEY" # env var that holds your sk-... key wire_api = "responses"
| Clave | Para qué sirve |
|---|---|
model_provider | Qué proveedor se usa por defecto: la x de [model_providers.x]. |
model | El Public Model Name del modelo por defecto, por ejemplo glm-4.6. También puedes cambiarlo con /model dentro de Codex. |
base_url | La base URL compatible con OpenAI de la plataforma, terminada en /v1: la misma dirección que usan los SDK. |
env_key | Nombre de la variable de entorno que guarda tu API key. Codex solo guarda el nombre; la clave nunca va en el archivo de configuración. |
wire_api | Tiene que ser responses. Codex eliminó el soporte de chat completions, con cualquier otro valor no conecta. |
El archivo está en ~/.codex/config.toml en macOS y Linux, y en la carpeta .codex de tu directorio de usuario en Windows. Si no existe, créalo.
3. Poner la clave y arrancar
Pon la clave en la variable que indica env_key y ejecuta codex desde tu proyecto:
# macOS / Linux export APEXNOVA_API_KEY=sk-xxxxxxxx codex # Windows PowerShell $env:APEXNOVA_API_KEY = "sk-xxxxxxxx" codex
Codex puede avisar Model metadata for … not found: no conoce los nombres de modelo de la plataforma y usa los metadatos por defecto. Es inofensivo.
4. Verificar
Cuando algo está mal configurado, el error de Codex rara vez apunta a la causa, así que llama primero al endpoint Responses con curl:
curl https://api.apexnova-consulting.com/v1/responses \
-H "Authorization: Bearer sk-xxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "glm-4.6",
"input": "ping"
}'Cuando curl devuelva contenido, arranca Codex y comprueba en «Uso» de la consola que aparece una llamada con ese modelo.
Límites conocidos del dialecto Responses
El endpoint Responses de la plataforma es siempre sin estado: el cliente lleva la conversación y la plataforma no guarda nada. Por eso estos parámetros no se comportan como en OpenAI:
- previous_response_id, conversation y background devuelven siempre 400 unsupported_parameter. Exigen guardar la conversación en el servidor, e ignorarlos en silencio haría que el modelo pareciera amnésico sin nada que diagnosticar, así que se rechazan en vez de fingir que funcionan.
- store, metadata, include, truncation y similares — parámetros que solo afectan a optimizaciones o metadatos — se ignoran en silencio, y la respuesta siempre indica store: false. Codex envía store en cada turno, así que devolver error lo dejaría inservible.
- Las herramientas integradas de servidor que no se pueden traducir (por ejemplo web_search) se descartan una a una en vez de tumbar la petición: una herramienta que el modelo no ve es una herramienta que no puede decir que usó. Si envías tools y no se puede traducir ninguna, entonces sí devuelve 400.
- Los modelos con clave propia (BYOK) no sirven este endpoint; usa /v1/chat/completions.
Diagnóstico
- 401 —— El nombre de la variable no coincide con env_key en config.toml, o la clave está revocada. Codex lee la variable que indica env_key, no OPENAI_API_KEY.
- 404 model_not_found —— model no es un Public Model Name de la plataforma, o queda fuera de la lista blanca del espacio de trabajo de esa clave, o es un modelo privado sin autorizar. Comprueba el nombre en el catálogo.
- 400 unsupported_parameter —— La petición llevaba un parámetro de continuación de conversación; mira los límites de arriba. Suele ser alguna configuración o extensión que envía previous_response_id.
- 429 —— Un tope de presupuesto del espacio de trabajo o de la clave, o un límite de RPM/TPM. Ajústalo en el espacio de trabajo.
- En Windows no puede escribir archivos —— Es el propio sandbox de Codex: workspace-write depende de Seatbelt en macOS y Landlock en Linux, y ninguno existe en Windows. No tiene que ver con la plataforma; ajusta la política de aprobación según la documentación de Codex.
Buenas prácticas
- Dale a Codex su propia clave dentro de su propio espacio de trabajo, con tope de presupuesto y límites de RPM/TPM, para que una sesión descontrolada choque contra el tope y no contra el saldo.
- Configura una cadena de conmutación por error para tu modelo principal en «Fallback de modelos». La facturación sigue al modelo que realmente respondió.
- Al ser un endpoint sin estado, cada turno reenvía el contexto completo y los tokens de entrada suben rápido en sesiones largas. Abrir una sesión nueva al cambiar de tarea sale mucho más barato que acumular en una sola.