Claude Code 공급자 전환: 5분 만에 배우는 CC Switch 사용법

이 튜토리얼은 CC Switch v4.0.26(2026년 11월)을 기준으로 작성했습니다. 이후 버전에서는 버튼 이름이 바뀔 수 있지만, 설정 방식은 동일합니다.

Claude Code에서 공급자를 바꾸려면 보통 ~/.claude/settings.json을 수정해야 합니다. 기본 URL과 API 키, 경우에 따라 모델도 바꿔야 하죠. 공급자가 하나라면 관리하기 어렵지 않습니다. 하지만 두세 개가 되면 소소한 유지 관리 작업이 생깁니다. 게다가 셸에 남아 있는 오래된 ANTHROPIC_* 환경 변수가 방금 수정한 파일의 설정을 덮어쓸 수 있어, 문제가 생겨도 눈치채기 어렵습니다.

CC Switch를 사용하면 클릭 한 번으로 공급자를 전환할 수 있습니다. 기본 제공되는 AiHubMix 프리셋이 엔드포인트를 채워 주므로 API 키만 붙여넣으면 됩니다. Claude Code는 대개 재시작하지 않아도 변경 사항을 다시 불러옵니다. 이 튜토리얼에서는 전체 설정 과정을 안내한 다음, CC Switch가 실제로 무엇을 기록하는지, 환경 변수로 인해 어떤 문제가 생길 수 있는지, 그리고 직접 모드만으로 충분한 경우는 언제인지 설명합니다.

요약만 보려면 다음과 같습니다. CC Switch를 설치하고, AIHubMix 키를 만든 다음, Claude Code에서 AiHubMix 프리셋을 선택해 키를 붙여넣습니다. 공급자 설정에 ANTHROPIC_MODEL=claude-sonnet-5-5를 추가하고 전환을 클릭한 뒤, claude -p "1+1, output only the answer" --model claude-sonnet-5-5를 실행하면 됩니다. 이 글의 나머지 부분에서는 각 단계를 자세히 설명합니다.

CC Switch란?

CC Switch는 Claude Code, Codex, Gemini CLI, OpenCode 및 기타 코딩 도구의 공급자 설정을 관리하는 오픈 소스 데스크톱 앱입니다(MIT 라이선스, Tauri + Rust + React). 90개가 넘는 공급자 프리셋을 제공하며 사용자 지정 공급자도 지원합니다.

단순한 키 전환 도구 그 이상입니다.

• 직접 모드는 클라이언트 설정 파일의 키 관련 필드를 바꾸고 클라이언트가 공급자와 직접 통신하도록 합니다.
• 라우팅 모드는 127.0.0.1:15721에서 로컬 게이트웨이를 실행하며, API 형식 변환, 장애 조치, 상태 확인, 요청 로그 기능을 제공합니다.
• 통합 모드는 여러 공급자의 모델을 하나의 /model 목록에 모아 보여 줍니다.

저장소와 사용자 설명서는 github.com/farion1231/cc-switch에서 확인할 수 있습니다. 공식 다운로드 경로는 ccswitch.io와 GitHub Releases 페이지뿐입니다. 결제나 계정 자격 증명을 요구하는 사이트는 공식 사이트가 아닙니다.

시작하기 전에

다음 세 가지가 필요합니다.

• Claude Code가 설치되어 있고 터미널에서 실행할 수 있어야 합니다. claude --version으로 확인하세요. 설치되어 있지 않다면 공식 설치 프로그램을 사용하세요. curl -fsSL https://claude.ai/install.sh | bash를 실행하거나, Node.js 22 이상에서 npm i -g @anthropic-ai/claude-code를 실행하면 됩니다.
• AIHubMix 계정과 API 키가 필요합니다. AIHubMix 콘솔에서 키를 만드세요. 키는 보통 sk-로 시작합니다.
• CC Switch 설치 파일이 필요합니다. ccswitch.io 또는 GitHub Releases에서 다운로드하세요.

1단계: CC Switch 설치

