Claude Code Router 3.1.1 설치·라우팅·오류 해결 가이드

Claude Code에서 DeepSeek, OpenRouter, Gemini, Kimi, Z.AI/GLM 또는 다른 compatible endpoint를 쓰고 싶은데, 찾은 문서는 여전히 config.json과 ccr code를 안내할 수 있습니다. 또는 UI는 열리지만 127.0.0.1:3456 gateway가 시작되지 않을 수 있습니다. 이 글은 현재 3.1.1 흐름을 기준으로 설치부터 검증된 Claude Code Profile까지 진행하고, 자주 생기는 실패를 계층별로 나눠 해결합니다.

먼저 버전을 확인하세요: 3.1.1은 수동 config.json 중심이 아닙니다

현재는 오래된 JSON 블록을 복사하지 말고 Web UI에서 Provider, Routing, Agent Profiles를 설정해야 합니다. 2026년 9월 26일 기준 npm의 latest는 3.1.1입니다. 현재 패키지는 주요 설정을 config.sqlite에 저장하고 실행 중인 gateway용 gateway.config.json을 생성합니다. 이는 npm registry metadata와 현재 프로젝트 README에서 확인할 수 있습니다.

이 버전 차이를 알면 두 가지 흔한 막힘도 이해할 수 있습니다. 현재 CLI 문서는 ccr <profile-name-or-id>로 Agent를 실행하며 ccr code를 목록에 두지 않습니다. gateway.config.json도 생성 파일이므로 수동으로 유지할 설정 원본이 아닙니다. config.json이나 ccr code를 요구하는 가이드를 보면 PATH 문제로 판단하기 전에 어떤 CCR 세대를 대상으로 했는지 확인하세요.

Node.js, upstream Provider, Claude Code를 준비하세요

Node.js 22 이상, 사용할 모델 Provider, 로컬에 설치된 Claude Code가 필요합니다. CCR은 요청을 라우팅하지만 Claude Code 자체를 설치하지 않습니다. API access도 Claude.ai 또는 Claude Max 구독과 같은 상품이 아닙니다.

먼저 Node.js를 확인합니다.

node --version

Major version이 22보다 낮으면 먼저 업데이트하세요. Upstream은 OpenRouter, DeepSeek, Gemini, Moonshot/Kimi, Z.AI 같은 built-in preset을 쓰거나 지원되는 OpenAI-compatible 또는 Anthropic-compatible protocol을 구현한 custom endpoint를 추가할 수 있습니다.

npm CLI를 설치하고 설정 전에 명령을 검증하세요

Global install 직후 help 명령부터 실행하세요. 그러면 npm 또는 PATH 문제와 Provider 또는 Routing 문제를 분리할 수 있습니다.

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

업데이트와 삭제 명령은 다음과 같습니다.

npm install -g @musistudio/claude-code-router@latest
npm uninstall -g @musistudio/claude-code-router

npm 패키지를 삭제해도 로컬 설정과 데이터베이스는 자동으로 지워지지 않습니다. Data directory는 macOS/Linux에서 ~/.claude-code-router, Windows에서 %APPDATA%\claude-code-router입니다.

Provider → Check Connection → Client Key → Routing → Server → Profile → end-to-end test 순서로 설정하세요

조건이나 fallback을 추가하기 전에 하나의 default route부터 성공시키세요. 여러 Provider, rewrites, retries, fallbacks를 한꺼번에 설정하면 401, 잘못된 Model ID, protocol mismatch를 구분하기 어렵습니다.

관리 UI를 엽니다.

ccr ui

Management UI 기본값은 http://127.0.0.1:3458, model gateway 기본값은 http://127.0.0.1:3456입니다. CCR이 출력하거나 자동으로 연 인증 URL을 사용하세요. 3458이 사용 중이면 CCR이 다음 관리 포트를 선택하고 실제 주소를 표시할 수 있습니다.

1. Providers에서 upstream을 추가하세요

Preset이 있으면 우선 사용하고, 필요할 때만 custom endpoint를 선택하세요. Providers → Add Provider에서 서비스를 선택하고, 그 Provider의 API Key, 올바른 protocol, 계정에서 실제 사용할 수 있는 Model ID를 입력합니다.

