Claude Code Router: 종합 사용 설명서

Claude Code Router: 종합 사용 설명서

소개

AI 기반 코딩 도구는 개발자 생산성을 높이는 데 필수적입니다. Anthropic의 Claude Code는 그중 하나로, 강력한 코딩 지원 기능을 제공합니다. 하지만 작업 유형에 따라 최적의 AI 모델을 선택할 수 있다면 더욱 효율적일 것입니다. Claude Code Router는 이러한 유연성을 제공하는 도구로, musistudio에서 개발되었습니다. 이 도구를 사용하면 Claude Code 요청을 다양한 AI 모델로 라우팅하여 작업에 맞는 최적의 환경을 구성할 수 있습니다. 이 설명서에서는 Claude Code Router의 설치, 설정, 주요 기능 및 활용 방법을 자세히 다룹니다.

Claude Code Router란?

Claude Code Router는 Claude Code와 다양한 AI 모델 간의 중개 역할을 하는 유틸리티입니다. 이를 통해 개발자는 작업 유형(예: 백그라운드 작업, 복잡한 추론, 긴 컨텍스트 처리)에 따라 적합한 모델을 선택할 수 있습니다. 또한 Anthropic의 최신 업데이트를 활용하면서도 요청을 사용자 정의할 수 있는 유연성을 제공합니다. 이 도구는 오픈소스로 제공되며, GitHub 페이지에서 자세한 정보를 확인할 수 있습니다.

설치 가이드

Claude Code Router를 사용하려면 다음 단계를 따라 설치하세요:

1. Claude Code 설치
   터미널에서 다음 명령어를 실행하여 Claude Code를 설치합니다:
2. npm install -g @anthropic-ai/claude-code
3. Claude Code Router 설치
   다음으로, Claude Code Router를 설치합니다:
4. npm install -g @musistudio/claude-code-router

설치가 완료되면 바로 설정 및 사용을 시작할 수 있습니다.

Claude Code Router 실행

설치 후, 다음 명령어로 Claude Code Router를 실행합니다:

ccr code

이 명령어는 Claude Code를 라우터와 통합하여 실행하며, 다양한 모델로 요청을 라우팅할 수 있는 환경을 제공합니다.

설정 방법

Claude Code Router의 고급 기능을 활용하려면 설정 파일을 구성해야 합니다. 설정 파일은 ~/.claude-code-router/config.json에 위치하며, AI 모델 제공자와 라우팅 규칙을 정의합니다.

설정 파일 예시

다음은 설정 파일의 예시입니다:

{
  "Providers": [
    {
      "name": "openrouter",
      "api_base_url": "https://openrouter.ai/api/v1/chat/completions",
      "api_key": "sk-xxx",
      "models": [
        "google/gemini-2.5-pro-preview",
        "anthropic/claude-sonnet-4",
        "anthropic/claude-3.5-sonnet",
        "anthropic/claude-3.7-sonnet:thinking"
      ]
    },
    {
      "name": "deepseek",
      "api_base_url": "https://api.deepseek.com/chat/completions",
      "api_key": "sk-xxx",
      "models": ["deepseek-chat", "deepseek-reasoner"],
      "transformer": {
        "use": ["deepseek"],
        "deepseek-chat": {
          "use": ["tooluse"]
        }
      }
    },
    {
      "name": "ollama",
      "api_base_url": "http://localhost:11434/v1/chat/completions",
      "api_key": "ollama",
      "models": ["qwen2.5-coder:latest"]
    }
  ],
  "Router": {
    "default": "deepseek,deepseek-chat",
    "background": "ollama,qwen2.5-coder:latest",
    "think": "deepseek,deepseek-reasoner",
    "longContext": "openrouter,google/gemini-2.5-pro-preview"
  }
}

설정 항목 설명

항목 설명

Providers	사용 가능한 AI 모델 제공자를 정의합니다. 각 제공자는 API 기본 URL, API 키, 지원 모델 목록을 포함합니다. 예: OpenRouter, DeepSeek, Ollama 등.
Router	작업 유형에 따라 모델을 매핑합니다: - default: 일반 작업에 사용되는 기본 모델. - background: 낮은 지능이 필요한 백그라운드 작업용 모델. - think: 복잡한 추론 작업용 모델. - longContext: 긴 컨텍스트(32K 토큰 이상)를 처리하는 모델.

