Claude Code에서 API 중계 서비스 Base URL을 설정하는 방법

최소 구성

Claude Code를 중계 서비스에 연결하기 전에, 그 서비스가 Anthropic 호환 API를 제공하는지 확인하세요. 가장 흔한 설정은 다음과 같습니다.

export ANTHROPIC_BASE_URL="https://your-proxy.example"
export ANTHROPIC_AUTH_TOKEN="your proxy API key"
claude

ANTHROPIC_BASE_URL은 요청을 중계 서비스 또는 게이트웨이로 보냅니다. ANTHROPIC_AUTH_TOKEN은 Bearer 토큰으로 전송됩니다.

Claude Code를 설정하기 전에 서비스를 비교하려면 Anthropic 호환, OpenAI 호환, 멀티 모델 서비스를 모은 AI API 중계 서비스를 이용하세요.

API 키 경로

서비스가 Anthropic 형식 API 키를 주면 다음 설정을 요구할 수 있습니다.

export ANTHROPIC_API_KEY="sk-..."
claude

주의: ANTHROPIC_API_KEY를 설정하면 Claude Code는 Claude Pro, Max, Team 구독 로그인의 할당량이 아니라 그 API 키를 씁니다. 중계 서비스를 시험할 때는 새 터미널을 열고, 그 창에서만 변수를 설정하세요.

흔한 오류

• 401: 키가 틀렸거나, 헤더 종류가 다르거나, 서비스가 ANTHROPIC_API_KEY가 아니라 ANTHROPIC_AUTH_TOKEN을 기대합니다.
• 404: Base URL 경로가 틀립니다. 서비스가 /v1을 요구하는지 특히 확인하세요.
• model not found: 그 모델 이름을 서비스가 제공하지 않거나, 커스텀 모델 옵션이 필요합니다.
• MCP 검색 문제: 공식이 아닌 Base URL을 쓰면 Claude Code의 MCP 도구 검색 동작이 달라질 수 있습니다. 필요한 기능이 서비스에서 완전히 전달되는지 확인하세요.

권장 순서

설정이 없는 새 터미널과 임시 구성부터 시작하세요. 동작이 확인된 뒤에 셸 프로필, 프로젝트 스크립트, 전환 도구로 옮깁니다. 처음부터 전역 설정을 바꾸면 계정, 환경 변수, 서비스 API 중 어디가 문제인지 가리기 어려워집니다.