Claude Code Router 설치 가이드

이 가이드는 Claude Code Router의 설치, 설정 및 사용 방법을 상세히 설명합니다. Claude Code Router는 Claude Code 요청을 다양한 모델로 라우팅하고, 요청을 커스터마이징할 수 있는 강력한 도구입니다. 주요 기능으로는 모델 라우팅, 다중 제공자 지원, 요청/응답 변환, 동적 모델 전환 등이 있습니다.

이 가이드는 영어 README 내용을 기반으로 하며, 설치 방법에 대한 세부 설명과 ~/.claude-code-router/config.json 파일의 예시를 포함합니다. 모든 설명은 한국어로 제공되며, 코드 예시는 원문의 영어 표기를 유지합니다.

✨ 주요 기능

모델 라우팅: 배경 작업(background tasks), 생각 모드(thinking), 긴 컨텍스트(long context) 등에 따라 요청을 다른 모델로 라우팅합니다.
다중 제공자 지원: OpenRouter, DeepSeek, Ollama, Gemini, Volcengine, SiliconFlow 등의 모델 제공자를 지원합니다.
요청/응답 변환: 제공자에 맞게 요청과 응답을 변환하는 트랜스포머를 사용합니다.
동적 모델 전환: Claude Code 내에서 /model 명령어로 모델을 실시간으로 전환할 수 있습니다.
GitHub Actions 통합: GitHub 워크플로에서 Claude Code 작업을 트리거할 수 있습니다.
플러그인 시스템: 커스텀 트랜스포머로 기능을 확장할 수 있습니다.

🚀 시작하기

1. 설치

먼저, Claude Code가 설치되어 있는지 확인하세요. Claude Code는 Anthropic의 공식 도구로, Claude 모델을 사용한 코드 생성을 지원합니다. 설치되지 않았다면 다음 명령어를 실행하세요:

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

그 다음, Claude Code Router를 설치합니다. 이는 글로벌로 설치하는 것이 권장됩니다:

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

상세 설명:

이 명령어는 Node.js 환경에서 실행됩니다. Node.js가 설치되어 있지 않다면 먼저 Node.js 공식 사이트에서 다운로드하세요.
설치 후, ccr 명령어가 사용 가능해집니다. (예: ccr code로 Claude Code를 라우터와 함께 실행)
문제가 발생하면, npm 캐시를 지우고 재설치하세요: npm cache clean --force 후 다시 설치.

2. 설정

설정 파일은 홈 디렉토리에 생성됩니다: ~/.claude-code-router/config.json. 이 파일은 모델 제공자, 라우터 규칙 등을 정의합니다. 자세한 내용은 config.example.json을 참조하세요.

config.json 파일의 주요 섹션:

PROXY_URL (선택): API 요청을 위한 프록시 설정 (예: "http://127.0.0.1:7890"). 네트워크 제한이 있는 환경에서 유용합니다.
LOG (선택): 로그 활성화 (true로 설정 시 ~/.claude-code-router.log 파일에 로그 저장).
APIKEY (선택): 요청 인증을 위한 시크릿 키. 설정 시 클라이언트는 Authorization: Bearer your-secret-key 헤더를 사용해야 합니다.
HOST (선택): 서버 호스트 주소 (기본: 127.0.0.1). APIKEY가 없으면 보안을 위해 127.0.0.1로 강제 설정됩니다.
Providers: 모델 제공자 배열. 각 제공자에 이름, API 베이스 URL, API 키, 모델 목록, 트랜스포머를 정의합니다.
Router: 라우팅 규칙. default는 기본 모델, 다른 키(예: background, think)는 특정 시나리오를 위한 모델을 지정합니다.
transformers (선택): 커스텀 트랜스포머를 로드하기 위한 배열.

예시 config.json 파일 (사용자 제공 경로: \home\koolab\.claude-code-router\config.json 기반으로 한 실제 예시): 아래는 실제 사용 중인 config.json의 예시입니다. 이는 Gemini 제공자를 사용하는 간단한 설정입니다. 필요에 따라 API 키와 모델을 수정하세요.

{
  "LOG": true,
  "Providers": [
    {
      "name": "gemini",
      "api_base_url": "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions",
      "api_key": "${GEMINI_API_KEY}",  // 실제 API 키로 교체하세요
      "models": [
        "gemini-2.5-pro"
      ],
      "transformer": {
        "use": [
          "openai"
        ]
      }
    }
  ],
  "Router": {
    "default": "gemini,gemini-2.5-pro",
    "background": "gemini,gemini-2.5-pro",
    "think": "gemini,gemini-2.5-pro",
    "longContext": "gemini,gemini-2.5-pro"
  },
  "HOST": "0.0.0.0"
}

