Claude Code 중계 설정 튜토리얼: 터미널 에이전트 및 Base URL 구성

发布时间2026年8月30日 09:08
语言ko

Anthropic 공식 터미널 코딩 에이전트 Claude Code 설정 튜토리얼: 설치, ANTHROPIC_BASE_URL 및 키 설정, 모델 전환 및 일반적인 문제 해결 방법.

1. Claude Code란 무엇인가

Claude Code는 Anthropic의 공식 터미널 코딩 에이전트(CLI)로, 터미널에서 직접 코드를 읽고 쓰고, 명령어를 실행하며, 작업을 수행할 수 있습니다. ANTHROPIC_BASE_URL 및 ANTHROPIC_API_KEY와 같은 환경 변수를 기본적으로 지원하므로, 중계 게이트웨이를 쉽게 설정하여 개인 키와 크레딧으로 사용할 수 있습니다.

2. Claude Code 설치

Node.js(공식 권장 버전 18 이상)가 필요하며, 다음과 같이 전역 설치합니다:

npm install -g @anthropic-ai/claude-code

설치 후 터미널에 claude를 입력하여 실행하세요. /model 또는 claude --model …을 사용하여 모델을 전환할 수 있습니다.

3. 환경 변수 설정

Windows (PowerShell)

$env:ANTHROPIC_BASE_URL="https://www.relay-api.com"
$env:ANTHROPIC_API_KEY="sk-당신의키"
$env:ANTHROPIC_MODEL="claude-sonnet-5"
claude

macOS / Linux (bash / zsh)

export ANTHROPIC_BASE_URL="https://www.relay-api.com"
export ANTHROPIC_API_KEY="sk-당신의키"
export ANTHROPIC_MODEL="claude-sonnet-5"
claude

설명: ANTHROPIC_API_KEY는 요청 헤더에 포함되며, ANTHROPIC_BASE_URL은 기본 API 엔드포인트를 재정의하여 해당 Anthropic 게이트웨이를 가리키도록 합니다.

4. 인터페이스 주소 대조표

모델 그룹	본 사이트 입구 (Base URL)	프로토콜
Claude / Anthropic	`https://www.relay-api.com`	Anthropic Messages
GPT / OpenAI	`https://www.relay-api.com/v1`	OpenAI Chat Completions
Gemini	`https://www.relay-api.com/v1beta`	Google generateContent

5. 일반적인 문제 해결

현상	조치
401 / 403	키가 유효하지 않거나, 활성화되지 않았거나, 잔액이 부족합니다. `sk-` 키가 정확한지 확인하고 충전하세요.
404 / 모델 사용 불가	모델 이름이 플랫폼 slug와 일치하지 않거나 해당 모델이 활성화되지 않았습니다. 모델 ID를 확인하세요.
Unknown model	입력한 모델 ID가 정확해야 합니다(대소문자 구분). 모델 리스트에서 확인하세요.
요청 시간 초과	작업이 길 경우 타임아웃 설정을 적절히 늘리거나, 네트워크 불안정 시 재시도하세요.

보안 권장 사항: 키를 공개 저장소에 작성하지 마십시오. .env 파일이나 환경 변수를 사용하세요. 코드 생성 작업은 토큰 소모가 많으니 잔액을 주의 깊게 살피고, '사용량 로그'에서 각 호출 내역을 확인하세요.

Base URL 설명: 본 사이트는 /v1beta/models/...와 /v1beta/v1beta/models/...(및 /v1/...와 /v1/v1/...)을 모두 허용하므로, 클라이언트가 /v1 또는 /v1beta를 자동으로 보완하더라도 호출에 영향이 없습니다. Base URL은 도메인 루트만 입력하거나 /v1beta가 포함된 주소를 입력해도 모두 작동합니다. 모델 ID는 제어판 '토큰' 페이지 오른쪽 상단의 '모델 ID'에서 복사하여 확인하세요.