Codex CLI con clave de API — configuración, modelos y coste de sesión

Codex CLI es el agente de código de terminal de código abierto de OpenAI, y funciona tanto iniciando sesión con ChatGPT como con una clave de API. La ruta de clave es la que conviene entender: cobra por token, sin cuota mensual, y es la única que permite apuntar la CLI a otro proveedor o a otra familia de modelos. Esta guía incluye la configuración que funciona, el requisito que hace fallar a la mayoría de las puertas de enlace, cuánto cuesta una sesión y cómo pagar la API desde Brasil mediante Pix.

El único requisito que importa

Codex CLI utiliza la Responses API de OpenAI, y solo esa API: el bloque model_providers solo acepta wire_api = "responses". Una puerta de enlace que ofrezca únicamente /v1/chat/completions simplemente no se puede configurar; por eso muchos endpoints «compatibles con OpenAI» fallan aquí. Kunavo ofrece POST /v1/responses junto con el endpoint de chat, así que el bloque siguiente funciona sin adaptación.

La configuración

# ~/.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"

env_key es el nombre de la variable de entorno, no la clave: Codex nunca guarda la clave en el archivo de configuración.

# O Codex lê a chave da variável indicada em env_key.
export KUNAVO_API_KEY="sk-kn-..."     # crie em kunavo.com/app/keys

# Deixe persistente (escolha o arquivo que o seu shell realmente carrega):
echo 'export KUNAVO_API_KEY="sk-kn-..."' >> ~/.zshrc

codex "explique a estrutura deste repositório"

Crea la clave en el panel después de registrarte y recargar $10; se muestra una sola vez.

Pagar desde Brasil: Pix, sin tarjeta internacional

Para el desarrollador brasileño, el obstáculo rara vez es el archivo TOML: es el método de pago. Pagar OpenAI API directamente requiere una tarjeta de crédito internacional habilitada para compras en el extranjero. En Kunavo, el checkout se procesa mediante Stripe y Pix aparece como método de pago para quienes pagan desde Brasil: importe en reales y compensación inmediata. Las tarjetas internacionales (Visa, Mastercard, American Express), Apple Pay y Google Pay siguen disponibles para quienes las prefieran.

Las tarifas por token se definen en USD: con Pix, Stripe muestra la conversión a reales en el momento del pago; con tarjeta, la conversión sigue el tipo de cambio del emisor (comprueba el IOF y la comisión por transacción internacional en la aplicación del banco). El procedimiento paso a paso para recargar mediante Pix está en la guía sobre cómo pagar la API con Pix. La billetera es prepago: recarga mínima de $10, sin suscripción ni renovación automática, y con saldo que nunca caduca.

Qué modelo usar

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

Ejecutar modelos Claude en Codex CLI

Esto suele sorprender: Codex CLI está vinculado al protocolo, no al modelo. Utiliza el formato Responses y cualquier modelo de chat detrás de ese endpoint puede responder. Apúntalo a claude-opus-5 y funcionará de principio a fin, incluidas las llamadas a herramientas, por lo que el agente seguirá leyendo archivos, proponiendo ediciones y ejecutando comandos.

# Mesmo bloco de provider, outro modelo — sem chave nova, sem config nova.
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 Responses a la API nativa Anthropic Messages y devuelve la respuesta al formato Responses. Una salvedad honesta: Codex envía elementos reasoning opacos que solo un modelo nativo de Responses puede consumir, y se descartan al pasar a un upstream que no sea GPT. El modelo pierde el borrador privado del turno anterior; la transcripción visible de la que parte permanece intacta. En la práctica, esto resta algo de continuidad en cadenas largas de razonamiento, pero no afecta a los ciclos habituales de editar-ejecutar-corregir.

Si quieres Claude específicamente, Claude Code está diseñado para ello y transmite cache_control sin traducción. Pero si prefieres el sandbox de Codex CLI y quieres ejecutar Claude detrás de él, la combinación existe.

Cuánto cuesta una sesión

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

En otras palabras: una recarga de $10 mediante Pix cubre aproximadamente 8 tareas agénticas de 20 pasos. Y las solicitudes fallidas no se cobran: un 5xx en mitad de una sesión no aparece como una línea en la factura.

Cuando algo no funciona

Antes de culpar a Codex, demuestra que la clave y el endpoint responden:

# Confirme a chave e o endpoint antes de culpar o 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": "Responda OK e nada mais."
  }'

• 404: el proveedor no implementa /v1/responses o base_url ya incluye /responses. Codex añade la ruta por sí solo: la base termina en /v1.
• 401: la variable indicada en env_key está vacía en el shell que abrió Codex. Compruébalo con echo $KUNAVO_API_KEY en ese mismo terminal.
• 402: saldo insuficiente; recarga en billing (el Pix se acredita al instante).
• model_not_found: el slug del modelo no existe en el catálogo; compruébalo en /models.

Preguntas frecuentes