Source: https://aiprimetech.io/ko/learn/claude-code-api-key-setup/

[홈](/ko/) / [학습](/ko/learn/) / Claude Code API 키 — ANTHROPIC_API_KEY: 발급 및 설정 방법과 claude setup-token을 대신 사용해야 하는 경우 

# Claude Code API 키 — ANTHROPIC_API_KEY: 발급 및 설정 방법과 대신 claude setup-token을 사용해야 하는 경우 

Claude Code가 작동하려면 API 키가 필요합니다. Claude Code를 처음 설정하든 Anthropic 직접 계정에서 정액제 게이트웨이로 이전하든, 키를 생성하고 환경 변수 두 개를 설정한 뒤 연결을 확인해야 합니다. 

## Claude Code API 키: 핵심 요약 

Claude Code API 키는 일반적인 Anthropic 형식의 키(sk-...)이며, Claude Code는 다음 환경 변수에서 이 키를 읽습니다: ANTHROPIC_API_KEY. Claude Console(설정 → API 키, 한 번만 표시됨) 또는 이 게이트웨이의 대시보드(언제든 확인 가능)에서 키를 발급받아 export로 설정하면, Claude Code가 브라우저 로그인 없이 시작됩니다. 게이트웨이 키를 사용하는 경우 다음 항목도 설정해야 합니다: ANTHROPIC_BASE_URL . 이 값은 게이트웨이 호스트로 설정합니다. 설정은 이것으로 끝입니다. 이 페이지의 나머지 부분에서는 API 키, 다음 명령으로 발급받는 OAuth 토큰 /login , claude.ai 세션 키의 차이, 운영 체제별 절차, 자주 발생하는 오류를 자세히 설명합니다. 

## Claude Code API 키란 

Claude Code API 키는 Claude Code CLI가 Claude 모델 제공업체에 요청을 보낼 수 있게 하는 인증 자격 증명입니다. 이 키가 없으면 Claude Code에서 실행하는 모든 명령이 인증 오류를 반환합니다. 키는 환경 변수에 저장하는 문자열로, ANTHROPIC_API_KEY(x-api-key 헤더로 전송) 또는 ANTHROPIC_AUTH_TOKEN(Bearer 토큰으로 전송)을 사용합니다. 둘 다 AI Prime Tech에서 작동합니다. 

Anthropic에 직접 연결하는 대신 AI Prime Tech 같은 게이트웨이를 사용하면, 키는 Anthropic Console이 아닌 게이트웨이 대시보드에서 발급받습니다. 키 형식은 다를 수 있지만 Claude Code의 설정 절차는 동일합니다. 환경 변수에 키를 설정하고 기본 URL을 게이트웨이로 지정하면 나머지는 Claude Code가 처리합니다. 키는 Anthropic 결제가 아닌 게이트웨이 계정의 잔액이나 구독에 연결됩니다. 

하나의 키를 여러 기기와 Claude Code 세션에서 동시에 사용할 수 있습니다. 다만 팀에서 키를 공유하면 모든 사용량이 동일한 계정의 요청 한도와 잔액에 합산됩니다. 팀 환경에서는 대시보드에서 개발자별로 별도의 키를 생성해야 각 사용자에 대한 사용량 추적과 요청 제한이 올바르게 작동합니다. 

## API 키와 OAuth 토큰 비교 — 그리고 "세션 키"란 

Claude Code는 두 종류의 자격 증명을 지원합니다. API 키(ANTHROPIC_API_KEY 또는 Bearer 토큰으로 전송되는 ANTHROPIC_AUTH_TOKEN)는 API 잔액에서 토큰별로 요금을 차감하며, 게이트웨이에서는 이 방식을 사용합니다. OAuth 토큰은 Claude Pro 또는 Max 구독에서 발급됩니다: /login 명령을 Claude Code 안에서 실행하면 로그인되며, claude setup-token 명령은 CI 또는 헤드리스 기기에 넣어 API 잔액 대신 구독을 사용하도록 할 수 있는 장기 유효 토큰을 발급합니다. 

