Clave de API de Codex CLI: configuración funcional de un proveedor personalizado

Una clave de API de Codex es cualquier clave con la que Codex CLI pueda facturar por token en lugar de utilizar un plan de ChatGPT: una clave de API de OpenAI de platform.openai.com o una clave de proveedor como la de Kunavo sk-kn-, que Codex lee desde la variable de entorno indicada por env_key en un bloque model_providers. El proveedor debe ofrecer la API Responses; ese es el único requisito que se indica a continuación.

Codex CLI es el agente de programación de terminal open source de OpenAI y funciona mediante un inicio de sesión de ChatGPT o una clave de API. Conviene entender la ruta de la clave de API: factura por token sin cuota mensual y es la única ruta que permite dirigir la CLI a otro proveedor, o incluso a otra familia de modelos. Esta guía cubre la configuración operativa, el único requisito que causa problemas a la mayoría de las puertas de enlace y el coste real de una sesión.

El único requisito importante

Codex CLI es más estricto con los endpoints personalizados que la mayoría de las herramientas. Su bloque model_providers tiene una clave wire_api y acepta exactamente un valor: responses. Esto significa que un proveedor personalizado debe ofrecer la API Responses de OpenAI en POST /v1/responses, no la mucho más común /v1/chat/completions. La mayoría de las puertas de enlace compatibles con OpenAI solo ofrecen esta última, por lo que muchas no pueden ejecutar Codex CLI, independientemente de qué base_url les proporciones.

Kunavo ofrece ambas superficies, por lo que la configuración siguiente funciona tal como está escrita.

La configuración

Codex lee ~/.codex/config.toml. Dos claves de nivel superior seleccionan el modelo y el proveedor; el bloque del proveedor describe cómo acceder a él:

# ~/.codex/config.toml
model          = "gpt-5-6-sol"
model_provider = "kunavo"

[model_providers.kunavo]
name     = "kunavo"
base_url = "https://api.kunavo.com/v1"
env_key  = "KUNAVO_API_KEY"
wire_api = "responses"

Observa lo que no aparece en ese archivo: la propia clave. env_key nombra una variable de entorno y Codex lee la clave de ella al iniciarse, por lo que el archivo de configuración es seguro para incluirlo en commits o compartirlo.

# Codex reads the key from the variable named by env_key.
export KUNAVO_API_KEY="sk-kn-..."     # create at kunavo.com/app/keys

# Persist it (pick the file your shell actually loads):
echo 'export KUNAVO_API_KEY="sk-kn-..."' >> ~/.zshrc

codex "explain the structure of this repository"

Crea la clave en el panel después de registrarte y recargar $10. Se muestra una sola vez, así que guárdala de inmediato. Si codex ya se estaba ejecutando en otro shell, reinícialo: lee la variable al iniciarse, no en cada solicitud.

Verifica antes de depurar

Si algo falla, averigua si el problema está en la clave, el endpoint o la CLI. Una solicitud basta para resolverlo:

# Confirm the key and the endpoint before blaming Codex.
curl https://api.kunavo.com/v1/responses \
  -H "Authorization: Bearer $KUNAVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5-6-sol",
    "input": "Say OK and nothing else."
  }'

Una respuesta JSON significa que la clave y el endpoint son correctos y que cualquier problema restante está en config.toml. Un 401 significa que la clave es incorrecta o que la variable está vacía en este shell. Un 404 en model significa que el slug no coincide con el catálogo.

Qué modelo configurar

El valor de model es solo un slug en el mismo endpoint, por lo que cambiar de modelo requiere editar una sola palabra: no necesitas una clave nueva ni un bloque de proveedor nuevo.

gpt-5-6-sol es el GPT ajustado para programación y la opción predeterminada natural para esta CLI, a $2.00 / $12.00 por 1M de tokens frente al precio de lista de OpenAI de $5.00 / $30.00 — aunque actualmente OpenAI cobra un precio promocional de $4.00 / $20.00, disponible al menos hasta 21 de noviembre de 2026. Las tarifas completas de todos los modelos están en la página de precios.

Ejecutar modelos Claude en Codex CLI

Esto sorprende a muchas personas: Codex CLI está vinculado al protocolo, no al modelo. Utiliza el formato de transmisión Responses y responde cualquier modelo de chat situado detrás de ese endpoint. Dirígelo a claude-opus-5 y se ejecutará de extremo a extremo, incluidas las llamadas a herramientas; el agente seguirá leyendo archivos, proponiendo cambios y ejecutando comandos con normalidad.

# Same provider block, different model — no new key, no new config.
model          = "claude-opus-5"
model_provider = "kunavo"

[model_providers.kunavo]
name     = "kunavo"
base_url = "https://api.kunavo.com/v1"
env_key  = "KUNAVO_API_KEY"
wire_api = "responses"

La puerta de enlace traduce la solicitud de Responses a la API Anthropic Messages y vuelve a traducir la respuesta al formato Responses. Una salvedad importante: Codex envía elementos opacos reasoning que solo puede consumir un modelo nativo de Responses, y estos se descartan al enviarlos a un upstream que no sea GPT. El modelo pierde su bloc de notas privado de la ronda anterior; la transcripción visible con la que trabaja permanece intacta. En la práctica, esto reduce un poco la continuidad en cadenas largas de razonamiento y no afecta en absoluto a los ciclos normales de editar-ejecutar-corregir.

Que sea una buena idea es una cuestión distinta de que funcione. Si quieres Claude específicamente, Claude Code está diseñado para ello y pasa cache_control sin traducir. Pero si prefieres el aislamiento de Codex CLI y quieres utilizar Claude detrás de él, esa combinación está disponible.

Cuánto cuesta una sesión

Las CLI agénticas reenvían el prompt del sistema, el historial de la tarea y el contexto actualizado de los archivos en cada paso, por lo que los tokens se acumulan más rápido de lo que sugiere el número de pasos. Un paso típico utiliza aproximadamente 25.000 tokens de entrada y 1.200 de salida:

Como las tarifas de salida difieren mucho más entre familias de modelos que las de entrada, el trabajo con mucha salida cambia el orden de clasificación: introduce tus propios números en la calculadora de costes en lugar de confiar en un único ejemplo calculado. Las solicitudes fallidas no se facturan.

Cuándo conviene más la ruta de la clave de API que una suscripción

Un plan de ChatGPT incluye el uso de Codex por una tarifa mensual fija; una clave de API factura solo lo que ejecutas. La ruta de la clave resulta ventajosa cuando programas por rachas en lugar de a diario, cuando quieres límites de gasto por clave y visibilidad del uso en lugar de una asignación opaca, o cuando quieres un modelo que la suscripción no ofrece. Pierde ventaja si eres un usuario intensivo diario: con ese volumen, es difícil superar una tarifa fija. Las rutas no son excluyentes: los perfiles de Codex permiten conservar ambas y cambiar entre ellas según la tarea.

Solución de problemas

Preguntas frecuentes