docs: README.md에 프로젝트 소개 및 시작하기 섹션 추가
- README.md: AI 개발 도구 통합 소개 및 사용 방법 추가 - MCP 서버 구성 방법 및 주요 기능 설명 추가
This commit is contained in:
226
docs/guides/Claude code router 설치 방법.md
Normal file
226
docs/guides/Claude code router 설치 방법.md
Normal file
@ -0,0 +1,226 @@
|
||||
# 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를 효과적으로 사용하시기 바랍니다!
|
||||
Reference in New Issue
Block a user