처음 실행하면 CC Switch가 기존 Claude Code 설정을 가져와 default라는 공급자로 등록하고 공식 공급자도 추가합니다. 기존 설정은 유지되므로 언제든지 다시 전환할 수 있습니다.

Claude Code가 아직 설치되어 있지 않다면 CC Switch의 앱 페이지에서 설치하거나 업그레이드할 수 있습니다.

2단계: AIHubMix API 키 만들기

AIHubMix API 키 페이지를 열고 키를 만든 다음 복사하세요.

문서에 나오는 AIHUBMIX_API_KEY는 실제 키가 아니라 자리 표시자입니다. 이 문자열을 그대로 붙여넣으면 401 invalid key: AIHUBMIX_API_KEY 오류가 발생합니다.

3단계: Claude Code에 AIHubMix 추가

1. 왼쪽 사이드바에서 Claude Code를 선택합니다.
2. 오른쪽 상단의 + 버튼을 클릭합니다.
3. AiHubMix를 검색하거나, 서드파티 플랫폼 카테고리에서 찾습니다.
4. 이름과 엔드포인트가 자동으로 입력됩니다. https://aihubmix.com입니다. API 키에 키를 붙여넣습니다.
5. 추가를 클릭합니다.

프리셋에는 다음 두 환경 변수가 저장됩니다.

{
  "env": {
    "ANTHROPIC_API_KEY": "sk-your-key",
    "ANTHROPIC_BASE_URL": "https://aihubmix.com"
  }
}

프리셋은 모델을 설정하지 않습니다. AIHubMix 가이드에서는 ANTHROPIC_MODEL을 핵심 변수로 안내하므로, 전환하기 전에 같은 env 블록에 추가하세요.

{
  "env": {
    "ANTHROPIC_API_KEY": "sk-your-key",
    "ANTHROPIC_BASE_URL": "https://aihubmix.com",
    "ANTHROPIC_MODEL": "claude-sonnet-5-5"
  }
}

모델을 지정하지 않으면 Claude Code가 기본 모델 ID를 전송하는데, 해당 모델은 AIHubMix에서 제공하지 않을 수 있습니다.

알아 두면 좋은 점이 두 가지 있습니다.

기본 URL 뒤에 /v1을 붙이지 마세요. Claude Code는 Anthropic Messages 프로토콜을 사용하며 요청 경로를 직접 구성합니다. 올바른 주소는 https://aihubmix.com입니다. https://aihubmix.com/v1은 다른 클라이언트에서 사용하는 OpenAI 호환 기본 URL이며, 이 주소를 사용하면 Claude Code가 여기에 자체 /v1/messages 경로를 덧붙입니다.

프리셋은 ANTHROPIC_API_KEY를 사용하지만, AIHubMix의 Claude Code 가이드에서는 ANTHROPIC_AUTH_TOKEN을 사용합니다. AIHubMix는 둘 다 지원합니다. ANTHROPIC_AUTH_TOKEN은 Bearer 헤더를 전송하고, ANTHROPIC_API_KEY는 x-api-key를 전송합니다. 둘 중 하나만 선택하세요. 서로 다른 값을 두 변수에 모두 입력하지 마세요. AIHubMix 설정 정보, 모델 ID, 오류 참조는 AIHubMix Claude Code 문서에서 확인할 수 있습니다.

프리셋이 보이지 않는 경우(예: 이전 버전을 사용하거나 카드를 삭제한 경우) 사용자 지정 구성을 선택하고 위 JSON을 붙여넣으세요. 공급자 카드의 엔드포인트 관리자에서 지연 시간을 테스트할 수 있습니다. 프리셋에는 https://api.aihubmix.com도 대체 엔드포인트로 포함되어 있어 aihubmix.com이 확인되지 않을 때 사용할 수 있습니다.

4단계: 전환하고 확인하기

직접 탭에서 AiHubMix 카드의 전환을 클릭합니다. 설정이 기록되면 버튼이 사용 중으로 바뀝니다.

Claude Code는 설정을 자동으로 다시 불러오므로 보통 재시작할 필요가 없습니다. 현재 세션에서 이전 공급자를 계속 사용한다면 종료한 뒤 다시 시작하세요.

