HiAPI로 Claude Code 연결하기: 월 $100 구독료를 절약하는 완전한 설정 가이드

Claude Code는 Anthropic이 만든 터미널 프로그래밍 도구로, 코드 이해와 리팩터링 능력은 동종 도구 중 최상위권입니다. 하지만 많은 사람이 망설이게 되는 진입 장벽이 하나 있습니다: Claude Code를 쓰려면 월 $200 Max 구독을 결제하거나, 제한된 사용량이 포함된 월 $100를 결제해야 합니다. 하루 종일 코드를 작성하지 않는 사람에게는 이 고정 월 요금이 부담스럽습니다.

좋은 소식은 Claude Code가 BYOK(Bring Your Own Key)를 지원한다는 점입니다. 환경 변수 두 줄만 설정하면 서드파티 API를 연결할 수 있습니다. 이 글에서는 HiAPI의 Claude 모델로 Claude Code를 구동해 고정 월 요금을 종량제로 바꾸는 방법을 설명합니다.

Claude Code 사용자들이 서드파티 API Key를 찾는 이유

Max 구독의 월 요금 구조는 두 부류의 사용자에게 불리합니다:

중·경량 사용자. 하루에 한두 시간만 Claude Code를 쓴다면 토큰 소비로는 Max의 가치를 채우기 어렵습니다. 월 $100를 내는 것은 매일 $3를 써서 실제로는 $0.5어치만 사용하는 셈입니다.

이미 API 사용 습관이 있는 사용자. 많은 사람이 이미 API Key 관리 워크플로를 갖추고 있어 구독제는 오히려 관리 부담이 늘어납니다. 이들은 "하나의 Key로 모든 도구를 연결"하고 싶어 하며, Claude Code만을 위해 별도 구독을 사고 싶어 하지 않습니다.

종량제의 장점은 직관적입니다: 쓴 만큼만 내고, 안 쓰면 돈이 들지 않습니다. 월 요금에서 아낀 부분은 다른 모델이나 도구에 투자할 수 있습니다.

Claude Code의 BYOK 메커니즘 사용법

Claude Code는 시작할 때 두 개의 환경 변수를 읽습니다(HiAPI의 Anthropic Messages 엔드포인트는 도구 호출, 스트리밍 응답, 확장 사고를 이미 구현했지만, Claude Code + HiAPI 엔드투엔드 조합은 아직 실측되지 않았으니 설정 후 간단한 작업으로 먼저 검증하는 것을 권장합니다):

• ANTHROPIC_BASE_URL: API 엔드포인트 주소. 기본값은 Anthropic 공식 주소이며, 서드파티 제공업체 주소로 바꾸면 커스텀 엔드포인트로 전환됩니다.
• ANTHROPIC_API_KEY: 인증 Key. 서드파티 제공업체에서 생성한 API Key로, 보통 sk-로 시작합니다.

원리는 복잡하지 않습니다: Claude Code의 모든 요청은 Anthropic Messages API 프로토콜을 따릅니다. 커스텀 엔드포인트가 이 프로토콜을 구현하기만 하면 Claude Code는 정상적으로 동작합니다. HiAPI의 /v1/messages 엔드포인트는 도구 호출, 스트리밍 응답, 확장 사고를 포함한 Anthropic Messages API를 완전히 지원합니다.

설정 방법은 이 두 변수를 터미널 환경에 기록한 뒤 평소처럼 claude 명령을 실행하는 것입니다. 아래에 전체 설정 단계가 이어집니다.

HiAPI로 Claude Code를 연결해야 하는 이유

HiAPI는 현재 4종의 Claude 모델을 제공하며(가격은 2026-10 기준), 다양한 시나리오와 예산을 커버합니다:

모델	입력 $/M	출력 $/M	컨텍스트
claude-opus-5-5	$2.02	$10.08	1M
claude-opus-4-8	$2.29	$11.47	200K
claude-sonnet-4-6	$3.00	$15.00	200K
claude-opus-4-8@aws	$5.74	$28.70	1M

핵심만 짚어 보면:

Opus 5.5가 가장 큰 강점입니다. 입력 $2.02/M, 출력 $10.08/M으로, 일반적인 Opus급 모델 가격($15/$75)보다 약 87% 저렴합니다. Opus급 성능으로 복잡한 리팩터링 작업을 처리하면서 비용은 예상보다 크게 낮아집니다.

