Claude Code API 키 — 어디서 발급하고 어디에 입력하며 잘못된 변수는 왜 조용히 실패하는가

Claude Code는 두 가지 방식으로 인증할 수 있으며, 필요한 방식에 따라 나머지가 모두 결정됩니다. claude.ai 구독 로그인은 Pro 또는 Max 요금제 내 사용량을 포함합니다. API 키는 요금제 한도 없이 토큰별로 청구됩니다. 이 가이드에서는 키를 받는 곳, 정확히 입력할 위치, 두 자격 증명 변수, 잘못된 변수를 선택했을 때 조용히 실패하는 이유, 작동 후 비용을 관리하는 방법을 설명합니다.

정말 키가 필요한가요?

시작하기 전에 알아둘 점: 키를 설정하면 구독이 일시 중단됩니다. 자격 증명 변수가 활성화되어 있는 동안 Claude Code는 저장된 claude.ai 로그인 대신 해당 변수를 사용하고, 요금제 한도는 적용되지 않으며 사용량은 키 소유자에게 청구됩니다. 변수를 해제하면 Claude Code가 구독으로 돌아갑니다.

옵션 1 — 자사 Anthropic 키

1. console.anthropic.com에 로그인하세요(claude.ai와 별도의 계정).
2. Billing에서 크레딧을 추가하세요. API는 선불 방식이며 구독과 별개입니다. Pro 요금제로는 API 비용을 결제할 수 없습니다.
3. API Keys에서 키를 생성하세요. 키는 sk-ant-로 시작하며 한 번만 표시됩니다.

export ANTHROPIC_API_KEY=sk-ant-...
# Then approve it once, interactively:
#   /config  ->  Use custom API key
claude

코드 조각의 두 번째 단계를 확인하세요. ANTHROPIC_API_KEY는 x-api-key 헤더로 전송되며 Claude Code가 사용하기 전에 한 번 대화형 승인을 받아야 합니다. 해당 프롬프트를 한 번이라도 거부하면 키는 이후 아무 프롬프트 없이 무시됩니다. 이는 변수를 읽지 않는 것처럼 보입니다. /config → Use custom API key에서 다시 활성화하세요.

옵션 2 — 토큰당 비용이 더 낮은 키

Claude Code는 ANTHROPIC_BASE_URL를 네이티브로 읽으므로 Anthropic Messages API를 제공하는 모든 엔드포인트에서 작동합니다. 플러그인, 프록시, 수정된 바이너리가 필요하지 않습니다. 게이트웨이에 지원되는 방식이며 동일한 Claude 모델을 더 낮은 요금으로 실행하는 방법입니다:

export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...
export ANTHROPIC_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5

ANTHROPIC_BASE_URL은 원본 주소일 뿐이며 Claude Code가 /v1/messages을 자체적으로 덧붙입니다. 모델 행은 그대로 유지하세요. Claude Code의 내장 기본값과 opus 별칭은 모두 최신 Opus로 확인되며, Kunavo가 아직 해당 모델을 제공하지 않으면 첫 요청은 404를 반환합니다. opus 행은 Claude Opus 5.5에 고정하며, Claude Code v2.1.280 이상이 필요합니다(이전 버전에서는 claude update를 실행하세요). sonnet 별칭은 Kunavo가 제공하지 않는 Sonnet 5.5를 요청하므로 ANTHROPIC_DEFAULT_SONNET_MODEL, /model sonnet이 없으면 opusplan의 실행 단계와 sonnet으로 설정된 하위 에이전트가 모두 404를 반환합니다. sk-kn- 키는 가입하고 $10를 충전한 후 대시보드에서 만드세요. 월 요금은 없으며 잔액은 만료되지 않습니다.

이는 주력 모델의 목록 가격보다 약 30% 낮습니다. 전체 요금은 Claude API 가격 가이드에 있으며, Claude Code 가격에서는 이 경로와 Pro 및 Max 요금제 비용을 비교합니다. 게이트웨이 뒤에서 작업별 모델 라우팅과 변경 사항을 포함한 전체 설정은 Claude Code 라우터 가이드에 있습니다. CLI가 아직 설치되지 않았다면 Claude Code 설치부터 시작하세요.