모델의 마케팅 이름만 보고 protocol을 추측하지 마세요. Anthropic Messages, OpenAI Chat/Responses, Gemini는 요청 형식이 다릅니다. Base URL, protocol, Model ID는 upstream의 현재 문서와 일치해야 합니다.

Provider를 저장한 뒤 Check Connection을 실행하세요. 이는 upstream 설정만 확인하며 Claude Code → CCR gateway → Routing → Provider 전체 경로를 검증하지는 않습니다.

2. API Keys에서 CCR client key를 만드세요

CCR client key와 management token은 서로 다른 자격 증명입니다. Management token은 Web UI와 RPC API를 보호하고, client key는 Claude Code가 gateway로 보내는 모델 요청을 인증합니다. ccr_web_token이 포함된 관리 URL은 비밀번호처럼 다루고 로그, 티켓, 채팅에 붙여 넣지 마세요.

3. 조건과 fallback 전에 default route를 만드세요

Check Connection을 통과한 Provider 하나와 그 Provider의 model 하나만 default route로 지정하세요. Route를 저장하되 아직 Claude Code request는 보내지 말고, 먼저 gateway를 시작하고 Agent Profile을 만드세요.

6단계의 end-to-end request가 성공한 뒤에만 Routing에서 conditions, retries, request rewrites, ordered fallback을 추가하세요. 한 번에 하나의 동작만 더하고 다시 검증합니다. Fallback model도 작업에 필요한 tools, context, protocol을 지원해야 합니다. 둘 다 대화형 모델이라는 이유만으로 서로 대체할 수는 없습니다.

4. Server에서 gateway를 시작하고 확인하세요

UI가 열렸다고 해서 3456 gateway를 사용할 수 있는 것은 아닙니다. Server에서 gateway를 시작하고 표시된 client-facing URL을 기록하세요. 기본값은 http://127.0.0.1:3456이며, CCR이 보여 주는 실제 URL을 사용해야 합니다. 시작에 실패하면 foreground mode로 오류를 확인합니다.

ccr serve

Foreground 출력은 포트 충돌, 불완전한 Provider, 누락된 모델, 로컬 파일 권한 문제를 구분하는 데 도움이 됩니다.

5. Claude Code용 Agent Profile을 만들고 활성화하세요

