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

이 요약은 AI가 원문을 분석해 생성했습니다. 정확한 내용은 원문 기준으로 확인하세요.

핵심 요약

Anthropic의 Claude Code와 Agent SDK는 강력한 기능을 제공하지만 Anthropic 모델에만 종속되는 한계가 있다. 이를 해결하기 위해 개발된 claude-code-agent-sdk-router는 Anthropic API 형식을 OpenAI, Gemini, Groq 등 타사 형식으로 변환해주는 프록시 서버이다. 사용자는 로컬 설정이나 게이트웨이 모드를 통해 다양한 모델을 Claude Code 인터페이스 내에서 실행하고 성능을 비교할 수 있다. 보안과 감사 가능성을 최우선으로 설계되어 최소한의 의존성만 사용하며 로컬 환경에서 안전하게 작동한다.

배경

Node.js >= 18.20, 하나 이상의 LLM 제공자 API 키 또는 로컬 Ollama 실행 환경

대상 독자

Claude Code를 사용하면서 다양한 LLM 모델을 테스트하거나 비용을 최적화하려는 개발자

의미 / 영향

이 도구는 특정 AI 기업의 도구 생태계에 갇히지 않고도 최신 코딩 에이전트 기능을 사용할 수 있게 한다. 특히 오픈소스 모델이나 타사 모델의 성능이 향상됨에 따라 개발자가 상황에 맞는 최적의 모델을 선택할 수 있는 유연성을 제공한다.

섹션별 상세

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 키를 안전하게 관리할 수 있다.

실무 Takeaway

Claude Code를 사용하면서도 Anthropic 외의 모델(GPT-4o, Gemini 등)을 활용하여 특정 작업에 최적화된 모델을 선택하고 비용을 절감할 수 있다.
로컬 LLM(Ollama)과 연동하여 Claude Code의 기능을 오프라인 환경이나 개인 정보 보호가 중요한 환경에서 실행할 수 있다.
게이트웨이 모드를 활용하면 멀티 테넌트 환경에서 사용자별 API 키를 안전하게 전달하고 모델 라우팅을 동적으로 제어할 수 있다.

언급된 리소스

GitHubclaude-code-agent-sdk-router GitHub Repository