Claude Code Router 분석 — 여러 AI 모델의 비용·경로·실패를 관리하는 법
Claude Code Router의 공식 문서와 GitHub 코드를 분석합니다. OpenRouter와의 차이, 모델 라우팅·서브에이전트 선택·재시도와 대체 경로, Fusion·ToolHub, 비용과 로그 보관의 실제 확인 기준을 정리합니다.
Claude Code Router, 줄여서 CCR은 AI 코딩 도구와 모델 제공자 사이에서 요청을 전달하는 오픈소스 게이트웨이입니다. 로컬 컴퓨터나 자신의 서버에서 실행하고, 어떤 요청을 어느 모델로 보낼지와 실패했을 때의 다음 경로를 정합니다. 프로젝트 공식 문서
핵심은 여러 모델을 연결하는 것에서 한 걸음 더 나아가, 선택한 경로와 실제 사용 결과를 관리하는 데 있습니다. 저렴한 모델을 일부 업무에 배정하고 중요한 작업은 다른 모델에 맡기는 구성을 만들 수 있습니다. 다만 모델을 바꿨을 때의 품질과 총비용은 실제 작업으로 확인해야 합니다.
Claude Code·OpenRouter·Claude Code Router는 어떻게 다른가요
이름이 비슷해서 혼동하기 쉽지만, 작업 흐름에서 맡는 위치가 다릅니다.
| 이름 | 주된 역할 | CCR과의 관계 |
|---|---|---|
| Claude Code | 프로젝트를 읽고 도구를 호출하며 개발 작업을 수행하는 에이전트 | CCR에 모델 요청을 보내는 클라이언트 |
| OpenRouter | 여러 AI 모델에 하나의 API로 접근하는 외부 서비스 | CCR에 연결할 수 있는 제공자 중 하나 |
| Claude Code Router | 요청 경로와 모델·연결 정보를 관리하는 게이트웨이 | 클라이언트와 모델 제공자 사이에 설치하는 소프트웨어 |
OpenRouter는 공식 안내에서 다수의 모델에 단일 API로 접근하는 서비스라고 설명합니다. CCR은 OpenRouter 외에도 DeepSeek 등 여러 제공자를 연결하고, 호환되는 API를 이용할 수 있다고 안내합니다. 따라서 두 도구를 함께 사용하는 구성이 가능합니다. CCR 제공자 연결 안내
CCR의 원본은 musistudio/claude-code-router이며 MIT 라이선스로 공개돼 있습니다. Claude라는 이름이 들어가지만 Anthropic이 배포하는 공식 Claude Code의 구성요소와는 구분해야 합니다. 현재 프로젝트는 Claude Code 외의 에이전트 연결도 다룹니다. 원본 저장소, 라이선스
현재 버전과 관심 지표부터 확인했습니다
| 항목 | 2026년 10월 19일 확인 내용 |
|---|---|
| 공식 문서 | ccrdesk.top |
| 원본 저장소 | musistudio/claude-code-router |
| 최신 릴리스 API 표시 | v3.1.3, 한국시간 10월 9일 20:45 공개 |
| GitHub Stars | 11:23 KST 기준 37,746개 |
| 이번 소스 검토 기준 | main의 057abaa1f955 커밋 |
버전과 관심 지표는 저장소 API와 최신 릴리스 API를 조회한 값입니다. Stars는 누적 관심 지표이며, 오늘의 증가량이나 실제 이용자 수를 뜻하지 않습니다.
v3.1.3 릴리스는 모델 목록 갱신, 라우팅 스크립트의 토큰 추정, 게이트웨이 복구와 스트리밍 오류 처리 개선 등을 소개합니다. 이 글의 코드 분석 기준인 main은 해당 릴리스 이후의 커밋입니다. 배포본을 사용할 때는 문서의 기능이 설치한 버전에 포함됐는지도 확인해야 합니다.
이 프로젝트가 관심을 끌 만한 이유는 여러 코딩 에이전트와 모델을 함께 쓰는 환경에서 설정을 한곳에 모으려는 접근에 있습니다. 이는 공개된 기능과 구조를 바탕으로 한 해석이며, 인기가 높아진 원인을 사용자 조사로 입증한 것은 아닙니다.
GitHub 구조를 보면 공통 게이트웨이가 중심입니다
소스는 핵심 처리부인 core, 명령행 진입점인 cli, React 관리 화면인 ui, 데스크톱 실행부인 electron 패키지로 나뉩니다. 핵심 패키지에는 제공자 연결, 라우팅, 로그·사용량, 프로필과 MCP 관련 코드가 모여 있습니다. 단순히 터미널 명령에 모델 이름을 붙이는 도구보다 관리 범위가 넓습니다. 검토한 패키지 구조
요청의 흐름은 다음처럼 이해할 수 있습니다.
- 에이전트가 CCR의 모델 게이트웨이로 요청을 보냅니다.
- CCR이 설정된 모델과 라우팅 규칙을 확인합니다.
- 선택한 제공자에 요청하고, 실패 시 설정에 따라 재시도하거나 다른 모델로 넘깁니다.
- 로그를 켰다면 실제로 연결된 제공자·모델과 응답 상태 등을 확인합니다.
설치 방식은 데스크톱 앱, npm CLI, Docker로 안내됩니다. CLI에는 Node.js 22 이상이 필요합니다. 데스크톱·CLI의 기본 모델 게이트웨이는 127.0.0.1:3456, CLI 관리 화면은 127.0.0.1:3458입니다. Docker 기본 구성은 하나의 진입점으로 관리와 모델 요청을 함께 제공합니다. 관리 화면이 열린 것과 모델 요청이 성공한 것은 별도로 확인해야 합니다. 공식 설치 안내
모델 선택은 규칙과 설명을 어떻게 쓰느냐에 달렸습니다
라우팅 구현에서 눈에 띄는 부분은 정해진 순서대로 정책을 평가하고, 먼저 결과를 반환한 정책을 사용하는 구조입니다. 코드의 RoutePolicyEngine.evaluate()도 이 순서를 따릅니다. 조건이 겹친다면 어떤 규칙을 위에 놓았는지가 중요합니다. 정책 평가 코드
사용자 규칙은 헤더나 요청 본문 조건을 보고 모델 등 요청 필드를 바꿀 수 있습니다. 예를 들어 분류가 명확한 반복 작업을 특정 모델로 보내는 구성을 생각할 수 있습니다. 이때 규칙이 비용을 절약했는지 판단하려면 선택된 모델뿐 아니라 재요청과 수정 작업도 함께 봐야 합니다.
Claude Code의 서브에이전트에는 별도의 선택 방식도 있습니다. 모델의 Description을 작성하면 CCR이 모델 목록과 설명을 관련 도구 안내에 넣고, 에이전트가 선택한 모델 태그를 이후 요청에서 읽어 라우팅합니다. 설명이 하나도 없으면 이 선택 안내를 주입하지 않는다고 문서는 명시합니다. 공식 라우팅 설명
모델 설명에는 ‘빠름’ 같은 표현만 적기보다 잘 맡길 수 있는 업무와 제한을 적는 편이 좋습니다. 예를 들어 ‘짧은 문서 분류에 사용, 큰 설계 변경은 검토 필요’처럼 선택 기준을 구체화할 수 있습니다. 이것은 운영 설계 제안이며, 설명만으로 에이전트가 항상 적절한 모델을 고른다는 보장은 아닙니다.
재시도와 대체 모델은 답변의 정답 여부를 판정하지 않습니다
코드를 보면 실패 대응은 실행 계획과 상태 코드 분류로 나뉩니다. 실행 계획은 같은 모델의 시도 목록 또는 중복을 제거한 대체 모델 목록을 만들고, 실패 분류기는 다음 시도로 넘어갈지를 판단합니다. 실행 계획 코드, 실패 분류 코드
| 방식 | 확인한 동작 | 도입할 때 볼 것 |
|---|---|---|
| Off | 현재 모델에 한 번 요청 | 실패를 어떻게 사용자에게 알릴지 |
| Retry | 같은 모델을 설정 횟수만큼 추가 시도 | 대기 시간과 중복 요청 비용 |
| Fallback targets | 현재 모델 다음으로 지정 모델을 순서대로 시도 | 대체 모델의 기능·결과 차이 |
상태 코드 기준으로 Retry는 408·409·429·5xx를 대상으로 하고, 모델 대체 방식은 4xx·5xx에 반응하도록 구현돼 있습니다. 네트워크 오류와 대기 규칙은 공식 실패 대응 설명에서 함께 안내합니다.
이 구조가 다루는 것은 요청 실패입니다. 정상 응답으로 돌아온 잘못된 코드나 빠진 요구사항을 자동으로 발견해 더 좋은 모델에 다시 묻는 품질 평가와는 다릅니다. 코드 변경의 검증에는 여전히 테스트와 리뷰가 필요합니다. 대체 경로가 자주 작동하면 작업이 끝나더라도 총시간과 비용이 예상보다 커질 수 있습니다. 에이전트 재시도·복구 설계와 함께 살펴볼 부분입니다.
Fusion과 ToolHub는 모델 주변의 도구를 조합합니다
Fusion은 기본 텍스트 모델에 이미지 이해·검색·MCP 도구 등의 능력을 연결하는 구성입니다. 필요한 도구의 결과를 문맥에 넣고 기본 모델이 최종 답변을 만드는 방식으로 설명됩니다. 이렇게 저장한 구성을 하나의 모델처럼 선택할 수 있지만, 여러 모델의 가중치를 합쳐 새로 학습하는 기능은 아닙니다. Fusion 공식 문서
ToolHub는 여러 MCP 서버를 하나의 진입점에 연결하고, 작업에 필요한 도구 묶음을 동적으로 찾도록 돕습니다. 에이전트에서 많은 도구를 관리하는 용도와, 특정 Fusion 모델에 정해진 도구를 붙이는 용도는 구분됩니다. 내장 브라우저 자동화는 데스크톱 앱에 한정된다고 문서는 안내합니다. ToolHub 공식 문서
이 기능들까지 더하면 CCR은 모델 연결 설정과 도구 구성을 함께 관리하는 도구로 볼 수 있습니다. 다만 연결 가능한 기능을 한꺼번에 켜기보다, 모델 요청 한 건이 의도한 경로로 처리되는지 확인한 뒤 필요한 기능을 더하는 편이 원인을 추적하기 쉽습니다.
비용 절감은 모델 단가보다 작업 완료 비용으로 봐야 합니다
MIT 라이선스로 공개된 CCR을 사용하는 것과 연결된 AI API를 사용하는 것은 비용의 단위가 다릅니다. CCR이 외부 모델의 사용료나 이용 권한을 대신 제공하지는 않습니다. 기존 구독으로 새 제공자의 모든 모델을 사용할 수 있다고 가정해서도 안 됩니다.
라우팅의 경제성을 볼 때는 다음 항목을 같은 작업 묶음으로 기록해 보세요.
| 비교 항목 | 판단에 도움이 되는 이유 |
|---|---|
| 최종 완료한 작업 수 | 요청 한 건의 단가와 실제 성과를 연결 |
| 전체 요청·재시도·도구 호출 | 추가 호출로 늘어난 비용 확인 |
| 작업 완료까지 걸린 시간 | 응답 속도 외에 대기·재작업까지 반영 |
| 사람이 고친 시간 | 저렴한 모델의 결과를 보완하는 부담 확인 |
| CCR 비용 추정과 제공자 청구 내역 | 표시된 추정값과 실제 과금 비교 |
예를 들어 초안 작성 비용이 줄어도 수정과 재시도가 늘면 전체 작업 비용은 줄지 않을 수 있습니다. 반대로 짧고 기준이 명확한 업무를 안정적으로 처리한다면 비싼 모델의 호출을 줄이는 데 도움이 될 수 있습니다. 이는 적용 가능성을 설명한 예이며, 이번 검토에서 비용 절감률을 실측한 결과는 아닙니다. AI API 비용 설계에서 다룬 작업 단위의 계산과 연결됩니다.
로그는 실제 경로를 보여주지만 보관 설정도 봐야 합니다
로그에서 중요한 항목은 요청한 모델과 실제 연결된 모델의 차이입니다. request model, resolved provider, resolved model과 상태·시간·토큰·비용 추정을 함께 보면 라우팅과 대체 경로가 의도대로 작동했는지 확인할 수 있습니다. 로그 설정 문서
로그 기능을 켜면 설정에 따라 요청·응답 본문도 기록됩니다. 문서는 본문 캡처 기본값을 all로 설명하며, errors 또는 none으로 바꿀 수 있다고 안내합니다. 일반 요청 로그는 당일 진단용이고, 날짜가 바뀐 뒤 다음 읽기·쓰기에서 이전 날짜 기록을 정리하는 방식입니다. 장기 감사 기록이 필요한 경우 이 기본 동작만으로 충족된다고 보면 안 됩니다.
코드에는 인증·쿠키·키·토큰 등을 나타내는 민감 헤더 이름을 식별하는 로직도 있습니다. 그러나 헤더를 구분하는 것과 코드·문서가 포함된 본문의 민감 정보를 모두 없애는 것은 별개의 문제입니다. 민감 헤더 판별 코드
또한 ‘로컬 게이트웨이’는 요청을 관리하는 위치를 뜻합니다. 외부 제공자를 선택하면 해당 모델 처리를 위해 요청을 전달합니다. 조직 자료를 다룬다면 허용된 제공자와 로그 캡처 범위를 먼저 정해 두는 것이 실질적인 운영 조건입니다.
어떤 팀이 작은 시험부터 해보면 좋을까요
여러 모델을 이미 사용하고 있고, 작업별 배정 기준을 정할 수 있는 개발자나 팀에 검토 가치가 있습니다. 한 모델로 충분한 환경이라면 라우터 설정과 유지보수에 드는 시간까지 포함해 판단해야 합니다.
아래는 도입 검토를 위한 제안입니다. CCR을 설치해 실사용 성능을 측정한 후기는 아닙니다.
- 문서 분류·테스트 초안·작은 버그 수정처럼 결과를 확인할 수 있는 대표 작업을 고릅니다.
- 하나의 제공자와 모델로 연결을 검증하고, 로그의 실제 처리 모델을 확인합니다.
- 작업 하나에만 모델 변경 규칙을 적용하고 완료율·총비용·수정 시간을 비교합니다.
- 대체 모델 경로는 별도로 시험해 실패 조건과 최종 모델을 확인합니다.
- 효과가 확인된 뒤에 서브에이전트 선택이나 ToolHub를 추가합니다.
CCR에서 배울 만한 설계는 모델 선택을 설정과 기록으로 드러내는 접근입니다. 도입의 기준은 연결한 모델의 개수보다, 우리 작업이 어떤 경로로 끝났고 그 결과를 다시 확인할 수 있는지에 두는 편이 좋습니다.
자주 묻는 질문
Q1. Claude Code Router는 Anthropic 공식 제품인가요?
원본은 musistudio/claude-code-router에 공개된 독립 오픈소스 프로젝트입니다. Claude Code와 연결할 수 있지만 공식 Claude Code 배포본과는 구분됩니다.
Q2. OpenRouter 계정이 꼭 필요한가요?
OpenRouter는 지원하는 제공자 중 하나입니다. 다른 제공자나 호환 API를 연결할 수 있으며, 선택한 경로에 필요한 계정과 이용 권한은 별도로 준비해야 합니다.
Q3. 모델을 바꿔도 Claude의 품질이 그대로 유지되나요?
라우터는 요청 경로와 형식을 관리합니다. 다른 모델의 추론·코딩·도구 사용 능력이 Claude와 같아지는 것은 아니므로 실제 작업으로 비교해야 합니다.
Q4. 자동 대체 기능이 잘못된 답변도 고쳐주나요?
검토한 실패 대응 코드는 상태 코드와 요청 실패를 다룹니다. 정상 응답의 내용이 맞는지는 별도 평가·테스트·사람 검토로 확인해야 합니다.
Q5. 로컬에서 실행하면 코드가 외부로 나가지 않나요?
외부 제공자의 모델을 선택하면 처리할 요청을 그 제공자에 전달합니다. 로컬 실행 위치와 모델 실행 위치, 로그 저장 범위를 나누어 확인해야 합니다.
공식 자료와 확인 기준일
- Claude Code Router — 공식 문서
- GitHub — 원본 저장소
- GitHub — v3.1.3 릴리스
- GitHub API — 저장소 정보
- GitHub API — 최신 릴리스
- CCR — 설치와 배포 방식
- CCR — 모델 라우팅과 실패 대응
- CCR — Fusion
- CCR — ToolHub
- CCR — 로그 설정
- GitHub — 검토한 소스 커밋
- OpenRouter — 공식 서비스 설명
확인 기준일: 2026-10-19 — 버전과 Stars는 11:23 KST의 공개 API 조회값입니다. 기능은 프로젝트 공식 문서와 main의 057abaa1f95519ab8faf999e1ccef2b80ccdeb9e 소스를 대조했습니다. CCR 설치·모델 연결·비용·속도·호환성의 실측 시험을 수행한 사용 후기는 아닙니다.