Claude Code Router — Claude Code를 모든 모델로 라우팅하거나 라우터를 완전히 건너뛰기

Claude Code Router를 검색하는 대부분의 사람은 서로 다른 두 가지 중 하나를 원합니다. 여러 모델 공급자에 걸쳐 Claude Code를 라우팅하거나, Anthropic의 정가보다 저렴한 곳에서 Claude Code를 실행하려는 것입니다. 라우터가 필요한 것은 첫 번째 경우뿐입니다. Claude Code는 ANTHROPIC_BASE_URL를 기본적으로 읽으므로 두 번째 경우에는 환경 변수 세 개만 설정하면 되고 추가 소프트웨어가 전혀 필요하지 않습니다.

이 가이드는 두 경로를 모두 다루며, 정확한 변수 이름, 조용한 401을 발생시키는 자격 증명 함정, 모든 게이트웨이 뒤에서 작동하지 않는 기능의 정직한 목록을 제공합니다. 최근 다른 CCR 문서를 읽었다면 먼저 옵션 B로 이동하세요. 해당 문서에서 편집하라고 안내하는 config.json는 더 이상 라우터가 읽는 구성이 아닙니다.

실제로 어떤 것이 필요한가요?

라우터는 로컬 서비스입니다. 실행하고 구성하고 최신 상태로 유지해야 하는 프로세스가 하나 더 생깁니다. 또한 2026년 현재 파일을 편집하는 방식이 아니라 자체 UI를 갖춘 데스크톱 앱입니다. 여러 공급자 라우팅, 요청별 비용 집계 또는 하위 에이전트 수준의 모델 선택이 실제로 필요할 때 이러한 비용을 감수할 가치가 있습니다. 기본 URL만으로 충분한 경우에는 그렇지 않습니다.

옵션 A — 기본 URL 변경(설치 없음)

Kunavo는 기본 Anthropic Messages API를 /v1/messages에서 제공하며, 이곳이 Claude Code가 호출하는 엔드포인트입니다. 해당 주소를 가리키세요.

export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...              # create at kunavo.com/app/keys
export ANTHROPIC_MODEL=claude-sonnet-5             # exact slug — see the table below
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5     # the opus alias and plan mode (v2.1.280+)
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5   # the sonnet alias; Sonnet 5.5 is not on Kunavo
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5   # background tasks

ANTHROPIC_BASE_URL는 Origin만 지정합니다. Claude Code가 /v1/messages를 직접 추가하므로 경로를 포함하지 마세요. 모델 관련 줄을 유지하세요. Claude Code의 내장 기본 모델과 opus 별칭은 모두 최신 Opus로 해석되며, Kunavo가 해당 모델을 아직 제공하지 않으면 첫 번째 요청에서 404가 반환됩니다. sonnet 별칭은 Kunavo가 제공하지 않는 Sonnet 5.5를 요청하므로 ANTHROPIC_DEFAULT_SONNET_MODEL 줄이 없으면 /model sonnet, opusplan의 실행 단계 및 model: sonnet로 설정된 모든 하위 에이전트가 404를 반환합니다. opus 별칭은 Opus 5.5(claude-opus-5-5)로 고정되며 Claude Code v2.1.280 이상이 필요합니다. 버전이 더 낮다면 claude update을 실행하세요. 가입 후 $10을 충전하면 대시보드에서 키를 확인할 수 있으며, 키는 한 번만 표시됩니다.

어떤 자격 증명 변수를 사용해야 하며, 그 이유는 무엇인가요?

Claude Code는 두 자격 증명 변수를 서로 다른 HTTP 헤더로 전송합니다. 서버가 읽지 않는 헤더에 키를 넣으면 401로 실패합니다.