포괄적인 예시 config.json (다중 제공자 포함, README 기반): 이 예시는 여러 제공자를 설정한 경우입니다. 각 제공자의 API 키를 실제 값으로 교체하세요.

{
  "APIKEY": "your-secret-key",  // 인증 키 (선택)
  "PROXY_URL": "http://127.0.0.1:7890",  // 프록시 (선택)
  "LOG": true,  // 로그 활성화
  "Providers": [
    {
      "name": "openrouter",
      "api_base_url": "https://openrouter.ai/api/v1/chat/completions",
      "api_key": "sk-xxx",  // 실제 OpenRouter API 키
      "models": [
        "google/gemini-2.5-pro-preview",
        "anthropic/claude-sonnet-4",
        "anthropic/claude-3.5-sonnet",
        "anthropic/claude-3.7-sonnet:thinking"
      ],
      "transformer": { "use": ["openrouter"] }  // 글로벌 트랜스포머
    },
    {
      "name": "deepseek",
      "api_base_url": "https://api.deepseek.com/chat/completions",
      "api_key": "sk-xxx",  // 실제 DeepSeek API 키
      "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"]
    },
    {
      "name": "gemini",
      "api_base_url": "https://generativelanguage.googleapis.com/v1beta/models/",
      "api_key": "sk-xxx",  // 실제 Gemini API 키
      "models": ["gemini-2.5-flash", "gemini-2.5-pro"],
      "transformer": { "use": ["gemini"] }
    },
    {
      "name": "volcengine",
      "api_base_url": "https://ark.cn-beijing.volces.com/api/v3/chat/completions",
      "api_key": "sk-xxx",  // 실제 Volcengine API 키
      "models": ["deepseek-v3-250324", "deepseek-r1-250528"],
      "transformer": { "use": ["deepseek"] }
    }
  ],
  "Router": {
    "default": "deepseek,deepseek-chat",  // 기본 모델
    "background": "ollama,qwen2.5-coder:latest",  // 배경 작업 모델
    "think": "deepseek,deepseek-reasoner",  // 생각 모드 모델
    "longContext": "openrouter,google/gemini-2.5-pro-preview",  // 긴 컨텍스트 모델
    "webSearch": "gemini,gemini-2.5-flash"  // 웹 검색 모델
  }
}

상세 설명:

Providers 섹션: 각 제공자에 API 키를 입력하세요. 모델 목록은 제공자 문서를 확인하세요.
Transformer: 제공자별로 요청을 조정합니다. 예: "gemini"는 Gemini API에 맞게 변환.
Router 섹션: 시나리오별 모델을 지정합니다. 웹 검색은 모델이 지원해야 합니다 (예: :online 접미사 사용).
파일을 직접 편집한 후, 서버를 재시작하세요.
커스텀 트랜스포머: transformers 배열에 경로를 추가하여 확장하세요.

3. Claude Code Router 실행

라우터와 함께 Claude Code를 시작합니다:

ccr code

상세 설명:

이 명령어는 라우터 서버를 시작하고 Claude Code를 호출합니다.
Claude Code 내에서 /model provider_name,model_name으로 모델을 전환하세요 (예: /model openrouter,anthropic/claude-3.5-sonnet).

🤖 GitHub Actions 통합

GitHub 워크플로에서 Claude Code Router를 사용하려면 .github/workflows/claude.yaml 파일을 수정하세요. 예시:

name: Claude Code

on:
  issue_comment:
    types: [created]
  # ... other triggers

jobs:
  claude:
    if: |
      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
      # ... other conditions
    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: "any-string-is-ok"

상세 설명: 이 설정은 GitHub Actions에서 라우터를 사용해 비용을 절감할 수 있습니다. secrets에 API 키를 저장하세요.

📝 추가 자료

문제가 발생하면 로그 파일을 확인하거나, GitHub 이슈를 제출하세요. 이 가이드를 통해 Claude Code Router를 효과적으로 사용하시기 바랍니다!

9.8 KiB Raw Blame History

Claude Code Router 설치 가이드

✨ 주요 기능

🚀 시작하기

1. 설치

2. 설정

3. Claude Code Router 실행

🤖 GitHub Actions 통합

📝 추가 자료

9.8 KiB

Raw Blame History