문서

CC Switch

CC Switch는 데스크톱 앱에서 Claude Code와 Codex의 공급자를 전환합니다. Kunavo는 사용자 지정 구성으로 추가합니다. 서비스 루트, Bearer 인증, Anthropic Messages 네이티브 방식이며 로컬 라우팅은 필요하지 않습니다.

필드 세 개와 드롭다운 두 개면 됩니다. https://api.kunavo.com는 엔드포인트, sk-kn-…는 API 키이며, 대부분의 가이드에서 빠뜨리는 핵심은 API Format는 Anthropic Messages (Native)로, Auth Field는 ANTHROPIC_AUTH_TOKEN로 유지하는 것입니다. Kunavo는 Messages API를 네이티브로 지원하므로 Claude Code 측에서 로컬 라우팅이 필요하지 않습니다.

CC Switch → Claude Code 탭 → Add provider

Provider Name   Kunavo
API Key         sk-kn-...
API Endpoint    https://api.kunavo.com      <- service root, no /v1, no trailing slash

Advanced Options
  API Format    Anthropic Messages (Native) <- the default; do NOT switch
  Auth Field    ANTHROPIC_AUTH_TOKEN (Default)

엔드포인트에는 서비스 루트를 입력합니다. /v1도 끝의 슬래시도 붙이지 않습니다. Anthropic 스타일 클라이언트는 /v1/messages를 자체적으로 덧붙입니다. 따라서 기본 URL에 /v1를 넣는 OpenAI 예시와 이 필드의 형식이 다른 것입니다. 자세한 설명은 ANTHROPIC_BASE_URL 페이지를 참조하세요.

단계별 안내 (Claude Code 탭)

/app/keys에서 키를 생성해 복사하세요. 키는 한 번만 표시됩니다.
맨 위의 Claude Code 탭에서 CC Switch를 열고 더하기 버튼을 클릭합니다. 프리셋을 선택하지 말고 기본 Custom Configuration을 유지합니다.
Provider Name, API Key을 입력하고 API Endpoint = https://api.kunavo.com로 설정합니다.
Advanced Options을 펼쳐 API Format이 Anthropic Messages (Native), Auth Field가 ANTHROPIC_AUTH_TOKEN (Default)인지 확인합니다. 둘 다 기본값이므로 변경하지 말고 확인만 하면 됩니다.
저장한 다음 Activate. 카드에는 Needs Routing 표시가 나타나서는 안 됩니다. 이 표시는 프로토콜 변환이 필요한 제공업체에만 나타납니다.

“라우팅 필요” 표시가 없는 이유

CC Switch의 로컬 라우팅은 프로토콜을 연결하기 위한 기능입니다. Claude Code는 Anthropic Messages 요청을 /v1/messages로 보냅니다. OpenAI Chat Completions 또는 Responses API만 제공하는 게이트웨이는 이에 응답할 수 없으므로, 라우트가 요청을 전송할 때 변환하고 응답을 돌려받을 때 다시 변환합니다. 이 과정에서 스트리밍 이벤트, 도구 호출, thinking 설정의 형태가 바뀝니다. 작동은 하지만 편집기와 모델 사이에 구성 요소가 하나 더 추가됩니다.

Kunavo는 POST /v1/messages를 직접 제공하므로 Claude Code 측에서 변환할 것이 없습니다. 공급자는 Anthropic Messages (Native)로 유지되고 라우트는 경로에 전혀 포함되지 않습니다. 또한 동일한 키로 POST /v1/chat/completions와 POST /v1/responses도 제공하므로, 아래에서 Codex 방향 설정이 가능합니다.

CC Switch 탭	형식을 다음으로 설정	로컬 라우팅
Claude Code	`Anthropic Messages (Native)`	필요 없음
Codex	`Anthropic Messages (routing required)`	필수 — 라우트가 /responses를 /v1/messages로 다시 씁니다

Codex에서 Claude 모델 실행하기

다른 공급자 가이드에서는 다루지 않는 방향입니다. Codex는 OpenAI Responses API와 통신하므로 /v1/messages 엔드포인트를 직접 지정하면 404가 반환됩니다. CC Switch는 Codex를 로컬 라우트에 연결하고 변환을 수행합니다. Codex 탭에는 Anthropic 프리셋이 없으므로 여기서도 Custom Configuration해야 합니다.

CC Switch → Codex 탭 → Add provider

Provider Name      Kunavo
API Key            sk-kn-...
API Request URL    https://api.kunavo.com
Default Model      claude-sonnet-5

Advanced Options
  Upstream Format  Anthropic Messages (routing required)

