Source: https://aiprimetech.io/ko/blog/claude-code-router/

2026년 9월 17일 · 8분 · 오픈 소스 

# Claude Code Router: 다른 모델에서 Claude Code 실행하기(그리고 게이트웨이가 더 간편한 경우) 

 A  작성자 [AI Prime Tech](https://aiprimetech.io/ko/)  · AI 활용    

Claude Code Router를 사용하면 제공업체 선택, 프로토콜 변환, 라우팅을 처리하는 로컬 게이트웨이를 통해 Claude Code를 다른 모델에 연결할 수 있습니다. 이 가이드에서는 설치, 에이전트 프로필, 폴백, 그리고 2026년 17월 기준 v3.1.1에서 제공되는 OpenCode Go 통합을 다룹니다. 또한 호스팅형 게이트웨이를 사용하면 어떤 경우에 로컬 설정 단계를 줄일 수 있는지도 알아봅니다. 

## Claude Code Router의 기능 

흔히 CCR로 줄여 부르는 musistudio의 Claude Code Router는 스스로를 “코딩 에이전트용 로컬 모델 게이트웨이 및 제어 영역”으로 설명합니다. Claude Code와 다른 클라이언트에 안정적인 로컬 엔드포인트를 제공하며, 제공업체 인증 정보, 라우팅 규칙, 재시도, 순차 폴백, 요청 로그를 지원합니다. 

이 [v3.1.1 README](https://raw.githubusercontent.com/musistudio/claude-code-router/v3.1.1/README.md) OpenAI Chat 및 Responses, Anthropic Messages, Gemini Generate Content 및 Interactions 형식에 대한 지원을 명시합니다. 프로토콜 변환 덕분에 CCR을 통해 Claude Code를 다른 모델과 함께 실행할 수 있습니다. 

CCR은 MIT 라이선스로 제공되며, musistudio의 2025 저작권 표시와 함께 “있는 그대로” 제공됩니다. 소프트웨어 사용 권한이 있다고 해서 업스트림 추론이 무료가 되는 것은 아닙니다. 제공업체 요금과 사용 한도는 별도로 적용됩니다. 과거 제공업체 가격과 OpenCode Go의 달러 기준 사용 한도는 이 글의 게시일 기준으로 검증되지 않았습니다. 

### 관련 Claude Code Router 3.1 릴리스 

버전 3.1.1은 2026년 16월에 출시되었습니다. OpenCode Go 로컬 가져오기를 정식 지원하고, 실패한 개별 게이트웨이 시도를 표시하며, 라우팅된 모델의 사용량 요금 계산을 수정합니다. 

이 릴리스에서는 다음도 허용합니다. --daemon 적용 대상: start 및 serve, Docker UI의 로그 본문 워커를 수정하고, macOS Apple Silicon 및 Intel 빌드, Windows 설치 프로그램, Linux AppImage를 제공합니다. 아래 설정에서는 npm 배포본과 v3.1.1에 고정된 문서를 사용합니다. 

## CCR 설치 및 Claude Code 연결 

npm 배포본에는 Node.js 22 이상이 필요합니다. [버전이 고정된 CLI 가이드](https://raw.githubusercontent.com/musistudio/claude-code-router/v3.1.1/docs/src/content/docs/en/guides/cli.md) 에는 다음 명령어가 나와 있습니다. 

```
npm install -g @musistudio/claude-code-router
ccr --help
ccr ui

```

브라우저를 열지 않고 시작하려면: 

```
ccr ui --no-open

```

관리 인터페이스와 모델 게이트웨이는 서로 다른 기본 주소를 사용합니다. 

  | 구성 요소  | 기본 주소  | 용도    

  | 관리 UI  | http://127.0.0.1:3458  | 제공업체, 프로필, 라우팅 구성  

  | 모델 게이트웨이  | http://127.0.0.1:3456  | 클라이언트의 모델 요청 수신    

이러한 역할을 명확히 구분하면 연결이 어디에서 실패했는지 확인하는 데 도움이 됩니다. 관리 페이지가 정상적으로 작동한다는 사실만으로 모델 게이트웨이가 해당 구성을 수락했다고 볼 수는 없습니다. 

### 제공업체 및 클라이언트 키 추가 

열기 제공업체 → 제공업체 추가에서 사전 설정 또는 다음을 선택하세요. 기타 / 사용자 지정 API 엔드포인트, 그리고 엔드포인트와 API 키를 입력하세요. CCR은 프로토콜과 모델을 감지합니다. 고급 설정 에서는 프로토콜을 수동으로 선택할 수 있습니다. 

다음을 사용하세요: 연결 확인 으로 제공업체를 테스트하세요. 실제 요청을 전송하므로 토큰이나 제공업체의 요청 한도 일부를 소모할 수 있습니다. 

다음을 생성하세요. CCR 클라이언트 키 적용 대상: API 키 에서 모델 요청용 키를 생성하세요. 이 키는 관리 UI/RPC 토큰과 별개입니다. 클라이언트 접근과 관리 접근을 서로 다른 구성 항목으로 취급하세요. 

### Claude Code 프로필 생성 

다음에서: 에이전트 구성, 다음을 위한 활성화된 프로필을 생성하세요. Claude Code, 다음과 같은 모델을 선택하세요. Provider/model, 그리고 저장하세요. “Claude Code - Work”라는 프로필을 실행하려면 다음을 사용하세요. 

```
ccr "Claude Code - Work"

```

데스크톱에서 생성된 실행 명령어는 다음을 사용합니다. ccr-app. [Claude Code 프로필 가이드](https://raw.githubusercontent.com/musistudio/claude-code-router/v3.1.1/docs/src/content/docs/en/configuration/agents/claude-code.md) 에서는 적용 범위를 두 가지로 구분합니다.  
- CCR에서 실행할 때만 은 CCR을 통해 실행할 때 구성을 적용합니다. 
- 시스템 기본값 은 Claude Code를 직접 실행할 때도 영향을 줍니다.  

프로필은 Fable, Opus, Sonnet, Haiku의 재정의 설정을 지원합니다. 다음으로 현재 선택을 확인하세요. /model, 그런 다음 CCR의 다음 항목을 확인하세요. 요청 로그 에서 게이트웨이를 통과하는 요청을 확인하세요. 다음을 가까이 두세요. [Claude Code 모델 가이드](/ko/claude-code/models/) 해당 선택을 계획할 때 참고할 수 있도록 하세요. 

## 라우팅, 재시도, 폴백 구성 

CCR 라우팅 규칙은 다음을 검사할 수 있습니다. request.header 및 request.body, 또한 다음을 다시 작성할 수 있습니다. request.body.model. 이를 통해 에이전트 프로필에서 선택한 모델 외에도 수신 요청을 기준으로 모델 선택을 제어할 수 있습니다. 

폴백 구성은 다음을 사용합니다. mode, models및 retryCount. 세 가지 모드는 다음과 같습니다. off, retry및 model-chain. 

  | 동작  | 해당 응답  | 작동 방식    

  | 재시도  | 408, 409, 429, 및 5xx  | 재시도 대상인 실패가 발생하면 요청을 다시 시도합니다.  

  | 폴백 대상  | 모든 4xx 또는 5xx  | 요청을 구성된 다른 모델로 넘길 수 있습니다.  

  | 지연 처리  | 양수 값의 Retry-After, 있는 경우  | 제공된 재시도 지연 시간을 사용합니다.  

  | 기본 백오프  | 양수 값의 다음 항목이 없을 때: Retry-After 적용되는 경우  | 일 초부터 시작하며, 시도당 최대 30초로 제한됩니다.    

재시도 대상 조건과 폴백 대상 조건의 차이는 중요합니다. 재시도 조건을 충족하지 않는 응답도 폴백 대상 조건은 충족할 수 있습니다. 

### 실제로 요청을 처리한 모델 확인 

모델 체인은 최종적으로 요청을 처리하는 모델을 바꿀 수 있습니다. CCR 로그에는 최종 제공업체와 모델이 표시되므로, 예상치 못한 동작이나 사용량을 확인할 때 이 로그를 활용하세요. 

제공업체와 모델을 식별할 수 있는 프로필부터 시작하세요. 라우팅 규칙과 폴백 대상을 신중하게 추가한 다음, 이를 실행해 본 후 최종 대상을 확인하세요. 이렇게 하면 응답이나 비용 패턴의 변화를 라우팅 구성과 연결해 파악하기가 더 쉬워집니다. 

버전 3.1.1에서는 실패한 개별 게이트웨이 시도도 표시합니다. 이 기록은 최종적으로 성공한 응답과 그에 앞선 시도들을 구분하는 데 도움이 됩니다. 

## v3.1.1에서 OpenCode Go 가져오기 사용 

musistudio Claude Code Router v3.1.1 릴리스에서는 OpenCode Go 로컬 가져오기를 정식 지원합니다. 이 통합은 다음으로 식별되는 Zen을 구분합니다. opencode, 다음으로 식별되는 Go와 구분합니다. opencode-go, 각 인증 정보와 서로 겹치는 모델 ID까지 구분합니다. 

가져오기 도구는 OpenCode 구성, auth.json, 캐시된 모델 메타데이터를 읽습니다. OPENCODE_API_KEY 두 서비스 모두에 적용됩니다. OPENCODE_GO_API_KEY Go 전용 재정의 설정을 제공합니다. 검색 시 프로토콜별로 모델을 필터링하고 캐시된 메타데이터를 실시간 /models 결과와 대조하여 조정합니다. 

### 세션 헤더가 중요한 이유 

이 [OpenCode Go 통합 PR](https://github.com/musistudio/claude-code-router/pull/1786) 에는 다음 엔드포인트로 보내는 요청에 https://opencode.ai/zen/go/v1 다음 항목이 필요하다고 명시되어 있습니다. x-opencode-session이 항목이 없으면 엔드포인트는 다음을 반환합니다. 400 MissingSessionID. 

CCR은 명시적 설정, 명시적 클라이언트 헤더, Claude 세션 헤더, metadata.user_id, 마지막으로 프로세스 내에서 일관되게 유지되는 대체 값 순서로 세션 값을 선택합니다. 헤더 주입은 공식 Go 엔드포인트로 제한됩니다. 

따라서 Go에서는 엔드포인트와 인증 정보만 입력하는 것으로는 충분하지 않을 수 있습니다. 세션 요구 사항은 제공업체 통합의 일부입니다. 

### 검색 새로고침 및 사용량 한도 확인 

Go 가져오기를 사용할 수 없다면 OpenCode에서 OpenCode Go 를 연결하고 로컬 모델 캐시를 새로고침한 뒤 CCR에서 다시 검색하세요. 

CCR은 다음에서 사용량을 가져옵니다. GET https://opencode.ai/zen/go/v1/usage 그리고 다섯 시간, 주간, 월간 구간별 잔여 비율을 표시합니다. 고정된 문서에는 달러 기준 허용 한도가 명시되어 있지 않습니다. 이 값은 해당 구간의 잔여 비율로 해석해야 하며, 금액 잔액을 나타내지는 않습니다. 

## 단계별 연결 문제 해결 

CCR의 문제 해결 자료는 라우팅 우회, 인증 실패, 모델 누락, 예상치 못한 모델 선택, 비용 급증, 시간 초과, 에이전트 추적 누락을 다룹니다. 요청을 실행 설정부터 최종 제공업체까지 따라가며 진단하는 순서가 유용합니다. 

### Claude Code가 CCR을 우회하는 경우 

의도한 Agent Config 프로필이 활성화되어 있고 해당 프로필을 통해 실행했는지 확인하세요. 프로필을 다음으로 설정하면 CCR에서 실행할 때만 해당 설정은 CCR을 통한 실행에만 적용됩니다. 직접 실행에도 적용하려면 다음을 선택해야 합니다. 시스템 기본값 를 선택한 경우입니다. 

다음을 사용하세요: /model 와 CCR 요청 로그를 함께 확인하여 설정을 검증하세요. 다음 자료는 [Claude Code CLI 참조](/ko/claude-code/cli/) 클라이언트 사용에 관한 더 폭넓은 참고 자료를 제공합니다. 

### 인증 오류 또는 모델 누락 

401/403 오류가 발생하면 관련된 각 계층의 인증 정보를 검토하세요. 제공업체 API 키, 모델 요청용 CCR 클라이언트 키, 별도의 관리 토큰을 확인해야 합니다. 이러한 인증 정보는 각각 다른 역할을 합니다. 

다음의 경우 model not found에는 감지된 모델, 선택한 프로토콜, 프로필의 제공업체/모델 선택을 검토하세요. OpenCode Go에서 가져오기를 사용할 수 없다면 로컬 캐시를 새로고침하고 다시 검색하세요. 

### 시작 실패 및 시간 초과 

버전 3.1.1에서는 게이트웨이 설정 수락 대기 시간을 다섯 초에서 30초로 늘립니다. 이는 특히 Windows에서 호스트 부하로 인해 관리 UI는 시작되지만 게이트웨이는 실패하는 경우를 해결합니다. 

CCR_GATEWAY_CONFIG_TIMEOUT_MS 는 시간 제한을 재정의합니다. 잘못된 값이나 1,000밀리초 미만의 값은 기본값으로 대체됩니다. 

설정은 macOS/Linux에서는 다음 위치에 저장됩니다. ~/.claude-code-router 그리고 Windows에서는 %APPDATA%\claude-code-router 에 저장됩니다. 관련 파일에는 다음이 포함됩니다. config.sqlite, 생성된 gateway.config.json및 service.json. 서비스 명령에는 다음이 포함됩니다. ccr start, ccr stop, 그리고 포그라운드 실행용 ccr serve. 

## 호스팅형 게이트웨이가 더 간단한 경우 

CCR은 로컬 제공업체 관리, 요청 기반 라우팅, 인증 정보 풀 또는 명시적 폴백 체인이 필요한 워크플로에 적합합니다. 당장의 목표가 Claude Code를 업스트림 서비스에 연결하는 것이라면 호스팅형 게이트웨이를 통해 로컬 설정 단계를 줄일 수 있습니다. 

OpenRouter의 [2026년 8월 4일 발표](https://openrouter.ai/blog/announcements/ori-harness/) 에는 다음 연결 설정이 명시되어 있습니다. 

```
ANTHROPIC_BASE_URL=https://openrouter.ai/api
ANTHROPIC_AUTH_TOKEN=<openrouter-api-key>
ANTHROPIC_API_KEY=

```

이 발표에는 추가 모델 및 기능 설정도 명시되어 있습니다. 이 세 변수는 연결 설정이며, 모든 모델을 위한 완전한 설정은 아닙니다. OpenRouter는 대부분의 오픈 모델이 도구 검색을 지원하지 않으므로 모델마다 설정이 다르다고 주의를 줍니다. 

OpenRouter의 Ori CLI는 다음을 통해 설정을 자동화합니다. 

```
ori login
ori claude

```

같은 워크플로는 Anthropic이나 OpenAI와 제휴 관계가 없는 독립 서비스인 AI Prime Tech와 같은 API 게이트웨이를 통해서도 실행할 수 있습니다. 다음 가이드를 참조하세요. [API 키로 Claude Code 사용하기](/ko/learn/claude-code-api-key-setup/). 

필요한 제어 기능을 기준으로 선택하세요. CCR은 라우트를 관리하고, 시도 내역을 확인하고, 폴백을 설정할 수 있는 로컬 환경을 제공합니다. 문서에 설명된 호스팅형 접근 방식을 사용하면 CCR을 로컬에서 운영할 필요가 없습니다. 

## 핵심 요점  
- Claude Code Router는 프로토콜 변환을 지원하는 일관된 로컬 엔드포인트를 통해 Claude Code 및 다른 클라이언트를 제공업체에 연결합니다. 
- npm 배포판에는 Node.js 22 이상이 필요하며, 관리 UI와 모델 게이트웨이는 서로 다른 기본 포트를 사용합니다. 
- Agent Config 범위는 프로필을 CCR을 통한 실행에만 적용할지, 직접 실행에도 적용할지를 결정합니다. 
- 폴백으로 인해 요청을 처리하는 모델이 바뀔 수 있습니다. 최종 제공업체와 모델은 요청 로그에서 확인하세요. 
- v3.1.1에서는 별도의 인증 정보와 필수 세션 헤더 처리를 포함한 OpenCode Go 가져오기가 추가됩니다. 
- CCR의 로컬 라우팅 제어 기능이 필요하지 않다면 호스팅형 게이트웨이로 로컬 설정을 줄일 수 있습니다.  

## 자주 묻는 질문 

### Claude Code Router는 무료인가요? 

Claude Code Router는 MIT 라이선스에 따라 소프트웨어 사용이 허용됩니다. 그렇다고 업스트림 추론이 무료라는 의미는 아니며, 과거 제공업체 가격이나 OpenCode Go의 달러 기준 허용 한도는 여기서 검증하지 않았습니다. 

### CCR을 통해 Claude Code를 다른 모델과 함께 사용할 수 있나요? 

네. CCR은 프로토콜 변환과 제공업체/모델 선택 기능을 제공하며, Claude Code 프로필에서 다음과 같은 모델을 선택할 수 있습니다. Provider/model. 지원되는 업스트림 형식에는 OpenAI Chat/Responses, Anthropic Messages, Gemini Generate Content/Interactions가 포함됩니다. 

### Claude Code Router 3.1.1에서는 무엇이 달라졌나요? 

2026년 9월 16일에 출시된 v3.1.1에서는 OpenCode Go 로컬 가져오기를 정식으로 지원하고, 실패한 개별 시도를 확인할 수 있도록 하며, 라우팅된 모델의 사용 요금 계산을 수정했습니다. 또한 게이트웨이 설정 수락 대기 시간을 30초로 늘리고 다음을 허용합니다. --daemon 적용 대상: start 및 serve. 

### OpenCode Go가 MissingSessionID를 반환하는 이유는 무엇인가요? 

공식 OpenCode Go 엔드포인트에는 다음 x-opencode-session 헤더가 필요하며, 다음을 반환합니다. 400 MissingSessionID 해당 헤더가 없을 때 반환합니다. CCR의 Go 통합은 정의된 우선순위에 따라 세션 값을 선택하고 공식 Go 엔드포인트에만 헤더를 주입합니다. 

[Claude](/ko/blog/tag/claude/)[코딩](/ko/blog/tag/coding/)[오픈 소스](/ko/blog/tag/open-source/) 

A

[AI Prime Tech](https://aiprimetech.io/ko/)

이 블로그는 AI Prime Tech가 발행합니다. 기사는 AI의 도움을 받아 초안을 작성합니다. 모델 ID, 가격, 한도 등 버전별 세부 정보는 활용하기 전에 공식 문서와 대조해 확인하세요. 

 더 저렴하게 Claude API 이용하기 

API 키 하나로 Claude Opus 5.5, Sonnet 5, Haiku 4.5, Fable 5.1 및 GPT-6개 모델을 이용하세요. 구독 없이 사용한 만큼만 결제합니다. [API 키 받기 →](/register)  

AI Prime Tech는 독립적인 타사 API 게이트웨이입니다. Claude™ 및 Anthropic®는 Anthropic, PBC의 상표입니다. 제휴 또는 보증 관계를 의미하지 않습니다.