Cómo usar Google Gemini 2.5 Pro con Open Codex CLI (Open Codex CLI)

Open Codex CLI es una herramienta de código abierto que lleva el poder de los grandes modelos de lenguaje (LLMs) directamente a tu flujo de trabajo en la terminal. Esta guía se centra específicamente en aprovechar uno de los modelos más avanzados disponibles hoy en día – Google's Gemini 2.5 Pro – dentro del entorno de Open Codex CLI.

Open Codex CLI es un fork del original OpenAI Codex CLI, manteniendo su funcionalidad central pero ampliando significativamente sus capacidades al agregar soporte para múltiples proveedores de IA, incluyendo Google Gemini. Esto permite a los desarrolladores elegir el mejor modelo para su tarea mientras permanecen en su interfaz de terminal familiar. Imagina hacer preguntas complejas de codificación, generar código base, refactorizar funciones existentes, explicar scripts complejos o incluso orquestar comandos de construcción, todo impulsado por la inteligencia de Gemini sin salir de tu línea de comandos.

Este artículo proporciona una guía completa, paso a paso, para instalar, configurar y usar Open Codex CLI específicamente con Google Gemini 2.5 Pro (refiriéndose a la gemini-2.5-pro-preview-03-25 versión del modelo disponible en el momento de escribir, como se especifica en la configuración de Open Codex CLI) y sus modelos hermanos como gemini-2.0-flash. Ya seas un desarrollador experimentado que busca optimizar su flujo de trabajo o nuevo en asistentes de codificación de IA, aprenderás a aprovechar esta poderosa combinación.

¿Por qué Open Codex CLI con Gemini?

Esto es increíble. En solo unas pocas horas, mi amigo bifurcó Open AI Codex para trabajar con Gemini 2.5 Pro 🤯 pic.twitter.com/gENT01q82P

— Sawyer Hood (@sawyerhood) 17 de abril de 2025

Combinar Open Codex CLI con Gemini 2.5 Pro ofrece un conjunto convincente de beneficios:

• Flujo de Trabajo Nativo de Terminal: Para los desarrolladores que prefieren la línea de comandos, Open Codex CLI proporciona una integración fluida. No es necesario cambiar de contexto entre tu editor, terminal y una ventana de navegador separada para asistencia de IA. Esto conduce a una iteración más rápida y menos interrupciones.
• Código Abierto y Flexible: Al ser de código abierto (open-codex en npm), la herramienta ofrece transparencia y el potencial para contribuciones de la comunidad. Su soporte de múltiples proveedores (Gemini, OpenAI, OpenRouter, Ollama) te brinda la flexibilidad de cambiar modelos o proveedores según sea necesario sin cambiar tus herramientas centrales.
• Potentes Capacidades de IA: Gemini 2.5 Pro aporta capacidades de razonamiento, generación de código y comprensión de última generación. Esto permite realizar tareas más complejas, mejores sugerencias de calidad de código y un análisis más profundo directamente dentro de la CLI.
• Orientado a la Acción: A diferencia de los chatbots simples, Open Codex CLI está diseñado para la acción. Puede leer tus archivos locales para obtener contexto, proponer modificaciones de archivos (parches) y ejecutar comandos de shell dentro de un entorno seguro, habilitando un verdadero desarrollo impulsado por chat.
• Enfoque en la Seguridad: La CLI incorpora mecanismos de sandboxing (Apple Seatbelt en macOS, Docker recomendado en Linux) para ejecutar operaciones potencialmente arriesgadas como comandos de shell de forma segura, especialmente al usar modos de aprobación automática. Ejecuta comandos deshabilitados de red y en un entorno de directorio aislado por defecto en modos de mayor autonomía.
• Integración con Control de Versiones: La herramienta está diseñada para trabajar junto a Git. Por defecto, requiere aprobación antes de modificar archivos, permitiéndote revisar los cambios antes de que afecten tu directorio de trabajo, asegurando que siempre tengas una red de seguridad.

Requisitos Previos

Antes de comenzar, asegúrate de tener lo siguiente:

