¿Cómo usar la CLI de OpenAI Codex con tu propia API Key?

La Codex CLI es una interfaz poderosa para interactuar con la IA desde tu terminal. Sin embargo, limitarse a un único proveedor restringe tu potencial.

Al conectar la CLI de Codex con Zeabur AI Hub, puedes enrutar tus consultas a cualquier modelo de primer nivel (como Claude、Grok o Gemini) utilizando exactamente la misma herramienta. Esta configuración funciona bajo un esquema de pago por uso (pay-as-you-go); no hay necesidad de gestionar múltiples suscripciones para diferentes proveedores de IA.

Aquí te explicamos cómo configurarlo.

🧱 Requisitos Previos

1. Instalar Codex CLI:

   npm install -g @openai/codex
   

2. Credenciales de Zeabur:

   • Ve a tu Zeabur Dashboard para obtener tu AI Hub API Key.

3. Elige tu Endpoint

   Zeabur actualmente ofrece dos endpoints. Elige el que esté geográficamente más cerca de ti:

   • Asia (Tokio): https://hnd1.aihub.zeabur.ai/
   • EE. UU. Oeste (San Francisco): https://sfo1.aihub.zeabur.ai/

---

⚙️ Guía de Configuración Rápida

Necesitas configurar Codex para que hable con la API unificada de Zeabur en lugar de hacerlo directamente con un proveedor específico.

1. Crear el Archivo de Configuración

Crea o edita el archivo de configuración en ~/.codex/config.toml. Pega la siguiente configuración para definir a Zeabur como proveedor:

# Modelo por defecto a usar
model = "gemini-3-pro-preview"
model_provider = "zeabur"

[model_providers.zeabur]
name = "Zeabur AI Hub"
# Nota: Asegúrate de añadir /v1 al endpoint
base_url = "<https://hnd1.aihub.zeabur.ai/v1>"
env_key = "ZEABUR_API_KEY"
wire_api = "chat"

2. Configurar tu API Key

Necesitas hacer que tu clave API esté disponible para la herramienta.

Opción A: Solo para probar (Temporal)

Para uso en una sola sesión:

export ZEABUR_API_KEY="tu-api-key-de-zeabur"
codex "Who are you?"

Opción B: Configúralo y olvídate (Permanente)

Para evitar configurar la clave cada vez, añádela a tu perfil de shell.

1. Abre la configuración de tu shell (ej. ~/.zshrc o ~/.bashrc):

   nano ~/.zshrc
   

2. Pega esta línea al final:

   export ZEABUR_API_KEY="tu-api-key-de-zeabur"
   

3. Guarda y recarga: source ~/.zshrc

---

💸 Empieza a Programar (Con cualquier modelo)

Ahora puedes usar la herramienta CLI con la flexibilidad de cambiar modelos sobre la marcha.

Uso Básico:

codex "Write a hello world function in Python"

Cambiando Modelos:

Puedes anular el modelo por defecto definido en tu configuración usando la bandera -m.

# Usar Gemini
codex -m gemini-3-pro-preview "hi"

# Usar Claude
codex -m claude-sonnet-4-20250514 "hi"

# Usar GPT-4o
codex -m gpt-4o "hi"

Por qué esto es mejor:

• Flexibilidad: Cambia entre Grok, Claude y GPT sin cambiar de herramientas.
• Eficiencia de Costos: Paga solo por los tokens que uses a través de Zeabur, en lugar de pagar tarifas mensuales fijas para múltiples suscripciones de IA.

---

🔧 Solución de Problemas (Troubleshooting)

Si encuentras problemas:

• 401 Unauthorized:
  • Verifica que base_url en tu configuración incluya /v1.
  • Verifica que tu variable de entorno esté configurada: echo $ZEABUR_API_KEY.
• Model Not Found:
  • Asegúrate de que el nombre del modelo (ej. gpt-4o) sea compatible actualmente con Zeabur AI Hub. Revisa el dashboard de Zeabur para ver la lista de IDs de modelos disponibles.

¡Feliz Código!