Claude Code Mux: 다양한 LLM들을 Claude Code에서 함께 사용할 수 있는 Rust 기반 AI 라우팅 프록시

읽을거리&정보공유
, , , ,
1

Claude Code Mux: 다양한 LLM들을 Claude Code에서 함께 사용할 수 있는 Rust 기반 AI 라우팅 프록시
Claude Code Mux: 다양한 LLM들을 Claude Code에서 함께 사용할 수 있는 Rust 기반 AI 라우팅 프록시1496×361 25.9 KB

Claude Code Mux 소개

Claude Code Mux는 Rust로 작성된 고성능 AI 라우팅 프록시 서버로, 최근 개발자들 사이에서 큰 주목을 받고 있는 'Claude Code' CLI 도구 및 다양한 AI 클라이언트와 함께 사용할 수 있는 강력한 미들웨어입니다. 최근 Anthropic의 Claude Code가 터미널 기반의 에이전트 코딩 도구로 자리를 잡으면서, 이를 더욱 안정적이고 효율적으로 활용하기 위한 니즈가 커졌습니다. Claude Code Mux는 그러한 필요에 맞춰 여러 AI 제공 업체(Provider)를 하나의 엔드포인트로 묶어 관리하고, 장애 발생 시 자동으로 백업 경로로 전환해주는 기능을 제공합니다.

보통 AI API를 사용하여 개발 도구나 서비스를 구축할 때 가장 큰 골칫거리 중 하나는 특정 API 제공 업체의 갑작스러운 장애나 속도 저하, 그리고 비용 문제입니다. 예를 들어, 주력으로 사용하는 모델의 API가 응답하지 않으면 개발 업무가 중단되거나 서비스에 차질이 빚어질 수 있습니다. Claude Code Mux는 이러한 단일 실패 지점(SPOF, Single Point of Failure) 문제를 해결하기 위해 등장했습니다. 사용자는 이 프록시를 통해 Anthropic, OpenAI, Google Gemini, OpenRouter 등 15개 이상의 다양한 AI 제공 업체를 유연하게 연결하고 조합할 수 있습니다.

image
image1364×1022 59.1 KB

이 도구를 주목해야 하는 이유는 자동 장애 조치(Automatic Failover) 및 스마트 라우팅(Smart Routing) 기능 때문입니다. Rust 언어 특유의 빠른 성능(오버헤드 100ms 미만)을 바탕으로, 주 사용 모델이 응답하지 않을 경우 즉시 설정된 우선순위에 따라 백업 모델로 요청을 우회시킵니다. 또한, 복잡한 JSON 설정을 직접 수정할 필요 없이 직관적인 웹 UI를 통해 제공 업체를 추가하거나 라우팅 규칙을 변경할 수 있어 사용자 편의성이 매우 뛰어납니다. 개발 생산성을 극대화하고 API 의존성 문제를 해결하고 싶은 엔지니어라면 반드시 살펴봐야 할 프로젝트입니다.

Claude Code Mux vs. LiteLLM

AI 모델 프록시 및 라우팅 분야에서 가장 널리 알려진 유사 프로젝트로는 LiteLLM이 있습니다. 두 도구 모두 여러 LLM API를 표준화된 인터페이스(주로 OpenAI 호환)로 사용할 수 있게 해준다는 공통점이 있지만, 설계 철학과 주 사용성에서 차이가 있습니다.

  • LiteLLM: Python 기반으로 작성되어 생태계가 매우 방대하고 설정이 유연하지만, Python 인터프리터 위에서 동작하므로 트래픽이 많을 경우 미세한 지연이 발생할 수 있습니다. 주로 서버 사이드 애플리케이션 통합에 강점이 있습니다.
  • Claude Code Mux: Rust로 작성되어 매우 가볍고 빠른 처리 속도를 자랑합니다. 특히 이름에서 알 수 있듯이 Anthropic의 Claude Code CLI 도구와의 연동성을 최우선으로 고려하여 설계되었습니다. 터미널 환경에서의 에이전트 코딩 워크플로우에 최적화된 라우팅 규칙과 웹 기반의 실시간 설정 UI를 제공하여, 개인 개발자나 소규모 팀이 로컬 환경에서 즉시 활용하기에 더욱 적합합니다.

