Codex 튜토리얼 — Codex CLI 설치, 구독 없이 API 키 사용하기, 작업 하나의 비용

Codex는 OpenAI의 AI 프로그래밍 에이전트(coding agent)입니다. 가장 기본적인 사용법은 터미널에서 실행되는 Codex CLI(npm install -g @openai/codex)를 설치하고, 처리할 프로젝트 폴더에서 codex를 실행한 다음 중국어로 원하는 작업을 설명하는 것입니다. 시작 방법은 두 가지입니다. ChatGPT 요금제(Plus, Pro, Business 등)로 로그인해 요금제 한도 내에서 사용하거나, API 키로 실행해 사용한 토큰만큼 결제할 수 있습니다. 중국어 가이드는 거의 모두 전자를 설명하지만, 이 글에서는 후자를 다룹니다. 구독 없이 Codex CLI를 실행하는 설정, 작업별 모델 선택, 실제 작업 하나에 드는 비용을 설명합니다.

Codex는 코드를 채팅 창에 붙여 넣는 도구가 아니라, 프로젝트에서 파일을 읽고 수정하며 테스트와 명령을 실행하는 에이전트입니다. 시작 후 /permissions로 어떤 작업을 확인 없이 바로 실행할 수 있는지 설정합니다.

Codex를 사용하는 두 가지 방법

API 키로 실행할 때 비용은 ChatGPT 요금제 한도와 별도로 계산됩니다. OpenAI API 키를 직접 사용할 수도 있지만, 이 글에서는 Responses API와 호환되는 엔드포인트에 연결하는 방법을 설명합니다. 동일한 키로 GPT-6 Astra부터 GPT-5.6 Terra까지 전환할 수 있습니다. 예를 들어 GPT-5.6 Sol의 OpenAI 공식 요금은 $5.00 / $30.00(OpenAI는 현재 프로모션 가격 $4.00 / $20.00로 제공하며, 공식 가격 페이지에는 최소 2026년 11월 21일까지라고 명시되어 있습니다)이며, 여기서는 1M token당 $2.00 / $12.00입니다(요금은 이 사이트의 카탈로그에서 직접 읽어오며 수동으로 입력한 값이 아닙니다).

Codex CLI 설치 — 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 설정 파일에 공급자 블록을 추가합니다:

# ~/.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는 안심하고 git에 커밋하거나 포럼에 질문을 올릴 때 붙여 넣을 수 있습니다.

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

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

Windows PowerShell에서는 setx KUNAVO_API_KEY sk-kn-...를 실행한 뒤 새 터미널을 여세요. 설정 파일 위치는 %USERPROFILE%\.codex\config.toml입니다. Codex를 시작하기 전에 요청 하나를 보내 키와 엔드포인트가 정상인지 확인하면, 이후 오류가 발생했을 때 어느 부분의 문제인지 판단하기 쉽습니다.

# 懷疑 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"}'

JSON이 반환되면 키와 엔드포인트가 모두 정상이며, 남은 문제는 config.toml에 있습니다. 각 설정 필드의 설명은 Codex CLI 통합 문서(영문)에 있고, Codex에서 Claude 모델을 호출하는 방법은 Codex CLI API 키 가이드(영문)에 설명되어 있습니다.

첫 번째 작업

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

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

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

/init가 생성하는 AGENTS.md는 ‘코드만 봐서는 알 수 없는 규칙’을 기록하는 파일입니다. 테스트 실행 방법, 사용할 라이브러리, 수정하면 안 되는 경로 등을 기록하며 이후 모든 세션에서 자동으로 읽습니다. 생성된 내용은 초안일 뿐이므로 직접 한 번 수정하세요.

명령을 내리는 요령은 Claude Code와 같습니다. 파일 이름과 경로를 포함하고, 큰 작업은 한 번에 넘기지 마세요. 탐색에 사용하는 토큰이 줄어들어 결과가 더 빠르고 정확해지며 비용도 낮아집니다.

작업별 모델 선택 — 실제 작업 비용

API 키로 실행할 때의 가장 큰 장점은작업의 난이도에 따라 모델을 선택할 수 있다는 점입니다. model는 엔드포인트상의 모델 이름일 뿐이므로 모델을 바꿔도 새 키나 추가 설정이 필요하지 않습니다.

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