요청이 처음부터 끝까지 정상적으로 처리되는지 확인하세요.

claude -p "1+1, output only the answer" --model claude-sonnet-5-5

응답이 2라면 요청이 AIHubMix에 도달한 것입니다. 대화형 세션에서는 /status의 Anthropic base URL 항목에 https://aihubmix.com이 표시되어야 합니다.

빠르게 전환하려면 시스템 트레이를 이용하세요. CC Switch 아이콘을 마우스 오른쪽 버튼으로 클릭하고 Claude Code 하위 메뉴를 연 다음 공급자를 클릭합니다. 하위 메뉴 제목에는 현재 활성화된 공급자와 할당량 요약이 표시됩니다.

공식 공급자로 돌아가려면 Claude Official로 전환하고 Claude Code를 재시작한 다음 로그인 절차를 완료하세요.

전환 시 실제로 바뀌는 항목

직접 모드에서 CC Switch는 ~/.claude/settings.json의 연결 및 호환성 관련 필드만 교체합니다. 여기에는 ANTHROPIC_*, AWS_*, CLAUDE_CODE_USE_BEDROCK 같은 프로토콜 선택자, model, apiKeyHelper, 그리고 CLAUDE_CODE_DISABLE_ARTIFACT 및 컨텍스트 윈도우 같은 일부 공급자별 호환성 옵션이 포함됩니다.

permissions, hooks, enabledPlugins, statusLine, MCP 설정, 주석 및 직접 추가한 그 밖의 항목은 그대로 유지됩니다. 정확한 목록은 설정 파일 참조에서 확인할 수 있습니다.

도구 설정을 처음으로 덮어쓰기 전에 CC Switch는 원본을 ~/.cc-switch/backups/live-first-write/에 백업합니다. JSON 형식이 잘못된 경우에는 기록을 거부하고 줄과 열을 알려 주며 파일을 변경하지 않습니다.

주의할 점: 오래된 ANTHROPIC_* 변수

CC Switch가 작동하지 않은 것처럼 보이게 만드는 문제가 바로 이것입니다.

이전에 수동 설정 가이드를 따라 export ANTHROPIC_BASE_URL=... 또는 export ANTHROPIC_AUTH_TOKEN=...을 ~/.zshrc나 ~/.bash_profile에 추가했다면, 해당 변수가 CC Switch가 기록한 값을 덮어쓸 수 있습니다. 카드를 AIHubMix로 전환해도 요청은 여전히 이전 엔드포인트로 전송됩니다.

CC Switch는 이런 충돌을 감지합니다. 창 상단의 노란색 배너에 환경 변수가 설정을 덮어쓸 수 있다고 표시되며, 자세히 보기를 누르면 변수 이름과 값, 출처를 확인할 수 있습니다. 선택 항목 삭제를 누르면 해당 변수를 제거하기 전에 ~/.cc-switch/backups/env-backup-<timestamp>.json에 백업합니다.

수동으로 확인하려면 다음과 같이 하세요.

grep -n "ANTHROPIC" ~/.zshrc ~/.bash_profile 2>/dev/null

기존 export 문을 주석 처리한 다음 source ~/.zshrc를 실행하거나 새 터미널을 여세요. AIHubMix 자체 문서에서는 CC Switch가 설정을 관리하는 경우 전역 ANTHROPIC_* 변수를 제거하도록 권장합니다. 전체 충돌 해결 과정은 환경 변수 참조에서 확인할 수 있습니다.

모델 별칭과 전환

ANTHROPIC_MODEL을 설정하면 Claude Code의 기본 모델은 Sonnet 5.5가 됩니다. /model 별칭(opus, sonnet, haiku, fable)을 AIHubMix의 모델 ID로 연결하려면 매핑도 설정해야 합니다. 다음 키를 env 안에 추가하세요.

공급자 설정 전체는 다음과 같습니다.

{
  "env": {
    "ANTHROPIC_API_KEY": "sk-your-key",
    "ANTHROPIC_BASE_URL": "https://aihubmix.com",
    "ANTHROPIC_MODEL": "claude-sonnet-5-5",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5-5",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5-5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-5-5",
    "ANTHROPIC_DEFAULT_FABLE_MODEL": "claude-fable-5-1"
  }
}