CC Switch의 자체 가이드에는 다시 언급할 만한 주의사항이 있습니다. 일부 공급자는 Claude API를 Claude Code 클라이언트에서만 사용하도록 제한하므로, 이러한 키는 Codex를 통해 사용하면 오류가 날 수 있습니다. Kunavo에는 그런 제한이 없습니다. 동일한 sk-kn-… 키로 Messages 인터페이스와 Responses 인터페이스를 모두 사용할 수 있으며, 어느 쪽에도 클라이언트 허용 목록이 없습니다. 변환 과정을 모두 건너뛰고 싶다면 Codex CLI에서 Kunavo의 네이티브 /v1/responses 인터페이스를 직접 지정할 수도 있습니다. 해당 방법은 Codex CLI 페이지에 안내되어 있습니다.

모델 매핑

CC Switch는 Claude Code의 세 가지 등급을 실제 모델 ID에 매핑합니다. 세 등급 모두와 Default fallback model를 입력하세요. 매핑되지 않은 요청은 원래 Claude 이름으로 전달되어 업스트림에서 오류가 발생합니다. 요금은 토큰 1M개당 USD이며, 입력 / 출력 순서로 카탈로그에서 실시간으로 가져옵니다.

등급	모델 ID	Kunavo 입력/출력	이유
Haiku	`claude-haiku-4-5`	$0.70 / $3.50	Claude Code가 백그라운드 하위 작업을 여기에 라우팅합니다. 가장 저렴한 등급이 적합합니다.
Sonnet	`claude-sonnet-5`	$1.40 / $7.00	편집 작업에 적합한 기본 모델
Opus	`claude-opus-5-5`	$2.80 / $14.00	아키텍처 수준의 변경

해당 등급이 실제로 1백만 토큰 컨텍스트 창을 지원하지 않는 한 1M 확인란을 선택하지 마세요. 업스트림이 지원하지 않는 컨텍스트를 선언해도 기능이 확장되지는 않습니다. 긴 대화 도중에 실패하도록 만들 뿐입니다.

앱을 디버깅하기 전에 확인하세요

요청 두 개면 문제가 키, 엔드포인트 또는 CC Switch 중 어디에 있는지 판단할 수 있습니다. 둘 다 200을 반환한다면 남은 문제는 양식의 필드에 있습니다. 거의 항상 Auth Field이거나 엔드포인트에 넣으면 안 되는 /v1입니다.

# Settles whether a failure is the key, the endpoint, or CC Switch.
# 200 + a JSON list of model ids means the same key works in the app.
curl -sS https://api.kunavo.com/v1/models \
  -H "Authorization: Bearer sk-kn-..."

# The Anthropic face, which is the one the Claude Code tab actually calls.
curl -sS https://api.kunavo.com/v1/messages \
  -H "Authorization: Bearer sk-kn-..." \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-haiku-4-5","max_tokens":16,
       "messages":[{"role":"user","content":"ping"}]}'

참고 자료

CC Switch는 오픈 소스이며 github.com/farion1231/cc-switch에서 확인할 수 있습니다. 위의 필드 이름과 동작은 자체 가이드인 Claude Code 라우팅 가이드와 Codex 라우팅 가이드에서 가져왔으며, 두 가이드 모두 3.17.0 이상에 적용된다고 명시합니다. 이전 버전에서는 양식이 다르므로 여기에 안내된 필드가 없다면 앱의 정보 패널을 확인하세요. Kunavo 측 문서는 Messages API, chat completions, 통합 허브에서 확인할 수 있습니다.

자주 묻는 질문

CC Switch에서 커스텀 제공자를 추가하려면 어떻게 하나요?

Claude Code 탭에서 더하기 버튼을 클릭하고 기본값인 Custom Configuration을 유지한 다음 Provider Name, API Key 및 API Endpoint를 입력하세요. API Endpoint는 끝에 슬래시가 없는 게이트웨이 서비스 루트입니다. Kunavo의 경우 https://api.kunavo.com이며 /v1은 붙이지 않습니다. 그런 다음 Advanced Options를 열어 API Format과 Auth Field를 확인하세요. 이 두 필드에 따라 제공자가 작동할지가 결정되지만, 대부분의 설정 가이드에서 빠져 있습니다.

Kunavo를 사용하려면 CC Switch의 로컬 라우팅을 켜야 하나요?

