Deepseek ArtifactsDeepseek Artifacts
Claude Code Router · 2026 가이드

Claude Code Router 튜토리얼: Claude Code를 DeepSeek·Gemini 등 원하는 모델에 연결하기

오픈소스 라우터인 Claude Code Router는 Claude Code의 사용 경험은 그대로 두면서 요청만 더 저렴한 모델 — DeepSeek, Kimi, Gemini, 로컬 Ollama — 로 보낼 수 있습니다. npm으로 설치하고, ccr ui 콘솔에서 프로바이더를 설정하고, 시나리오별 라우팅을 구성한 뒤 실제 작업으로 검증까지, 스크린샷과 함께하는 15단계 가이드입니다.

설정 시작하기FAQ 보기

요약: Claude Code Router가 하는 일

  • Claude Code Router(CCR)는 무료 오픈소스 프록시입니다. Claude Code의 UI, 시스템 프롬프트, 도구는 그대로 유지되고 모델 호출만 내가 설정한 곳 — DeepSeek, Kimi K2, Gemini, OpenRouter 또는 로컬 Ollama 모델 — 로 향합니다.
  • 설치는 npm 명령 한 줄이면 끝입니다(npm install -g @musistudio/claude-code-router). ccr ui 웹 콘솔이 ~/.claude-code-router/config.json을 대신 편집해 주므로 JSON을 손으로 쓸 필요가 없습니다.
  • 라우팅은 시나리오별로 이루어집니다. default(일반), background(백그라운드 작업), think(Plan Mode 추론), longContext(6만 토큰을 넘으면 자동 활성화), webSearch 슬롯마다 각자 다른 모델을 지정합니다.
  • ccr code로 라우팅 세션을 시작하면 베이스 URL이 http://127.0.0.1:3456 로 바뀝니다. 일반 claude 명령은 예전 그대로 작동하고요. 알려진 특이사항: /cost가 $0에 머물러 있으므로 지출은 프로바이더 대시보드에서 확인하세요.

Claude Code Router: Use Gemini 2.5 Pro FREE API in Claude Code

원본 영상:AI With Nathan10:52

열기

claude-code-router — official README

제품 정보:musistudio on GitHubDocs

열기

단계와 스크린샷은 원본 영상을 따르며, config.json 필드명·라우터 역할·transformer 동작은 공식 README와 대조해 확인했습니다.

이미지는 출처를 밝힌 영상 스크린샷이며 각각 타임스탬프에 연결되어 있습니다. 본문은 자체 제작된 원고로, 자막을 옮긴 것이 아닙니다.

Claude Code Router 설정, 단계별 가이드

1 · Claude Code를 더 저렴한 모델로 향하게 하기

  1. 1

    Claude Code에 라우터가 필요한 이유부터

    Claude Code는 Claude 모델에 묶여 있고 가격도 만만치 않습니다. Opus 4.1은 입력 100만 토큰당 15달러, 출력은 75달러입니다. 오픈소스 프로젝트 Claude Code Router(CCR)는 Claude Code 경험은 그대로 두면서 요청만 DeepSeek, Kimi, Gemini 또는 로컬 Ollama 모델 등 내가 고른 모델로 보냅니다.

    Anthropic API pricing page showing Claude Opus 4.1 at 15 dollars per million input tokens and 75 dollars per million output tokens, the cost Claude Code Router helps you avoid
    전환 전 Anthropic 정가 — CCR이 피해주는 바로 그 요금입니다.0:30 구간 보기
  2. 2

    Claude Code 설치 후 라우터 설치

    CCR은 Claude Code가 이미 설치되어 있다고 가정합니다: npm install -g @anthropic-ai/claude-code. 그다음 라우터를 설치합니다: npm install -g @musistudio/claude-code-router. 프로바이더 설정은 ~/.claude-code-router/config.json에 저장됩니다.

    Claude Code Router README Getting Started section listing npm install -g @anthropic-ai/claude-code and npm install -g @musistudio/claude-code-router
    공식 README의 두 가지 npm 설치 명령 — 라우터는 Claude Code를 대체하지 않습니다.3:36 구간 보기
  3. 3

    npm의 전역 설치가 끝나길 기다리기

    npm이 라우터의 의존성을 내려받습니다(node-domexception 사용 중단 경고가 보여도 정상입니다). 완료되면 ccr 명령을 어디서든 쓸 수 있습니다.

    Terminal output while npm installs @musistudio/claude-code-router globally with cached package fetches and a node-domexception deprecation warning
    @musistudio/claude-code-router 전역 설치 중 패키지를 내려받는 npm.3:49 구간 보기