1. Sistema Operativo: macOS 12 o más reciente, una distribución moderna de Linux (como Ubuntu 20.04+, Debian 10+), o Windows 10/11 usando el Subsistema de Windows para Linux (WSL2). No hay soporte directo para Windows.
2. Node.js: Se requiere la versión 22 o más reciente. Las versiones LTS (Soporte a Largo Plazo) son generalmente recomendadas. Puedes verificar tu versión ejecutando node -v en tu terminal. Descarga Node.js desde nodejs.org.
3. Cuenta de Google Cloud & Clave API de Gemini: Necesitarás una clave API para autenticar las solicitudes a los modelos de Gemini. Puedes obtener una a través de Google AI Studio o la Consola de Google Cloud. Mantén esta clave segura, ya que está vinculada a tu cuenta.
4. Familiaridad con la Terminal: Se asume un conocimiento básico de uso de la interfaz de línea de comandos de tu sistema (Terminal, iTerm, Bash, Zsh, etc.).

Paso 1: Instalando Open Codex CLI

La forma recomendada de instalar Open Codex CLI es globalmente a través de npm (Node Package Manager), que viene incluido con Node.js. Abre tu terminal y ejecuta:

npm install -g open-codex

Alternativamente, si usas Yarn como tu gestor de paquetes, puedes ejecutar:

yarn global add open-codex

Este comando descarga el paquete open-codex y hace que el comando open-codex sea accesible desde cualquier lugar en tu terminal. Evita usar sudo para instalaciones globales de npm; si encuentras problemas de permisos, es mejor solucionar los permisos de npm.

Puedes verificar la instalación ejecutando open-codex --version o open-codex --help.

Paso 2: Configurando el Acceso a Gemini

Para usar los modelos de Gemini, Open Codex CLI necesita tu clave API y necesitar saber que quieres usar el proveedor gemini. Hay dos maneras principales de configurar esto:

Método 1: Variable de Entorno (Recomendado para Inicio Rápido/Pruebas)

La forma más sencilla de proporcionar tu clave API es a través de una variable de entorno. Open Codex CLI busca específicamente GOOGLE_GENERATIVE_AI_API_KEY cuando se selecciona el proveedor gemini.

En tu terminal, ejecuta el siguiente comando, reemplazando "YOUR_API_KEY_HERE" con tu clave API de Gemini real:

export GOOGLE_GENERATIVE_AI_API_KEY="YOUR_API_KEY_HERE"

Importante: Este comando establece la variable de entorno solo para la sesión actual de terminal. Si cierras la terminal o abres una nueva, necesitarás ejecutar el comando nuevamente.

Para hacer que la clave API esté disponible de forma permanente, necesitas agregar la línea export al archivo de configuración de tu shell. Los archivos comunes incluyen:

• ~/.zshrc (para Zsh, el predeterminado en las versiones recientes de macOS)
• ~/.bashrc o ~/.bash_profile (para Bash)

Agrega la línea export GOOGLE_GENERATIVE_AI_API_KEY="YOUR_API_KEY_HERE" al archivo correspondiente, guárdalo y luego reinicia tu terminal o ejecuta source ~/.zshrc (o la ruta de archivo relevante) para aplicar los cambios.

Luego puedes especificar a Gemini como el proveedor en cada invocación usando el flag --provider:

open-codex --provider gemini "¿Cuál es la capital de Francia?"

Método 2: Archivo de Configuración (Recomendado para Configuración Persistente)

Para una configuración más permanente, especialmente si planeas usar Gemini de manera consistente, puedes usar el archivo de configuración de Open Codex CLI. La CLI busca un archivo de configuración en ~/.codex/config.json.

Crea el directorio si no existe: mkdir -p ~/.codex

Crea y abre el archivo de configuración: nano ~/.codex/config.json (o usa tu editor de texto preferido).

Agrega el siguiente contenido JSON para especificar a Gemini como el proveedor predeterminado:

{
  "provider": "gemini"
}