아니요. 로컬 라우팅은 프로토콜 간 변환을 위해 사용됩니다. 업스트림이 해당 형식만 지원할 때 Claude Code의 /v1/messages 요청을 OpenAI Responses 또는 Chat Completions로 변환합니다. Kunavo는 Anthropic Messages API를 https://api.kunavo.com/v1/messages에서 기본 제공하므로 API Format은 기본값인 Anthropic Messages (Native)로 유지하고, 제공자 카드에 Needs Routing 표시가 나타나지 않으며, 요청은 업스트림으로 직접 전달됩니다. Chat Completions만 제공하는 게이트웨이는 모든 요청에 로컬 라우팅을 실행해야 합니다.

OpenAI 예시에는 /v1이 있는데 API Endpoint에는 왜 없나요?

두 규칙이 의도적으로 다르기 때문입니다. Anthropic 스타일 클라이언트는 /v1/messages를 직접 덧붙이므로 도메인 주소만 사용합니다. 즉 https://api.kunavo.com입니다. OpenAI SDK는 /v1이 이미 base_url에 포함되어 있기를 기대하므로 https://api.kunavo.com/v1을 사용합니다. CC Switch의 Claude Code 탭은 Anthropic 방식이므로 /v1을 생략합니다. 이 둘을 혼동하는 것은 모든 클라이언트에서 가장 흔한 설정 실패 원인입니다. ANTHROPIC_BASE_URL 페이지에서 두 형식을 설명합니다.

Auth Field를 ANTHROPIC_API_KEY로 설정해야 하나요?

아니요. 기본값인 ANTHROPIC_AUTH_TOKEN을 유지하세요. 이 기본값을 사용하면 CC Switch는 Authorization: Bearer <key>를 전송합니다. ANTHROPIC_API_KEY를 선택하면 대신 x-api-key 헤더를 전송하며 Kunavo는 이 형식도 동일하게 읽습니다. 따라서 문제는 헤더가 아니라 승인 절차입니다. 대화형 세션에서 Claude Code가 ANTHROPIC_API_KEY를 사용하기 전에 일회성 승인을 요청합니다. 여기서 키 사용을 거부하면 이후 해당 키는 무시됩니다. 키가 정상인데도 인증 오류가 발생하는 것처럼 보일 수 있습니다.

CC Switch를 통해 Codex에서 Claude 모델을 실행할 수 있나요?

예. 대부분의 제공자 가이드에서 빠뜨리는 설정 절반이 여기에 있습니다. Codex 탭에서 Custom Configuration을 추가하고 API Request URL을 https://api.kunavo.com으로, Default Model을 claude-sonnet-5 같은 모델로 설정한 다음 Advanced Options에서 Upstream Format을 Anthropic Messages (routing required)로 설정하세요. Codex는 Responses API를 사용하고 라우팅이 /responses를 /v1/messages로 바꾸므로 이 방향에서는 로컬 라우팅을 켜야 합니다. CC Switch 자체 가이드에는 일부 제공자가 Claude API를 Claude Code 클라이언트에서만 사용하도록 제한하며 그런 키는 Codex를 통한 요청에서 실패한다고 경고되어 있습니다. Kunavo는 그런 제한이 없습니다. 동일한 sk-kn- 키로 두 경로 모두 사용할 수 있습니다.

CC Switch의 모델 매핑에는 어떤 모델 ID를 입력해야 하나요?

Kunavo의 카탈로그 ID를 사용하세요. 기본 분할은 Haiku 등급에 claude-haiku-4-5($0.70 / $3.50/100만 토큰)를 사용하는 것입니다. Claude Code가 백그라운드 하위 작업을 이 등급으로 보내기 때문입니다. Sonnet 등급에는 claude-sonnet-5($1.40 / $7.00), Opus 등급에는 claude-opus-5-5($2.80 / $14.00)를 사용하세요. Default fallback model도 항상 입력하세요. 비워 두면 CC Switch가 일치하지 않는 요청을 원래 Claude 이름으로 전달하며, 해당 요청은 업스트림에서 오류가 발생합니다. 실시간 목록은 GET /v1/models에서 확인할 수 있습니다.

CC Switch는 API 키를 어디에 저장하나요?

클라이언트 구성 파일이 아닌 CC Switch 자체 저장소에 보관됩니다. CC Switch는 제공자를 ~/.cc-switch/cc-switch.db에 저장하며, 로컬 라우팅이 클라이언트를 맡을 때 ~/.claude/settings.json에는 인증 항목의 자리표시자와 함께 로컬 라우트 주소만 기록합니다. 실제 키는 전달 시점에 라우트가 삽입합니다. 이는 Kunavo가 아닌 CC Switch의 특성입니다. 붙여 넣은 키가 커밋하려는 파일에 저장된 키와 다르다는 점을 알아 두면 좋습니다.