구체적인 이유로 ANTHROPIC_AUTH_TOKEN를 선호하세요. ANTHROPIC_API_KEY에는 대화형 세션에서 일회성 승인이 필요하며, 한 번 거부한 키는 이후 메시지 없이 무시됩니다. 변수는 분명히 설정되어 있지만 사용되지 않는 혼란스러운 실패입니다. Kunavo에서는 모델 검색이 이를 결정하지 않습니다. Claude Code의 게이트웨이 모델 검색은 ANTHROPIC_AUTH_TOKEN가 설정된 경우 bearer 토큰만 전송하고, 그렇지 않으면 x-api-key로 대체됩니다. Kunavo의 /v1/models 엔드포인트는 어느 헤더에서든 키를 읽습니다.

설정을 적용하기

셸 export는 해당 터미널과 그 터미널에서 실행된 항목에만 적용됩니다. Dock에서 연 편집기는 이를 볼 수 없고 백그라운드 에이전트도 마찬가지입니다. 모든 항목에 적용하려면 설정 파일에 값을 입력하세요.

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.kunavo.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-kn-...",
    "ANTHROPIC_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5-5",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5"
  }
}

모든 프로젝트에는 ~/.claude/settings.json를 사용하세요. 프로젝트의 .claude/settings.json에는 절대 키를 넣지 마세요. 해당 파일은 커밋됩니다.

신뢰하기 전에 확인하기

먼저 엔드포인트를 직접 테스트하세요. 그러면 실패 원인이 Claude Code가 아니라 구성으로 좁혀집니다.

curl -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":1,"messages":[{"role":"user","content":"."}]}'

# A response starting with {"id":"msg_ means the URL and key both work.
# 401 -> the key is in the wrong header; see "Which credential variable" below.

그런 다음 같은 셸에서 claude를 시작하고 /status를 실행하세요. Anthropic base URL 줄에 api.kunavo.com가 표시되고 Auth token 줄에 변수 이름이 표시되면 두 부분이 모두 활성 상태임을 확인할 수 있습니다.

사용자 지정 모델 설정 — 슬러그를 명시적으로 선택하기

Kunavo는 모델 슬러그를 정확히 일치시켜 처리하며 날짜 접미사가 붙은 이름에 별칭을 지정하지 않습니다. 따라서 claude-sonnet-4-5-20250929는 404를 반환하고 claude-sonnet-5는 성공합니다. 기본 제공값에 의존하지 말고 항상 ANTHROPIC_MODEL를 설정하세요.

별칭 변수는 별도의 라우터 없이 작업별 라우팅을 제공합니다. ANTHROPIC_DEFAULT_OPUS_MODEL는 opus 별칭과 계획 모드를 지원하고, ANTHROPIC_DEFAULT_SONNET_MODEL는 sonnet 및 opusplan의 실행 단계를 지원하며, ANTHROPIC_DEFAULT_HAIKU_MODEL는 haiku와 Claude Code의 백그라운드 작업(조용히 비용을 누적하는 요약과 제목)을 지원합니다. 이 변수를 claude-haiku-4-5로 지정하는 것이 구성에서 가장 가치가 높은 한 줄입니다. (ANTHROPIC_SMALL_FAST_MODEL는 동일한 설정의 더 이상 사용되지 않는 표기입니다.)

선택 사항: 선택기에 모든 모델 표시

CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1(Claude Code v2.1.129+)를 설정하면 Claude Code가 시작 시 GET /v1/models를 조회하고, 찾은 항목을 From gateway로 표시된 /model 선택기에 추가합니다. Kunavo는 해당 엔드포인트를 제공하므로 활성화된 모든 Claude 모델이 표시되고 /model는 직접 관리하는 목록이 아니라 실시간 메뉴가 됩니다. 두 자격 증명 변수 중 어느 것이든 사용할 수 있습니다. 위 내용을 참조하세요.

옵션 B — 현재 실제로 작동하는 claude-code-router