Claude Code Mux의 주요 기능과 특징

Claude Code Mux 프로젝트는 단순한 API 포워딩을 넘어, 개발자가 AI 도구를 사용할 때 겪는 불편함을 해소하기 위한 다양한 기능을 포함하고 있습니다. Clayde Code Mux의 주요 기능은 다음과 같습니다:

  • 강력한 자동 장애 조치 (Automatic Failover): Claude Code Mux의 핵심 기능은 안정성입니다. 사용자는 모델별로 우선순위를 설정할 수 있습니다. 예를 들어, 코딩 작업 시 glm-4.6 모델을 주력으로 사용하도록 설정(priority = 1)해두고, 이 공급자에 문제가 생겼을 때 자동으로 openrouter나 다른 백업 공급자(priority = 2)로 연결되도록 구성할 수 있습니다. 이 과정에서 클라이언트(예: Claude Code CLI)는 오류를 감지하지 못하며, 끊김 없는 작업이 가능합니다.

    image
    image1356×1019 67.9 KB

  • 직관적인 웹 관리 인터페이스 (Web UI): 기존의 많은 프록시 도구들이 복잡한 YAML이나 JSON 설정 파일을 직접 수정하고 서버를 재시작해야 했던 것과 달리, Claude Code Mux는 제로 다운타임(Zero-downtime) 설정을 지원하는 웹 UI를 내장하고 있습니다.

    • 간편한 공급자 추가: 웹 화면에서 클릭 몇 번으로 새로운 API 키와 공급자를 등록할 수 있습니다.

    • 실시간 라우팅 변경: 드롭다운 메뉴를 통해 모델 간 라우팅 규칙을 변경하면 즉시 반영됩니다.

    • 설정 공유: 현재 구성을 JSON 파일이나 URL 형태로 동료와 쉽게 공유할 수 있습니다.

  • 폭넓은 호환성과 OpenAI 엔드포인트 지원: Claude Code Mux는 Anthropic, OpenAI, Cerebras, Minimax, Kimi 등 15개 이상의 주요 AI 공급자를 기본적으로 지원합니다. 더불어 v0.3.0 업데이트를 통해 OpenAI 호환 엔드포인트 (/v1/chat/completions) 를 완벽하게 지원하게 되었습니다.

    image
    image1362×1022 64.5 KB

    이로써 Claude Code CLI뿐만 아니라, OpenAI API 방식을 사용하는 VS Code 확장 프로그램(Cursor, Windsurf 등)이나 다른 AI 도구에서도 Claude Code Mux를 백엔드 라우터로 활용할 수 있습니다.

    또한, 스트리밍(Streaming) 요청도 완벽하게 처리하여, 실시간으로 답변이 생성되는 경험을 그대로 유지합니다.

  • 스마트 라우팅 (Smart Routing): 단순한 장애 조치를 넘어, 요청의 성격에 따라 가장 적합한 모델로 트래픽을 분산시킬 수 있습니다. 예를들어, 최신 정보 검색이 필요한 쿼리는 검색 기능이 강화된 모델로 라우팅하거나, 복잡한 추론이 필요한 작업은 추론(Reasoning) 기능이 있는 o1, Claude 3.5 Sonnet 등의 모델로 연결하는 방식으로 동작합니다. 그 외에도 사용자가 직접 대면하지 않는 백그라운드 작업은 비용 대비 효율적인 모델로 처리하는 방식으로 동작합니다.

    image
    image1362×1020 59.4 KB

  • Rust 기반의 고성능 아키텍처: 시스템 리소스를 적게 차지하면서도 빠른 처리 속도를 보장하기 위해 Rust 언어로 개발되었습니다. 라우팅 과정에서 발생하는 오버헤드를 100ms 미만으로 억제하여, 사용자는 프록시를 거치고 있다는 사실을 거의 체감할 수 없습니다. 로컬 머신에 백그라운드 서비스로 띄워두고 사용하기에 부담이 없습니다.

