Claude Code에 타사 API 연결하기: 환경 변수부터 CC Switch까지

공급자를 바꾸기 전에 준비할 것

Claude Code는 필요한 Anthropic API 형식을 지원하는 타사 게이트웨이로 요청을 보낼 수 있습니다. 동작하는 CLI, 공급자 인증 정보, Anthropic 호환 Base URL, 활성화된 Claude 모델, 사용 가능한 잔액이 필요합니다. OpenAI Chat Completions 엔드포인트만으로는 이 구성을 사용할 수 없습니다.

이 글은 API Route의 https://global.api-route.com과 claude-sonnet-4-6을 예로 듭니다. 먼저 현재 요금과 키에서 허용된 모델을 확인하세요. 가입 후 API 연결에서 키를 설정하고 소량의 예산으로 시작하세요.

설정 근거는 2026년 10월 17일 공식 게이트웨이 연결 가이드, 호환성 요구사항, 모델 설정과 대조했습니다. CLI 설치는 공식 절차를 따르고 claude --version으로 확인하세요.

Anthropic Base URL에 /v1을 중복으로 붙이지 마세요

API Route에서는 ANTHROPIC_BASE_URL=https://global.api-route.com을 설정합니다. Claude Code가 /v1/messages 같은 경로를 추가합니다. 웹사이트 주소나 /v1/chat/completions를 넣지 마세요. 키가 유효해도 잘못된 프로토콜 경로라면 404가 날 수 있습니다.

ANTHROPIC_AUTH_TOKEN은 Authorization의 Bearer 토큰으로, ANTHROPIC_API_KEY는 x-api-key 헤더로 전송됩니다. 아래 예제는 API Route CC Switch 내보내기와 같은 Bearer 방식을 사용합니다. 한 가지 인증 방식을 선택하고 현재 셸의 충돌하는 이전 인증 정보를 제거하세요.

1. 새 터미널 세션에 환경 변수 설정하기

기존 공급자 설정을 기록하고 ~/.claude/settings.json이 있다면 비공개로 백업하세요. 키가 포함될 수 있으므로 공개 저장소에 두지 마세요. 셸 환경 변수와 프로젝트·사용자·관리 설정을 로컬에서 확인해 중복 설정을 찾고, 비밀값을 이슈에 붙여 넣지 마세요.

macOS / Linux: Bash 또는 Zsh

unset ANTHROPIC_API_KEY CLAUDE_CODE_OAUTH_TOKEN
export ANTHROPIC_BASE_URL='https://global.api-route.com'
read -rsp 'API Route key: ' ANTHROPIC_AUTH_TOKEN; printf '\n'
export ANTHROPIC_AUTH_TOKEN
export ANTHROPIC_MODEL='claude-sonnet-4-6'
export ANTHROPIC_DEFAULT_SONNET_MODEL="$ANTHROPIC_MODEL"

Windows: PowerShell 7

Remove-Item Env:ANTHROPIC_API_KEY, Env:CLAUDE_CODE_OAUTH_TOKEN -ErrorAction SilentlyContinue
$env:ANTHROPIC_BASE_URL = 'https://global.api-route.com'
$env:ANTHROPIC_AUTH_TOKEN = Read-Host 'API Route key' -MaskInput
$env:ANTHROPIC_MODEL = 'claude-sonnet-4-6'
$env:ANTHROPIC_DEFAULT_SONNET_MODEL = $env:ANTHROPIC_MODEL

이 변수는 현재 터미널과 여기서 시작한 프로세스에 적용됩니다. 이미 열려 있는 다른 터미널로 자동 전파되지 않습니다. Haiku나 Opus 별칭을 사용하는 작업이 있다면 라우트가 지원하는 모델로 먼저 고정하세요. 모든 별칭을 하나의 모델로 연결하면 모델 선택 동작이 바뀌므로 의도적으로 결정해야 합니다.

2. Claude Code 실행 전에 Messages API 확인하기

설정한 터미널에서 작은 유료 요청부터 보냅니다. Bash 예제에는 curl과 jq가 필요하며 PowerShell용 명령도 아래에 있습니다. content 배열과 usage 객체가 반환되면 기본 Messages 연결은 확인됩니다. 도구와 스트리밍은 별도로 테스트해야 합니다.

curl --fail-with-body -sS "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H 'anthropic-version: 2023-06-01' \
  -H 'content-type: application/json' \
  -d "$(jq -nc --arg model "$ANTHROPIC_MODEL" \
    '{model:$model,max_tokens:32,messages:[{role:"user",content:"Reply with OK."}]}')"

