코덱스 사용법 — 설치부터 구독 없이 API 키로 쓰는 법, 작업 하나의 실제 비용까지

코덱스(Codex)는 OpenAI의 코딩 에이전트입니다. 기본 사용법은 터미널에서 도는 Codex CLI를 설치하고(npm install -g @openai/codex), 작업할 저장소에서 codex를 실행한 뒤 한국어로 요청하는 것입니다. 시작하는 방법은 두 가지입니다. ChatGPT 플랜(Plus · Pro · Business 등)으로 로그인해 사용량 한도 안에서 쓰는 방법과, API 키로 돌리고 쓴 토큰만큼만 내는 방법. 국내 사용법 글은 거의 전부 앞의 방법만 다루기 때문에, 이 글은 뒤의 방법 — 구독 없이 Codex CLI를 돌리는 설정, 작업마다 모델을 고르는 법, 작업 하나의 실제 비용 — 을 차례로 정리합니다.

코덱스는 채팅창에 코드를 붙여 넣는 도구가 아니라, 저장소 안에서 파일을 읽고 고치고 테스트와 명령을 실행하는 에이전트입니다. 무엇을 확인 없이 맡길지는 실행 후 /permissions로 정할 수 있습니다.

코덱스를 쓰는 두 가지 방법

API 키로 돌리면 청구는 ChatGPT 플랜의 사용량과 별도로 계산됩니다. OpenAI API 키를 그대로 쓸 수도 있지만, 이 글은 Responses API 호환 엔드포인트로 연결하는 방법을 다룹니다. 같은 키로 GPT-6 Astra부터 GPT-5.6 Luna까지 바꿔 쓸 수 있고, 예를 들어 GPT-5.6 Sol은 OpenAI 정가 $5.00 / $30.00 대비 1M 토큰당 $2.00 / $12.00입니다(요율은 카탈로그에서 직접 읽어옵니다).

코덱스 설치 — npm 또는 Homebrew

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

# Homebrew (macOS)
brew install --cask codex

두 방법 모두 OpenAI 공식 README에 있는 설치 방법입니다. Windows에서도 npm 명령으로 설치됩니다. 설치가 끝나면 작업할 저장소 디렉터리에서 codex를 입력하면 실행됩니다. ChatGPT로 로그인해서 쓸 거라면 여기서 끝이고, 아래 설정은 필요 없습니다.

API 키로 돌리기 — config.toml 한 블록

먼저 가입하고 $10부터 충전한 뒤 API 키 화면에서 키를 만듭니다. 키는 한 번만 표시되므로 바로 저장하세요. 그다음 코덱스 설정 파일에 프로바이더 블록을 하나 추가합니다.

# ~/.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"        # 유일하게 유효한 값. 생략해도 같습니다

가장 많이 틀리는 곳은 env_key입니다. 여기에 적는 것은 키 자체가 아니라 키를 담을 환경 변수의 이름입니다. 키가 설정 파일에 들어가지 않으므로 config.toml은 커밋하거나 질문 글에 붙여도 안전합니다.

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

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

Windows PowerShell이라면 setx KUNAVO_API_KEY sk-kn-...를 실행한 뒤 새 터미널을 여세요. 설정 파일 위치는 %USERPROFILE%\.codex\config.toml입니다. 코덱스를 실행하기 전에 요청 한 번으로 키와 엔드포인트를 확인해 두면 문제를 나누기가 쉬워집니다.

# 코덱스를 의심하기 전에, 키와 엔드포인트만 요청 한 번으로 확인합니다
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라고만 답해줘"}'

JSON이 돌아오면 키와 엔드포인트는 정상이고, 남은 문제는 config.toml 쪽입니다. 설정 항목은 Codex CLI 연동 문서(영어)에, 코덱스에서 Claude 모델을 부르는 방법까지 담은 해설은 Codex CLI API 키 가이드(영어)에 있습니다.

첫 작업

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

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

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

/init이 만드는 AGENTS.md는 테스트 실행 방법, 쓰는 라이브러리, 건드리면 안 되는 경로처럼 「코드를 읽어도 알 수 없는 규칙」을 적어 두는 파일이고, 이후 세션에서 자동으로 읽힙니다. 생성된 내용은 초안이니 손으로 다듬으세요.

