Codex CLI: Una introducción práctica

Anteriormente presentamos Claude Code. Este capítulo cubre otra herramienta de codificación con IA en terminal igualmente potente: Codex CLI.

Nota: Codex también tiene una versión de aplicación de escritorio (interfaz gráfica), que se cubrirá en un capítulo posterior. Este capítulo se centra en Codex CLI basado en terminal.

Codex CLI basado en terminal, al igual que Claude Code, es un asistente de codificación con IA que se ejecuta en la terminal. Si ya aprendiste Claude Code en el capítulo anterior, te resultará muy fácil aprender Codex CLI, ya que la lógica operativa es casi idéntica.

¿Qué es Codex CLI?

Introducción en una frase

Codex CLI = Asistente de codificación con IA en terminal de OpenAI

Similar a Claude Code, es una herramienta de IA que se ejecuta en la terminal. Le dices lo que quieres en lenguaje natural y puede ayudarte a:

• Crear nuevos proyectos
• Escribir código
• Modificar código
• Corregir errores
• Ejecutar comandos
• Buscar en la web la información más reciente

¿Cuál es la diferencia entre Codex CLI y Claude Code?

Diferencia principal: diferentes modelos subyacentes. Claude Code usa modelos Claude, Codex CLI usa el modelo GPT-5-Codex de OpenAI optimizado para programación. Ambas herramientas tienen sus puntos fuertes. Se recomienda instalar ambas y elegir según la tarea.

¿Cómo instalar Codex CLI?

Requisitos previos

1. Node.js: Al igual que Claude Code, requiere el entorno Node.js

   • Si ya lo tienes (por haber instalado Claude Code antes), no necesitas reinstalarlo
   • Si no, ve a https://nodejs.org y descarga la versión LTS

2. Red: Necesitas acceso a los servicios de OpenAI (puede requerir un proxy)

Pasos de instalación

Abre la terminal y ejecuta:

npm install -g @openai/codex

Espera a que termine.

Verificar la instalación:

codex --version

Si muestra un número de versión (por ejemplo, codex-cli 0.98.0), la instalación fue exitosa.

Los usuarios de Mac también pueden instalar mediante Homebrew:

brew install codex

Varias formas de usarlo

Al igual que Claude Code, Codex CLI admite múltiples formas de acceder a las capacidades de IA.

Método 1: Comprar membresía de ChatGPT (la más sencilla)

Codex CLI está incluido en los planes de pago de ChatGPT.

Tipos de membresía compatibles:

Configuración:

1. Después de comprar la membresía de ChatGPT, abre la terminal
2. Ejecuta codex para iniciar
3. Sigue las indicaciones para iniciar sesión en tu cuenta de ChatGPT (se abrirá un navegador para la autorización)
4. Una vez iniciada la sesión, puedes usarlo

También puedes iniciar sesión manualmente:

codex login

Método 2: Usar una clave de API de OpenAI

Si tienes una clave de API de OpenAI, puedes usarla directamente:

1. Establece la variable de entorno:

export OPENAI_API_KEY="your API Key"

2. Luego ejecuta codex

Método 3: Usar API de terceros (integración de modelos nacionales)

¡Esto es lo que más les importa a muchos usuarios nacionales!

Al igual que Claude Code, Codex CLI también puede integrarse con APIs de terceros, como DeepSeek, Volcengine y otros modelos nacionales.

La configuración se realiza modificando el archivo ~/.codex/config.toml (detallado en la siguiente sección).

Integración de modelos nacionales: Modificar config.toml

¿Dónde está config.toml?

Ruta del archivo de configuración: ~/.codex/config.toml

• Mac/Linux: /Users/tunombredeusuario/.codex/config.toml
• Windows (WSL): ~/.codex/config.toml

Consejo: Si este archivo no existe, ejecuta codex primero; creará automáticamente la carpeta .codex. Luego puedes crear manualmente el archivo config.toml.

Estructura básica de configuración

La configuración de config.toml se divide en varias partes principales:

# ===== Basic settings =====
model = "gpt-5.3-codex"              # Model to use
model_provider = "openai"             # Model provider (default openai)
approval_policy = "on-failure"        # Approval policy
sandbox_mode = "workspace-write"      # Sandbox mode

# ===== Custom model providers =====
[model_providers.custom_name]
name = "Display name"
base_url = "API URL"
env_key = "API_KEY environment variable name"
wire_api = "responses"

# ===== Profiles =====
[profiles.profile_name]
model_provider = "custom_name"
model = "model name"

Importante: wire_api debe usar “responses”

¡Esto es un error común!

Codex CLI admite dos protocolos de API: "chat" (Chat Completions heredado) y "responses" (nueva API Responses).

A partir de febrero de 2026, OpenAI ha dejado de usar el protocolo "chat" y ha cambiado completamente a "responses". Por lo tanto, al configurar modelos de terceros, wire_api debe establecerse en "responses". Si tu proveedor de API de terceros no admite el formato de API Responses, no puedes integrarlo directamente con Codex.

Afortunadamente, las principales plataformas de retransmisión de API (como OpenRouter, etc.) ya admiten la API Responses.

Para una discusión detallada, consulta: https://github.com/openai/codex/discussions/7782

Práctica: Integrar DeepSeek

Usando DeepSeek como ejemplo, así es como se configura:

Paso 1: Editar config.toml

# Default to DeepSeek
model_provider = "deepseek"
model = "deepseek-chat"

# Define DeepSeek provider
[model_providers.deepseek]
name = "DeepSeek"
base_url = "https://api.deepseek.com/v1"
env_key = "DEEPSEEK_API_KEY"
wire_api = "responses"

Paso 2: Establecer variable de entorno

Establece tu clave de API de DeepSeek en la terminal:

export DEEPSEEK_API_KEY="your DeepSeek API Key"

Para hacerlo permanente, agrega la línea al final de tu ~/.zshrc (Mac) o ~/.bashrc (Linux):

echo 'export DEEPSEEK_API_KEY="your DeepSeek API Key"' >> ~/.zshrc
source ~/.zshrc

Paso 3: Iniciar Codex

codex

Ahora Codex usará el modelo DeepSeek.

Nota: Si la API oficial de DeepSeek aún no admite el formato de API Responses y causa fallos de conexión, puedes cambiar a una plataforma de retransmisión que admita Responses API (como OpenRouter) y cambiar base_url a la dirección de la plataforma de retransmisión.

Práctica: Integrar Volcengine (Doubao)

model_provider = "volcengine"
model = "doubao-pro-32k"

[model_providers.volcengine]
name = "Volcengine"
base_url = "https://ark.cn-beijing.volces.com/api/v3"
env_key = "VOLCENGINE_API_KEY"
wire_api = "responses"

También es necesario establecer la variable de entorno:

export VOLCENGINE_API_KEY="your Volcengine API Key"

Usar perfiles para cambiar entre varios modelos

Si has configurado varios modelos, puedes usar perfiles para cambiar rápidamente:

# Default to OpenAI
model_provider = "openai"
model = "gpt-5.3-codex"

# Define DeepSeek provider
[model_providers.deepseek]
name = "DeepSeek"
base_url = "https://api.deepseek.com/v1"
env_key = "DEEPSEEK_API_KEY"
wire_api = "responses"

# Define Volcengine provider
[model_providers.volcengine]
name = "Volcengine"
base_url = "https://ark.cn-beijing.volces.com/api/v3"
env_key = "VOLCENGINE_API_KEY"
wire_api = "responses"

# DeepSeek profile
[profiles.ds]
model_provider = "deepseek"
model = "deepseek-chat"

# Volcengine profile
[profiles.volc]
model_provider = "volcengine"
model = "doubao-pro-32k"

Cambiar al usarlo:

# Use default OpenAI
codex

# Use DeepSeek
codex --profile ds

# Use Volcengine
codex --profile volc

¡Esto te permite cambiar libremente entre diferentes modelos, muy conveniente!

Un método más simple: OPENAI_BASE_URL

