Claude Code Router

Claude Code 요청을 원하는 모델로 갈아끼우는 라우팅 프록시

npm install -g @musistudio/claude-code-router

Claude Code가 보내는 요청을 가로채 DeepSeek·Gemini·Ollama 같은 다른 모델로 돌리는 프록시입니다. background·think·longContext처럼 요청 성격을 보고 모델을 자동으로 갈아끼웁니다. ccr code로 띄우고, 설정은 ccr ui나 config.json에서 만집니다.

판단

이럴 때 씁니다

  • Claude Code의 background·think·longContext 요청을 성격별로 다른 모델에 자동 분기해 비용을 줄이고 싶을 때.
  • 가벼운 작업은 싼 DeepSeek이나 로컬 Ollama로 넘기고 싶을 때.
  • OpenRouter·DeepSeek·Gemini·Ollama 등 여러 공급자를 동시에 물려 쓰고 싶을 때.
  • ccr ui 웹 화면이나 ccr model 터미널 전환으로 모델을 손쉽게 갈아끼우고 싶을 때.

이럴 땐 쓰지 마세요

  • 버전 안정성에 민감하다면 주의가 필요합니다. v2.0.0은 시작 시 크래시가 보고돼 1.0.73으로 내려 쓰는 회피책이 공유됐습니다.
  • config.json을 고친 뒤 ccr restart를 잊으면 반영이 안 됩니다. CI·Docker 같은 비대화형 환경은 NON_INTERACTIVE_MODE를 따로 켜야 합니다.
  • 출력을 줄이는 RTK와 방식이 겹쳐, 둘을 함께 써도 비용 절감 효과가 누적되지는 않습니다.

차별점

  • 요청 종류마다 다른 모델을 씁니다. 가벼운 background 작업은 싼 모델로, 긴 맥락은 다른 모델로 자동 분기합니다.
  • OpenRouter·DeepSeek·Gemini·Ollama 등 여러 공급자를 동시에 물립니다.
  • 공급자마다 다른 API 포맷은 트랜스포머 플러그인이 흡수하므로 코드를 건드릴 일이 없습니다.
  • ccr ui 웹 화면, ccr model 터미널 전환, 프리셋 export로 설정을 관리합니다.

워크플로

  1. 01ccr start로 라우터 서비스를 띄웁니다.
  2. 02config.json이나 ccr ui에서 요청 종류별로 어떤 공급자·모델을 쓸지 설정합니다.
  3. 03ccr code로 라우터를 거쳐 Claude Code를 실행합니다.
  4. 04작업 중 모델을 바꾸려면 ccr model로 터미널에서 전환합니다.
  5. 05설정을 고쳤다면 ccr restart로 반영합니다.

주요 명령

명령설명
ccr start라우터 서비스를 시작합니다
ccr code라우터를 거쳐 Claude Code를 실행합니다
ccr model터미널에서 모델을 골라 전환합니다

설정

// ~/.claude-code-router/config.json
{
  "APIKEY": "your-secret-key",
  "Providers": [
    { "name": "openai", "api_base_url": "https://api.openai.com/v1/chat/completions", "api_key": "sk-xxx", "models": ["gpt-4"] }
  ],
  "Router": { "default": "openai,gpt-4" }
}

함정

설치 전에 확인하세요

  • config.json을 고친 뒤에는 ccr restart를 돌려야 반영됩니다.
  • APIKEY를 비우면 호스트가 127.0.0.1로 고정돼 외부에서 못 붙습니다. CI·Docker 같은 비대화형 환경은 NON_INTERACTIVE_MODE를 켜야 합니다.

검토 메모

공식 문서·릴리스·공개 자료를 바탕으로 정리한 편집 메모입니다.

비용 병목이 Anthropic 모델 자체일 때 답이 됩니다. 가벼운 background 작업은 DeepSeek이나 로컬 Ollama로 넘기고 긴 맥락은 다른 모델로 분기하는 식으로, 요청 종류마다 값을 다르게 매깁니다. 대신 공급자 키와 라우팅 규칙을 직접 관리해야 하니 절감액과 운영 손이 맞바꿈이라는 점은 감안해야 합니다.

처음 만지면 두 곳에서 막히기 쉽습니다. config.json을 고치면 ccr restart를 해야 반영되고, APIKEY를 비우면 호스트가 로컬로 고정돼 외부에서 못 붙습니다.

최근 안정성은 따로 확인하는 게 좋습니다. v2.0.0이 시작과 동시에 크래시한다는 이슈가 올라와 1.0.73으로 내려야 한다는 회피책이 공유됐습니다. 절감이 목적인 도구지만 어떤 작업을 어느 모델로 보낼지 잘못 짜면 비용이 거꾸로 늘 수도 있어, 모델별 단가를 보고 규칙을 정해야 합니다.

비교

Claude Code만 쓰면 Anthropic 모델에 비용이 고정됩니다. 라우터를 끼우면 background 작업을 싼 DeepSeek이나 로컬 Ollama로 넘겨 그 비용을 깎습니다. 출력을 줄이는 RTK와 달리, 이쪽은 모델 자체를 바꾸는 방식이라 둘은 함께 쓰면 효과가 겹치지 않습니다.

최근 변경

v3.0.22에서는 SSE 응답을 변환할 때 청크 경계에 걸린 멀티바이트 문자가 깨지던 문제와, 로컬 에이전트 계정을 가져올 때 provider 사용량 미터가 초기화되던 문제를 고쳤습니다. openai_responses 경로에는 세션 ID를 prompt_cache_key로 전달하는 기능을, fusion-vision에는 전달 전 이미지 입력을 검증·복구하는 처리를 추가했습니다.

공식 변경 내역