También puedes opcionalmente establecer un modelo predeterminado de Gemini. Open Codex CLI define gemini-2.5-pro-preview-03-25 como el modelo "agente" predeterminado y gemini-2.0-flash como el modelo "de contexto completo" predeterminado para Gemini. Para establecer explícitamente el poderoso modelo 2.5 Pro como el predeterminado para la mayoría de las interacciones, usa:

{
  "provider": "gemini",
  "model": "gemini-2.5-pro-preview-03-25"
}

Guarda el archivo y sal del editor.

Crucialmente, incluso al usar el archivo de configuración para establecer el proveedor y modelo, todavía necesitas establecer la variable de entorno GOOGLE_GENERATIVE_AI_API_KEY como se describe en el Método 1. El archivo de configuración le dice a la CLI qué proveedor usar, mientras que la variable de entorno proporciona las credenciales para ese proveedor.

Con el archivo de configuración establecido, ahora puedes simplemente ejecutar open-codex y se usará por defecto el proveedor de Gemini especificado:

open-codex "¿Cuál es la capital de Francia?"

Paso 3: Uso Básico con Gemini

Ahora que Open Codex CLI está instalado y configurado para Gemini, exploremos cómo interactuar con él.

Modo Interactivo (REPL)

Para una experiencia similar a un chat, ejecuta la CLI sin un prompt específico:

open-codex
# O si no has establecido el proveedor predeterminado en config.json:
# open-codex --provider gemini

Esto inicia un Bucle de Lectura-Evaluación-Impresión (REPL) donde puedes escribir prompts, obtener respuestas y tener una conversación continua con Gemini.

❯ open-codex --provider gemini
¡Bienvenido a Open Codex CLI! Escribe tu solicitud, luego presiona Enter dos veces para enviar.
> Háblame sobre el modelo Gemini 2.5 Pro.

Presiona Enter dos veces para enviar el prompt. Gemini responderá dentro de la terminal. Puedes continuar la conversación escribiendo preguntas de seguimiento.

Prompts Directos

Para solicitudes puntuales, puedes pasar el prompt directamente como un argumento. Si no has establecido los valores predeterminados en config.json, necesitarás el flag del proveedor. También puedes especificar el modelo exacto usando el flag --model o -m:

• Usando el modelo predeterminado de Gemini (si está establecido en config):

open-codex "Explica el concepto de cierres en Python."

• Especificando explícitamente el proveedor y modelo:

open-codex --provider gemini --model gemini-2.5-pro-preview-03-25 "Escribe un script bash para encontrar todos los archivos mayores de 10MB en el directorio actual y sus subdirectorios."

• Usando un modelo diferente de Gemini (por ejemplo, Flash para tareas potencialmente más rápidas/baratas):

open-codex --provider gemini --model gemini-2.0-flash "Resume los puntos principales de la documentación de React sobre hooks."

La CLI procesará la solicitud con Gemini e imprimirá la respuesta directamente en la salida estándar.

Paso 4: Aprovechando las Funciones de Open Codex con Gemini

El verdadero poder de Open Codex CLI radica en su capacidad para interactuar con tu entorno de desarrollo local, guiado por Gemini.

Interacción con el Sistema de Archivos

Gemini, a través de Open Codex CLI, puede leer archivos en tu proyecto actual para obtener contexto para tus solicitudes. También puede proponer cambios (escrituras o parches) a tus archivos.

• Lectura de Archivos: Cuando mencionas nombres de archivos en tu prompt, la CLI a menudo los lee automáticamente para proporcionar contexto a Gemini.

# Suponiendo que tienes un archivo llamado 'calculate.js'
open-codex --provider gemini "Lee 'calculate.js' y sugiere mejoras para la legibilidad."

• Escritura/Parcheo de Archivos: Si le pides a Gemini que modifique un archivo, la CLI generará un dif (un resumen de los cambios propuestos) y pedirá tu aprobación antes de aplicar cualquier cosa.

open-codex --provider gemini "Agrega una nueva función llamada 'subtract' a 'calculate.js' que tome dos argumentos y devuelva su diferencia."

La CLI mostrará los cambios propuestos y preguntará: ¿Aplicar parche? [y/N]. Presiona y para aceptar o n para rechazar.