$body = @{
  model = $env:ANTHROPIC_MODEL
  max_tokens = 32
  messages = @(@{ role = 'user'; content = 'Reply with OK.' })
} | ConvertTo-Json -Depth 5
Invoke-RestMethod -Method Post -Uri "$env:ANTHROPIC_BASE_URL/v1/messages" -Headers @{
  Authorization = "Bearer $env:ANTHROPIC_AUTH_TOKEN"
  'anthropic-version' = '2023-06-01'
} -ContentType 'application/json' -Body $body

이후 claude --model claude-sonnet-4-6을 실행하고 /status에서 모델과 인증 정보 출처를 확인한 뒤 짧은 답변을 요청하세요. 사용 로그에서 요청 시각과 모델, 요금을 대조하세요. 게이트웨이나 CLI가 정확한 업스트림 식별 정보를 제공하지 않는다면 표시된 모델 이름만으로 실제 라우트를 증명할 수는 없습니다.

3. CC Switch로 공급자 프로필 저장하기

CC Switch는 독립 커뮤니티가 제공하는 데스크톱 설정 관리 도구입니다. 프로젝트 자체 배포 경로에서 설치하고 어떤 정보가 저장되는지 확인하세요. 선택 사항이므로 연결 시험만 한다면 앞의 셸 설정으로도 충분합니다.

1. API Route의 API 연결에서 검증된 키, 사용 가능한 Claude 모델, 엔드포인트를 선택합니다.
2. 대상 앱을 Claude Code로 선택해 CC Switch로 가져오고 Base URL, 모델, 인증 필드를 로컬에서 확인합니다.
3. 가져온 공급자를 활성화합니다. 수동 추가라면 Claude Code를 선택하고 같은 URL·키·env 설정을 입력합니다.
4. Claude Code를 다시 시작합니다. 저장한 프로필을 검증하기 전에 셸의 이전 덮어쓰기 값을 지우세요. 환경 변수가 파일 설정보다 우선할 수 있습니다.
5. 짧은 요청을 보내 API Route 사용 로그에서 요금을 확인합니다. 여러 설정 관리 도구가 같은 파일을 동시에 수정하지 않도록 하세요.

수동으로 저장하려면 아래 항목을 개인용 ~/.claude/settings.json에 병합합니다. Windows 경로는 %USERPROFILE%\.claude\settings.json입니다. 다른 설정은 보존하고 키는 로컬에서 교체하며 이 파일을 버전 관리에 넣지 마세요.

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://global.api-route.com",
    "ANTHROPIC_AUTH_TOKEN": "REPLACE_WITH_YOUR_KEY",
    "ANTHROPIC_MODEL": "claude-sonnet-4-6",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-6"
  }
}

CLI와 편집기 확장은 설정을 읽는 방식이 다를 수 있습니다. 예를 들어 VS Code 확장에는 공식 문서의 claudeCode.environmentVariables 항목이 있습니다. 실행 중인 편집기가 새 터미널 변수를 상속했다고 가정하지 말고 실제 사용하는 확장에서 검증하세요.

응답 코드와 현재 설정을 기준으로 문제 해결하기

문의할 때는 시각, HTTP 상태, 비밀값을 제거한 오류 본문, 제공되는 요청 ID를 기록하세요. 키나 소스 코드는 보내지 마세요. 필수 헤더와 기능 전달은 호환성 가이드를 참고하세요. 타사 라우트는 Claude Code의 새 기능 지원이 늦을 수 있습니다.

단계적으로 이전하고 복구 경로 남기기

1. 이전 프로필과 설정을 비공개로 백업하고 모델 선택 및 셸 시작 파일의 변수를 기록합니다.
2. 짧은 텍스트, 스트리밍, 읽기 전용 도구, 대표적인 저장소 작업으로 시험합니다. 비용 비교와 실제 청구액을 대조하세요.
3. 캐시 검증 방법으로 반복 입력을 측정합니다. 공급자가 바뀌어도 캐시나 크레딧이 이전된다고 가정하지 마세요.
4. 일부 작업부터 옮기고 인증 정보는 분리합니다. 이전 키가 더 이상 쓰이지 않는 것을 확인한 후 폐기하세요.
5. 복구하려면 새 CC Switch 프로필을 비활성화하거나 이전 사용자 설정을 복원하고, 셸과 시작 파일에서 새 변수를 제거한 뒤 클라이언트를 다시 시작합니다. /status와 요금 로그를 다시 확인하세요.

타사 인증 정보로 보낸 요청은 해당 공급자 계정에 별도로 청구되며 Claude 앱 구독과 다릅니다. 저장소를 연결하기 전에 데이터 처리와 라우트 제약을 검토하세요. API 호환성만으로 도구, 한도, 고객 지원, 서비스 약관까지 같아지는 것은 아닙니다.

API Route 계정을 만들고 목표 모델의 요금을 확인한 뒤 첫 요청을 검증하고 지속 사용 예산을 충전하세요. 계정 설정과 첫 호출은 빠른 시작에서 안내합니다.