문서

문서

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과 함께 사용하세요.

~/.zshrc
# 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는 프로세스가 시작될 때 이 변수들을 읽으므로 이미 실행 중인 세션은 이전 엔드포인트를 계속 사용합니다.

ANTHROPIC_BASE_URL에 /v1을 넣지 마세요. Anthropic 클라이언트가 경로를 직접 추가하므로 https://api.kunavo.com/v1는 /v1/v1/messages로 요청을 보내고 모든 호출에서 404가 반환됩니다. OpenAI SDK는 반대 규칙을 사용하므로 포함해야 합니다. 이번에는 /v1를 base_url에 넣습니다. 이 차이가 여기서 가장 흔한 설정 오류입니다.

각 변수의 기능

Claude Code가 읽는 전체 변수 목록은 Anthropic의 환경 변수 참조에서 확인할 수 있습니다. 엔드포인트를 다른 곳으로 지정할 때 중요한 변수는 다음과 같습니다.

변수값제어하는 항목
ANTHROPIC_BASE_URLhttps://api.kunavo.com모든 요청을 보낼 origin입니다. 경로와 끝의 슬래시는 넣지 마세요.
ANTHROPIC_AUTH_TOKENsk-kn-…Authorization: Bearer로 보내는 인증 정보입니다. 게이트웨이에 필요한 항목입니다.
ANTHROPIC_API_KEYsk-ant-…api.anthropic.com이 기대하는 형식인 x-api-key 헤더로 보내는 인증 정보입니다. 이 항목과 위의 토큰 중 하나만 설정하세요.
ANTHROPIC_MODELclaude-sonnet-5Claude Code가 대화에 사용하는 기본 모델입니다.
ANTHROPIC_DEFAULT_OPUS_MODELclaude-opus-5-5opus 별칭(/model opus)이 사용하는 모델입니다. Claude Code 자체 기본값은 최신 Opus이므로 엔드포인트가 제공하는 모델로 고정하세요. Opus 5.5에는 Claude Code v2.1.280 이상이 필요합니다.
ANTHROPIC_DEFAULT_SONNET_MODELclaude-sonnet-5sonnet 별칭(/model sonnet)이 사용하는 모델입니다. 이 별칭은 기본적으로 Sonnet 5.5를 요청하므로 엔드포인트가 제공하는 Sonnet 모델로 고정하세요.
ANTHROPIC_DEFAULT_HAIKU_MODELclaude-haiku-4-5Claude Code가 자체 백그라운드 호출에 사용하는 저렴한 모델입니다. 캐싱 다음으로 비용을 가장 크게 줄일 수 있는 항목입니다.
모델 이름은 엔드포인트에서 실제로 제공하는 것이어야 합니다. 게이트웨이를 지정하고 해당 게이트웨이에서 제공하지 않는 모델 ID를 그대로 두는 것이 두 번째로 흔한 오류입니다. 이 경우 인증 오류가 아니라 404 model_not_found가 발생합니다. Kunavo의 모델 ID는 모델 페이지에 나와 있으며 GET /v1/models에서도 실시간으로 반환됩니다.

클라이언트별 설정

Claude Code

Claude Code가 시작될 때 사용하는 셸 프로필에 변수를 내보내도록 설정한 다음 새 터미널을 여세요. 설치나 작업 방식은 달라지지 않습니다.

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

Claude Code에서 /status를 실행해 현재 세션이 사용하는 엔드포인트를 확인하세요. 키 생성 위치를 포함한 단계별 안내: Claude Code에서 API 키 설정하기.

Anthropic SDK(Python / TypeScript)

SDK는 같은 환경 변수를 읽으며 두 설정 모두 생성자에 직접 전달할 수도 있습니다. 하나의 프로세스에서 여러 엔드포인트와 통신할 때 유용합니다.

anthropic_sdk.py
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로 호출하면 됩니다.

openai_sdk.py
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_BASE_URL 끝에 /v1가 붙어 있음origin만 설정하세요. 클라이언트가 /v1/messages를 추가합니다.
401 / invalid x-api-key엔드포인트가 Bearer 토큰으로 인증하는데 인증 정보가 ANTHROPIC_API_KEY로 설정됨대신 ANTHROPIC_AUTH_TOKEN를 사용하세요. 차이점 전체 보기
계속 api.anthropic.com에 연결됨세션이 시작된 뒤 변수를 내보냈거나, 셸이 읽지 않는 프로필에 설정함새 터미널을 여세요. 클라이언트를 실행하는 동일한 셸에서 echo $ANTHROPIC_BASE_URL로 확인하세요.
404 model_not_found엔드포인트에서 제공하지 않는 모델 IDGET /v1/models의 ID를 사용해 ANTHROPIC_MODEL를 설정하세요.
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가 다시 해당 요금제를 사용합니다.