Ejecutar Comandos

Open Codex CLI también puede ejecutar comandos de shell sugeridos por Gemini. Esto es poderoso pero requiere precaución.

• Modos de Aprobación: El flag --approval-mode (o -a) controla el nivel de autonomía:
• suggest (predeterminado): Requiere aprobación explícita para todos los cambios de archivos y todos los comandos de shell. Recomendado para comenzar.
• auto-edit: Aplica automáticamente los cambios de archivos pero aún pide aprobación para los comandos de shell.
• full-auto: Aplica automáticamente los cambios de archivos Y ejecuta comandos de shell (dentro del sandbox). Úsalo con extrema precaución, especialmente en repositorios no confiables.
• Sandboxing: En los modos auto-edit y full-auto, los comandos se ejecutan deshabilitados de red y confinados al directorio de trabajo actual y archivos temporales por razones de seguridad.
• Ejemplo (con el modo predeterminado 'suggest'):

open-codex --provider gemini "Instala la biblioteca 'requests' usando pip."

Gemini podría proponer el comando pip install requests. La CLI mostrará el comando y preguntará: ¿Ejecutar comando? [y/N].

Contexto del Proyecto (codex.md)

Puedes proporcionar instrucciones o contexto persistente sobre tu proyecto a Gemini creando archivos codex.md. La CLI lee estos archivos en orden:

1. ~/.codex/instructions.md (Instrucciones personales globales)
2. codex.md en la raíz de tu repositorio (Notas a nivel de proyecto)
3. codex.md en el directorio de trabajo actual (Notas específicas de subdirectorio)

Esto te permite guiar el comportamiento de Gemini o proporcionar información sobre estándares del proyecto, bibliotecas utilizadas, etc., sin repetirlo en cada prompt.

Solución de Problemas & Consejos

• Errores de Clave API: Asegúrate de que GOOGLE_GENERATIVE_AI_API_KEY esté correctamente establecido, exportado y accesible en tu sesión actual de terminal. Verifica si hay errores tipográficos.
• Modelo No Encontrado: Verifica que el nombre del modelo (gemini-2.5-pro-preview-03-25, gemini-2.0-flash, etc.) coincida con los que se admiten o están configurados. Revisa el ~/.codex/config.json o usa correctamente el flag --model.
• Errores de Proveedor: Asegúrate de que el proveedor esté establecido en gemini ya sea a través de config.json o el flag --provider gemini.
• Registro Verboso: Para depuración, ejecuta comandos con la variable de entorno DEBUG=true precedida: DEBUG=true open-codex --provider gemini "Mi prompt". Esto imprimirá información detallada de solicitud/respuesta.
• Comienza Simple: Comienza con prompts sencillos y aumenta gradualmente la complejidad a medida que te sientas cómodo con cómo interactúan Gemini y la CLI.
• Revisa las Aprobaciones Cuidadosamente: Especialmente al tratar con modificaciones de archivos o ejecución de comandos, siempre revisa los cambios o comandos propuestos antes de aprobarlos (respondiendo y).

Conclusión

Open Codex CLI, impulsado por Google Gemini 2.5 Pro, transforma tu terminal en un asistente de codificación inteligente. Siguiendo los pasos descritos en esta guía, puedes integrar sin problemas capacidades avanzadas de IA en tu flujo de trabajo diario de desarrollo, directamente desde la línea de comandos.

Desde fragmentos de código rápidos y explicaciones hasta refactorizaciones complejas y ejecución de scripts, esta combinación ofrece un potencial significativo para aumentar la productividad y agilizar tareas. El enfoque de la herramienta en la seguridad a través del sandboxing y las aprobaciones del usuario, combinado con la flexibilidad de soporte de múltiples proveedores y su naturaleza de código abierto, hacen de Open Codex CLI una opción convincente para los desarrolladores que buscan aprovechar la IA dentro de su terminal.

Experimenta con diferentes prompts, explora los varios modos de aprobación (¡con precaución!) y descubre cómo Gemini y Open Codex CLI pueden mejorar tu experiencia de codificación.