# 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 모델을 사용한 코드 생성을 지원합니다. 설치되지 않았다면 다음 명령어를 실행하세요:

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

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

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

**상세 설명**:
- 이 명령어는 Node.js 환경에서 실행됩니다. Node.js가 설치되어 있지 않다면 먼저 [Node.js 공식 사이트](https://nodejs.org/)에서 다운로드하세요.
- 설치 후, `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 키와 모델을 수정하세요.

```json
{
  "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 키를 실제 값으로 교체하세요.

```json
{
  "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를 시작합니다:

```shell
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` 파일을 수정하세요. 예시:

```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 키를 저장하세요.

## 📝 추가 자료
- [Claude Code Router 공식 깃헙헙](https://github.com/musistudio/claude-code-router)
- [프로젝트 동기 및 작동 원리](https://github.com/musistudio/claude-code-router/blob/main/blog/en/project-motivation-and-how-it-works.md)
- [라우터로 더 많은 작업하기](https://github.com/musistudio/claude-code-router/blob/main/blog/en/maybe-we-can-do-more-with-the-route.md)

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