Tutorial de Codex — instalar Codex CLI, usar una clave API sin suscripción y cuánto cuesta cada tarea

Codex es el agente de programación (coding agent) de IA de OpenAI. Su uso básico consiste en instalar Codex CLI en el terminal (npm install -g @openai/codex), ejecutarlo en la carpeta del proyecto que quieres procesar (codex) y decirle en chino qué debe hacer. Hay dos formas de empezar: iniciar sesión con un plan de ChatGPT (Plus, Pro, Business, etc.) y usar su cuota, o ejecutarlo con una clave de API y pagar por los tokens utilizados. Casi todas las guías en chino solo cubren la primera opción; esta explica la segunda: cómo ejecutar Codex CLI sin suscripción, elegir el modelo según la tarea y calcular cuánto cuesta realmente una tarea.

Codex no es una herramienta para pegar código en una ventana de chat, sino un agente que lee archivos, los modifica y ejecuta pruebas y comandos dentro del proyecto. Configura con /permissions qué acciones puede realizar directamente sin confirmación después de iniciarlo.

Dos formas de usar Codex

Cuando se ejecuta con una clave de API, el coste se calcula por separado de la cuota del plan de ChatGPT. También puedes usar directamente una clave de API de OpenAI, pero esta guía explica cómo conectarlo a un endpoint compatible con Responses API: una misma clave permite cambiar entre GPT-6 Astra y GPT-5.6 Terra. Por ejemplo, el precio oficial de OpenAI para GPT-5.6 Sol es $5.00 / $30.00(OpenAI lo ofrece actualmente a un precio promocional de $4.00 / $20.00, y la página oficial de precios indica que este precio se mantendrá al menos hasta 21 de noviembre de 2026), mientras que aquí es $2.00 / $12.00 por cada 1M de tokens (las tarifas se leen directamente del catálogo del sitio, no se introducen manualmente).

Instalar Codex CLI: npm o Homebrew

# npm（有 Node.js 就能用，macOS / Linux / Windows 通用）
npm install -g @openai/codex

# Homebrew（macOS）
brew install --cask codex

Ambos son métodos de instalación oficiales del README de OpenAI; en Windows también se puede instalar con la misma instrucción npm. Después de instalarlo, escribe codex en la carpeta del proyecto para iniciarlo. Si vas a iniciar sesión con ChatGPT, aquí termina el proceso y puedes omitir la configuración siguiente.

Ejecutarlo con una clave de API: añadir un bloque a config.toml

Primero registra una cuenta, recarga desde $10 y crea una clave en la página de claves de API. La clave solo se muestra una vez, así que guárdala de inmediato. Después, añade un bloque de proveedor al archivo de configuración de Codex:

# ~/.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"        # 唯一有效的值，省略也一樣

Lo más fácil de escribir mal es env_key: aquí debes introducir el nombre de la variable de entorno que contiene la clave, no la clave en sí. La clave no aparece en el archivo de configuración, por lo que puedes enviar config.toml a git o pegarlo en un foro para pedir ayuda.

# 把金鑰放進 env_key 指定名稱的變數（金鑰以 sk-kn- 開頭）
export KUNAVO_API_KEY="sk-kn-..."

# 寫進 shell 的設定檔，就不必每次都 export
echo 'export KUNAVO_API_KEY="sk-kn-..."' >> ~/.zshrc

En PowerShell de Windows puedes ejecutar setx KUNAVO_API_KEY sk-kn-... y después abrir un terminal nuevo; la ubicación del archivo de configuración es %USERPROFILE%\.codex\config.toml. Antes de iniciar Codex, haz una solicitud para confirmar que la clave y el endpoint funcionan; así será más fácil localizar el origen de los errores posteriores.

# 懷疑 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": "只回 OK"}'

Si devuelve JSON, la clave y el endpoint funcionan correctamente; el problema restante está en config.toml. Las explicaciones de cada campo de configuración están en Documentación de integración de Codex CLI (inglés); el método para llamar a modelos Claude desde Codex también está en Guía de claves de API de Codex CLI (inglés).

La primera tarea

# 1. 進到要處理的專案資料夾，啟動 Codex
cd ~/work/my-app
codex

# 2. 讓它產生 AGENTS.md 草稿（寫測試怎麼跑、專案規則的檔案）
> /init

# 3. 之後直接用中文交代。附上檔名，做得更快也更省
> src/utils/date.test.ts 一直失敗，找出原因修好，並確認測試通過