Sonnet 4.6은 가격이 공식과 동일합니다. $3/$15 가격 덕분에 일상적인 코딩 시나리오에서 추가 비용이 없으며, 쓰던 대로 쓰면 됩니다.

4종 모델은 각자 역할이 있습니다. "싼 것을 쓰자"가 아니라 작업 복잡도에 따라 모델을 고르는 것이며, 다음 섹션에서 구체적으로 설명합니다.

또한 HiAPI의 이 Claude 모델들은 Anthropic Messages와 OpenAI Chat 두 프로토콜을 동시에 지원합니다. Claude Code는 Messages 프로토콜을 사용하고, OpenAI 호환 인터페이스를 지원하는 다른 도구(예: Cursor, Codex CLI)도 연결할 수 있어 하나의 Key로 여러 프로그래밍 환경을 커버합니다.

설정 단계(5분이면 완료)

1. HiAPI API Key 발급

HiAPI에 로그인하고 콘솔의 「API Key」 페이지로 들어가 새 Key를 생성합니다. Key 형식은 sk-로 시작하며, 생성 후 즉시 복사해 보관하세요.

계정이 없다면 먼저 가입하고 기본 설정을 완료하세요.

2. 환경 변수 설정

터미널에서 실행:

export ANTHROPIC_BASE_URL=https://api.hiapi.ai
export ANTHROPIC_API_KEY=sk-<당신의 HiAPI Key>

<당신의 HiAPI Key>를 앞 단계에서 받은 Key로 바꾸세요.

이 두 줄을 셸 설정 파일(~/.zshrc 또는 ~/.bashrc)에 기록해 두면 터미널을 열 때마다 다시 입력하지 않아도 됩니다:

echo 'export ANTHROPIC_BASE_URL=https://api.hiapi.ai' >> ~/.zshrc
echo 'export ANTHROPIC_API_KEY=sk-<당신의 HiAPI Key>' >> ~/.zshrc
source ~/.zshrc

3. Claude Code 시작

claude

Claude Code는 시작 후 이 두 환경 변수를 자동으로 읽어 요청을 HiAPI로 보냅니다. 모두 정상이라면 평소처럼 Claude Code를 사용할 수 있으며, 차이는 백엔드가 HiAPI로 바뀐 것뿐입니다.

4. 검증

시작 후 "현재 디렉터리의 파일 나열" 같은 간단한 작업을 입력해 테스트하여 응답이 정상이고 스트리밍 출력이 원활한지 확인하세요. 문제가 있다면 환경 변수가 올바르게 설정되었는지 확인하세요:

echo $ANTHROPIC_BASE_URL
echo $ANTHROPIC_API_KEY

모델 선택: Sonnet vs Opus

초보자가 가장 쉽게 저지르는 실수는 "Opus가 있으면 Opus를 쓴다"입니다. 사실 가격보다 작업에 따라 모델을 고르는 것이 더 중요합니다. 아래에 시나리오별 권장 사항을 제시합니다:

일상 코딩 → claude-sonnet-4-6. 코드 작성, 버그 수정, 기능 추가, 프로젝트 구조 이해. Sonnet의 응답 속도는 충분히 빠르고 대부분의 일상 프로그래밍 요구를 커버합니다. 가격은 공식과 동일하지만 월 $100 진입 장벽이 없어 실제 지출은 훨씬 적습니다.

복잡한 리팩터링 / 파일 간 수정 → claude-opus-5-5. 여러 파일에 걸친 아키텍처 조정, 코드 로직에 대한 깊은 이해가 필요한 작업. Opus 5.5는 성능이 가장 강력하면서 가격은 $2.02/$10.08에 불과해 현재 가장 가성비 좋은 Opus 옵션입니다. 1M 컨텍스트도 대형 프로젝트를 처리하기에 충분합니다.

일반적인 복잡 작업 → claude-opus-4-8. Sonnet과 Opus 5.5 사이에 위치합니다. 가격 $2.29/$11.47도 부담이 없습니다. 모델 선택에서 고민하고 싶지 않을 때 쓰는 "기본 강화판"에 적합합니다.

1M 컨텍스트가 필요하지만 Opus 5.5를 쓸 수 없을 때 → claude-opus-4-8@aws. Opus 4.8의 대형 컨텍스트 버전으로, 가격이 높은 편($5.74/$28.70)이라 초대형 코드베이스의 전역 분석에 적합합니다. 일반적인 시나리오에서는 Opus 5.5를 우선 고려하세요.