키가 실제로 들어가는 곳

두 변수와 두 개의 서로 다른 HTTP 헤더가 있습니다. 서버가 읽지 않는 헤더에 키를 넣으면 401으로 실패합니다:

어떤 종류의 키인지 모른다면 승인 단계가 필요 없는 ANTHROPIC_AUTH_TOKEN부터 사용하세요. Kunavo에서는 두 변수 중 어느 것이든 Claude Code가 모델 목록을 검색할 수 있습니다. /v1/models가 두 헤더 중 어느 쪽에서든 키를 읽기 때문입니다.

셸 export와 설정 파일

셸 export는 해당 터미널과 그 자식 프로세스에만 적용됩니다. Dock에서 실행한 에디터도 이를 볼 수 없고 백그라운드 에이전트도 마찬가지입니다. 영구적으로 사용하려면 대신 ~/.claude/settings.json의 env 블록을 사용하세요. 동일한 키가 Claude Code가 실행되는 모든 곳에 적용됩니다. 프로젝트의 .claude/settings.json에 키를 넣지 마세요. 이 파일은 커밋되어 저장소를 복제하는 모든 사람과 공유됩니다.

/status를 실행하여 현재 활성화된 자격 증명을 확인하세요. 변수 이름을 표시하는 Auth token 또는 API key 줄이 있으면 키가 활성화된 것입니다. claude.ai 계정을 표시하는 Login method 줄이 있으면 활성화되지 않은 것입니다.

파일을 편집하지 않고 키 교체하기

자격 증명이 일정에 따라 만료되거나 볼트에서 제공되는 경우, apiKeyHelper가 현재 키를 출력하는 명령을 가리키도록 하세요:

#!/bin/bash
# Any command that prints the current key to stdout works.
vault kv get -field=api_key secret/claude-code

설정 파일에서 "apiKeyHelper": "~/bin/get-key.sh"로 참조하세요. Claude Code는 출력을 5분 동안 캐시하고 401 시 다시 실행합니다. CLAUDE_CODE_API_KEY_HELPER_TTL_MS로 조정할 수 있습니다. 값은 두 헤더 모두로 전송되므로 어느 방식으로도 작동합니다.

예측 가능한 비용 유지

에이전트 코딩은 토큰을 많이 사용합니다. 모든 단계에서 시스템 프롬프트, 작업 기록, 새로운 파일 컨텍스트가 다시 전송됩니다. 무엇보다 중요한 네 가지는 다음과 같습니다:

1. 백그라운드 작업을 Haiku로 라우팅하세요. ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5는 Claude Code가 자체적으로 생성하는 요약과 제목을 처리합니다. 한 줄 설정으로 순수하게 비용을 절약하며, 작업이 여러 갈래로 확장될 때 특히 중요합니다. 비용은 Claude Code 워크플로의 비용에 반영됩니다.
2. 동일한 두 변수가 Agent SDK도 라우팅합니다. 자체적인 기본 URL 옵션은 없습니다. 이 CLI를 실행하고 환경을 그대로 전달하므로 Agent SDK 프로그램은 위 설정에 의해 정확히 라우팅됩니다.
3. 하나의 작업을 영원히 늘리지 말고 새 작업을 시작하세요. 모든 단계에서 컨텍스트가 다시 전송되므로 긴 세션의 비용은 제곱에 비례해 증가합니다. 주력 모델에 어떤 등급을 배치할지는 토큰당 비용이 아니라 완료된 작업당 비용 기준으로 Opus 대 Sonnet 대 Haiku에서 설명합니다.
4. 프롬프트 캐싱을 활용하세요. 캐시된 입력은 입력 요금의 10%로 청구되며, 네이티브 Messages API 경로는 cache_control를 번역하지 않고 그대로 전달합니다(세부 정보).
5. 대시보드에서 에디터 전용 키와 지출 한도를 설정한 다음 일주일 후 사용량을 확인하세요. 키별 한도는 무한 반복을 상한이 있는 반복으로 바꿉니다.

문제 해결

자주 묻는 질문