여기서 시작해야 합니다. CCR에 대해 작성된 거의 모든 내용이 더 이상 존재하지 않는 버전을 설명하기 때문입니다. 라우터는 한때 JSON 파일과 ccr code 명령이었습니다. 이제는 데스크톱 앱, 관리 UI, 요청 로그 및 모델 게이트웨이를 갖춘 로컬 제어 플레인입니다. 모든 튜토리얼에서 보여 주는 config.json가 더 이상 이를 구성하지 않습니다.

CCR은 ~/.claude-code-router/config.sqlite(Windows에서는 %APPDATA%\claude-code-router\config.sqlite)에 런타임 구성을 저장합니다. 레거시 config.json는 아직 SQLite 구성이 없을 때 마이그레이션 소스로 한 번 읽힙니다. 첫 실행 후에는 편집해도 실행 중인 구성에 영향을 주지 않으며 오류나 경고도 없습니다. 정성스럽게 붙여 넣은 Providers 블록은 단순히 구성 파일이 아닙니다.

여기에는 2026-09-06 이전의 이 페이지도 포함됩니다. 여기에 있던 JSON 스니펫은 잘못되어 있었고, 무시되었다는 사실을 알려주는 것이 아무것도 없어서 오후 한나절을 낭비하게 만드는 종류의 오류였습니다. 이제 구성은 UI에서 이루어집니다. 백업이 필요하면 Settings → Export data를 사용하세요. CCR이 실행 중일 때 라이브 SQLite 파일을 복사하지 마세요.

설치 및 실행

CCR은 두 가지 방식으로 제공됩니다. GitHub Releases의 데스크톱 앱(트레이, 자동 업데이트, 데스크톱 통합)과 헤드리스 또는 관리형 배포를 위한 npm CLI입니다. 두 방식은 동일한 구성 디렉터리를 공유합니다.

# CCR ships as a desktop app (GitHub Releases) or an npm CLI. Both read the
# same ~/.claude-code-router directory. The CLI needs Node.js 22+.
npm install -g @musistudio/claude-code-router
ccr ui        # management UI on :3458, model gateway on :3456

# Configure the provider and an Agent Config profile in that UI, then launch
# Claude Code through the profile by name:
ccr "Claude Code - Kunavo"        # npm CLI
ccr-app "Claude Code - Kunavo"    # the desktop app's own launcher

# There is no 'ccr code' in the current command reference. The service commands
# are start / ui / stop / serve / web; everything else is a profile name.

