문서
ANTHROPIC_BASE_URL
Claude Code와 Anthropic SDK를 api.anthropic.com이 아닌 다른 엔드포인트에 연결하는 환경 변수입니다. 전체 변수 참조, 클라이언트별 설정, 거의 모든 오류의 원인이 되는 두 가지 주의사항을 확인하세요.
ANTHROPIC_BASE_URL은 기본값인 https://api.anthropic.com 대신 API 요청을 보낼 호스트를 Anthropic SDK와 Claude Code에 알려 줍니다. 경로가 없는 origin만 설정하세요. 클라이언트가 /v1/messages를 직접 추가합니다. Authorization: Bearer 헤더로 전달되는 ANTHROPIC_AUTH_TOKEN과 함께 사용하세요.
# The origin only — no trailing /v1, no trailing slash.
export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...그런 다음 새 터미널을 여세요. Claude Code와 SDK는 프로세스가 시작될 때 이 변수들을 읽으므로 이미 실행 중인 세션은 이전 엔드포인트를 계속 사용합니다.
https://api.kunavo.com/v1는 /v1/v1/messages로 요청을 보내고 모든 호출에서 404가 반환됩니다. OpenAI SDK는 반대 규칙을 사용하므로 포함해야 합니다. 이번에는 /v1를 base_url에 넣습니다. 이 차이가 여기서 가장 흔한 설정 오류입니다.각 변수의 기능
Claude Code가 읽는 전체 변수 목록은 Anthropic의 환경 변수 참조에서 확인할 수 있습니다. 엔드포인트를 다른 곳으로 지정할 때 중요한 변수는 다음과 같습니다.
| 변수 | 값 | 제어하는 항목 |
|---|---|---|
ANTHROPIC_ | https://api. | 모든 요청을 보낼 origin입니다. 경로와 끝의 슬래시는 넣지 마세요. |
ANTHROPIC_ | sk-kn-… | Authorization: Bearer로 보내는 인증 정보입니다. 게이트웨이에 필요한 항목입니다. |
ANTHROPIC_ | sk-ant-… | api. |
ANTHROPIC_ | claude-sonnet-5 | Claude Code가 대화에 사용하는 기본 모델입니다. |
ANTHROPIC_ | claude-opus-5-5 | opus 별칭(/model opus)이 사용하는 모델입니다. Claude Code 자체 기본값은 최신 Opus이므로 엔드포인트가 제공하는 모델로 고정하세요. Opus 5.5에는 Claude Code v2.1.280 이상이 필요합니다. |
ANTHROPIC_ | claude-sonnet-5 | sonnet 별칭(/model sonnet)이 사용하는 모델입니다. 이 별칭은 기본적으로 Sonnet 5.5를 요청하므로 엔드포인트가 제공하는 Sonnet 모델로 고정하세요. |
ANTHROPIC_ | claude-haiku-4-5 | Claude Code가 자체 백그라운드 호출에 사용하는 저렴한 모델입니다. 캐싱 다음으로 비용을 가장 크게 줄일 수 있는 항목입니다. |
GET /v1/models에서도 실시간으로 반환됩니다.클라이언트별 설정
Claude Code
Claude Code가 시작될 때 사용하는 셸 프로필에 변수를 내보내도록 설정한 다음 새 터미널을 여세요. 설치나 작업 방식은 달라지지 않습니다.
# ~/.zshrc (or ~/.bashrc) — applies to every Claude Code session.
export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...
# Pin models this endpoint serves. Claude Code's default and its opus/sonnet
# aliases follow Anthropic's newest models, which may not be served here —
# unpinned, those calls 404.
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-5Claude Code에서 /status를 실행해 현재 세션이 사용하는 엔드포인트를 확인하세요. 키 생성 위치를 포함한 단계별 안내: Claude Code에서 API 키 설정하기.
Anthropic SDK(Python / TypeScript)
SDK는 같은 환경 변수를 읽으며 두 설정 모두 생성자에 직접 전달할 수도 있습니다. 하나의 프로세스에서 여러 엔드포인트와 통신할 때 유용합니다.
from anthropic import Anthropic
# The Anthropic SDK appends /v1/messages, so pass the origin — not .../v1.
client = Anthropic(
base_url="https://api.kunavo.com",
auth_token="sk-kn-...", # sets the Authorization: Bearer header
)
msg = client.messages.create(
model="claude-sonnet-5",
max_tokens=512,
messages=[{"role": "user", "content": "Say hi"}],
)
print(msg.content[0].text)OpenAI SDK — 다른 규칙
코드가 이미 OpenAI 형식을 사용한다면 ANTHROPIC_BASE_URL는 전혀 필요하지 않습니다. base_url를 OpenAI 호환 경로로 지정하세요. 이번에는 /v1를 포함해 지정한 다음 동일한 Claude 모델을 /v1/chat/completions로 호출하면 됩니다.
from openai import OpenAI
# The OpenAI SDK is the other convention: it wants the /v1 in the base_url.
client = OpenAI(
api_key="sk-kn-...",
base_url="https://api.kunavo.com/v1",
)
r = client.chat.completions.create(
model="claude-sonnet-5",
messages=[{"role": "user", "content": "Say hi"}],
)
print(r.choices[0].message.content)Cline, Roo Code, Kilo Code, Cursor
에디터 에이전트는 대개 환경 변수 대신 자체 UI에서 동일한 두 설정을 제공합니다. "base URL" 또는 "custom endpoint" 필드와 API 키 필드입니다. 규칙은 같습니다. Anthropic 방식 제공자에는 /v1가 없는 origin을 입력하고, API 키 필드에 키를 입력하세요. 클라이언트별 안내: Cline, Roo Code, Kilo Code.
설정이 제대로 되었는지 확인
curl 한 번으로 기본 URL과 인증 정보를 동시에 확인할 수 있습니다. JSON 본문과 함께 200 응답이 오면 둘 다 올바르게 설정된 것입니다.
# 200 and a JSON body means the base URL and the token are both right.
curl -sS https://api.kunavo.com/v1/messages \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
-H "content-type: application/json" \
-d '{"model":"claude-haiku-4-5","max_tokens":16,
"messages":[{"role":"user","content":"ping"}]}'
# In Claude Code, /status shows the endpoint the session is actually using.작동하지 않는 경우
| 증상 | 원인 | 해결 방법 |
|---|---|---|
| 모든 요청에서 404 발생 | ANTHROPIC_ 끝에 /v1가 붙어 있음 | origin만 설정하세요. 클라이언트가 /v1/ |
| 401 / invalid x-api-key | 엔드포인트가 Bearer 토큰으로 인증하는데 인증 정보가 ANTHROPIC_로 설정됨 | 대신 ANTHROPIC_를 사용하세요. 차이점 전체 보기 |
| 계속 api. | 세션이 시작된 뒤 변수를 내보냈거나, 셸이 읽지 않는 프로필에 설정함 | 새 터미널을 여세요. 클라이언트를 실행하는 동일한 셸에서 echo $ANTHROPIC_ |
| 404 model_ | 엔드포인트에서 제공하지 않는 모델 ID | GET /v1/models의 ID를 사용해 ANTHROPIC_를 설정하세요. |
| Claude Code에서 잔액이 부족하다고 표시됨 | 요청은 엔드포인트에 도달했으며 구독이 아니라 키에 요금이 청구됨 | 예상된 동작입니다. 잔액을 충전하거나 토큰을 해제해 요금제로 돌아가세요. 크레딧 부족 참조 |
Pro 또는 Max 구독에 미치는 영향
인증 변수가 설정되어 있는 동안 Claude Code는 로그인된 구독이 아니라 키에 요금을 청구합니다. 요금제 한도는 적용되지 않으며 사용 요금은 키 소유자에게 청구됩니다. 구독 자체에는 영향이 없습니다. 변수를 제거하고 새 터미널을 열면 Claude Code가 다시 해당 요금제를 사용합니다. 두 결제 방식은 결합되지 않습니다. 두 방식의 비용 계산은 Claude Code 요금에서 확인하세요.
다음
자주 묻는 질문
ANTHROPIC_BASE_URL이란?
ANTHROPIC_BASE_URL은 기본 https://api.anthropic.com 대신 API 요청을 보낼 호스트를 Anthropic SDK와 Claude Code에 알려 주는 환경 변수입니다. 경로 없이 origin만 설정하세요. 클라이언트가 /v1/messages를 직접 추가합니다. Authorization: Bearer 헤더로 전달되는 ANTHROPIC_AUTH_TOKEN과 함께 사용하세요. Anthropic 호환 엔드포인트라면 어디든 사용할 수 있으며, Kunavo에서는 https://api.kunavo.com을 값으로 사용합니다.
ANTHROPIC_BASE_URL에 /v1을 포함해야 하나요?
아니요. ANTHROPIC_BASE_URL에는 origin만 입력합니다. https://api.kunavo.com은 맞지만 https://api.kunavo.com/v1은 아닙니다. Anthropic SDK와 Claude Code가 /v1/messages 경로를 직접 추가하기 때문입니다. /v1을 포함하면 요청 경로가 /v1/v1/messages가 되어 404가 반환됩니다. OpenAI SDK는 반대 규칙을 따르므로 base_url에 /v1을 포함해야 합니다. 따라서 호출하는 클라이언트에 따라 동일한 게이트웨이 주소를 서로 다른 방식으로 작성합니다.
ANTHROPIC_AUTH_TOKEN과 ANTHROPIC_API_KEY의 차이는 무엇인가요?
ANTHROPIC_AUTH_TOKEN은 인증 정보를 Authorization: Bearer 헤더로 보내고, ANTHROPIC_API_KEY는 api.anthropic.com이 기대하는 x-api-key 헤더로 보냅니다. Bearer 토큰으로 인증하는 게이트웨이에는 ANTHROPIC_AUTH_TOKEN이 필요합니다. ANTHROPIC_BASE_URL을 변경한 뒤 401 오류가 발생하는 가장 흔한 원인은 대신 ANTHROPIC_API_KEY를 설정하는 것입니다. 둘 중 하나만 설정하세요. 둘 다 있으면 동작 방식은 클라이언트 버전에 따라 달라집니다.
Claude Code에서 사용자 지정 기본 URL을 어떻게 설정하나요?
Claude Code가 시작될 때 사용하는 셸 프로필(~/.zshrc 또는 ~/.bashrc)에 ANTHROPIC_BASE_URL과 ANTHROPIC_AUTH_TOKEN을 내보내도록 설정한 다음, 새 터미널을 여세요. Claude Code는 시작할 때 이 변수들을 읽으므로 이미 실행 중인 세션은 이전 엔드포인트를 계속 사용합니다. Claude Code에서 /status를 실행해 현재 세션이 사용하는 엔드포인트를 확인하세요.
ANTHROPIC_BASE_URL을 설정하면 Claude Pro 또는 Max 구독이 비활성화되나요?
ANTHROPIC_AUTH_TOKEN과 같은 인증 변수 설정 중에는 Claude Code가 로그인된 구독이 아닌 키에 요금을 청구합니다. 따라서 Pro 및 Max 요금제 한도가 적용되지 않고, 사용 요금은 키 소유자에게 청구됩니다. 구독 자체는 영향을 받지 않으며 해제되지도 않습니다. 변수를 제거하고 새 터미널을 열면 Claude Code가 다시 해당 요금제를 사용합니다.