요청 요령은 클로드 코드와 같습니다. 파일 경로를 붙이고, 큰 작업을 한 번에 던지지 않기. 탐색에 쓰는 토큰이 줄어 결과가 빠르고 정확해지고 청구 금액도 내려갑니다. 클로드 코드 쪽 운영법은 클로드 코드 사용법에 정리돼 있습니다.

작업마다 모델 고르기 — 작업 하나의 실제 비용

API 키로 돌리는 가장 큰 이점은 작업의 무게에 맞춰 모델을 고를 수 있다는 점입니다. model은 엔드포인트의 모델 이름일 뿐이라, 바꾸는 데 새 키나 추가 설정이 필요 없습니다.

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

「작업 하나」는 실패하는 테스트 하나를 고치는 일을 20스텝으로 본 계산입니다. 1스텝은 입력 25,000 토큰(시스템 프롬프트 + 대화 기록 + 읽은 파일)과 출력 1,200 토큰(한 번의 수정이나 설명)이므로, 작업 하나에 입력 500,000 · 출력 24,000 토큰입니다. GPT-5.6 Sol이면 $1.29, 같은 토큰을 OpenAI API 정가로 내면 $3.22입니다. 싼 모델일수록 고치고 다시 고치느라 왕복이 늘 수 있으니, 한 번에 안 끝나면 한 단계 올리는 방식이 현실적입니다. 내 토큰 수로 직접 넣어 보려면 비용 계산기를 쓰세요.

이 계산은 캐시를 반영하지 않았습니다. 코덱스는 스텝마다 대화 기록을 다시 보내므로, 캐시에 올라간 입력은 입력 단가의 0.10배(GPT-5.6 Sol 기준 1M 토큰당 $0.20)로 청구되고, 새로 캐시에 쓰이는 분량은 입력 단가의 1.25배입니다. 또 GPT-5.6 계열과 GPT-6 Astra는 요청 하나의 프롬프트가 272K 토큰을 넘으면 그 요청 전체가 입력 2배 · 출력 1.5배로 청구됩니다. 한 세션에 작업을 너무 많이 몰아넣지 말고 작업마다 새로 실행하는 편이 안전합니다. 추론 모델의 사고 토큰은 출력으로 청구되므로 어려운 작업일수록 출력도 늘어납니다. 실제 금액은 응답의 usage와 사용 내역에서 확인하세요. 모델 사양은 GPT-5.6 Sol 모델 페이지, 전체 요율은 요금표에 있습니다.

자주 나는 오류

솔직하게 — ChatGPT 플랜이 더 나은 경우

매일 몇 시간씩 코덱스와 대화하며 작업한다면 정액 플랜이 대체로 더 쌉니다. 종량제는 토큰 양에 그대로 비례하므로, 사용량이 많고 꾸준할수록 정액의 이점이 커집니다. 기준은 「월정액 ÷ 작업 하나 단가」이고, 플랜과의 손익분기점은 코덱스 요금에서 계산해 두었습니다.

알아 둘 점이 두 가지 더 있습니다. OpenAI 문서에 따르면 ChatGPT 워크스페이스나 클라우드에 기대는 기능은 API 키로 쓸 때 제한되거나 쓸 수 없습니다. 그리고 Kunavo 경로는 공유 용량이라 전용 쿼터도 계약상 SLA도 없습니다. 보장된 한도나 SLA가 필요하다면 OpenAI와 직접 계약하는 편이 맞습니다.

반대로 API 키가 맞는 사람은 쓰는 날과 안 쓰는 날의 차이가 큰 사람, 작업마다 모델을 고르고 싶은 사람, 팀에서 키마다 한도와 사용 내역을 나누고 싶은 사람, 그리고 플랜 한도가 바닥난 날에만 작업을 이어가고 싶은 사람입니다. 둘은 함께 쓸 수 있습니다. config.toml의 model_provider 줄을 지우면 ChatGPT 로그인으로 돌아가고, 실행할 때마다 바꾸고 싶다면 코덱스의 --profile을 쓰면 됩니다.

결제는 카드와 Apple Pay 등으로 하며, 국내 발급 카드는 대부분 결제됩니다. 카카오페이와 토스는 지원하지 않습니다. 잔액에는 유효 기간이 없고, 실패한 요청은 청구되지 않습니다. 코덱스와 클로드 코드 사이에서 고민 중이라면 코덱스 vs 클로드 코드를 참고하세요.

자주 묻는 질문