"Claude 세션 키"는 둘 중 어느 것도 아닙니다. 이는 claude.ai의 브라우저 세션 쿠키로, 일부 비공식 클라이언트가 채팅 인터페이스를 구동하기 위해 추출하는 값입니다. API 자격 증명이 아니며, 일반 사용자용 서비스 약관을 위반하고, 만료되며, 계정이 정지되는 원인이 될 수 있습니다. 프로그래밍 방식으로 접근하려면 Anthropic Console이나 이와 같은 게이트웨이에서 발급받은 API 키를 사용하세요. 

## 단계 1 — 키 발급: Claude Console 또는 게이트웨이 대시보드 

Claude Code가 지원하는 키를 발급하는 곳은 두 군데입니다. Claude Console(platform.claude.com의 Claude 플랫폼)에서 설정 → API 키를 열고 키 만들기를 클릭한 다음, 이름을 지정하고 키의 비밀 값을 복사하세요. Console은 이 값을 한 번만 표시하며 이후에는 이름과 접두사만 나열하므로, 여기서 키를 관리할 때는 기존 키를 다시 조회하는 대신 새 키를 생성해야 합니다. 

Claude Code에는 일반 키가 필요합니다. 관리자 API 키는 조직 관리용 별도 자격 증명이며 요청을 인증하는 데 사용할 수 없습니다. 그런 다음 export ANTHROPIC_API_KEY=sk-ant-... 명령을 셸에서 실행하면 Claude Code가 /login 없이 이 키를 사용합니다. Anthropic은 토큰별로 요금을 청구하며, 먼저 계정에 결제 수단을 등록해야 합니다. 

더 빠른 방법은 게이트웨이 키를 사용하는 것입니다. aiprimetech.io에 가입하고 대시보드에서 API 키를 연 다음 만들기를 클릭하세요. 키는 대시보드에서 언제든 확인할 수 있으므로 원하는 때에 다시 복사하거나 이름을 바꾸거나 폐기할 수 있습니다. 키는 동일한 sk- 형식을 사용하며 같은 환경 변수에서 작동합니다. 추가로 필요한 단계는 ANTHROPIC_BASE_URL뿐이며, 단계 2에서 설명합니다. 

이 시점에는 키는 있지만 잔액은 없습니다. 테스트하기 전에 소액을 충전하세요. 모델 페이지에서 모델별로 일 달러로 이용할 수 있는 양을 확인할 수 있습니다. Claude Code를 하루 종일 사용할 예정이라면 /plans/에서 무제한 요금제를 선택하세요. 

## 단계 2 — 환경 변수 설정 

Claude Code는 게이트웨이 설정을 위해 ANTHROPIC_BASE_URL와 ANTHROPIC_API_KEY 환경 변수를 읽습니다. ANTHROPIC_BASE_URL는 경로 접미사 없이 게이트웨이의 루트 호스트로 설정하세요. Anthropic SDK가 /v1/messages를 자동으로 추가하므로, 기본 URL에 /v1을 포함하면 요청이 /v1/v1/messages로 전송되어 404 오류가 반환됩니다. 

Linux 또는 macOS에서는 셸 프로필(~/.bashrc, ~/.zshrc 또는 ~/.profile)에 다음 줄을 추가하세요: export ANTHROPIC_BASE_URL="https://aiprimetech.io" 및 export ANTHROPIC_API_KEY="your-key-here". Windows에서는 설정 > 시스템 > 고급 시스템 설정 > 환경 변수를 통해 시스템 환경 변수로 설정하거나 PowerShell $PROFILE에 추가하세요. 

프로젝트별로 설정하려면 프로젝트 루트에 동일한 변수를 담은 .env 파일을 만드세요. Claude Code는 작업 디렉터리에서 .env 파일을 로드하며, 이 파일의 값은 시스템 수준 변수보다 우선합니다. 프로젝트마다 다른 API 제공업체를 사용하는 경우 유용합니다. 키를 실수로 버전 관리에 커밋하지 않도록 .gitignore에 .env를 반드시 추가하세요. 

## 단계 3 — 연결 확인 

