Claude Code에서 서드파티 API를 사용하는 설정 방법: Base URL과 자주 발생하는 오류

원문 발행 2026. 05. 22. 20:54원문 언어 일본어AI 한국어 번역Qiita AI 원문 보기

요약

Claude Code를 서드파티 API 게이트웨이와 연결할 때 발생하는 Base URL 설정 오류와 해결 방법을 설명합니다. 특히 OpenAI 호환 SDK와 달리 Anthropic API 호환 설정을 위해 루트 URL을 사용해야 함을 강조합니다.

Claude Code를 서드파티 API 게이트웨이(API Gateway)를 통해 사용할 때, 가장 실수하기 쉬운 부분은 Base URL입니다.

OpenAI 호환 SDK에서는 흔히 다음과 같은 URL을 사용합니다.

하지만 Claude Code는 Anthropic API 호환 설정이 되기 때문에, /v1을 붙이지 않은 루트 URL(Root URL)을 지정해야 하는 경우가 있습니다.

Crazyrouter를 예로 들면:

ANTHROPIC_BASE_URL=https://crazyrouter.com
ANTHROPIC_API_KEY=sk-your-key

문서 입구:

Claude Code 설정 페이지:

export ANTHROPIC_BASE_URL="https://crazyrouter.com"
export ANTHROPIC_API_KEY="sk-your-key"

중국향 루트를 사용하는 경우:

export ANTHROPIC_BASE_URL="https://cn.crazyrouter.com"
export ANTHROPIC_API_KEY="sk-your-key"

중요: ANTHROPIC_BASE_URL 끝에 /v1을 붙이지 않습니다.

매번 export 하는 것이 번거롭다면, 셸(Shell) 설정에 추가합니다.

zsh의 경우:

echo 'export ANTHROPIC_BASE_URL="https://crazyrouter.com"' >> ~/.zshrc
echo 'export ANTHROPIC_API_KEY="sk-your-key"' >> ~/.zshrc
source ~/.zshrc

bash의 경우:

echo 'export ANTHROPIC_BASE_URL="https://crazyrouter.com"' >> ~/.bashrc
echo 'export ANTHROPIC_API_KEY="sk-your-key"' >> ~/.bashrc
source ~/.bashrc

setx ANTHROPIC_BASE_URL "https://crazyrouter.com"
setx ANTHROPIC_API_KEY "sk-your-key"

새로운 PowerShell을 열어 반영 여부를 확인합니다.

echo $env:ANTHROPIC_BASE_URL
echo $env:ANTHROPIC_API_KEY

프로젝트 디렉토리에서 Claude Code를 실행합니다.

cd your-project
claude

처음에는 작은 질문으로 확인하는 것을 추천합니다.

이 리포지토리의 구성을 간단히 설명해 주세요.

갑자기 큰 편집을 요청하기보다, 먼저 API 연결과 모델 응답을 확인합니다.

Base URL에 /v1을 붙였을 가능성이 있습니다.

NG:

ANTHROPIC_BASE_URL=https://crazyrouter.com/v1

OK:

ANTHROPIC_BASE_URL=https://crazyrouter.com

API 키가 다르거나, 만료되었거나, 또는 환경 변수가 반영되지 않았을 가능성이 있습니다.

echo $ANTHROPIC_API_KEY

키를 로그나 Git에 남기지 않도록 주의하십시오.

여러 설정 파일이나 셸에 다른 환경 변수가 남아 있으면 의도하지 않은 연결 대상으로 향할 수 있습니다.

env | grep -i anthropic

으로 확인할 수 있습니다.

동일한 Crazyrouter라도, OpenAI 호환 SDK에서는 보통:

Claude Code에서는:

이 차이점만 기억해 두어도 상당한 설정 실수를 피할 수 있습니다.

Claude Code에서 서드파티 API를 사용할 때는 일반적인 OpenAI SDK 설정을 그대로 유용하지 않는 것이 안전합니다.

체크포인트:

Crazyrouter의 Claude Code 설정은 여기에서:

AI 자동 생성 콘텐츠