Codex 사용법 — 설치부터 구독 없이 API 키로 실행하는 방법까지

Codex는 OpenAI의 코딩 에이전트입니다. 기본 사용법은 터미널에서 실행되는 Codex CLI를 설치하고(npm install -g @openai/codex), 작업할 리포지토리에서 codex를 시작한 뒤 일본어로 요청하는 것입니다. 시작 방법은 2가지입니다. ChatGPT 플랜(Plus·Pro·Business 등)으로 로그인하여 사용량 한도 내에서 사용하는 방법과 API 키로 실행하고 사용한 토큰만큼 지불하는 방법입니다. 일본어 설명 글은 거의 전자만 다루므로 이 페이지에서는 후자—구독 없이 Codex CLI를 실행하는 설정, 작업별 모델 선택 방법, 작업 1개의 실제 비용—를 차례로 설명합니다.

Codex는 채팅 화면에 코드를 붙여 넣는 도구가 아니라 리포지토리 안에서 파일을 읽고 수정하며 테스트와 명령을 실행하는 에이전트입니다. 시작 후 확인 없이 어디까지 맡길지는 /permissions로 결정할 수 있습니다.

Codex를 사용하는 2가지 방법

API 키로 실행하는 경우 청구는 OpenAI 플랜의 사용량과 별도로 계산됩니다. 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당 $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에 블록 1개

먼저 계정을 만들고 $10부터 충전한 뒤 API 키 화면에서 키를 만듭니다. 키는 한 번만 표시되므로 즉시 기록하세요. 다음으로 Codex 설정 파일에 제공업체 블록 1개를 작성합니다.

# ~/.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입니다. Codex를 시작하기 전에 키와 엔드포인트가 올바른지 요청 1회로 확인해 두면 이후 문제를 쉽게 분리할 수 있습니다.

# Codex を疑う前に、キーとエンドポイントだけを 1 回で確かめる
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에서 호출하는 방법까지 포함한 설명은 Codex CLI API 키 설정 가이드(영어)에 있습니다.

첫 번째 작업

# 1. 作業したいリポジトリに入って起動する
cd ~/work/my-app
codex

# 2. AGENTS.md の雛形を作らせる（テストの実行方法や決めごとを書くファイル）
> /init

# 3. あとは日本語で頼む。ファイル名を添えるほど速く、安く終わる
> src/utils/date.test.ts が落ちている。原因を調べて直し、テストが通るのを確認して

/init가 만드는 AGENTS.md는 테스트 실행 방법, 사용할 라이브러리, 건드리면 안 되는 경로 등 ‘코드를 읽어도 알 수 없는 규칙’을 적어 두는 파일이며 이후 세션에서 자동으로 읽힙니다. 생성된 내용은 초안이므로 직접 수정하세요.

요청할 때의 요령은 Claude Code와 동일합니다. 파일 이름과 경로를 함께 적고 큰 요청을 한 번에 보내지 마세요. 탐색에 사용하는 토큰이 줄어들어 결과가 더 빠르고 정확해지며 청구액도 낮아집니다. 확인 대화상자의 빈도는 /permissions로 조정할 수 있습니다. Claude Code 측 운영 방법은 Claude Code 사용 방법에 정리되어 있습니다.

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

API 키를 사용하는 가장 큰 이점은 작업의 복잡도에 맞춰 모델을 선택할 수 있다는 점입니다. model은 엔드포인트의 모델 이름일 뿐이므로, 전환을 위해 키나 설정을 추가할 필요가 없습니다.

# config.toml の既定（gpt-5-6-sol）はそのまま、この起動だけモデルを変える
codex -m gpt-6-astra     # 原因の見えないバグ、設計をまたぐ変更
codex -m gpt-5-6-terra   # 定型の修正、一括置換、ログの要約などの軽い作業

‘작업 1건’은 실패한 테스트 하나를 수정하는 작업을 20단계로 보고 계산한 것입니다. 1단계는 입력 25,000토큰(시스템 프롬프트 + 대화 기록 + 읽은 파일)과 출력 1,200토큰(한 번의 편집 또는 설명)이므로, 작업 1건은 입력 500,000토큰·출력 24,000토큰입니다. GPT-5.6 Sol라면 $1.29이며, 같은 토큰 수를 OpenAI에 직접 지불하면 현재 프로모션 가격으로 $2.48(정가라면 $3.22)입니다. 저렴한 모델일수록 재작업으로 왕복 횟수가 늘어날 수 있으므로, 한 번에 끝나지 않으면 한 단계 더 높은 모델로 올리는 방식이 현실적입니다.

이 계산에는 캐시가 고려되지 않았습니다. Codex는 매 단계마다 대화 기록을 다시 전송하므로, 캐시된 입력에는 입력 단가의 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 플랜이 더 유리한 경우

매일 몇 시간씩 Codex와 대화하며 작업한다면 정액제 플랜이 대체로 더 저렴합니다.종량제는 토큰 양에 정확히 비례하므로, 사용량이 많고 일정한 사람일수록 정액제의 이점이 커집니다. 손익분기점은 ‘월 요금 ÷ 작업 1건의 단가’이며, 플랜과의 손익분기점은 Codex 요금에서 계산하고 있습니다.

그 밖에도 알아두어야 할 점이 2가지 있습니다. OpenAI 문서에 따르면 ChatGPT 워크스페이스나 클라우드에 의존하는 기능은 API 키로 사용할 때 제한되거나 사용할 수 없습니다. 또한 Kunavo의 경로는공유 용량이며, 전용 쿼터도 계약상 SLA도 없습니다. 보장된 용량이나 SLA가 필요하다면 OpenAI와 직접 계약하는 편이 적절합니다.

반대로 API 키가 적합한 사람은 사용하는 날과 사용하지 않는 날의 차이가 큰 사람, 작업별로 모델을 선택하고 싶은 사람, 팀에서 키별로 한도와 사용 기록을 분리하고 싶은 사람, 그리고 플랜 한도가 소진된 날에만 작업을 계속하고 싶은 사람입니다. 두 방식은 함께 사용할 수 있습니다. config.toml의 model_provider 줄을 삭제하면 ChatGPT 로그인으로 돌아가며, 실행할 때마다 전환하고 싶다면 Codex의 --profile를 사용할 수 있습니다.

결제에는 카드（JCB 포함）, Apple Pay, Google Pay 등을 사용할 수 있으며 잔액에는 유효 기간이 없습니다. 편의점 결제와 PayPay는 지원되지 않습니다. 실패한 요청에는 요금이 부과되지 않습니다. Codex와 Claude Code 중 어느 것을 사용할지 고민 중이라면 Codex와 Claude Code 비교를 참조하세요.

자주 묻는 질문