Claude Code Mux 설치

Claude Code Mux는 실행 파일(바이너리)를 빌드하여 제공하고 있습니다. 프로젝트 릴리즈 페이지에서 OS 및 아키텍처에 맞춰 실행 파일(바이너리)을 다운로드 받아 설치합니다. macOS, Windows, Linux용 사전 빌드 버전이 제공됩니다.

예를 들어, Linux에서는 다음과 같이 다운로드 및 설치가 가능합니다:

# 다운로드 및 압축 해제
curl -L https://github.com/9j/claude-code-mux/releases/latest/download/ccm-linux-x86_64.tar.gz | tar xz

# 설치
sudo mv ccm /usr/local/bin/

# 실행 확인
ccm --version

또는, 이미 Rust 개발 환경을 구성해두었다면 Cargo로 설치할 수도 있습니다. 다음과 같은 명령어를 사용하면 됩니다:

cargo install claude-code-mux

설치 후에는 다음과 같은 명령어로 실행할 수 있습니다:

ccm start

실행 후 웹 브라우저에서 http://127.0.0.1:13456을 열어 기본 UI를 사용할 수 있습니다.

Claude Code Mux 빠른 시작

먼저, LLM 서비스 제공자를 선택하기 위해 Providers 탭에서 Anthropic OAuth, OpenAI API Key, Google Gemini OAuth 등의 AI 제공자를 추가합니다.

이후, 각 서비스 제공자의 모델을 추가합니다. Models 탭에서 사용 가능한 모델을 매핑할 수 있습니다. 예를 들어, glm-4.6 → z.ai + fallback: openrouter와 같이 설정합니다.

마지막으로 Router 탭에서 라우팅 규칙 설정합니다. 예를 들어, 다음과 같이 구성할 수 있습니다:

  • 기본(default): minimax-m2
  • Think: kimi-k2
  • Background: glm-4.5-air
  • WebSearch: glm-4.6
  • Regex auto-map: ^claude-

이 때, 라우팅 규칙은 다음 단계로 수행됩니다:

  1. Auto-mapping: 모델명이 정규식(^claude-)에 매칭되면 변환.
  2. WebSearch: 도구(tool)에 web_search가 포함되어 있으면 WebSearch 모델 사용.
  3. Subagent: <CCM-SUBAGENT-MODEL> 태그가 있으면 해당 모델로 라우팅.
  4. Think Mode: thinking: enabled 요청은 Think 모델 사용.
  5. Background: Haiku 등 백그라운드 모델 패턴 매칭 시 Background 모델 사용.
  6. Default: 위 조건에 해당하지 않으면 기본(default) 모델 사용.

이러한 계층적 라우팅 구조 덕분에 요청이 복잡하더라도 예측 가능한 방식으로 처리됩니다.

image
image1360×1022 59.9 KB

이상과 같이 설정이 완료되면 Test 탭에서 구성을 확인하고 테스트해볼 수 있습니다.

라이선스

Claude Code Mux 프로젝트는 MIT License로 공개되어 있으며, 상업적 이용 및 수정, 배포가 자유롭게 가능합니다.

:github: Claude Code Mux 프로젝트 GitHub 저장소

https://github.com/9j/claude-code-mux



이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다. :hugs:

:pytorch:파이토치 한국 사용자 모임:south_korea:이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일:love_letter:로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)

:wrapped_gift: 아래:down_right_arrow:쪽에 좋아요:+1:를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~ :star_struck:

2개의 좋아요