‘작업 하나’는 실패한 테스트 하나를 수정하는 일을 20단계로 계산합니다. 각 단계에서 입력 25,000 token(시스템 프롬프트 + 대화 기록 + 읽어 온 파일), 출력 1,200 token(한 번의 수정 또는 설명)을 사용하므로 작업 하나는 입력 500,000, 출력 24,000 token입니다. GPT-5.6 Sol을 사용하면 약 $1.29입니다; 동일한 토큰 수를 OpenAI에 직접 지불하면 현재 프로모션 요금으로 $2.48(정가 기준 $3.22)입니다. 저렴한 모델일수록 올바르게 수정하기까지 왕복이 더 필요할 수 있으므로, 실제로는 한 번에 해결되지 않으면 한 단계 더 높은 모델로 전환하는 것이 좋습니다.

이 계산에는 캐시가 반영되지 않았습니다. Codex는 매 단계 대화 기록을 다시 전송하며, 캐시 적중 입력에는 입력 단가의 0.10배가 부과됩니다(GPT-5.6 Sol의 경우 1M token당 $0.20). 새로 캐시에 기록되는 부분에는 입력 단가의 1.25배가 부과됩니다. 또한 GPT-5.6 시리즈와 GPT-6 Astra는 단일 요청의 프롬프트가 272K token을 초과하면 전체 요청에 입력 2배, 출력 1.5배의 요금이 적용됩니다. 따라서 한 세션에 너무 많은 작업을 넣지 말고 작업 하나마다 세션을 다시 시작하는 편이 안전합니다. 추론 모델의 사고 token에는 출력 요금이 적용되며, 문제가 어려울수록 출력이 많아집니다. 실제 금액은 응답의 usage 및사용량 기록을 확인하세요. 모델 사양은 GPT-5.6 Sol 모델 페이지에서, 모든 모델의 요금은가격표에서 확인할 수 있습니다.

일반적인 오류

솔직히 말해 — ChatGPT 요금제가 더 저렴한 경우

매일 몇 시간씩 Codex와 대화를 주고받는다면 고정 월 요금제가 보통 더 저렴합니다.종량제 비용은 토큰 사용량에 비례하므로, 사용량이 많고 일정할수록 월 요금제의 이점이 커집니다. 손익분기점은 ‘월 요금 ÷ 작업 하나의 단가’이며, 요금제 간 손익분기점은 Codex 비용 페이지에서 계산되어 있습니다.

먼저 알아야 할 사항이 두 가지 더 있습니다. OpenAI 문서에 따르면 ChatGPT 작업 공간이나 클라우드 서비스에 의존하는 기능은 API 키 사용 시 제한되거나 사용할 수 없습니다. 또한 Kunavo 경로는공유 용량이므로 전용 할당량이나 계약상 보장되는 SLA가 없습니다. 보장된 할당량이나 SLA가 필요하다면 OpenAI와 직접 계약하는 편이 적합합니다.

반대로 API 키가 적합한 경우는 사용량이 일정하지 않은 사람, 작업별로 모델을 선택하고 싶은 사람, 팀에서 키별 한도와 사용량 기록을 분리하고 싶은 사람, 또는 요금제 한도를 모두 사용한 날에도 계속 작업하고 싶은 사람입니다. 두 방식을 함께 사용할 수도 있습니다. config.toml에서 model_provider 줄을 삭제하면 ChatGPT 로그인으로 돌아갑니다. 실행할 때마다 전환하려면 Codex의 --profile를 사용할 수 있습니다.

JCB를 포함한 국제 신용카드, Apple Pay 또는 Google Pay로 결제하세요. 대만에는 현지 결제 수단이 없으며 JKO Pay와 LINE Pay는 지원되지 않습니다. 선불 방식은 충전할 때 한 번만 카드가 결제되고 잔액은 만료되지 않으며 실패한 요청에는 요금이 부과되지 않습니다. Codex와 Claude Code 중에서 고민 중이라면 Claude Code vs Codex CLI(영문)을 확인하세요. Claude Code의 요금 계산 방식은 Claude Code 비용에서 확인할 수 있습니다.

자주 묻는 질문