Claude Code Router란 무엇인가 / 어떻게 쓰나

먼저 결론입니다. Claude Code Router(CCR)는 Claude Code(와 비슷한 코딩 에이전트)가 보내는 요청을 중간에서 받아, 설정해 둔 provider와 모델로 나눠 보내 주는 로컬 라우터입니다. CCR을 쓰면 Claude Code의 작업 흐름은 그대로 두고, 뒤에서 응답하는 모델은 OpenRouter, DeepSeek, Gemini, 로컬 모델 등으로 바꾸거나 작업 종류별로 나눌 수 있습니다. 즉, 하나의 백엔드에 묶이지 않게 해 주는 도구입니다.

이 글은 CCR이 무엇이고 언제 필요한지, 설정을 어떤 개념으로 이해하면 되는지, 라우팅이 실제로 걸렸는지 어떻게 확인하는지를 다룹니다. 세부 옵션과 최신 명령어는 계속 바뀌므로, 정확한 값은 CCR GitHub 저장소의 README와 Claude Code 공식 문서를 기준으로 확인하시기 바랍니다.

Claude Code Router는 정확히 무엇인가요?

한 줄 답: Claude Code와 모델 API 사이에 서는 로컬 프록시이며, 요청을 받아 어떤 provider의 어떤 모델로 보낼지 결정하고 필요하면 요청 형식을 변환합니다.

Claude Code는 기본적으로 Anthropic API 형식으로 요청을 보냅니다. CCR은 로컬에서 서버를 띄우고, Claude Code가 Anthropic 대신 이 로컬 서버로 요청을 보내도록 연결합니다. 그러면 CCR이 요청을 받아 다음 두 가지 일을 합니다.

  • 라우팅: 이 요청을 어느 provider의 어느 모델로 보낼지 정합니다. 기본 작업, 백그라운드 작업, 긴 컨텍스트, 추론(think) 작업 등 요청 성격에 따라 다른 모델을 지정할 수 있습니다.
  • 변환(transformer): provider마다 API 형식과 지원 파라미터가 다르기 때문에, Anthropic 형식 요청을 각 provider가 받아들이는 형식으로 바꿔 줍니다.

그래서 Claude Code 쪽에서는 평소처럼 파일을 읽고, 명령을 실행하고, 코드를 고치는 흐름을 유지하면서 실제 응답은 다른 모델이 만들게 할 수 있습니다. CCR은 Anthropic의 공식 제품이 아니라 오픈소스 커뮤니티 프로젝트라는 점도 기억해 두시면 좋습니다.

언제 CCR이 필요할까요?

한 줄 답: 한 가지 모델·한 가지 결제 경로만으로는 부족할 때입니다.

다음 중 하나에 해당하면 CCR을 검토할 만합니다.

  • 여러 모델을 섞어 쓰고 싶을 때: 일상적인 편집은 저렴하고 빠른 모델로, 어려운 설계나 디버깅은 강한 추론 모델로 보내고 싶은 경우입니다.
  • OpenRouter나 다른 provider를 쓰고 싶을 때: 이미 OpenRouter, DeepSeek, Gemini 등의 API 키가 있고, Claude Code의 에이전트 흐름을 그 모델들로 돌려 보고 싶은 경우입니다.
  • 비용과 지연 시간을 조절하고 싶을 때: 백그라운드 작업처럼 품질보다 속도·비용이 중요한 요청을 가벼운 모델로 빼면 전체 비용과 대기 시간을 줄일 수 있습니다.
  • 긴 컨텍스트가 필요한 작업이 있을 때: 컨텍스트가 일정 길이를 넘으면 긴 컨텍스트를 지원하는 모델로 보내도록 나눌 수 있습니다.
  • 로컬 모델을 섞고 싶을 때: Ollama 같은 로컬 서버를 provider로 등록해 일부 요청만 로컬에서 처리할 수 있습니다.