• background: 백그라운드 작업은 높은 지능이 필요하지 않으므로, 로컬에서 실행 가능한 Ollama의 qwen2.5-coder:latest 같은 모델을 사용할 수 있습니다.
• think: 추론 작업에 사용되며, DeepSeek-R1 모델은 현재 예산 제어 기능을 지원하지 않으므로 UltraThink와 Think 모드 간 차이가 없습니다.
• longContext: 컨텍스트 길이가 32K 토큰을 초과할 때 사용되며, google/gemini-2.5-pro-preview 같은 모델이 적합합니다.

모델 전환

Claude Code 내에서 /model 명령어를 사용하여 모델을 동적으로 전환할 수 있습니다. 예:

/model openrouter,anthropic/claude-3.5-sonnet

이 명령은 OpenRouter의 claude-3.5-sonnet 모델로 전환합니다.

주요 기능

Claude Code Router는 다음과 같은 기능을 제공합니다:

기능 설명

모델 전환	/model 명령어로 작업 중 모델을 즉시 변경 가능.
GitHub Actions 통합	GitHub 워크플로우에서 자동화된 작업 실행 지원.
상세 로그	디버깅을 위한 자세한 로그 제공.
이미지 지원	이미지 관련 작업 처리 가능.
웹 검색 지원	코딩 환경에서 웹 검색 기능 통합.

GitHub Actions 통합

Claude Code Router를 GitHub Actions와 통합하여 워크플로우를 자동화할 수 있습니다. 다음 단계를 따르세요:

1. Claude Code Actions 설치
   공식 문서에 따라 리포지토리에 Claude Code Actions를 설치합니다.
2. 워크플로우 파일 수정
   .github/workflows/claude.yaml 파일을 수정하여 라우터를 포함합니다. 예시:

name: Claude Code

on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
  issues:
    types: [opened, assigned]
  pull_request_review:
    types: [submitted]

jobs:
  claude:
    if: |
      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
      (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: read
      issues: read
      id-token: write
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 1

      - name: Prepare Environment
        run: |
          curl -fsSL https://bun.sh/install | bash
          mkdir -p $HOME/.claude-code-router
          cat << 'EOF' > $HOME/.claude-code-router/config.json
          {
            "log": true,
            "OPENAI_API_KEY": "${{ secrets.OPENAI_API_KEY }}",
            "OPENAI_BASE_URL": "https://api.deepseek.com",
            "OPENAI_MODEL": "deepseek-chat"
          }
          EOF
        shell: bash

      - name: Start Claude Code Router
        run: |
          nohup ~/.bun/bin/bunx @musistudio/claude-code-router@1.0.8 start &
        shell: bash

      - name: Run Claude Code
        id: claude
        uses: anthropics/claude-code-action@beta
        env:
          ANTHROPIC_BASE_URL: http://localhost:3456
        with:
          anthropic_api_key: "test"

이 설정은 특정 이벤트(예: 이슈 댓글, 풀 리퀘스트 등)에 따라 Claude Code를 실행하며, 비용 효율적인 시간대에 작업을 스케줄링할 수 있습니다.

실용적인 팁

• DeepSeek 모델 활용: DeepSeek API는 비용 효율적이며, 특히 베이징 시간 기준 00:30~08:30에는 deepseek-v3 모델이 50%, deepseek-r1 모델이 25% 비용으로 사용 가능합니다.
• 컨텍스트 관리: 공식 DeepSeek API는 64K 토큰 컨텍스트를 지원하며, 긴 대화에서는 컨텍스트 초과 오류가 발생할 수 있습니다. ByteDance의 DeepSeek API(128K 토큰 지원)를 사용하거나 이전 컨텍스트를 초기화하세요.
• 성능 최적화: 많은 컨텍스트 정보를 포함하면 모델 간 성능 차이를 줄이고 더 나은 결과를 얻을 수 있습니다.

결론

Claude Code Router는 AI 기반 코딩 워크플로우를 최적화하려는 개발자에게 필수적인 도구입니다. 다양한 모델로 요청을 라우팅하고, GitHub Actions와 통합하며, 이미지 및 웹 검색 기능을 제공하여 생산성을 극대화합니다. 자세한 정보는 Claude Code Router GitHub 페이지를 방문하세요.