Claude Code 중계 접속 튜토리얼: 터미널 에이전트와 Base URL 설정

1. Claude Code란 무엇인가

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

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. 문제 해결 (Troubleshooting)

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

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