Si solo quieres usar temporalmente una API de terceros sin modificar config.toml, puedes establecer directamente las variables de entorno:

export OPENAI_BASE_URL="https://api.deepseek.com/v1"
export OPENAI_API_KEY="your DeepSeek API Key"
codex

Este método es más simple, pero deja de ser válido al cerrar la terminal.

¿Cómo usar Codex CLI?

Inicio básico

Igual que Claude Code:

1. Abre la terminal
2. Usa cd para navegar a tu carpeta de proyecto
3. Escribe codex y presiona Enter

cd /path/to/your/project
codex

Codex iniciará una interfaz de terminal a pantalla completa donde puedes comenzar a ingresar tus requisitos.

Tres modos de operación

Codex CLI tiene tres modos que controlan su “nivel de autonomía”:

Se recomienda a los principiantes usar el modo Suggest (predeterminado), para que puedas ver lo que Codex hace en cada paso.

Después de familiarizarte, puedes usar el modo Full Auto:

codex --full-auto "Run tests and fix all failing cases"

Asignación directa de tareas (modo no interactivo)

También puedes agregar directamente una descripción de tarea después del comando:

codex "Create a Snake game for me"

De esta manera, Codex comenzará a ejecutar la tarea directamente sin necesidad de ingresar a la interfaz interactiva.

Reanudar conversación anterior

Similar a --resume de Claude Code, Codex también admite reanudar sesiones anteriores:

codex resume

Esto te permite continuar desde donde lo dejaste.

Práctica: Haz que Codex cree un juego de Snake para nosotros

Paso 1: Crear carpeta de proyecto

1. Crea una nueva carpeta en el escritorio, por ejemplo, codex-demo
2. Abre esta carpeta en la terminal

Paso 2: Iniciar Codex

codex

Paso 3: Ingresar requisitos

En Codex, ingresa:

Create a Snake game for me with the following requirements:

1. Features:
   - Classic Snake gameplay
   - Control snake movement with arrow keys
   - Snake grows longer when eating food, score increases
   - Game over when hitting wall or itself
   - Start and restart buttons

2. Interface:
   - Clean and beautiful, pixel style
   - Display current score and high score
   - Support dark theme

3. Technical requirements:
   - Use only HTML, CSS, JavaScript
   - All code in a single HTML file
   - Use Canvas for game rendering

Please create this HTML file directly.

Paso 4: Esperar a que Codex termine

Codex creará automáticamente el archivo HTML y escribirá todo el código. Dependiendo del modo que hayas elegido:

• Modo Suggest: Pedirá confirmación en cada paso; tú confirmas antes de que ejecute
• Modo Full Auto: Completará todo directamente

Paso 5: Abrir el juego

¡Haz doble clic en el archivo HTML generado para jugarlo en tu navegador!

Codex CLI vs Claude Code: ¿Cómo elegir?

Recomiendo instalar ambos. Cada uno tiene sus puntos fuertes:

Mi sugerencia:

• Instala ambos, elige el más adecuado según la tarea
• Proyectos simples: Ambos son capaces, elige cualquiera
• Proyectos complejos: Prueba uno primero; si el resultado no es bueno, cambia al otro
• Usuarios de modelos nacionales: Ambos admiten integración de API de terceros, configuración similar

La filosofía central sigue siendo: No necesitas saber programar, solo necesitas saber describir requisitos.

Resumen

Lo que aprendimos hoy:

1. Qué es Codex CLI: El asistente de codificación con IA en terminal de OpenAI, similar a Claude Code
2. Cómo instalarlo: npm install -g @openai/codex, un solo comando
3. Cómo usarlo: Misma lógica operativa que Claude Code, cd al directorio del proyecto y luego codex para iniciar
4. Integración de modelos nacionales: Modificar ~/.codex/config.toml, configurar model_providers
5. Tres modos: Suggest (conservador), Auto Edit (moderado), Full Auto (totalmente automático)
6. Cambio de perfil: Configurar varios modelos, usar el parámetro --profile para cambiar libremente

¡Ahora tienes dos potentes herramientas de codificación con IA: Claude Code y Codex CLI!