2 · ccr ui 콘솔에서 프로바이더 추가하기

  1. 4

    ccr ui로 설정 콘솔 열기

    JSON을 손으로 고치는 대신 ccr ui를 실행하세요. 브라우저에서 127.0.0.1:3456 이 열리고, 왼쪽에서 프로바이더를 관리하고, 오른쪽 Router 섹션에서 시나리오별 모델을 지정하며, 그 아래에 Custom Transformers가 있습니다.

    Claude Code Router web console from ccr ui on first launch with an empty Providers list and Default, Background, and Think router slots
    ccr ui 콘솔 첫 실행 — 프로바이더는 비어 있고 라우터 슬롯이 기다리고 있습니다.4:08 구간 보기
  2. 5

    템플릿으로 프로바이더 추가하기

    Add Provider를 누르고 템플릿을 고르세요. 영상에서는 OpenRouter를 사용했지만 deepseek, gemini, dashscope, modelscope, siliconflow, volcengine 프리셋도 있습니다. 템플릿이 API URL과 기본 모델 목록을 채워 주며, transformer는 비워 두어도 됩니다.

    Add Provider template dropdown in the Claude Code Router console listing dashscope, deepseek, gemini, modelscope, openrouter, siliconflow, and volcengine presets
    ccr ui의 프로바이더 템플릿 — 하나를 고르면 URL과 모델이 자동으로 채워집니다.4:30 구간 보기
  3. 6

    API 키를 붙여넣고 모델 고르기

    정말 중요한 필드는 세 개뿐입니다. API URL(이미 채워짐), 시크릿 키, 모델 목록. 영상에서는 OpenRouter 아래에 DeepSeek R1과 Kimi K2를 추가한 뒤 저장하고, 프로바이더가 왼쪽 패널에 나타나 할당 준비를 마칩니다.

    Edit Provider dialog for the openrouter template showing the pre-filled API Full URL https://openrouter.ai/api/v1/chat/completions, a masked API key field, and the models list
    Edit Provider 폼: URL, 키, 모델 — 나머지는 기본값 두어도 됩니다.4:53 구간 보기
  4. 7

    API 차이는 transformer에 맡기기

    transformer는 요청과 응답 페이로드를 재작성해 서드파티 API가 Claude Code와 호환되도록 만듭니다. CCR에는 합리적인 기본값이 내장되어 있습니다. 예컨대 api.deepseek.com용 deepseek transformer, deepseek-chat용 tooluse transformer 같은 것들이라 직접 쓸 일은 거의 없습니다.

    Claude Code Router README transformer section with a Model-Specific Transformer example applying the deepseek transformer to the api.deepseek.com provider and deepseek-chat model
    README의 전역·모델별 transformer 예시로, DeepSeek 프리셋도 포함되어 있습니다.3:54 구간 보기
  5. 8

    추론 작업용 무료 Gemini 키 추가하기

    Gemini 템플릿으로 두 번째 프로바이더를 추가하고 Google AI Studio에서 무료 API 키를 발급받으세요(Get API key → Create API key). 붙여넣고 저장하면 끝 — 곧 이 프로바이더를 think, longContext, webSearch 슬롯에 할당하게 됩니다.

    Google AI Studio Create API key dialog used to generate the free Gemini API key for the Claude Code Router think and longContext routes
    Google AI Studio에서 CCR용 무료 Gemini API 키를 발급받는 화면.5:45 구간 보기