El AGENTS.md generado por /init es un archivo que describe «reglas que no se pueden deducir leyendo el código»: cómo ejecutar las pruebas, qué bibliotecas usar y qué rutas no modificar. Se carga automáticamente en cada sesión de trabajo. El contenido generado es solo un borrador; recuerda revisarlo y editarlo.

El consejo para dar instrucciones es el mismo que con Claude Code: incluye nombres y rutas de archivos y no envíes las tareas grandes de una sola vez. Reducirás los tokens usados en la exploración, obtendrás resultados más rápidos y precisos y también bajará la factura.

Elegir el modelo según la tarea: coste real de una tarea

La mayor ventaja de ejecutar con una clave de API es que puedes elegir el modelo según la dificultad del trabajo. model es solo el nombre del modelo en el endpoint; cambiar de modelo no requiere una clave nueva ni configuración adicional.

# config.toml 的預設（gpt-5-6-sol）不動，只有這次啟動換模型
codex -m gpt-6-astra     # 找不到原因的 bug、跨模組的修改
codex -m gpt-5-6-terra   # 例行修改、大量取代、整理日誌這類輕量工作

El cálculo de «una tarea» considera 20 pasos para corregir una prueba fallida. Cada paso tiene 25.000 tokens de entrada (prompt del sistema + historial de conversación + archivos leídos) y 1.200 tokens de salida (una modificación o explicación), por lo que una tarea equivale a 500.000 tokens de entrada y 24.000 de salida. Con GPT-5.6 Sol son aproximadamente $1.29; por el mismo número de tokens pagado directamente a OpenAI, al precio promocional actual serían $2.48 (al precio de lista, $3.22). Cuanto más barato sea el modelo, más probable es que necesite más intercambios para corregir el problema, así que en la práctica conviene subir un nivel si no se resuelve al primer intento.

Este cálculo no incluye la caché. Codex vuelve a enviar el historial en cada paso; las entradas que alcanzan la caché se cobran a 0,10 veces el precio de entrada (GPT-5.6 Sol cuesta $0.20 por cada 1M de tokens), mientras que la parte nueva escrita en la caché cuesta 1,25 veces el precio de entrada. Además, en la serie GPT-5.6 y GPT-6 Astra, cuando el prompt de una solicitud individual supera los 272K tokens, toda la solicitud se cobra a 2 veces la entrada y 1,5 veces la salida. Por eso conviene no acumular demasiado trabajo en una misma sesión y abrir una nueva sesión para cada tarea. Los tokens de razonamiento se cobran como salida; cuanto más difícil es el problema, mayor es la salida. Consulta usage y el registro de uso de la respuesta para conocer el importe real. Las especificaciones del modelo están en Página del modelo GPT-5.6 Sol; las tarifas de todos los modelos, en la tabla de precios.

Errores frecuentes

Sinceramente: cuándo resulta más rentable un plan de ChatGPT

Si pasas varias horas al día conversando con Codex, el plan de cuota mensual fija suele ser más barato. El pago por uso es proporcional a los tokens; cuanto mayor y más estable sea el uso, mayor será la ventaja de la cuota mensual. El punto de equilibrio es «cuota mensual ÷ precio de una tarea»; el punto de equilibrio entre planes ya está calculado en la página Coste de Codex.

Hay otros dos aspectos que conviene saber. Según la documentación de OpenAI, las funciones que dependen del espacio de trabajo o de los servicios en la nube de ChatGPT pueden estar limitadas o no estar disponibles al usar una clave de API. Además, la ruta de Kunavo utiliza capacidad compartida: no incluye cuota dedicada ni un SLA garantizado por contrato. Si necesitas cuota o SLA garantizados, es más adecuado contratar directamente con OpenAI.

En cambio, la clave de API es adecuada para quienes tienen un uso variable, quieren elegir el modelo según la tarea, necesitan separar límites y registros de uso por clave en un equipo o solo quieren continuar trabajando el día en que agotan la cuota del plan. Puedes usar ambas opciones: elimina la línea model_provider de config.toml para volver al inicio de sesión de ChatGPT; si quieres cambiar en cada inicio, usa --profile de Codex.

Paga con una tarjeta internacional (incluida JCB), Apple Pay o Google Pay; en Taiwán no hay métodos de pago locales: JKoPay y LINE Pay no están disponibles. Con el prepago solo se cobra una vez al recargar, el saldo no caduca y las solicitudes fallidas no se facturan. Si dudas entre Codex y Claude Code, consulta Claude Code vs Codex CLI (en inglés); para saber cómo se calcula el coste de Claude Code, consulta Coste de Claude Code.

Preguntas frecuentes