현재 CLI는 활성화된 Agent Profile을 통해 Claude Code를 시작합니다. Agent Profiles에서 Claude Code Profile을 만들고, Check Connection을 통과한 Provider의 default route에 사용되는 model을 선택한 뒤 저장하고 활성화합니다. CCR mode에서 Claude Code는 Server에 표시된 CCR gateway(기본값 http://127.0.0.1:3456)에 연결하며 upstream Provider URL에 직접 연결하지 않습니다. Profile 이름은 자유롭게 정할 수 있으며 Claude - Review 같은 이름을 사용할 수 있습니다.

이름 또는 ID로 실행합니다.

ccr "Claude - Review"

Claude Code 전용 인수는 -- 뒤에 두어 CCR option으로 해석되지 않게 합니다.

ccr "Claude - Review" cli -- --model sonnet

Claude - Review는 실제로 만든 Profile 이름 또는 ID로 바꾸세요.

6. Claude Code에서 request를 보내고 Logs를 확인하세요

이제 첫 실제 end-to-end test를 수행합니다. 실행한 Profile에서 Claude Code로 간단한 request를 보낸 다음 Logs에서 의도한 Provider와 model이 선택되고 성공 status가 기록됐는지 확인하세요.

Provider의 Check Connection은 upstream 연결만 확인합니다. 실제 request는 CCR client key, gateway, Routing, Agent Profile, model call까지 함께 검증합니다.

ccr start, ui, serve, stop의 역할을 구분하세요

평소에는 ccr ui 또는 ccr start, 진단할 때는 ccr serve를 사용하세요.

명령	적합한 상황	동작
ccr start	지속적인 background 사용	Detached 관리 서비스와 gateway를 시작하고 인증된 관리 URL을 출력
ccr ui	로컬 대화형 설정	기존 background service를 재사용하거나 시작한 뒤 UI를 엶
ccr serve	Troubleshooting 또는 process supervisor	Foreground에서 실행되어 시작·요청 오류를 계속 표시하며 ccr web은 alias
ccr stop	Background 설정 재생성	start 또는 ui로 시작한 detached service를 중지

start, ui, serve는 --host, --port, --open/--no-open, --gateway/--no-gateway를 지원합니다. 여기서 --port는 선호하는 management port이며 model gateway의 3456을 자동으로 의미하지 않습니다.

“ccr: command not found”는 Node와 npm global bin부터 확인하세요

반복해서 재설치하기 전에 runtime과 global prefix를 검증하세요.

node --version
npm prefix -g

Node.js가 22 이상인지 확인하고 npm의 global executable directory가 현재 shell의 PATH에 있는지 확인합니다. 일부 shell은 command location을 cache하므로 설치 후 새 terminal을 여세요.

Desktop app도 설치했다면 관련 명령 ccr-app이 생깁니다. 여기서 설명하는 npm 패키지는 ccr을 설치합니다. ccr-app이 있다고 해서 npm CLI가 PATH에 있다는 뜻은 아닙니다.

127.0.0.1:3456에서 listen하지 않는 gateway를 해결하세요

Gateway가 시작되지 않은 것인지, 다른 process가 포트를 소유한 것인지 먼저 구분하세요. 3458의 UI가 정상이라고 3456도 정상인 것은 아닙니다.

macOS/Linux에서는 다음을 실행합니다.

lsof -nP -iTCP:3456 -sTCP:LISTEN

Windows에서는 다음을 사용합니다.

netstat -ano | findstr :3456

오래된 CCR process나 다른 프로그램이 포트를 사용한다면 중지하기 전에 PID를 확인하세요. 이후 ccr serve를 실행하고 Server로 돌아가 Provider, model, client key가 있는지 확인한 뒤 gateway를 다시 시작합니다.

401, model not found, protocol error는 세 가지 매핑으로 해결하세요

Credentials, protocol, Model ID 순서로 확인하세요. Management token을 client key로 사용하거나, CCR client key를 upstream Provider에 넣거나, Anthropic-compatible endpoint를 OpenAI-compatible route로 호출하는 실수가 흔합니다.

다음 순서로 점검합니다.

1. Claude Code는 ccr_web_token이 아니라 CCR client key로 CCR에 인증합니다.
2. Provider entry에는 upstream service 자체의 API Key를 저장합니다.
3. 선택한 protocol이 endpoint와 일치합니다.
4. Routing한 Model ID가 해당 Provider와 계정에서 실제로 제공됩니다.
5. Logs가 의도한 Provider와 model로 resolve됩니다.

Claude Code의 마지막 오류만 보지 마세요. CCR Logs는 실패가 client authentication, route resolution, upstream authentication, model request 중 어디에서 발생했는지 보여줄 수 있습니다.

Profile을 찾지 못하거나 background service가 이전 option을 쓸 때 해결하세요

활성화된 Agent Profiles만 실행할 수 있습니다. 이름 비교는 대소문자를 구분하지 않고 정규화된 이름도 허용하지만, 모호한 이름은 Profile ID가 필요합니다. 생성 launcher가 없다면 Profile을 다시 저장하세요.

재사용 중인 background process는 새로운 host, port, gateway option을 자동 적용하지 않습니다. 중지한 뒤 다시 만드세요.

ccr stop
ccr start --host 127.0.0.1 --port 3458

명령이 성공해 보이는데도 서비스가 이전 설정을 계속 쓰는 이유가 이것입니다.

Endpoint가 하나뿐이면 ANTHROPIC_BASE_URL 직접 연결이 더 간단합니다

Anthropic-compatible Endpoint 하나, 주력 모델 하나만 쓰고 conditional routing, fallback, 공통 Logs, 여러 Profile이 필요 없다면 직접 연결이 보통 더 짧습니다. Provider의 Claude Code 문서에 따라 ANTHROPIC_BASE_URL, 인증 변수, model mapping을 설정하면 local gateway를 추가할 필요가 없습니다.

다음 중 하나라도 해당하면 CCR이 더 적합합니다.

• DeepSeek, OpenRouter, Gemini, Kimi, Z.AI, custom endpoints 사이를 전환합니다.
• 작업이나 Profile마다 다른 모델을 써야 합니다.
• retries, 조건 Routing, rewrites, ordered fallback이 필요합니다.
• 실제 route, status, tokens, latency, errors를 한 곳에서 보고 싶습니다.
• 여러 client가 하나의 local gateway를 공유해야 합니다.

상황	우선 선택
안정적인 Anthropic-compatible Endpoint 하나	직접 ANTHROPIC_BASE_URL
여러 Provider, model, Profile	CCR
각 request의 route를 확인해야 함	CCR
한 서비스에 가장 빨리 연결하려 함	직접 연결로 시작하고 workflow가 커지면 CCR로 이동

Compatible endpoint 예시: CCR에 BetterToken 추가하기

BetterToken은 custom Anthropic-compatible Provider의 한 예시이며 유일한 답은 아닙니다. CCR Providers에서 https://bettertoken.ai를 upstream API endpoint/Base URL field에 입력하세요. 이는 Claude Code Base URL이 아니며 /v1을 붙이지 않습니다. Protocol은 명시적으로 Anthropic Messages를 선택하고 자신의 BetterToken API Key와 사용 가능한 Model ID를 입력한 뒤 Provider를 저장하고 Check Connection을 실행하세요.

CCR을 사용할 때 Claude Code는 Server에 표시된 CCR gateway(일반적으로 http://127.0.0.1:3456)에 연결합니다. Agent Profile을 실행해 request를 보낸 뒤 Logs에서 의도한 BetterToken model로 route됐는지 확인하세요. 이 mode에서 Claude Code를 https://bettertoken.ai에 직접 연결하면 CCR을 우회하게 됩니다.

CCR을 의도적으로 생략하고 이 단일 Endpoint에 직접 연결할 때만 BetterToken Claude Code 문서에 따라 macOS/Linux에서 Base URL을 설정하세요.

export ANTHROPIC_BASE_URL="https://bettertoken.ai"

PowerShell에서는 다음과 같습니다.

$env:ANTHROPIC_BASE_URL="https://bettertoken.ai"

이 direct mode에서도 인증 변수와 model mapping은 현재 문서에서 가져와야 합니다. Claude Code에 OpenAI-compatible Base URL인 https://www.bettertoken.ai/v1을 재사용하지 마세요.

로컬 자격 증명을 보호하고 안전하게 백업하세요

원격 접근이 의도된 경우가 아니라면 management listener를 127.0.0.1에 유지하세요. 원격 접근에는 firewall 또는 private network와 신뢰할 수 있는 reverse proxy의 TLS를 사용합니다. CCR client keys 없이 gateway를 외부 네트워크에 노출하지 마세요.

Upstream credentials, logs, runtime databases는 CCR의 local data directory에 있습니다. CCR이 쓰는 중에는 config.sqlite를 수정하거나 복사하지 마세요. UI export를 사용하거나 filesystem backup 전에 CCR을 중지합니다.

UI만 보지 말고 전체 request 경로를 검증하세요

성공은 Claude Code request가 의도한 route를 거쳐 정상 응답을 받은 상태입니다. 다음을 확인하세요.

• node --version이 22 이상을 표시합니다.
• ccr --help가 실행됩니다.
• Providers에 Check Connection을 통과한 upstream이 하나 이상 있습니다.
• API Keys에 CCR client key가 있습니다.
• Server가 실행 중인 gateway와 client-facing URL(기본값 http://127.0.0.1:3456)을 표시합니다.
• Agent Profile이 저장되고 활성화되었습니다.
• ccr <profile-name-or-id>가 Claude Code를 시작합니다.
• Claude Code에서 실제 request를 보냈고 Logs가 의도한 Provider, model, 성공 status를 보여 줍니다.
• 새 route나 fallback을 추가할 때마다 다시 검증했습니다.

이 순서를 따르면 installation, authentication, Routing, Agent 실행을 별도 계층으로 유지할 수 있습니다. 문제가 생겨도 CCR을 재설치하거나 오래된 config.json을 임의로 수정하지 않고 원인이 있는 계층만 고칠 수 있습니다.