환경 변수를 설정한 후에는 변수가 로드되도록 새 터미널 세션을 열고 Claude Code를 실행하세요. '안녕하세요. 응답할 수 있는지 확인해 주세요.'와 같은 간단한 메시지를 입력하세요. Claude의 응답을 받으면 설정이 전체 과정에서 정상적으로 작동하는 것입니다. 키가 유효하고 기본 URL이 올바르며 게이트웨이가 요청을 Claude로 정상적으로 전달하고 있다는 뜻입니다. 

확인에 실패하면 오류 메시지에서 원인을 알 수 있습니다. 401 또는 403 오류는 API 키가 유효하지 않거나 만료되었다는 뜻이므로, 대시보드에서 키를 다시 복사하세요. 404 오류는 거의 항상 기본 URL이 잘못되었다는 뜻이므로, 실수로 /v1 접미사나 끝에 슬래시를 추가했는지 확인하세요. 연결 거부 오류는 게이트웨이에 접근할 수 없다는 뜻이므로 네트워크, VPN 또는 방화벽 설정을 확인하세요. 

curl로 게이트웨이의 상태 엔드포인트에 요청하여 프로그래밍 방식으로 확인할 수도 있습니다: curl -H 'Authorization: Bearer YOUR_KEY' https://aiprimetech.io/v1/models. 키가 유효하면 사용 가능한 모델 목록이 반환됩니다. 이 요청은 작동하지만 Claude Code가 작동하지 않는다면, 문제는 키나 게이트웨이 자체가 아니라 환경 변수 로드에 있습니다. 

## 단계 4 — 모델 기본 설정 구성 

기본적으로 Claude Code는 각 등급(Sonnet, Opus, Haiku)에 대해 내장된 모델 선택값을 사용합니다. 추가 환경 변수 ANTHROPIC_DEFAULT_SONNET_MODEL, ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_HAIKU_MODEL, ANTHROPIC_DEFAULT_FABLE_MODEL으로 이 값을 재정의할 수 있습니다. 이 변수에는 게이트웨이가 지원하는 정확한 모델 식별자를 설정하세요. 

대부분의 개발자에게는 ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-5 및 ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-6 설정이면 충분합니다. Claude Code는 대부분의 상호작용에서 기본적으로 Sonnet을 사용하며, /model 명령으로 Opus를 선택하거나 계획 모드에서 더 강력한 모델로 전환할 때 Opus를 사용합니다. 게이트웨이는 현재의 모든 Claude 모델 버전을 지원합니다. 

CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1로 설정하여 게이트웨이 모델 검색을 활성화하세요. 이렇게 하면 Claude Code가 하드코딩된 목록 대신 게이트웨이에 사용 가능한 모델을 조회합니다. 또한 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1으로 설정하여 텔레메트리 요청이 게이트웨이로 전송되지 않도록 하세요. 불필요한 요청이 줄어들고 요청 지연 시간도 조금 개선됩니다. 

## 일반적인 인증 오류 해결 

가장 자주 발생하는 문제는 환경 변수가 로드되지 않는 것입니다. 프로필에 변수를 설정한 후에는 반드시 새 터미널을 열어야 합니다. 기존 터미널은 이전 환경을 사용합니다. Windows에서는 새 탭을 여는 것만으로는 부족하고 터미널 애플리케이션을 완전히 다시 시작해야 할 수 있습니다. echo $ANTHROPIC_BASE_URL(bash/zsh) 또는 echo $env:ANTHROPIC_BASE_URL(PowerShell)로 확인하세요. 

연결이 유효한데도 '모델을 찾을 수 없음' 오류가 발생하면 모델 식별자가 게이트웨이에서 제공하는 모델과 일치하지 않는 것입니다. 모델 ID는 대소문자를 구분하며 버전별로 다릅니다. 대시보드 또는 /v1/models 엔드포인트에서 지원되는 정확한 식별자를 확인하세요. 흔한 실수로는 'claude-opus-4-6' 대신 'claude-3-opus'을 사용하거나 환경 변수 값에 불필요한 공백을 추가하는 경우가 있습니다. 

대시보드에서 잔액을 확인하세요. 중단 없이 계속 사용하려면 종량제 잔액을 충전하거나 무제한 요금제로 업그레이드하세요. 1일($9) 또는 1주($39) 동안 토큰별 과금 없이 모든 모델을 정액으로 이용할 수 있습니다. 