모델 선택 우선순위(높은 순): /model <name> → claude --model <name> → ANTHROPIC_MODEL → settings.json의 model 필드. AIHubMix 모델 목록에서 모델 ID를 복사하세요. 모델 ID는 대소문자를 구분합니다.

라우팅 또는 통합 모드를 사용할 때

AIHubMix에는 직접 모드를 기본으로 사용하는 것이 적합합니다. 엔드포인트가 이미 Anthropic Messages 프로토콜을 지원하므로 프로토콜을 변환할 필요가 없습니다.

장애 조치 대기열을 원하거나 OpenAI 형식의 공급자를 Claude Code 뒤에 연결해야 한다면 라우팅을 사용하세요. 라우팅 모드에서는 Claude Code가 http://127.0.0.1:15721을 가리키고, 설정의 키를 PROXY_MANAGED로 바꾸며, 실제 키는 CC Switch가 주입합니다. 앱을 계속 실행해 두어야 합니다. CC Switch를 종료하면 직접 연결 설정으로 되돌아갑니다. 공식 Claude 구독은 라우팅을 통해 사용할 수 없으므로 직접 모드를 사용하세요.

통합을 사용하면 여러 공급자의 모델을 하나의 /model 목록에서 사용할 수 있습니다. 기본 공급자는 접두사 없이 요청을 처리하고, 다른 공급자의 모델은 ccs- 접두사가 붙어 표시됩니다. 통합은 대체 공급자로 자동 전환하지 않습니다. Claude Code와 Codex에서만 사용할 수 있으며, Claude 공식 구독은 통합에서 지원되지 않습니다. ccs- 모델 목록을 사용하려면 Claude Code 2.1.243 이상이 필요합니다. Claude Code에서는 모델 목록 변경 사항이 즉시 반영되지만, Codex에서는 완전히 재시작해야 합니다.

CC Switch에서 관리하는 다른 항목

• 사용량: 대시보드에서 라우팅된 요청 로그와 로컬 세션 로그를 함께 확인할 수 있습니다. 라우팅 없이도 세션을 검색할 수 있으며, 로그에 기록된 모델을 기준으로 요금이 산정됩니다. 라우팅된 요청은 별도로 기록됩니다.
• MCP: MCP 서버를 한곳에서 관리하고, 선택한 앱과 동기화하는 통합 패널입니다.
• 스킬: 한곳에서 스킬을 검색하고 설치하거나 제거할 수 있습니다.
• 세션: 로컬 세션을 검색하고, 확인하고, 내보내고, 이어서 진행할 수 있습니다.
• 프로젝트: 프로젝트의 공급자, MCP 서버, 스킬, 메모리 파일을 스냅샷으로 저장한 다음, 프로젝트별로 전체 구성을 전환할 수 있습니다.

데이터는 ~/.cc-switch/에 저장되며, SQLite 데이터베이스가 중심 역할을 합니다. 자동 백업은 기본적으로 최근 10개를 보관하며, WebDAV 또는 S3 호환 동기화를 사용할 수 있습니다. 데이터베이스와 내보낸 백업에는 키를 포함한 공급자 구성이 들어 있으므로 비밀 정보로 취급하세요.

문제 해결

아래 오류 문구는 AIHubMix의 Claude Code 문서에서 인용했습니다.

오류 외 증상이 나타날 경우:

• 로그인 화면이 표시되거나 Not logged in이 나타남: /status를 확인하고, 설정 → 앱 설정 → Claude Code에서 Claude Code 최초 실행 확인 건너뛰기를 활성화한 다음 재시작하고 키가 입력되어 있는지 확인하세요.
• 전환이 적용되지 않음: 오래된 셸 변수나 캐시된 세션이 원인일 수 있습니다. 새 터미널을 열거나 Claude Code를 재시작하세요.
• 카드의 연결 테스트는 통과하지만 요청이 실패함: 테스트는 연결 가능 여부만 확인하며 키나 모델은 확인하지 않습니다. 종단 간 테스트를 위해 claude -p 명령을 실행하세요.
• 공식 공급자로 돌아가고 싶음: Claude Official로 전환하고 Claude Code를 재시작한 뒤 다시 로그인하세요.