3 · 라우팅 규칙 설정하기

  1. 9

    다섯 가지 라우터 역할 이해하기

    default는 일반 작업을 맡습니다(지정하지 않은 작업도 여기로 갑니다). background는 백그라운드 작업을 처리하며 작은 로컬 모델을 쓰면 비용을 아낄 수 있습니다. think는 Plan Mode 같은 무거운 추론을 담당합니다. longContext는 longContextThreshold(기본 6만 토큰)를 넘으면 자동으로 개입하고, webSearch는 해당 기능을 지원하는 모델이 필요합니다. OpenRouter에서는 모델명 뒤에 :online을 붙이세요. /model로 세션 도중에도 모델을 바꿀 수 있습니다.

    Claude Code Router README describing the Router roles default, background, think, longContext with a 60000 token longContextThreshold, and webSearch with the :online suffix
    README의 Router 객체: 모든 역할, 6만 토큰 임계값, :online 접미사.1:06 구간 보기
  2. 10

    시나리오마다 모델 할당하기

    Router 섹션에서 저장된 프로바이더의 모델을 고릅니다. 영상에서는 default에 DeepSeek R1, 일반 용도에 Kimi K2, longContext에 Gemini 2.5 Pro(100만 토큰 컨텍스트), webSearch에 빠른 Gemini Flash를 지정합니다. 끝나면 오른쪽 위의 Save and Restart를 누르세요.

    Claude Code Router console setting openrouter,deepseek/deepseek-r1-0528 as the Default model with the model picker dropdown open over the saved openrouter provider
    저장된 프로바이더의 deepseek/deepseek-r1-0528을 Default 슬롯에 지정하는 장면.5:15 구간 보기
  3. 11

    ccr code로 라우팅 세션 시작하기

    터미널로 돌아가 ccr code를 실행하세요. Claude Code 환영 화면에 Overrides (via env) — API Base URL http://127.0.0.1:3456 — 가 표시되며, 요청이 라우터를 거친다는 증거입니다. 일반 claude 명령은 여전히 라우팅 없이 시작되므로 아무것도 지울 필요가 없습니다.

    Claude Code session launched with ccr code showing Overrides via env with API Base URL http://127.0.0.1:3456, proving requests route through Claude Code Router
    환영 화면의 Overrides 블록: 트래픽이 이제 CCR의 로컬 프록시를 지나갑니다.6:45 구간 보기

4 · 실제 작업을 돌리고 검증하기

  1. 12

    실제 코딩 작업 맡기기

    평소처럼 프롬프트를 작성하세요. 영상에서는 모던한 애니메이션이 있는 네온 벽돌 깨기 게임을 요청합니다. Claude Code가 할 일 목록을 세우고 라우팅된 모델로 단계별로 실행합니다. 입력 토큰 카운터가 0에 머무는 등 표면적인 특이사항은 감안하세요.

    Claude Code executing a neon brick breaker game todo list inside a session proxied by Claude Code Router
    CCR이 모델 호출을 중계하는 동안 Claude Code가 할 일 목록을 진행하는 모습.7:06 구간 보기
  2. 13

    완성된 결과 확인하기

    에이전트는 시각 효과, 반응형 디자인, 조작법, 게임 메커니즘을 정리하는 기능 요약으로 마무리하고, 파일은 프로젝트(index.html, style.css, script.js)에 저장됩니다. HTML을 브라우저에서 열어 직접 테스트해 보세요.

    Claude Code completion summary for a neon brick breaker game listing visual effects, responsive design, touch controls, and game mechanics
    네온 벽돌 깨기 게임에 대한 Claude Code의 완료 요약.7:30 구간 보기
  3. 14

    프로바이더 대시보드에서 실제 사용량 확인하기

    OpenRouter의 Your Activity 페이지가 진짜 기록입니다. 라우팅된 호출 — Kimi K2가 반복 호출되고 DeepSeek 호출도 한 건 — 이 토큰 수와 지출과 함께 표시됩니다. 이것으로 CCR이 실제로 더 저렴한 모델을 쓰고 있음을 확인할 수 있습니다.

    OpenRouter Your Activity dashboard showing spend, token, and request charts with a Kimi K2 request row after routing Claude Code through Claude Code Router
    세션 이후의 OpenRouter 사용량: 라우팅된 모델에 실제 요청 기록이 쌓여 있습니다.7:45 구간 보기
  4. 15

    의존하기 전에 알아둬야 할 미완성 부분

    라우팅 세션에서 /cost를 실행하면 $0.0000이 나오고 모델별 사용량에도 claude-sonnet 0으로 표시됩니다 — 비용 계산이 아직 외부 프로바이더와 연결되지 않은 것입니다. 라우팅 자체는 잘 작동하니, 당분간 지출은 프로바이더 대시보드로 확인하세요.

    Claude Code /cost command reporting a 0.0000 dollar total and claude-sonnet zero-token usage, the known accounting gap when models are routed externally
    라우팅 세션에서 /cost의 알려진 오차 — 실제 계량기는 프로바이더 대시보드입니다.9:25 구간 보기

Claude Code Router FAQ

더 둘러보기

DeepSeek Harness 설정: 완전히 내 것인 무료 Claude CodeCursor에서 DeepSeek 사용하기Cline + DeepSeek 튜토리얼Roo Code 대안GLM Coding Plan 가이드DeepSeek App Builder전체 가이드