Claude Code Router

에이전트 관리

CCR은 Claude Code, Claude Design, Codex, Grok CLI, Kimi CLI, Kilo Code, OpenCode, Pi, ZCode 및 WorkBuddy에 대한 프로파일을 제공하며, 모델 오버라이드, 스코프, 환경 설정, CLI 및 앱 진입 항목, 멀티 인스턴스 워크플로우를 지원합니다.

제공자 관리

내장된 제공자 프리셋 또는 커스텀 엔드포인트를 지원하며, 프로토콜 탐지, 모델 탐지, 연결성 검사, 지원되는 경우 로컬 로그인 가져오기, 단일 키 및 자격 증명 풀을 제공합니다.

모델 및 라우팅

검색 가능한 모델 카탈로그, 작업 선택을 위한 모델 설명, 헤더 및 본문에 대한 조건, 접두사, 재작성, 재시도 및 순차적 폴백을 지원합니다.

도구 및 확장

Fusion 모델, ToolHub, 내장 브라우저 자동화, Chrome 로그인 상태 가져오기, 래퍼 및 코어 게이트웨이 플러그인, 로컬 라우트 및 가상 모델을 지원합니다.

접근 및 할당량

만료 및 로컬 요청, 토큰 및 이미지 제한이 있는 별도의 CCR 클라이언트 키를 제공합니다.

관찰 가능성

요청 및 응답 세부 정보, 해결된 제공자, 모델 및 자격 증명, 상태, 대기 시간, 토큰, 예상 비용, 도구 호출 및 에이전트 트레이스를 제공합니다.

AgentClaw

Weixin iLink, WeCom, Slack, Discord, Telegram, LINE, Feishu 및 DingTalk을 통해 에이전트 중계를 제공합니다.

데스크톱 앱 (권장)

1. GitHub 릴리스 페이지에서 Windows용 Claude-Code-Router_3.1.0.exe 파일을 다운로드합니다.

2. 다운로드한 실행 파일을 실행하여 설치를 완료합니다.

3. 설치 후 애플리케이션을 실행합니다.

CLI

1. Node.js 22 이상이 설치되어 있는지 확인합니다.

2. 터미널에서 다음 명령을 실행하여 전역으로 설치합니다:

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

3. 설치 후 다음 명령을 실행하여 관리 UI를 시작합니다:

ccr ui

4. 브라우저에서 http://127.0.0.1:3458를 열어 제공자, 서버 및 에이전트 프로필을 구성합니다. 모델 게이트웨이는 http://127.0.0.1:3456에서 실행됩니다.

Docker

1. 저장소 루트에서 다음 명령을 실행하여 Docker Compose를 시작합니다:

npm run docker:compose:up

2. Docker는 기본적으로 관리 UI와 게이트웨이 라우트를 http://127.0.0.1:3458를 통해 노출합니다. 게이트웨이는 http://127.0.0.1:3456에서 실행됩니다.

기본 사용법/명령어

데스크톱 앱을 실행한 후, 다음 단계를 따라 기본 설정을 완료합니다:

1. Providers → Add Provider 메뉴로 이동하여 내장된 프리셋 또는 커스텀 엔드포인트를 선택합니다.
2. API 키를 입력하고, 프로토콜 및 모델을 선택한 후 저장합니다.
3. Server 탭에서 Start 버튼을 클릭하여 로컬 모델 게이트웨이를 시작합니다. 기본적으로 http://127.0.0.1:3456에서 수신 대기합니다.
4. Agent Config 탭에서 Claude Code, Claude Design, Codex, Grok CLI, Kimi CLI, Kilo Code, OpenCode, Pi, ZCode 또는 WorkBuddy 중 하나를 선택하고, 사용할 모델을 적용합니다.
5. 선택한 에이전트를 실행하여 작업을 시작합니다. Logs 탭을 열어 해결된 제공자, 모델, 상태, 토큰, 대기 시간 및 오류를 확인합니다.

라우팅 조건, 재시도, 요청 재작성 또는 폴백 모델을 추가하려면 Routing 섹션을 엽니다.

이런 경우에 유용합니다

여러 코딩 에이전트를 동시에 사용하면서 각 에이전트별로 별도의 API 키 및 모델 구성을 관리해야 하는 개발자에게 유용합니다. CCR을 통해 하나의 인터페이스에서 모든 제공자 및 모델을 중앙에서 관리할 수 있어, 에이전트 구성 파일을 반복적으로 수정하지 않고도 제공자나 모델을 빠르게 전환할 수 있습니다.

작업 중에 모델이 응답하지 않거나 오류가 발생했을 때, 수동으로 구성 파일을 편집하지 않고도 자동 재시도 및 폴백 모델을 통해 작업을 중단 없이 계속할 수 있습니다. 이는 특히 장시간 실행되는 코딩 작업이나 CI/CD 파이프라인에서 안정성을 높이는 데 도움이 됩니다.

시각적 입력이 필요한 작업(예: 이미지 기반 코드 생성)을 수행할 때, Fusion 기능을 통해 텍스트 모델에 시각 처리 도구를 결합하여 새로운 기능을 추가할 수 있습니다. 별도의 도구 설정이 필요 없이 CCR 내에서 직접 시각 모델을 구성하고 사용할 수 있습니다.

지원 환경·시스템 요구사항

데스크톱 앱은 Windows x64 시스템에서 실행되며, better-sqlite3의 네이티브 Electron 모듈 때문에 Windows x64 환경에서만 패키징이 가능합니다. macOS 및 Linux 버전도 제공되지만, Windows 사용자는 x64 아키텍처를 갖춘 시스템에서만 설치를 권장합니다.

최신 버전·업데이트

현재 버전은 3.0.22이며, 최신 릴리스 정보 및 업데이트 내역은 GitHub 저장소의 Releases 섹션에서 확인할 수 있습니다.

제한 사항·확인 사항

Windows용 데스크톱 앱은 better-sqlite3 의존성으로 인해 Windows x64 아키텍처에서만 정상적으로 동작합니다. ARM 기반 Windows 또는 32비트 Windows에서는 설치를 권장하지 않습니다.

CCR은 로컬에서 실행되는 모델 게이트웨이로, 외부 네트워크에 직접 노출되지 않도록 설계되었습니다. 원격 액세스가 필요한 경우, Docker 배포 가이드를 참조하여 적절한 보안 조치를 취해야 합니다.

FAQ

1. CCR은 무료로 사용할 수 있나요?

   네, CCR은 MIT 라이선스 하에 오픈소스로 제공되며, 소스 코드는 GitHub에서 freely 다운로드 및 수정할 수 있습니다.

2. CCR을 사용하려면 인터넷 연결이 필수인가요?

   아니요, CCR 자체는 로컬에서 실행되지만, 제공자(예: OpenAI, Anthropic 등)와 통신하기 위해서는 인터넷 연결이 필요합니다. 로컬에서만 작동하는 커스텀 제공자를 사용하는 경우 인터넷이 필요하지 않을 수 있습니다.

3. CCR은 어떤 프로그래밍 언어로 작성되었나요?

   CCR의 프론트엔드 및 백엔드는 주로 TypeScript로 작성되었으며, Node.js 환경을 기반으로 합니다.