반대로 Anthropic 구독이나 API 키 하나로 Claude 모델만 쓰고 있고 불편함이 없다면 CCR을 굳이 추가할 필요는 없습니다. 중간 계층이 하나 늘어나는 만큼 확인할 지점도 늘어나기 때문입니다.

기본 설정은 어떤 흐름으로 이해하면 될까요?

한 줄 답: “provider 등록 → 모델 지정 → 라우팅 규칙 → Claude Code를 CCR 경유로 실행 → 로그로 확인” 순서입니다.

설치와 실행 명령은 README에 정리되어 있습니다. 보통 npm으로 CCR을 전역 설치한 뒤, ccr code로 CCR을 거쳐 Claude Code를 실행하는 방식입니다. 설정을 바꾼 뒤에는 ccr restart로 서비스를 다시 띄워야 반영되고, 버전에 따라 ccr ui로 브라우저에서 설정을 편집할 수도 있습니다. 설치 명령과 플래그는 버전마다 달라질 수 있으니 README에 있는 그대로 사용하시기 바랍니다.

설정 파일(README 기준 ~/.claude-code-router/config.json)은 크게 두 부분으로 이해하면 됩니다.

1. Providers: 어떤 백엔드를 쓸 수 있는지

각 provider 항목에는 이름, API 엔드포인트 주소, API 키, 그 provider에서 쓸 모델 ID 목록, 필요한 transformer가 들어갑니다. 예를 들어 OpenRouter를 등록한다면 OpenRouter의 API 주소와 키, 그리고 OpenRouter에서 쓰는 모델 ID를 적고 OpenRouter용 transformer를 지정하는 식입니다.

여기서 중요한 점은 모델 ID를 provider가 실제로 쓰는 문자열 그대로 적어야 한다는 것입니다. 사람이 부르는 모델 이름이나 다른 provider에서 쓰는 ID를 적으면 요청이 실패합니다.

2. Router: 어떤 요청을 어디로 보낼지

Router 부분에서는 요청 종류별로 “provider 이름, 모델 ID” 조합을 지정합니다. README에는 기본(default), 백그라운드(background), 추론(think), 긴 컨텍스트(longContext) 같은 항목이 있습니다. 개념적으로는 다음처럼 생각하면 됩니다.

  • default: 대부분의 요청이 가는 기본 모델
  • background: 가볍고 반복적인 보조 요청을 보낼 저렴한 모델
  • think: 계획이나 추론이 많이 필요한 요청을 보낼 모델
  • longContext: 컨텍스트가 길어졌을 때 보낼 모델

모든 항목을 처음부터 채울 필요는 없습니다. 처음에는 default 하나만 지정해 동작을 확인하고, 필요해질 때 하나씩 나누는 편이 문제를 찾기 쉽습니다.

모델은 어떻게 고르면 될까요?

Claude Code는 파일 읽기, 명령 실행, 편집 같은 도구 호출(tool use)을 계속 사용합니다. 따라서 모델을 고를 때 가장 먼저 볼 것은 벤치마크 점수가 아니라 tool use를 안정적으로 지원하는지입니다. 일반 채팅은 잘 되는데 에이전트 작업 단계에서 멈추는 모델이 적지 않습니다.

그다음으로 컨텍스트 길이, 가격, 응답 속도를 보고 default와 background에 각각 어떤 모델을 둘지 정하면 됩니다. OpenRouter를 경유한다면 같은 모델이라도 뒤에서 응답하는 provider endpoint가 여러 개일 수 있으니, 모델 페이지에서 tools 지원 여부를 함께 확인해야 합니다.

라우팅이 실제로 걸렸는지는 어떻게 확인하나요?

설정을 저장했다고 해서 끝난 것이 아닙니다. 다음을 확인해야 합니다.

  1. 설정을 바꾼 뒤 ccr restart로 CCR을 다시 시작합니다.
  2. 설정에서 로그 옵션을 켜고, ccr code로 실행한 Claude Code에서 짧은 요청을 보냅니다.
  3. CCR 로그에서 요청이 어떤 provider와 모델로 나갔는지 확인합니다.
  4. 가능하면 provider 쪽 대시보드(예: OpenRouter의 사용 기록)에도 해당 요청이 찍혔는지 대조합니다.

