API 키를 사용하는 Codex CLI — 설정, 모델 및 세션 비용

Codex CLI는 OpenAI의 오픈 소스 터미널 코드 에이전트이며, ChatGPT 로그인과 API key를 모두 지원합니다. 이해해야 할 핵심은 key 경로입니다. 월정액 없이 토큰 단위로 청구되며, CLI를 다른 공급업체나 다른 모델 제품군으로 지정할 수 있는 유일한 방식입니다. 이 가이드에서는 작동하는 구성, 대부분의 게이트웨이를 막는 요구 사항, 세션 비용 및 브라질에서 Pix로 결제하는 방법을 설명합니다.

중요한 유일한 요구 사항

Codex CLI는 OpenAI의 Responses API만 사용하며 다른 API는 사용하지 않습니다. model_providers 블록은 wire_api = "responses"만 허용합니다. /v1/chat/completions만 제공하는 게이트웨이는 구성할 수 없습니다. 이것이 ‘OpenAI 호환’이라고 표시된 많은 엔드포인트가 여기서 실패하는 이유입니다. Kunavo는 채팅 엔드포인트와 함께 POST /v1/responses도 제공하므로 아래 블록을 수정 없이 사용할 수 있습니다.

구성

# ~/.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는 환경 변수의 이름이지 key가 아닙니다. Codex는 구성 파일에 key를 절대 기록하지 않습니다.

# O Codex lê a chave da variável indicada em env_key.
export KUNAVO_API_KEY="sk-kn-..."     # crie em kunavo.com/app/keys

# Deixe persistente (escolha o arquivo que o seu shell realmente carrega):
echo 'export KUNAVO_API_KEY="sk-kn-..."' >> ~/.zshrc

codex "explique a estrutura deste repositório"

대시보드에서 가입한 후 $10을 충전하여 key를 생성하세요. key는 한 번만 표시됩니다.

브라질에서 결제하기 — 국제 카드 없이 Pix 사용

브라질 개발자에게 장애물은 대개 TOML 파일이 아니라 결제 수단입니다. OpenAI API에 직접 결제하려면 해외 결제가 가능한 국제 신용카드가 필요합니다. Kunavo에서는 결제가 Stripe를 통해 처리되고, 브라질에서 결제하는 사용자의 결제 수단으로 Pix가 표시됩니다. 금액은 헤알화로 표시되고 즉시 반영됩니다. 국제 카드（Visa, Mastercard, American Express）, Apple Pay 및 Google Pay도 계속 사용할 수 있습니다.

토큰 요금은 USD로 책정됩니다. Pix를 사용하면 결제 시 Stripe가 브라질 헤알화 환산액을 표시하고, 카드 결제 시에는 카드 발급사의 환율이 적용됩니다. 은행 앱에서 IOF와 국제 거래 수수료를 확인하세요. Pix를 통한 충전 절차는 Pix로 API 결제하는 방법 가이드에 설명되어 있습니다. 지갑은 선불 방식이며, 최소 충전액은 $10이고 구독이나 자동 갱신이 없습니다. 잔액은 만료되지 않습니다.

어떤 모델을 사용할까요?

gpt-5-6-sol는 코드에 맞게 조정된 GPT로, 이 CLI의 자연스러운 기본 모델입니다. 가격은 OpenAI의 정가표(현재 OpenAI는 프로모션 가격 $4.00 / $20.00를 부과하며, 가격 페이지에 따르면 이 가격은 최소 2026년 11월 21일까지 제공됨)의 $5.00 / $30.00와 비교해 1M 토큰당 $2.00 / $12.00입니다. 전체 요금은 가격 페이지에서 확인하세요.

Codex CLI에서 Claude 모델 실행하기

놀라울 수 있지만 Codex CLI는 모델이 아니라 프로토콜에 종속됩니다. Responses 형식으로 통신하므로 해당 엔드포인트 뒤에 있는 모든 채팅 모델이 응답할 수 있습니다. claude-opus-5를 가리키면 도구 호출을 포함해 처음부터 끝까지 실행됩니다. 따라서 에이전트는 계속 파일을 읽고, 편집을 제안하고, 명령을 실행할 수 있습니다.

# Mesmo bloco de provider, outro modelo — sem chave nova, sem config nova.
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가 그 목적에 맞게 만들어졌고 cache_control를 변환 없이 전달합니다. 하지만 Codex CLI의 sandbox를 선호하면서 그 뒤에서 Claude를 사용하고 싶다면 이 조합도 가능합니다.

세션 비용

Agentic CLI는 각 단계마다 system prompt, 작업 기록 및 파일 컨텍스트를 다시 전송하므로 단계 수에서 예상하는 것보다 토큰이 빠르게 누적됩니다. 일반적인 한 단계는 input 약 25,000토큰과 output 1,200토큰으로 구성됩니다.

즉 Pix로 $10을 충전하면 20단계 agentic 작업을 약 8회 수행할 수 있습니다. 실패한 요청에는 비용이 청구되지 않으므로 세션 중 발생한 5xx 오류가 청구서에 기록되지 않습니다.

작동하지 않을 때

Codex를 탓하기 전에 key와 엔드포인트가 응답하는지 확인하세요.

# Confirme a chave e o endpoint antes de culpar o 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": "Responda OK e nada mais."
  }'

• 404 — provider가 /v1/responses를 구현하지 않았거나 base_url에 이미 /responses가 포함되어 있습니다. Codex가 경로를 자동으로 추가하므로 base는 /v1로 끝나야 합니다.
• 401 — env_key에 지정된 변수가 Codex를 실행한 shell에서 비어 있습니다. 같은 터미널에서 echo $KUNAVO_API_KEY로 확인하세요.
• 402 — 잔액 부족입니다. billing에서 충전하세요(Pix는 즉시 반영됩니다).
• model_not_found — 모델 slug가 카탈로그에 없습니다. /models에서 확인하세요.

자주 묻는 질문