Cómo usar Codex — desde la instalación hasta usarlo con una clave API sin suscripción, incluido el coste real de una tarea

Codex es el agente de programación de OpenAI. Para usarlo básicamente, instala Codex CLI, que se ejecuta en el terminal (npm install -g @openai/codex), ejecuta codex en el repositorio de trabajo y solicita lo que necesites en coreano. Hay dos formas de empezar: iniciar sesión con un plan de ChatGPT (Plus · Pro · Business, etc.) y usarlo dentro del límite de uso, o ejecutarlo con una clave de API y pagar solo por los tokens utilizados. Como casi todos los artículos sobre el uso en Corea tratan únicamente el primer método, este artículo explica el segundo: la configuración para ejecutar Codex CLI sin suscripción, cómo elegir un modelo para cada tarea y el coste real de una tarea. Los límites por plan y las opciones cuando se agota el límite están resumidos aparte en Límites de uso de Codex.

Codex no es una herramienta para pegar código en una ventana de chat: es un agente que lee y modifica archivos dentro del repositorio y ejecuta pruebas y comandos. Después de ejecutarlo, puedes decidir qué delegar sin confirmación mediante /permissions.

Dos formas de usar Codex

Si lo ejecutas con una clave de API, la facturación se calcula por separado del uso del plan de ChatGPT. Puedes usar directamente una clave de API de OpenAI, pero este artículo explica cómo conectarse mediante un endpoint compatible con Responses API. Puedes cambiar con la misma clave desde GPT-6 Astra hasta GPT-5.6 Terra; por ejemplo, GPT-5.6 Sol cuesta $2.00 / $12.00 por 1M de tokens frente al precio oficial de OpenAI de $5.00 / $30.00(OpenAI lo ofrece actualmente a un precio promocional de $4.00 / $20.00, que, según la página de precios, se mantiene al menos hasta 21 de noviembre de 2026) (las tarifas se leen directamente del catálogo).

Instalar Codex: npm o Homebrew

# npm (Node.js만 있으면 macOS / Linux / Windows 공통)
npm install -g @openai/codex

# Homebrew (macOS)
brew install --cask codex

Ambos métodos de instalación aparecen en el README oficial de OpenAI. También puedes instalarlo en Windows con el comando npm. Cuando termine la instalación, ejecútalo escribiendo codex en el directorio del repositorio en el que trabajarás. Si vas a iniciar sesión con ChatGPT, aquí termina el proceso y no necesitas la configuración siguiente.

Obtener y configurar una clave de API de Codex: un bloque en config.toml

Primero regístrate y recarga desde $10; después crea una clave en la pantalla de claves de API. La clave solo se muestra una vez, así que guárdala inmediatamente. A continuación, 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"        # 유일하게 유효한 값. 생략해도 같습니다

El error más frecuente está en env_key. Lo que debes escribir aquí es el nombre de la variable de entorno que contendrá la clave, no la clave en sí. Como la clave no se incluye en el archivo de configuración, config.toml puede confirmarse o pegarse en una consulta con seguridad.

# env_key에 적은 이름의 변수에 키를 넣습니다 (키는 sk-kn-으로 시작)
export KUNAVO_API_KEY="sk-kn-..."

# 매번 export하지 않도록, 쓰는 셸의 설정 파일에 추가해 둡니다
echo 'export KUNAVO_API_KEY="sk-kn-..."' >> ~/.zshrc

Si usas Windows PowerShell, ejecuta setx KUNAVO_API_KEY sk-kn-... y después abre un terminal nuevo. La ubicación del archivo de configuración es %USERPROFILE%\.codex\config.toml. Comprobar la clave y el endpoint con una solicitud antes de ejecutar Codex facilita aislar el problema.

# 코덱스를 의심하기 전에, 키와 엔드포인트만 요청 한 번으로 확인합니다
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 vuelve JSON, la clave y el endpoint son correctos; el problema restante está en config.toml. Los elementos de configuración están en la documentación de integración de Codex CLI (inglés), y la explicación de cómo llamar modelos Claude desde Codex está en la guía de claves de API de Codex CLI (inglés).

Primera tarea

# 1. 작업할 저장소로 들어가 실행합니다
cd ~/work/my-app
codex

# 2. AGENTS.md 초안을 만들게 합니다 (테스트 실행법이나 규칙을 적는 파일)
> /init

# 3. 이후엔 한국어로 요청합니다. 파일 경로를 붙일수록 빠르고 싸게 끝납니다
> src/utils/date.test.ts가 실패해. 원인을 찾아서 고치고 테스트가 통과하는지 확인해줘