“응답이 왔다”는 사실만으로는 의도한 모델이 응답했는지 알 수 없습니다. 로그와 provider 사용 기록이 일치하는지까지 보는 것이 확인의 기준입니다.

자주 틀리는 지점은 무엇인가요?

모델 ID 매핑이 틀림

가장 흔한 실수입니다. Router에 적은 모델 ID가 Providers의 모델 목록과 다르거나, provider가 실제로 쓰는 ID와 철자·버전·prefix가 다르면 404나 “모델 없음” 오류가 납니다. OpenRouter는 제공자/모델 형식을 쓰므로 prefix까지 정확히 맞아야 합니다. 모델 ID는 기억에 의존하지 말고 provider의 모델 페이지에서 복사해 붙이시기 바랍니다.

인증 환경 변수가 CCR에 전달되지 않음

API 키를 셸 환경 변수로 넣었는데 CCR 서비스가 다른 셸이나 백그라운드에서 떠 있어 그 값을 못 읽는 경우가 있습니다. 키를 설정 파일에 직접 넣었는지, 환경 변수를 참조하도록 했는지, 그 환경 변수가 CCR이 실행되는 환경에 실제로 있는지를 확인해야 합니다. 또 Claude Code 쪽에 남아 있는 기존 Anthropic 관련 환경 변수가 CCR 연결과 충돌하지 않는지도 봐야 합니다. 키를 바꾼 뒤에는 역시 ccr restart가 필요합니다.

IDE의 모델 선택기만 바꾸면 된다고 생각함

에디터나 IDE 확장의 모델 선택 메뉴에서 모델 이름을 바꾸는 것만으로는 CCR 라우팅이 바뀌지 않을 수 있습니다. 실제로 어떤 모델로 가는지는 CCR의 Router 설정과, Claude Code가 CCR을 경유해 실행되고 있는지에 달려 있습니다. Claude Code를 CCR 없이 직접 실행하고 있다면 CCR 설정을 아무리 바꿔도 반영되지 않습니다. README에는 Claude Code 안에서 /model 명령으로 provider와 모델을 바꾸는 방법도 나와 있지만, 이 역시 CCR을 거쳐 실행 중일 때만 의미가 있습니다.

설정을 바꾸고 재시작하지 않음

파일은 수정했는데 실행 중인 CCR은 이전 설정을 들고 있는 경우입니다. 결과가 이상하면 가장 먼저 ccr restart부터 해 보시기 바랍니다.

처음부터 규칙을 너무 많이 나눔

default, background, think, longContext를 한 번에 서로 다른 provider로 나누면, 문제가 생겼을 때 어느 경로가 원인인지 찾기 어렵습니다. 한 번에 한 경로씩 추가하는 편이 좋습니다.

OpenRouter 모델을 바꿨을 때 멈추거나 빈 응답이 나오는 구체적인 사례는 Claude Code Router OpenRouter, 다른 모델에서 멈추면 provider only를 의심해야 합니다에 따로 정리해 두었습니다.

여기서 시작하세요: 체크리스트

  • 정말 여러 모델이나 다른 provider가 필요한지 먼저 판단합니다.
  • CCR README의 설치 방법대로 설치합니다.
  • Providers에 provider 하나만 등록합니다. API 주소, 키, 모델 ID를 provider 문서에서 그대로 복사합니다.
  • 고른 모델이 tool use를 지원하는지 확인합니다.
  • Router에는 default 하나만 지정합니다.
  • ccr restart 후 ccr code로 Claude Code를 실행합니다.
  • 로그와 provider 사용 기록으로 요청이 의도한 모델로 갔는지 확인합니다.
  • 동작이 확인된 뒤에 background, think, longContext를 하나씩 추가합니다.

Cursor나 Claude Code 구독 경로를 알아보고 있다면 Gamsgo 허브도 참고하실 수 있습니다.