macOS에서 claude 명령을 찾을 수 없다면, 공식 설치 프로그램은 보통 해당 명령을 ~/.local/bin/claude에 설치합니다. 셸 프로필에 export PATH="$HOME/.local/bin:$PATH"를 추가하고 새 터미널을 여세요.

체크리스트

• [ ] ccswitch.io 또는 GitHub Releases에서 CC Switch를 설치합니다.
• [ ] AIHubMix 콘솔에서 API 키를 만듭니다.
• [ ] Claude Code → + → AiHubMix → 키 붙여넣기 → 추가.
• [ ] 공급자 JSON에 ANTHROPIC_MODEL=claude-sonnet-5-5를 추가합니다.
• [ ] 전환을 클릭하고 카드에 사용 중이 표시되는지 확인합니다.
• [ ] 셸 프로필에서 오래된 ANTHROPIC_* 내보내기 항목을 제거합니다.
• [ ] claude -p "1+1, output only the answer" --model claude-sonnet-5-5를 실행하고 2가 표시되는지 확인합니다.

마지막 명령에서 2가 반환되면 공급자 전환이 완료된 것입니다. 이제 원하는 모델 별칭을 추가하고 라우팅이나 통합이 필요한지 결정하면 됩니다. 대부분의 AIHubMix 사용자에게는 직접 모드로 충분합니다.

자주 묻는 질문

CC Switch는 무료인가요?
네. MIT 라이선스로 공개된 오픈 소스입니다. 사용하는 API의 공급자에게만 비용을 지불하면 됩니다.

전환하면 훅, MCP 서버 또는 플러그인이 삭제되나요?
아니요. 직접 전환은 엔드포인트, 키, 모델, 그리고 공급자별 옵션 몇 가지를 바꿉니다. 훅, 권한, MCP 서버, 플러그인, 상태 표시줄 설정은 파일에 그대로 남습니다.

CC Switch가 제 API 키를 업로드하나요?
공급자 구성은 로컬의 ~/.cc-switch/cc-switch.db에 저장됩니다. WebDAV 또는 S3 동기화를 활성화하면 직접 관리하는 저장소와 동기화됩니다. 데이터베이스와 백업에는 키가 포함되므로 비밀 정보로 취급하세요.

CC Switch를 계속 실행해 두어야 하나요?
직접 모드에서는 그럴 필요가 없습니다. 라우팅과 통합을 사용하려면 앱을 실행 중이어야 하며, CC Switch를 종료하면 클라이언트는 직접 모드로 돌아갑니다.

Claude Official과 AIHubMix를 동시에 사용할 수 있나요?
직접 모드에서는 한 번에 하나의 공급자만 활성화할 수 있습니다. 통합을 사용하면 여러 공급자의 모델을 하나의 목록에 추가할 수 있지만, Claude 공식 구독은 통합에서 지원되지 않습니다. Claude 공식 구독을 사용하려면 직접 모드로 다시 전환하세요.

Windows에서도 작동하나요?
네. CC Switch는 .msi 설치 프로그램 또는 포터블 빌드를 통해 Windows 10 이상을 지원합니다. Linux는 glibc 2.35 이상과 WebKitGTK 4.1이 필요합니다.

공급자 카드에는 연결 상태가 정상으로 표시되는데 Claude Code는 왜 계속 실패하나요?
카드의 연결 확인은 엔드포인트에 연결할 수 있는지만 테스트합니다. API 키나 모델의 유효성은 확인하지 않습니다. 전체 경로를 테스트하려면 종단 간 테스트 명령인 claude -p를 사용하세요.

출처

• CC Switch 저장소
• CC Switch 사용자 설명서: 공급자 추가
• CC Switch 사용자 설명서: 공급자 전환
• CC Switch 사용자 설명서: 구성 파일
• AIHubMix 문서: Claude Code