Kunavo를 추가하는 작업은 공급자 항목 하나(Providers → Add provider, 사전 설정 Other / custom API endpoint, 엔드포인트 https://api.kunavo.com, 사용자의 sk-kn- 키)와 프로필 하나(Agent Config → Add profile → Claude Code)로 구성됩니다. Check Connection과 모델 검색을 포함한 필드별 설명은 Claude Code Router 통합 페이지에 있습니다. 이 섹션의 나머지 부분에서는 해당 페이지에서 다루지 않은 자격 증명, 비용 구조 및 실패 모드를 설명합니다.

세 가지 자격 증명과 401이 가리키는 자격 증명

정상적으로 작동하는 설정이 고장 난 것처럼 보이는 가장 일반적인 원인입니다. CCR에는 서로 다른 세 가지 홉을 인증하는 별도의 비밀 값 세 개가 있습니다.

포트 조합도 자주 혼동됩니다. 관리 서비스의 기본 포트는 127.0.0.1:3458이고 모델 게이트웨이는 127.0.0.1:3456입니다. 3458을 가리키는 기본 URL은 게이트웨이가 아니라 UI에 연결됩니다. (Docker는 의도적으로 두 서비스를 하나의 Nginx 엔드포인트 뒤에 통합하므로 Docker 지침이 다르게 보입니다.) UI에 연결된다고 해서 게이트웨이가 작동하는 것은 아닙니다. 게이트웨이 주소에서 /health를 확인하고 Server에 Running이 표시되는지 확인하세요.

티어별 매핑이 핵심입니다

Claude Code는 모델을 요청하는 것이 아니라 티어를 요청합니다 — 주 루프는 Sonnet 또는 Opus를 사용하고, 백그라운드 작업(서브에이전트, 검색, 요약, 대화 제목)은 작고 빠른 모델을 사용합니다. Agent Config의 Claude Code 프로필은 이를 별도 필드로 노출합니다. 기본 Model과 선택적 Fable, Opus, Sonnet, Haiku 오버라이드가 있으며, 각각 Provider/model 값을 받습니다. 티어를 비워 두면 Claude Code가 해당 티어를 선택합니다.

누군가의 티어 매핑을 복사하기 전에 이 표를 읽으세요. 가장 분명한 분할이 첫 번째 수단입니다. claude-sonnet-5는 Kunavo에서 claude-opus-5-5보다 50% 저렴합니다($1.40 / $7.00 대 $2.80 / ). 두 번째 수단은 Haiku 티어입니다. $0.70 / $3.50에서 Sonnet 5보다 2배 저렴하며, 눈에 잘 띄지 않는 대량 사용량을 담당합니다. 모든 하위 에이전트, 모든 파일 분류 작업, 생성되는 모든 제목이 여기에 포함됩니다. claude-sonnet-4-6는 더 이상 저렴한 Sonnet이 아닙니다. $2.10 / $10.50에서 Sonnet 5보다 50% 비싸므로 위의 예시에서는 ANTHROPIC_MODEL=claude-sonnet-5를 설정합니다.

서브에이전트 라우팅 — 티어 매핑으로는 할 수 없는 작업

티어 오버라이드는 모든 서브에이전트를 하나의 모델에 고정합니다. CCR은 더 세밀하게 라우팅할 수 있습니다. Claude Code 요청이 기본 제공 라우트와 일치하면 Agent / Task 도구 설명에 사용 가능한 모델 목록을 삽입하고, Claude Code는 생성되는 각 에이전트의 프롬프트 앞에 원하는 모델을 지정하는 태그를 붙입니다:

<CCR-SUBAGENT-MODEL>provider/model</CCR-SUBAGENT-MODEL>

CCR은 태그를 제거하고 해당 요청을 그에 맞게 라우팅하므로, 검색 서브에이전트는 Haiku에서 실행하고 검토 서브에이전트는 Opus에서 실행할 수 있습니다. 모델 하나에 고정되는 것이 아니라 작업별로 선택됩니다. 이 전환은 놓치기 쉽습니다. Models 페이지에서 하나 이상의 모델에 Description이 지정되기 전까지 이 메커니즘은 꺼져 있습니다. 설명이 없으면 CCR은 아무것도 삽입하지 않으며 모든 서브에이전트가 조용히 프로필 기본값으로 폴백합니다. 설명은 작업 적합성을 기준으로 작성하세요 — Haiku에는 “코드 검색, 파일 분류, 저렴한 병렬 서브에이전트”, Opus에는 “아키텍처 분석, 고위험 검토”를 입력합니다. 작동하면 요청 로그에 라우트 이유로 builtin:claude-code-subagent가 표시됩니다.

프로토콜 선택과 캐시 비용

CCR은 엔드포인트를 탐색하고 전송 프로토콜을 선택합니다. 기본 오리진 https://api.kunavo.com을 지정하면 Anthropic Messages를 사용하고, https://api.kunavo.com/v1를 지정하면 OpenAI-compatible 형식을 사용합니다. 두 인터페이스 모두 동일한 키에서 활성화되어 있으며 Advanced 설정에서 자동 감지를 재정의할 수 있습니다.

Anthropic Messages 형식을 권장합니다. 이 형식은 전송 시 cache_control를 유지하므로 프롬프트 캐싱이 모델에 도달하고 캐시된 입력은 입력 요율의 10%로 청구됩니다(작동 방식). 매 단계마다 안정적인 접두사를 다시 보내는 에이전트 루프에서는 가장 큰 단일 절감 효과입니다. 다만 경로에 라우터가 있으면 요청이 여전히 수정된다는 점에 유의하세요. CCR은 Claude Code가 삽입하는 청구 헤더 시스템 메시지를 제거하고, 서브에이전트 라우팅이 켜져 있으면 도구 설명에 모델 목록을 추가합니다. 두 요소 모두 캐시 중단점보다 앞에 있으므로 콘텐츠가 변경될 때마다 캐시 미스가 한 번 발생하고 새 접두사가 다시 준비됩니다. 이후에는 안정적이지만, 실행 부담이 더 적다는 점 외에도 Option A가 Option B보다 캐시 효율이 약간 더 좋은 실제 이유입니다.

폴백: 재시도와 장애 조치

필요하기 전에 Routing 페이지의 Default on failure를 설정해 두는 것이 좋습니다. Retry는 408, 409, 429, 5xx에서 동일한 모델로 다시 전송하며, Retry-After를 따르고 그렇지 않으면 1초부터 30초 상한까지 지수 백오프를 적용합니다. Fallback targets는 백업 모델의 순서가 지정된 목록을 순회하고 모든 4xx 또는 5xx에서 트리거됩니다. 모델을 찾을 수 없거나 제공업체가 거부한 경우 현재 대상에만 문제가 있을 수 있다는 전제입니다. 개별 규칙은 전역 설정을 재정의할 수 있습니다. 폴백이 실행되면 응답에 x-ccr-fallback-attempts 및 x-ccr-fallback-model가 포함되어 사후에 확인할 수 있습니다.

실제로 경로에 포함되었는지 확인

프로필에서 Claude Code를 실행하고 메시지를 하나 보낸 다음 CCR에서 Request logs를 엽니다. 행에는 request model(Claude Code가 요청한 값), resolved provider 및 resolved model(요청이 전달된 위치)가 표시됩니다 — 이 세 가지가 증거입니다. CLI 내부에서 /model를 실행하면 CCR이 노출하는 모델이 나열됩니다. Claude Code가 응답하지만 로그 행이 없다면 CCR을 통해서가 아니라 직접 Claude Code를 시작한 것이며, 프로필 범위가 Only opened from CCR로 설정된 것입니다.

코딩 세션 비용

Claude Code는 모든 단계에서 시스템 프롬프트, 대화 및 새 파일 컨텍스트를 다시 보내므로 토큰당 요율이 빠르게 누적됩니다. Kunavo 요율 기준 claude-sonnet-5에서:

프롬프트 캐싱 전에도 주 모델에서 대략 30% 절감됩니다. 전체 요율은 Claude API pricing guide에 있으며, cost calculator에서는 직접 토큰 수를 입력할 수 있습니다.

여전히 작동하는 것과 작동하지 않는 것

Claude Code를 어떤 게이트웨이에 연결하든 몇 가지가 달라집니다. 커밋하기 전에 알아둘 만한 항목은 많지 않습니다:

마지막 행에 관해 설명하면, 토큰 수 계산은 Anthropic 자체 게이트웨이 사양에서 선택 사항으로 표시한 유일한 엔드포인트이며, 이 엔드포인트가 없으면 Claude Code가 컨텍스트 사용량을 로컬에서 추정합니다. 현재 Kunavo는 /v1/messages/count_tokens를 제공하지 않으므로 /context 수치는 정확한 계산이 아니라 추정치입니다. 그 수치 외에는 기능이 저하되지 않으며 자동 압축과 세션 자체는 영향을 받지 않습니다.

문제 해결

기본 URL 경로

…라우터가 경로에 있을 때

API 자체의 오류별 해결 방법은 invalid API key 및 rate limit 문제 해결 페이지에 있습니다.

자주 묻는 질문