Claude Code 및 Agent SDK를 위한 멀티 LLM 라우터: claude-code-agent-sdk-router

섹션별 상세

Claude Code와 Anthropic Agent SDK의 API 호출을 가로채어 설정된 다른 LLM 제공자로 전달한다. Anthropic의 /v1/messages 형식을 중간 표현으로 변환한 뒤, OpenAI, Gemini, Groq, Mistral, Ollama 등 7개 제공자의 네이티브 형식으로 다시 변환하는 트랜스포머 구조를 갖추고 있다.

Claude Code 인터페이스 내에서 OpenAI의 Codex 모델이 실행되는 모습 — Screenshot이 이미지는 라우터를 통해 Anthropic의 전용 도구인 Claude Code에서 타사 모델이 실제로 작동함을 증명한다. 동일한 인터페이스 내에서 모델만 교체하여 작업이 수행되는 과정을 시각적으로 보여준다.

두 가지 운영 모드를 지원하여 사용 환경에 맞게 선택할 수 있다. Standard 모드는 로컬에서 Claude Code를 사용하는 단일 사용자를 위해 설정 파일을 기반으로 작동하며, Gateway 모드는 멀티 테넌트 애플리케이션을 위해 요청별 자격 증명과 라우팅을 처리한다.

bash

export ANTHROPIC_BASE_URL=http://127.0.0.1:8901
export ANTHROPIC_API_KEY=sk-or-v1-...
export ANTHROPIC_MODEL="openrouter,google/gemini-2.5-flash"

게이트웨이 모드에서 환경 변수를 통해 타사 모델을 Claude Code에 연결하는 방법

모델 티어링 시스템을 통해 Claude의 Opus, Sonnet, Haiku 모델 이름을 사용자가 지정한 타사 모델로 매핑한다. 예를 들어 Sonnet 요청을 Gemini 2.5 Pro로, Haiku 요청을 Gemini 2.5 Flash로 자동 라우팅하여 비용과 성능을 최적화할 수 있다.

json

{
  "Providers": {
    "anthropic": "$ANTHROPIC_API_KEY",
    "openrouter": "$OPENROUTER_API_KEY",
    "gemini": "$GEMINI_API_KEY"
  },
  "Routes": {
    "mixed": {
      "sonnet": "openrouter,google/gemini-2.5-pro-preview",
      "haiku": "gemini,gemini-2.5-flash"
    }
  },
  "ActiveRoute": "mixed"
}

모델 티어별로 서로 다른 제공자와 모델을 매핑하는 설정 파일 예시

보안과 투명성을 위해 약 2,000라인의 TypeScript 코드로 작성되었으며 외부 파일의 동적 로딩을 배제했다. 기본적으로 127.0.0.1 로컬 호스트에만 바인딩되어 외부 네트워크 노출을 차단하며, 모든 통신 로그를 검토할 수 있는 기능을 제공한다.

대화형 설정 마법사인 ccasr setup을 통해 API 키 관리와 모델 라우팅 규칙을 손쉽게 구성한다. 설정은 JSON5 형식을 사용하여 주석 처리가 가능하며, 환경 변수를 참조하여 API 키를 안전하게 관리할 수 있다.

용어 해설

API 프록시(API Proxy): — 클라이언트와 서버 사이에서 통신을 중계하며 요청을 가로채거나 변환하는 중간 서버이다. 이 도구에서는 Anthropic API 호출을 가로채어 다른 LLM 제공자의 형식으로 변환하여 전달하는 역할을 수행한다.
벤더 종속성(Vendor Lock-in): — 특정 업체의 제품이나 서비스에 지나치게 의존하게 되어 다른 대안으로 교체하기 어려워지는 현상이다. 이 프로젝트는 Anthropic 생태계에 묶이지 않고 다양한 모델을 선택할 수 있는 옵션을 제공하여 이를 해결한다.
멀티 테넌트(Multi-tenant): — 하나의 소프트웨어 인스턴스가 여러 사용자나 그룹(테넌트)에게 서비스를 제공하는 아키텍처이다. 게이트웨이 모드에서는 사용자별로 서로 다른 API 키와 설정을 적용하여 독립적인 세션을 관리할 수 있다.
중간 표현(Intermediate Representation): — 서로 다른 데이터 형식 간의 변환을 용이하게 하기 위해 사용하는 공통된 내부 데이터 구조이다. Anthropic 형식을 OpenAI 호환 형식으로 먼저 바꾼 뒤 최종 제공자 형식으로 변환하는 가교 역할을 한다.

기술

Node.js
TypeScript
Fastify
Claude Code
OpenRouter
Ollama
Gemini API

활용 사례

Claude Code 인터페이스에서 GPT-4o 사용
로컬 LLM을 이용한 오프라인 코딩 보조
모델별 코딩 성능 비교 테스트

언급된 리소스

GitHubclaude-code-agent-sdk-router GitHub Repository