복사

```
# Add to ~/.bashrc or ~/.zshrc:
export ANTHROPIC_BASE_URL="https://aiprimetech.io"
export ANTHROPIC_API_KEY="your-key-from-dashboard"
export ANTHROPIC_DEFAULT_SONNET_MODEL="claude-sonnet-4-5"
export ANTHROPIC_DEFAULT_OPUS_MODEL="claude-opus-4-6"
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1

# Verify connection:
# $ source ~/.bashrc && claude
# Or test the gateway directly:
# $ curl -H "x-api-key: $ANTHROPIC_API_KEY" https://aiprimetech.io/v1/models
```

## 자주 묻는 질문 

 ANTHROPIC_API_KEY — 어떻게 발급받나요?

Claude Console에서 키를 생성하거나(Settings → API keys → Create Key, 키 비밀값은 한 번만 복사 가능), 여기 게이트웨이 대시보드에서 생성하세요. 게이트웨이에서는 키를 계속 확인할 수 있습니다. 키를 ANTHROPIC_API_KEY로 내보내고, 게이트웨이 키를 사용하는 경우 ANTHROPIC_BASE_URL도 설정하세요. Claude Code와 다른 도구에 별도의 키가 필요한가요?

아니요. 동일한 API 키를 Claude Code, Cursor, Cline, Aider 및 Anthropic Messages API나 OpenAI 호환 엔드포인트를 사용하는 다른 모든 도구에서 사용할 수 있습니다. 하나의 키로 여러 도구를 사용하세요. Claude 세션 키는 API 키와 같은가요?

아니요. 세션 키는 비공식 클라이언트에서 사용하는 claude.ai 브라우저 쿠키이며, API 키는 API와 Claude Code에서 요구하는 인증 정보입니다. 지원과 과금이 적용되고 안정적으로 사용할 수 있는 것은 API 키뿐입니다. ANTHROPIC_API_KEY는 어떻게 발급받나요?

Anthropic 콘솔에서 발급받거나(Anthropic 계정에 정가로 과금), 이 게이트웨이의 대시보드에서 발급받을 수 있습니다(액면가보다 저렴하게 구매한 크레딧 또는 무제한 요금제로 과금). 어느 쪽이든 ANTHROPIC_API_KEY 환경 변수에 설정하면 됩니다. 무엇을 claude setup-token 무엇을 하나요?

Claude 구독용 장기 OAuth 토큰을 생성하여 Claude Code가 대화형 로그인 없이 CI 또는 헤드리스 환경에서 실행되도록 합니다. API 크레딧이 아닌 구독 사용량을 소비하며, 게이트웨이에서는 대신 API 키를 사용합니다. ANTHROPIC_BASE_URL에 /v1을 포함해야 하나요?

아니요. 루트 호스트만 설정하세요: https://aiprimetech.io. Anthropic SDK가 /v1/messages를 자동으로 덧붙입니다. /v1을 포함하면 경로가 중복되어 404 오류가 발생합니다. 여러 컴퓨터에서 동일한 키를 사용할 수 있나요?

네. 하나의 키를 모든 기기에서 동시에 사용할 수 있습니다. 모든 사용량에는 동일한 계정의 잔액과 요청 제한이 적용됩니다. 팀에서는 개별적으로 추적할 수 있도록 개발자마다 별도의 키를 생성하세요.  

몇 분 만에 Claude 사용 시작하기

API 키를 발급받으세요 — Anthropic 계정이나 대기자 명단 등록이 필요하지 않습니다.[API 키 발급받기](/register) 

AI Prime Tech는 독립적인 API 게이트웨이입니다. Anthropic과 제휴 관계가 없으며, Anthropic의 보증을 받거나 Anthropic의 리셀러로 활동하지 않습니다. Claude 및 관련 모델 이름은 각 소유자의 상표입니다.    

## 더 많은 Claude API 가이드