El AGENTS.md que crea /init es un archivo que describe «reglas que no puedes saber solo leyendo el código», como cómo ejecutar las pruebas, qué bibliotecas se usan y qué rutas no deben tocarse, y que se lee automáticamente en sesiones posteriores. El contenido generado es un borrador, así que revísalo manualmente.

La forma de solicitar tareas es la misma que con Claude Code: incluye la ruta del archivo y no envíes trabajos grandes de una sola vez. Reducirás los tokens empleados en la exploración, mejorarás la velocidad y precisión del resultado y disminuirás el importe facturado. Las prácticas operativas de Claude Code están resumidas en Cómo usar Claude Code.

Elegir el modelo para cada tarea: coste real de una tarea

La mayor ventaja de ejecutarlo con una clave de API es que puedes elegir el modelo según el peso de la tarea. model solo es el nombre del modelo del endpoint, por lo que cambiarlo no requiere una clave nueva ni configuración adicional.

# config.toml의 기본값(gpt-5-6-sol)은 그대로 두고, 이번 실행만 모델을 바꿉니다
codex -m gpt-6-astra     # 원인을 모르는 버그, 여러 모듈에 걸친 변경
codex -m gpt-5-6-terra   # 정형화된 수정, 일괄 치환, 로그 요약 같은 가벼운 작업

«Una tarea» se calcula como corregir una prueba fallida en 20 pasos. Un paso consta de 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 contiene 500 000 tokens de entrada y 24 000 de salida. Con GPT-5.6 Sol, el coste es $1.29, si pagas los mismos tokens directamente a OpenAI, al precio promocional actual son $2.48 (al precio oficial serían $3.22). Los modelos más baratos pueden requerir más rondas porque hay que corregir y volver a corregir, así que en la práctica conviene subir un nivel si la tarea no se termina de una vez. Para introducir directamente tu propio número de tokens, usa la calculadora de costes.

Este cálculo no tiene en cuenta la caché. Codex vuelve a enviar el historial de conversación en cada paso, por lo que la entrada almacenada en caché se factura a 0,10 veces la tarifa de entrada (para GPT-5.6 Sol, $0.20 por 1M de tokens) y la parte que se escribe por primera vez en la caché se factura a 1,25 veces la tarifa de entrada. Además, para la familia GPT-5.6 y GPT-6 Astra, si el prompt de una solicitud supera los 272K tokens, toda la solicitud se factura al doble para la entrada y a 1,5 veces para la salida. No concentres demasiadas tareas en una sesión; es más seguro iniciar una nueva para cada tarea. Los tokens de razonamiento se cobran como salida, por lo que las tareas difíciles también aumentan la salida. Consulta el importe real en usage de la respuesta y en el historial de uso. Las especificaciones del modelo están en la página del modelo GPT-5.6 Sol, las tarifas completas en la tabla de precios y la tabla que compara las tarifas por token de los modelos GPT usados por Codex está en Precios de la API de GPT.

Errores frecuentes

Hablando claro: cuándo conviene más un plan de ChatGPT

Si trabajas con Codex durante varias horas al día, un plan de tarifa fija suele ser más barato. El pago por uso es directamente proporcional a la cantidad de tokens, así que cuanto mayor y más constante sea el uso, mayor será la ventaja del plan. El criterio es «cuota mensual ÷ coste por tarea», y hemos calculado el punto de equilibrio con el plan en Precios de Codex.

Hay dos aspectos más que conviene conocer. Según la documentación de OpenAI, las funciones que dependen del espacio de trabajo de ChatGPT o de la nube están limitadas o no están disponibles cuando se usan con una clave de API. Además, la ruta de Kunavo utiliza capacidad compartida, por lo que no incluye una cuota dedicada ni un SLA contractual. Si necesitas límites o un SLA garantizados, lo adecuado es contratar directamente con OpenAI.

En cambio, la clave de API es adecuada para quienes tienen una gran diferencia entre los días de uso y los días sin uso, quieren elegir el modelo para cada tarea, desean repartir los límites y el historial de uso por clave dentro de un equipo, o solo quieren continuar trabajando los días en que se agota el límite del plan. Puedes usar ambas opciones juntas. Si eliminas la línea model_provider de config.toml, volverás al inicio de sesión de ChatGPT; si quieres cambiarlo en cada ejecución, usa el --profile de Codex.

Las recargas de Kunavo pueden pagarse con tarjetas, Apple Pay, Google Pay y otros métodos. Si la pantalla de pago aparece en wones, también se muestran KakaoPay, Naver Pay, PAYCO, Samsung Pay y tarjetas nacionales, incluidas las que no tienen habilitados los pagos internacionales. Toss no es compatible. El saldo no caduca y las solicitudes fallidas no generan cargos. Si dudas entre Codex y Claude Code, consulta Codex frente a Claude Code.

Preguntas frecuentes