Claude Code Router 프로젝트 소개

프로젝트 개요

Claude Code Router는 Claude Code 요청을 다양한 AI 모델로 라우팅하는 것을 목표로 하는 오픈 소스 프로젝트입니다. 이는 코딩 인프라의 기반으로서 사용자가 모델과 상호 작용하는 방식을 결정할 수 있게 하면서 Anthropic의 업데이트를 계속 활용할 수 있도록 합니다. 이 프로젝트의 핵심 목표는 지능형 라우팅과 다중 모델 협업을 통해 Claude Code 사용 비용을 크게 절감하는 것입니다.

프로젝트 동기

기존 AI 프로그래밍 도구에는 다음과 같은 문제가 있었습니다:

• 높은 비용: Claude와 같은 고성능 모델을 모든 작업에 직접 사용하는 것은 비용이 많이 듭니다.
• 모델 한계: 단일 모델은 모든 시나리오에서 최상의 성능을 발휘할 수 없습니다.
• 자원 낭비: 간단한 작업에도 복잡한 모델을 사용하여 자원 낭비를 초래합니다.

Claude Code Router는 지능형 라우팅을 통해 이러한 문제들을 해결합니다. 저자는 VSCode Copilot에서 Claude-4를 사용하여 Flutter 문제를 처리할 때 세 번의 대화만으로 파일이 엉망이 되어 롤백해야 했던 경험을 언급했습니다. 반면, Claude Code를 DeepSeek과 함께 사용했을 때는 서너 번의 대화 끝에 작업을 성공적으로 완료했으며, 비용은 1위안 미만이었습니다.

핵심 기능

1. 듀얼 모드 실행

• Normal Mode (일반 모드): 단일 모델을 사용하여 모든 작업을 완료합니다.
• Router Mode (라우터 모드): 여러 전문화된 모델이 협력하여 다양한 유형의 작업을 완료합니다.

2. 지능형 모델 분업

라우터 모드에서 시스템은 네 가지 다른 전문화된 모델을 사용합니다:

• Router Agent (라우팅 분배기): qwen2.5-coder-3b

  • 요청 라우팅 및 분배를 담당합니다.
  • 높은 지능이 필요하지 않으므로 작은 모델로도 충분합니다.
  • 현재 알리바바 클라우드 공식 무료 qwen2.5-coder-3b 모델을 사용합니다.

• Tool Agent (도구 호출기): qwen-max-0125

  • 도구 호출을 담당합니다.
  • 함수 호출을 지원해야 합니다.
  • 충분히 큰 도구 설명 길이(이상적으로는 1754 이상)를 지원해야 합니다.

• Coder Agent (코드 생성기): deepseek-v3

  • 코드 생성 작업을 전문적으로 담당합니다.
  • DeepSeek 시리즈 모델을 사용합니다.

• Think Agent (추론 모델): deepseek-r1

  • 복잡한 추론 작업을 담당합니다.
  • DeepSeek R1 추론 모델을 사용합니다.

3. 비용 최적화

• 알리바바 클라우드의 무료 qwen2.5-coder-3b 모델과 DeepSeek의 KV-Cache 기술 덕분입니다.
• Claude Code 사용 비용을 크게 절감할 수 있습니다.
• 작업 분업을 통해 간단한 작업에 비싼 모델을 사용하는 것을 방지합니다.

설치 및 구성

1. Claude Code 설치

npm install -g @anthropic-ai/claude-code

2. 프로젝트 클론

git clone https://github.com/musistudio/claude-code-reverse.git

3. 의존성 설치

npm i

4. 환경 변수 구성

일반 모드 구성

# 라우터 비활성화
ENABLE_ROUTER=false
OPENAI_API_KEY=""
OPENAI_BASE_URL=""
OPENAI_MODEL=""

라우터 모드 구성

# 라우터 활성화
ENABLE_ROUTER=true
export TOOL_AGENT_API_KEY=""
export TOOL_AGENT_BASE_URL=""
export TOOL_AGENT_MODEL="qwen-max-2025-01-25"
export CODER_AGENT_API_KEY=""
export CODER_AGENT_BASE_URL="https://api.deepseek.com"
export CODER_AGENT_MODEL="deepseek-chat"
export THINK_AGENT_API_KEY=""
export THINK_AGENT_BASE_URL="https://api.deepseek.com"
export THINK_AGENT_MODEL="deepseek-reasoner"
export ROUTER_AGENT_API_KEY=""
export ROUTER_AGENT_BASE_URL=""
export ROUTER_AGENT_MODEL="qwen2.5-coder-3b-instruct"

5. 서비스 시작

node index.mjs

6. Claude Code 환경 변수 구성

export DISABLE_PROMPT_CACHING=1
export ANTHROPIC_AUTH_TOKEN="test"
export ANTHROPIC_BASE_URL="http://127.0.0.1:3456"
export API_TIMEOUT_MS=600000
claude

기술 아키텍처

라우터 모드 작동 원리

1. 요청 수신: Claude Code가 로컬 프록시 서버로 요청을 보냅니다.
2. 지능형 라우팅: Router Agent가 요청 유형을 분석하여 어떤 전문화된 모델로 전달할지 결정합니다.
3. 작업 실행:
   • 도구 호출 작업 → Tool Agent
   • 코드 생성 작업 → Coder Agent
   • 복잡한 추론 작업 → Think Agent
4. 결과 반환: 각 모델이 작업을 완료한 후 결과를 반환합니다.

주요 장점

• 작업 분리: 도구 호출과 코딩 작업을 분리합니다.
• 모델 전문화: 각 모델이 자신이 가장 잘하는 작업에 집중합니다.
• 비용 제어: 작업 복잡도에 따라 적절한 모델을 선택합니다.
• 추론 모델 지원: 함수 호출을 지원하지 않는 R1과 같은 추론 모델을 지원합니다.

주의사항

⚠️ 중요 알림:

• 이 프로젝트는 테스트 단계에 있으며, 많은 토큰을 소모할 수 있습니다.
• 작업 실행 실패가 발생할 수 있습니다.
• 프로젝트에 적절한 ignorePatterns 설정을 권장합니다.

프로젝트의 의미

Claude Code Router는 AI 프로그래밍 도구 발전의 중요한 방향을 제시합니다:

• 비용 민주화: 더 많은 개발자가 AI 프로그래밍 도우미를 감당할 수 있게 합니다.
• 모델 다양화: 단일 모델에 의존하지 않고, 가장 적합한 모델을 유연하게 선택할 수 있습니다.
• 아키텍처 혁신: 라우팅과 전문화된 분업을 통해 전반적인 효율성을 향상시킵니다.

이 프로젝트는 개발자에게 Claude Code의 강력한 기능을 유지하면서도 사용 비용을 크게 절감할 수 있는 강력한 도구를 제공하며, AI 프로그래밍 도구의 대중화에 중요한 기여를 합니다.