[Claude API 키 발급 방법](/ko/learn/how-to-get-a-claude-api-key/)[Claude API 요금 해설](/ko/learn/claude-api-pricing-explained/)[Claude API를 가장 저렴하게 사용하는 방법](/ko/learn/cheapest-way-to-use-claude-api/)[Claude API로 Cursor 무제한 사용](/learn/use-claude-api-with-cursor/)[Claude Code 무제한 이용](/ko/learn/use-claude-api-with-claude-code/)[Claude API 게이트웨이와 Anthropic 직접 이용 비교](/ko/learn/claude-api-vs-anthropic-direct/)[OpenAI 호환 API를 통해 Claude 사용하기](/ko/learn/openai-compatible-claude-api/)[Claude 모델 해설: Claude Opus, Sonnet, Haiku, Fable 비교 — 모든 Claude API 모델, Anthropic 모델 이름 및 가격 (2026)](/ko/learn/claude-api-models-compared/)[암호화폐로 Claude API 요금 결제하기](/ko/learn/claude-api-with-crypto-payment/)[대기 명단 없이 Claude API 이용하기](/ko/learn/claude-api-without-waitlist/)[Claude 토큰 사용량을 줄이는 방법](/ko/learn/how-to-reduce-claude-token-usage/)[Claude API로 Cline 무제한 사용](/ko/learn/use-claude-api-with-cline/)[Claude API로 Roo Code 무제한 사용](/ko/learn/use-claude-api-with-roo-code/)[JetBrains IDE에서 Claude 무제한 사용](/ko/learn/use-claude-api-with-jetbrains/)[Claude API로 Aider 무제한 사용하기](/ko/learn/use-claude-api-with-aider/)[VS Code에서 Claude 무제한 사용](/ko/learn/use-claude-api-with-vscode/)[Claude API로 OpenCode 무제한 사용하기](/ko/learn/use-claude-api-with-opencode/)[Claude에서 Hermes 에이전트 무제한 실행하기](/ko/learn/run-hermes-agent-with-claude-api/)[Claude에서 OpenClaw 무제한 실행하기](/ko/learn/run-openclaw-with-claude-api/)[Anthropic 호환 API의 의미](/ko/learn/anthropic-compatible-api/)[Claude Code API 비용 — 요금과 절감 방법](/ko/learn/claude-code-api-costs/)[Claude API 오류 설명: 서버 오류 500, 과부하 529, 사용량 제한 429, 잘못된 요청 400 — 각 오류의 해결 방법](/ko/learn/claude-api-errors-troubleshooting/)[Claude API 크레딧 구매 방법 — 그리고 Claude 크레딧이 어떤 "Claude 계정 구매" 상품보다 나은 이유](/ko/learn/buy-claude-api-credits/)[Claude 무료 API: 무료 Claude API 키가 있나요? 2026년에 실제로 무료인 것은 무엇인가요?](/ko/learn/claude-api-free-trial/)[Claude API와 Claude Pro/Max 구독 — 어떤 것을 선택할까요](/ko/learn/claude-api-vs-subscription/)[Claude에서 Codex CLI 실행하기](/ko/learn/use-claude-api-with-codex/)[Claude를 n8n에 연결하기](/ko/learn/use-claude-api-with-n8n/)[LiteLLM을 Claude로 라우팅하기](/ko/learn/use-claude-api-with-litellm/)[Kilo Code에서 Claude 사용하기](/ko/learn/use-claude-api-with-kilo-code/)[GitHub Copilot에 Claude 연결하기](/ko/learn/use-claude-api-with-github-copilot/)[게이트웨이를 통해 Zed를 Claude에 연결하기](/ko/learn/use-claude-api-with-zed/)[Cherry Studio를 Claude에 연결하기](/ko/learn/use-claude-api-with-cherry-studio/)[LangChain을 게이트웨이의 Claude에 연결하기](/ko/learn/use-claude-api-with-langchain/)[Claude로 Factory Droid 실행하기](/ko/learn/use-claude-api-with-factory-droid/)[Claude Code API 이해하기](/ko/learn/claude-code-api/)[애플리케이션에 Claude API 통합하기](/ko/learn/claude-api-integration/)[Claude를 무제한으로 사용하는 방법 — 그리고 "Claude Code 크랙 버전"이 없는 이유](/ko/learn/get-unlimited-claude-usage/)