Codex CLI API 키 — 작동하는 사용자 지정 제공업체 설정

Codex API key는 ChatGPT 요금제 대신 Codex CLI가 토큰별로 과금할 수 있는 모든 key를 의미합니다. platform.openai.com의 OpenAI API key 또는 Kunavo의 sk-kn-와 같은 provider key가 이에 해당하며, Codex는 model_providers 블록에서 env_key가 지정한 환경 변수로부터 이를 읽습니다. provider는 Responses API를 제공해야 합니다. 이것이 아래의 유일한 요구 사항입니다.

Codex CLI는 OpenAI의 오픈 소스 터미널 코딩 에이전트이며 ChatGPT 로그인 또는 API key로 실행됩니다. API key 경로를 이해할 가치가 있습니다. 월정액 없이 토큰별로 과금되며, CLI를 다른 provider 또는 완전히 다른 모델 계열로 지정할 수 있는 유일한 경로이기 때문입니다. 이 가이드에서는 실제 설정, 대부분의 게이트웨이에서 문제가 되는 한 가지 요구 사항, 그리고 실제 세션 비용을 설명합니다.

중요한 유일한 요구 사항

Codex CLI는 대부분의 도구보다 사용자 지정 엔드포인트에 대해 더 엄격합니다. model_providers 블록에는 wire_api key가 있으며, 정확히 하나의 값인 responses만 허용합니다. 즉 사용자 지정 provider는 POST /v1/responses에서 OpenAI의 Responses API를 제공해야 하며, 훨씬 흔한 /v1/chat/completions는 제공 대상이 아닙니다. 대부분의 OpenAI 호환 게이트웨이는 후자만 제공하므로, base_url를 무엇으로 지정하든 Codex CLI를 구동할 수 없습니다.

Kunavo는 두 인터페이스를 모두 제공하므로 아래 설정이 그대로 작동합니다.

설정

Codex는 ~/.codex/config.toml를 읽습니다. 최상위 key 두 개로 모델과 provider를 선택하고, provider 블록에서 연결 방법을 설명합니다.

# ~/.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"

파일에 없는 항목에 주목하세요. 바로 key 자체입니다. env_key는 환경 변수의 이름을 지정하고 Codex는 시작 시 그곳에서 key를 읽으므로 config 파일을 안전하게 커밋하거나 공유할 수 있습니다.

# Codex reads the key from the variable named by env_key.
export KUNAVO_API_KEY="sk-kn-..."     # create at kunavo.com/app/keys

# Persist it (pick the file your shell actually loads):
echo 'export KUNAVO_API_KEY="sk-kn-..."' >> ~/.zshrc

codex "explain the structure of this repository"

가입하고 $10을 충전한 다음 dashboard에서 key를 생성하세요. key는 한 번만 표시되므로 즉시 저장하세요. codex가 다른 셸에서 이미 실행 중이었다면 다시 시작하세요. 요청마다가 아니라 시작 시 환경 변수를 읽기 때문입니다.

디버깅 전에 확인하세요

문제가 발생하면 원인이 key인지, 엔드포인트인지, CLI인지 확인하세요. 요청 하나로 판단할 수 있습니다.

# Confirm the key and the endpoint before blaming 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": "Say OK and nothing else."
  }'

JSON 응답이 반환되면 key와 엔드포인트는 정상이며, 남은 문제는 config.toml에 있습니다. 401는 key가 잘못되었거나 이 셸에서 변수가 비어 있다는 뜻입니다. model의 404는 slug가 카탈로그와 일치하지 않는다는 뜻입니다.

설정할 모델

model 값은 동일한 엔드포인트의 slug일 뿐이므로 모델을 바꾸는 것은 단어 하나를 수정하는 일입니다. 새 key나 새 provider 블록은 필요하지 않습니다.

gpt-5-6-sol는 코딩에 맞게 조정된 GPT이며 이 CLI의 자연스러운 기본값입니다. 1M 토큰당 가격은 $2.00 / $12.00이며, OpenAI 공식 정가는 $5.00 / $30.00입니다 — 다만 OpenAI는 현재 프로모션 가격 $4.00 / $20.00를 부과하며, 최소 2026년 11월 21일까지 제공됩니다. 모든 모델의 전체 요금은 가격 페이지에서 확인할 수 있습니다.

Codex CLI에서 Claude 모델 실행하기

많은 사람이 놀라는 부분입니다. Codex CLI는 모델이 아니라 프로토콜에 종속됩니다. Responses wire 형식을 사용하며 해당 엔드포인트 뒤에 있는 모든 채팅 모델이 응답합니다. claude-opus-5를 가리키면 도구 호출을 포함해 처음부터 끝까지 실행됩니다. 따라서 에이전트는 평소처럼 파일을 읽고, 변경 사항을 제안하고, 명령을 실행할 수 있습니다.

# Same provider block, different model — no new key, no new config.
model          = "claude-opus-5"
model_provider = "kunavo"

[model_providers.kunavo]
name     = "kunavo"
base_url = "https://api.kunavo.com/v1"
env_key  = "KUNAVO_API_KEY"
wire_api = "responses"

게이트웨이는 Responses 요청을 Anthropic Messages API로 변환하고 응답을 다시 Responses 형식으로 변환합니다. 한 가지 분명한 제한이 있습니다. Codex는 Responses 네이티브 모델만 사용할 수 있는 불투명한 reasoning 항목을 보내며, 이러한 항목은 비-GPT 업스트림으로 전달되는 과정에서 삭제됩니다. 모델은 이전 턴의 비공개 스크래치패드를 잃지만, 작업에 사용하는 보이는 대화 기록은 유지됩니다. 실제로 긴 추론 체인에서는 연속성이 약간 떨어지지만, 일반적인 편집-실행-수정 루프에서는 전혀 문제가 되지 않습니다.

이것이 좋은 생각인지 여부는 작동하는지 여부와 별개의 문제입니다. Claude를 특별히 원한다면 Claude Code가 Claude에 맞게 설계되어 있고 cache_control를 변환 없이 전달합니다. 하지만 Codex CLI의 샌드박싱을 선호하면서 Claude를 그 뒤에서 사용하고 싶다면 이 조합도 가능합니다.

세션 비용

Agentic CLI는 각 단계마다 system prompt, 작업 기록 및 새로운 파일 컨텍스트를 다시 전송하므로 토큰은 단계 수가 암시하는 것보다 빠르게 누적됩니다. 일반적인 한 단계는 입력 약 25,000토큰과 출력 1,200토큰을 사용합니다.

모델군마다 출력 요금의 차이가 입력 요금보다 훨씬 크기 때문에, 출력 중심 작업에서는 순위가 달라집니다. 하나의 계산 예시를 그대로 믿지 말고 직접 수치를 비용 계산기에 입력하세요. 실패한 요청에는 요금이 부과되지 않습니다.

API 키 방식이 구독보다 유리한 경우

ChatGPT 요금제는 Codex 사용량을 월 정액으로 묶지만, API 키는 실제로 실행한 만큼만 청구합니다. 매일이 아니라 몰아서 코딩할 때, 불투명한 사용 한도 대신 키별 지출 한도와 사용량 확인을 원할 때, 또는 구독에서 제공하지 않는 모델을 사용하려 할 때는 키 방식이 유리합니다. 반대로 매일 많이 사용하는 사용자에게는 불리합니다. 그 정도 사용량에서는 정액 요금을 이기기 어렵습니다. 두 방식은 배타적이지 않습니다. Codex 프로필에서 둘 다 유지하고 작업별로 전환할 수 있습니다.

문제 해결

자주 묻는 질문