Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
CCR-Rust는 AI 코딩 도구와 모델 제공자 사이에 위치하는 경량의 자체 호스팅 LLM 라우터입니다. 이 도구는 단일 로컬 URL로 통신하며, 요청을 받아 어떤 제공자가 처리할지 결정하고 API 형식을 변환합니다. 이를 통해 사용자는 특정 제공자의 할당량 소진이나 장애 발생 시에도 코딩 작업을 지속할 수 있습니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 GitHub AI Tools의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기CCR-Rust는 사용자의 AI 코딩 도구(Claude Code, Codex, OpenCode 또는 모든 OpenAI 호환 클라이언트)와 모델 제공자 사이에 위치하는 경량의 자체 호스팅 LLM 라우터입니다. 사용자의 클라이언트는 하나의 로컬 URL과 통신하며, CCR-Rust가 어떤 제공자와 모델이 실제로 각 요청을 처리할지 결정하고, 필요에 따라 API 형식을 변환하며, 제공자에 문제가 생기면 자동으로 장애 조치(fail over)를 수행합니다. 이 도구는 개발자 및 팀이 선호하는 코딩 CLI를 계속 사용하면서도 제공자를 전환하거나, 여러 모델에 부하를 분산시키거나, 사용량 제한이 소진된 후에도 작업을 지속하고 싶은 사람들을 목표로 합니다.
사람들이 가장 흔하게 설치하는 이유는 다음과 같습니다: Claude 플랜을 다 써버렸을 때, 도구를 변경하는 대신 GLM, MiniMax, DeepSeek 또는 다른 제공자를 사용하여 Claude Code를 계속 사용하는 것.
코딩 에이전트와 그 모델 제공자는 두 개의 독립적인 계층이며, 실제로 긴 에이전트 세션을 중단시키는 실패는 제공자 계층에서 발생합니다: 할당량 창(5시간, 주간, 월간)이 소진되거나, 피크 시간대에 제공자들이 429 폭풍을 내보내거나, 엔드포인트에 지역적 장애가 발생하거나, 모델이 사용 중단되거나 조용히 라우팅되거나, 가격이나 약관이 예고 없이 변경됩니다. 아무리 좋은 에이전트라도 자신에게 속도 제한(rate-limiting)을 거는 제공자를 고칠 수는 없습니다. 라우터는 에이전트와 이 전체 실패 표면 사이에 로컬이며 제공자 독립적인 엔드포인트를 배치합니다:
라우터는 용량을 생성하지 않습니다. 라우터는 사용자가 이미 보유하고 있는 모든 용량을, 연결하는 모든 제공업체에 걸쳐 최대화합니다.
/v1/messages)와 OpenAI API(/v1/chat/completions, /v1/responses)를 모두 지원하며, 요청 및 응답 변환을 처리해 드립니다.작은 크기: 약 15MB의 바이너리로, P99 라우팅 오버헤드가 50ms 미만이며, 사용자의 흐름을 방해하지 않도록 설계되었습니다.
┌──────────────┐ ┌────────────┐ ┌─────────────────────┐
│ Claude Code │ ─────▶ │ │ ─────▶ │ Z.AI (GLM-5.2) │ tier 0
│ Codex │ ─────▶ │ CCR-Rust │ ─────▶ │ MiniMax (M3) │ tier 1
...
Rust 툴체인(rustup을 사용하는 것이 가장 쉽습니다)이 필요합니다.
git clone https://github.com/RESMP-DEV/ccr-rust.git
cd ccr-rust
cargo build --release
...
이렇게 하면 ccr-rust 바이너리가 ~/.cargo/bin에 설치됩니다 (해당 디렉터리가 PATH에 포함되어 있는지 확인하세요).
Dockerfile과 docker-compose.yml이 포함되어 있습니다. compose 파일은 리포지토리 루트의 ./config.json을 마운트합니다:
cp config.example.json config.json # 이후 providers/keys로 수정하세요
docker compose up --build
또는 이미지를 직접 빌드하고 실행할 수 있습니다:
docker build -t ccr-rust .
docker run --rm -p 3456:3456 \
-v ./config.json:/etc/ccr/config.json:ro \
...
사전 빌드된 릴리스 바이너리는 아직 게시되지 않았습니다. 소스에서 빌드하거나 Docker를 사용하세요. 향후 바이너리 릴리스는 리포지토리의 Releases 페이지를 확인해 주세요.
이미 로컬에 설정하셨나요? claude-ccr, codex-ccr, 서비스 제어 및 검증에 대해서는 로컬 작업 및 에이전트 사용을 참조하세요. 개인 플랜과 기업 플랜을 분리하려면 인증 스위트(Authentication suites)를 따르세요.
Claude Code가 CCR을 통해 라우팅되는 것은 기기별 옵트인 방식이며, 유지 관리자 Mac의 경우 Claude Code는 네이티브 Anthropic 구독 로그인을 사용하고 claude-ccr은 폐지되었습니다.
전체 문서 색인(documentation index)에서 설정 및 작동 방식을 확인할 수 있습니다.
코딩 플랜 전환을 사용하여 세션별로 Kimi 또는 Z.AI GLM을 선택하거나, Codex 프로필을 저장하거나, 의도적인 폴백(fallback)을 구성할 수 있습니다. 테스트된 두 공급자 시작점은 examples/coding-plans.json입니다.
Qwen Token Plan을 크레딧 레인으로 추가하려면 Qwen Token Plan 통합을 참조하세요.
권장되는 다중 공급자(multi-provider) 시작 지점은 examples/config.followers.json입니다. 이 파일은 1차 계층으로 GLM 코딩 플랜, 2차 계층으로 MiniMax 토큰 플랜, 오버플로우를 위한 무료 NVIDIA NIM 체험 계층을 포함하며, 경계가 있는 홀드(bounded hold)로 재시도 스윕(retry sweeps)이 활성화되어 있습니다. 이 구성의 근거는 Why route at all를 참조하십시오. OpenRouter 전용 무료 티어 설정의 경우, examples/openrouter-free.json 및 OpenRouter 설정을 참조하십시오.
최소한의 단일 공급자(single-provider) 구성은 약 2분 만에 로컬에서 라우터(router)를 실행할 수 있습니다. 이 팔로워 템플릿은 세 개의 API 키와 세 계층 전체를 커버하는 유효성 검사(validate run)가 필요합니다.
위의 설치를 따르고, 다음을 확인하십시오:
ccr-rust version
mkdir -p ~/.claude-code-router
cp config.example.json ~/.claude-code-router/config.json
~/.claude-code-router/config.json을 열고 API 키를 가진 공급자만 남겨두십시오. 최소한의 단일 공급자 구성은 다음과 같습니다 (복사 붙여넣기 버전은 examples/config.minimal.json을 참조하십시오):
{
"Providers": [
{
...
${DEEPSEEK_API_KEY}는 환경 변수에서 확장되므로, 먼저 키를 내보내십시오:
export DEEPSEEK_API_KEY="sk-..."
ccr-rust validate # 시작하기 전에 구성을 확인합니다
ccr-rust start # 127.0.0.1:3456에서 라우터를 시작합니다
두 번째 터미널에서:
ccr-rust status # ✓ CCR-Rust가 127.0.0.1:3456에서 실행 중입니다
curl -s http://127.0.0.1:3456/v1/messages \
-H "content-type: application/json" \
-d '{
...
# Claude Code용: 이 명령어에만 옵트인합니다
ANTHROPIC_BASE_URL=http://127.0.0.1:3456 \
ANTHROPIC_AUTH_TOKEN=ccr-local ANTHROPIC_API_KEY=ccr-local claude
...
위에 언급된 로컬 클라이언트 토큰은 플레이스홀더입니다. CCR는 자체 설정에서 업스트림 제공업체 키를 사용하며, HTTP 리스너가 클라이언트를 인증하지 않습니다. 루프백(loopback) 상태로 유지하세요. 일반적인 `claude` 및 `codex` 실행은 기존 설정을 유지합니다. 모델 오버라이드와 프로필 형식에 대한 내용은 클라이언트 가이드를 참조하세요.
더 많은 예시(다단계 장애 조치, 프리셋, 스모크 테스트 스크립트)는 [`examples/`](examples/)에서 확인할 수 있습니다.
## 사용법 (Usage)
전체 참고 자료를 보려면 `ccr-rust --help`를 실행하세요. 가장 일반적인 명령어들은 다음과 같습니다:
| 명령어 | 목적 |
| :--- | :--- |
| `ccr-rust start` | 라우터 시작 (기본 명령어 — 단순히 `ccr-rust`를 실행하는 것도 동일합니다) |
| ... |
### 예시 (Examples)
```bash
# 사용자 지정 주소/포트에서 시작하기
ccr-rust start --host 0.0.0.0 --port 8080
...
| 엔드포인트 | 메서드 | 목적 |
|---|---|---|
/v1/messages | POST | Anthropic 메시지 API |
| ... |
CCR-Rust는 기본적으로 ~/.claude-code-router/config.json 파일을 읽습니다( --config 또는 CCR_CONFIG로 재정의 가능). "${MY_API_KEY}"와 같은 값은 환경 변수에서 확장되므로, 비밀 정보가 파일에 저장될 필요가 없습니다. 리버스 프록시 노출을 위해 별도의 키 보호 리스너를 추가하려면 AUTH_PORT와 함께 CLIENT_API_KEY를 설정하세요. 일반적인 HOST/PORT 리스너는 기존의 인증되지 않은 로컬 계약(local contract) 상태로 유지됩니다. 원격 API (Remote API)를 참조하세요.
가장 많이 다루게 될 세 가지 섹션은 다음과 같습니다:
Providers — 업스트림 엔드포인트: 이름, 기본 URL, API 키, 모델, 선택적 트랜스포머(transformers).Router — 라우팅 규칙: default 경로, 선택적 background / think / webSearch 경로, tiers 장애 조치 계층 구조(failover cascade), 재시도(retries), 그리고 GP 라우팅.Presets — 매개변수 오버라이드가 적용된 이름 지정 경로: /preset/{name}/v1/messages에서 접근 가능.{
"Providers": [
{
...
전체 스키마, 트랜스포머 참조 및 제공업체별 설정: docs/configuration.md. 일반적인 시나리오를 위한 준비된 설정: docs/presets.md 및 examples/.
type: "rate_limit_error", code: "rate_limited")과 어느 제공업체가 속도 제한에 걸렸는지 식별하는 x-ccr-tier 헤더와 함께 클라이언트로 전달됩니다. 속도 제한은 내부적으로 추적되므로, 향후 요청 시 해당 티어는 백오프(backoff)되는 동안 건너뛰게 됩니다.X-RateLimit-Remaining: 0)는 기본적으로 선제적인 티어 건너뛰기를 유발합니다. 이러한 정보성 경고를 실제 강제 적용 없이 보내는 제공업체(예: Z.AI)의 경우, 각 제공업체별로 `status가 'Not running'이라고 나오지만 방금 시작했습니다
기본적으로 status는 127.0.0.1:3456을 확인합니다. 만약 다른 호스트/포트로 시작했다면, 동일한 값을 전달하세요: ccr-rust status --host 0.0.0.0 --port 8080.
Claude Code는 ANTHROPIC_API_KEY를 요청합니다
클라이언트의 환경 변수에 비어있지 않은 값으로 설정해 주세요. CCR-Rust는 자체 설정 파일에 있는 키를 사용하여 상위 시스템(upstream) 인증을 수행합니다.