한 줄 요약: 일상은 Sonnet, 복잡한 작업은 Opus 5.5로 전환. 일 단위로 비용을 계산하면 중간 정도 사용 시 대략 $1-3/일로, 월 $100 구독보다 훨씬 유연합니다.

비용에 관하여: Claude Code가 대화마다 소비하는 토큰량은 차이가 큽니다. 간단한 질의응답은 수백 토큰, 복잡한 리팩터링은 수만 토큰에 이를 수 있습니다. 가격표만 보지 말고 일주일 실제 사용량으로 구독보다 유리한지 평가하는 것을 권장합니다. HiAPI 콘솔은 사용량 통계를 제공해 실제 소비를 추적하기 편리합니다.

FAQ

Claude Code에서 정말 서드파티 API Key를 쓸 수 있나요?

가능합니다. Anthropic 공식은 Claude Code에서 ANTHROPIC_BASE_URL 환경 변수를 제공하며, 이는 커스텀 엔드포인트를 지원하기 위한 것입니다. 크랙이나 비공식 사용법이 아닙니다.

설정 후 Claude Code 기능에 빠지는 것이 있나요?

핵심 기능(코드 읽기/쓰기, 터미널 실행, 도구 호출, 대화)은 모두 Anthropic Messages API 프로토콜을 따르므로 영향을 받지 않습니다. HiAPI 엔드포인트는 해당 프로토콜을 완전히 구현했습니다. 비정상 동작이 발생하면 먼저 API Key가 유효한지, 환경 변수가 올바른지 확인하세요.

설정 후 Claude Code에서 오류가 나면 어떻게 하나요?

가장 흔한 문제는 환경 변수가 적용되지 않은 것입니다. 현재 터미널 세션에서 echo $ANTHROPIC_BASE_URL에 출력이 있는지 확인하세요. Claude Code 데스크톱 앱(터미널 버전이 아닌)을 사용한다면 환경 변수 적용 방식이 다르므로, Claude Code의 해당 플랫폼 환경 변수 설정 방법을 확인해야 합니다.

한 달에 얼마나 절약할 수 있나요?

매일 Claude Code로 2-3시간 코딩한다고 가정하고 Sonnet 4.6 가격으로 계산하면, 일평균 토큰 소비는 대략 $1-3 정도로 월 지출은 약 $30-90입니다. 월 $100 Max 구독과 비교하면 중·경량 사용자는 40-70%를 절약할 수 있습니다.

중량 사용자(전일 코딩, 대량 리팩터링)의 경우는 실측이 필요합니다: 월 $100가 분기점이며, 실제 API 비용이 이 수치를 넘으면 Max 구독이 오히려 더 유리합니다. 먼저 서드파티 Key로 일주일 실행해 실제 토큰 비용과 Max 구독 가격을 비교한 뒤 결정하는 것을 권장합니다.

HiAPI의 다른 모델(GPT, DeepSeek 등)을 Claude Code에 쓸 수 있나요?

아니요. Claude Code는 Anthropic의 도구이므로 Claude 시리즈 모델만 쓸 수 있습니다. 다만 HiAPI의 비-Claude 모델은 OpenAI 호환 인터페이스를 지원하는 다른 프로그래밍 도구(예: Codex CLI, Cursor 등)에서 사용할 수 있어, 동일한 Key로 여러 도구를 커버합니다.

HiAPI의 Claude 모델에 속도 제한이 있나요?

HiAPI는 API Key에 속도 제한이 있으며 구체적인 수치는 콘솔에서 확인할 수 있습니다. 일반적인 프로그래밍 시나리오에서는 제한에 도달하지 않습니다. 장시간 연속 고강도로 사용한다면 콘솔에서 현재 제한값을 먼저 확인하세요.

---

HiAPI로 Claude Code를 연결하면 가장 큰 변화는 비용 절약 자체가 아니라 더 이상 한 도구를 위해 별도의 월 요금을 내지 않아도 된다는 점입니다. 하나의 Key로 Claude Code도, 다른 프로그래밍 환경도 관리하며 사용량 기반 과금이라는 단순한 논리로 돌아갑니다.

Claude Sonnet 4.6 모델 상세 보기 · Claude Opus 5.5 모델 상세 보기