사용자 지정 base URL에서 Claude Code “API Error: 401 authentication_error” — 모든 원인

세 변수를 출력하고 base URL에 경로가 없는지 확인하세요

가장 흔한 원인은 여기에서 확인할 수 있습니다. 클라이언트가 엔드포인트를 직접 추가하므로 base URL은 origin이어야 하며 /v1이나 뒤따르는 경로가 없어야 합니다. /v1로 끝나는 base URL은 /v1/v1/messages에 대한 요청을 생성합니다.

env | grep -E '^ANTHROPIC_(BASE_URL|AUTH_TOKEN|API_KEY|MODEL)='

# Right: https://api.kunavo.com
# Wrong: https://api.kunavo.com/v1

엔드포인트를 두 방식으로 직접 호출하세요

Kunavo의 /v1/messages는 x-api-key 또는 Authorization: Bearer 중 어느 헤더로도 자격 증명을 허용합니다. 따라서 Claude Code 앞에 플러그인이나 프록시가 필요하지 않습니다. curl은 성공하지만 CLI가 실패한다면 문제는 서버가 아니라 셸 환경에 있습니다.

curl -s https://api.kunavo.com/v1/messages   -H "x-api-key: $ANTHROPIC_AUTH_TOKEN"   -H "anthropic-version: 2023-06-01"   -H "content-type: application/json"   -d '{"model":"claude-sonnet-5","max_tokens":8,
       "messages":[{"role":"user","content":"hi"}]}'

# Same call, other header style — both are accepted:
#   -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"

사용하지 않는 변수를 해제하세요

ANTHROPIC_API_KEY와 ANTHROPIC_AUTH_TOKEN이 모두 설정되어 있으면 잘못된 변수가 우선될 수 있습니다. ANTHROPIC_API_KEY를 해제하고 새 셸을 시작한 다음 다시 시도하세요. 셸 프로필의 오래된 export는 다른 모든 해결 방법보다 오래 남습니다.

상태가 404라면 키 디버깅을 중단하세요

메시지에 모델 이름이 포함된 404가 반환되면 자격 증명은 승인되었지만 모델 문자열은 승인되지 않았다는 뜻입니다. ANTHROPIC_MODEL을 수정하세요. 키에는 문제가 없습니다. 새로 설정할 때 흔한 원인은 모델을 지정하지 않았기 때문입니다. 그러면 Claude Code가 내장 기본값인 최신 Opus를 전송하는데, Kunavo가 아직 제공하지 않을 수 있습니다. 또한 /model sonnet은 Kunavo가 제공하지 않는 Sonnet 5.5를 요청합니다. GET /v1/models에서 반환된 ID로 ANTHROPIC_MODEL, ANTHROPIC_DEFAULT_OPUS_MODEL 및 ANTHROPIC_DEFAULT_SONNET_MODEL을 설정하세요.

내 키가 curl에서는 작동하지만 Claude Code에서는 작동하지 않는 이유는 무엇인가요?

거의 항상 셸 프로필에 설정된 두 번째 변수이거나, 경로가 포함된 base URL 때문입니다. 엔드포인트는 두 헤더 형식을 모두 허용하므로 헤더 차이가 원인은 아닙니다.

ANTHROPIC_AUTH_TOKEN과 ANTHROPIC_API_KEY 중 어느 것을 사용해야 하나요?

타사 base URL에는 AUTH_TOKEN을 사용하세요. 즉시 사용됩니다. API_KEY는 먼저 일회성 승인 프롬프트를 표시하며, 이를 실패로 오해하는 경우가 많습니다.

Claude 구독으로 사용자 지정 base URL을 이용할 수 있나요?

아니요. 구독은 제공업체 자체 엔드포인트에 인증합니다. CLI를 다른 곳으로 지정하면 해당 엔드포인트의 자격 증명을 사용하며, 요금도 해당 엔드포인트에서 청구됩니다.