Claude Code 한도 뒤에도 계속 코딩하는 9Router 설정

공식 GitHub: https://github.com/decolua/9router
공식 사이트: https://9router.com/
공식 npm 패키지: https://www.npmjs.com/package/9router

Quick Start

STEP 1. 설치하고 실행하기: 3분

아래 명령어를 순서대로 복사해서 실행하세요.

node --version
npm --version
npm install -g 9router
9router

9Router npm 패키지는 Node.js 18 이상을 요구합니다. 설치 오류가 나면 Node.js 20 이상 LTS로 올린 뒤 다시 실행하세요.

브라우저가 자동으로 열리지 않으면 아래 주소를 직접 여세요.

http://localhost:20128/dashboard

확인 방법: 터미널에 Server: http://localhost:20128가 나오고 대시보드가 열리면 설치가 끝난 겁니다.

npm 설치부터 localhost 대시보드 실행까지의 터미널 화면

9Router는 Claude Code와 여러 LLM 공급자 사이에 놓이는 로컬 라우터입니다. Claude Code는 한 엔드포인트로만 요청하고, 9Router가 주 모델부터 무료 백업 모델까지 정해둔 순서대로 연결합니다.

Claude Code 요청이 9Router를 거쳐 주 모델과 무료 백업 모델로 넘어가는 전체 흐름

용어: Fallback은 앞 모델이 한도 초과나 공급자 오류로 응답하지 못할 때 같은 Combo의 다음 모델을 시도하는 방식입니다.

STEP 2. 대시보드 비밀번호 바꾸기: 2분

첫 로그인 비밀번호는 별도 설정이 없을 때 123456입니다. 로그인한 뒤 Profile → Security에서 바로 바꾸세요.

9Router는 공급자 OAuth 토큰과 API 키를 로컬 데이터베이스에 저장합니다. 처음에는 localhost에서만 사용하고 20128 포트를 인터넷에 그대로 열지 마세요.

확인 방법: 로그아웃한 뒤 새 비밀번호로 다시 로그인하세요.

STEP 3. 주 공급자와 무료 백업 공급자 연결하기: 5분

대시보드에서 Providers를 열고 아래 순서로 연결합니다.

기존 Claude Pro·Max 구독을 먼저 쓰려면 Claude Code를 연결하고 OAuth 로그인을 마칩니다.
무료 백업은 OpenCode Free 또는 Kiro AI를 연결합니다.
공급자 카드가 ACTIVE로 바뀌는지 확인합니다.

OpenCode Free는 공식 문서 기준으로 별도 인증 없이 현재 제공 모델을 자동으로 불러옵니다. Kiro AI는 화면에 나오는 AWS Builder ID, Google, GitHub 같은 로그인 방식 중 하나를 사용합니다.

Providers에서 주 공급자와 무료 백업 공급자의 활성 상태를 확인하는 화면

여기서 말하는 무료는 9Router 프로그램과 선택한 무료 공급자 경로에만 해당합니다. 9Router가 Claude 구독이나 유료 API를 무료로 바꾸는 건 아닙니다. 무료 모델과 할당량은 공급자 정책에 따라 바뀔 수 있으니 모델 선택 화면과 각 공급자 약관을 함께 확인하세요.

확인 방법: 연결한 공급자 카드가 활성 상태이고 모델 선택 창에 해당 공급자의 모델이 보이면 됩니다.

STEP 4. Claude Code용 로컬 API 키 만들기: 2분

대시보드의 Endpoint에서 API Keys를 열고 Create Key를 누릅니다. 이름은 아래처럼 정하면 알아보기 쉽습니다.

claude-local

생성된 키를 복사하세요. 이 키는 비밀번호처럼 다루고 GitHub, 캡처 화면, 공유 문서에 넣지 마세요.

확인 방법: API Keys 목록에 claude-local이 보이고 복사 버튼이 작동하면 됩니다.

STEP 5. Fallback Combo 만들기: 5분

Combos → Create Combo를 누르고 이름을 입력합니다.

claude-backup

Combo 이름에는 영문, 숫자, 마침표, 밑줄, 하이픈만 쓸 수 있습니다.

기존 Claude 구독을 먼저 쓰다가 무료 모델로 넘기려면 모델을 아래 순서로 넣으세요.

1. Claude Code 공급자의 현재 Sonnet 모델
2. Kiro AI의 현재 Claude 또는 GLM 코딩 모델
3. OpenCode Free에서 현재 제공되는 코딩 모델

공식 문서의 모델 ID 예시는 아래와 같습니다. 실제 선택 창에 없는 모델을 억지로 직접 입력하지 말고 현재 표시되는 모델을 고르세요.

1. cc/claude-sonnet-4-6
2. kr/claude-sonnet-4.5
3. kr/glm-5
4. oc/로 시작하는 현재 OpenCode Free 코딩 모델

Combo를 만든 뒤 전략을 Fallback — try in order로 선택하세요.

Fallback: 위에서 아래로 시도합니다. 이번 설정에 맞습니다.
Round Robin: 요청마다 시작 모델을 돌려 씁니다. 한도 소진 뒤에만 바꾸려는 목적과 다릅니다.
Fusion: 여러 모델을 동시에 호출하고 판정 모델이 답을 합칩니다. 호출량이 늘어나므로 무료 백업용 설정이 아닙니다.

Fallback과 Round Robin의 차이를 보여주는 O·X 비교

claude-backup Combo의 모델 우선순위와 Fallback 전략 설정 예시

확인 방법: claude-backup 카드에 모델 순서가 그대로 보이고 전략이 Fallback으로 표시돼야 합니다.

STEP 6. Claude Code 설치하기: 3분

Claude Code가 아직 없다면 공식 npm 패키지를 설치합니다.

npm install -g @anthropic-ai/claude-code
claude --version

확인 방법: Claude Code 버전 번호가 출력되면 준비가 끝난 겁니다.

STEP 7. Claude Code를 Combo에 연결하기: 5분

대시보드에서 CLI Tools → Claude Code를 열고 아래처럼 설정합니다.

Select Endpoint에서 http://localhost:20128/v1을 고릅니다.
API Key에서 STEP 4의 claude-local을 고릅니다.
화면에 보이는 Claude 모델 매핑을 모두 claude-backup으로 지정합니다.
Apply를 누릅니다.

Claude Code의 Endpoint와 API Key, 모델 매핑을 Combo에 연결하는 화면

9Router는 이 설정을 ~/.claude/settings.json의 env에 합쳐 저장합니다. 기존 설정이 중요하다면 Apply 전에 먼저 백업하세요.

cp ~/.claude/settings.json ~/.claude/settings.json.backup

대시보드 자동 적용이 안 될 때만 아래 형식을 직접 저장합니다. <대시보드에서 만든 API 키>는 실제 키로 바꾸되, 완성된 파일은 외부에 공유하지 마세요.

{
  "hasCompletedOnboarding": true,
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:20128/v1",
    "ANTHROPIC_AUTH_TOKEN": "<대시보드에서 만든 API 키>",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-backup",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-backup",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-backup"
  }
}

기존 settings.json에 다른 항목이 있다면 파일 전체를 교체하지 말고 env 안에 위 항목만 합치세요.

확인 방법: Claude Code 카드에 Connected가 표시되고 현재 Endpoint가 /v1로 끝나야 합니다.

STEP 8. 연결과 Fallback을 실제로 확인하기: 3분

9Router가 실행 중인 터미널은 그대로 두고 새 터미널에서 Claude Code를 시작합니다.

claude

아래 문장을 복사해 보내세요.

현재 폴더의 파일은 수정하지 말고 “9Router 연결 성공”이라고 한 줄만 답해주세요.

응답이 오면 9Router 대시보드의 Usage에서 사용된 공급자와 모델을 확인합니다.

Fallback까지 확인하려면 Providers에서 주 공급자만 잠시 비활성화하고 같은 요청을 한 번 더 보내세요. Usage에 Combo의 다음 무료 모델이 기록되면 순서가 제대로 작동한 겁니다. 테스트가 끝나면 주 공급자를 다시 활성화하세요.

Claude Code 성공 응답과 Usage의 실제 라우팅 기록 예시

확인 방법: Claude Code 응답과 Usage 기록이 모두 생기고, 주 공급자를 껐을 때 다음 모델이 선택돼야 합니다.

STEP 9. 업데이트하고 다시 실행하기: 1분

최신 npm 배포판으로 올릴 때는 아래 명령어를 실행합니다.

npm install -g 9router@latest

브라우저를 자동으로 열지 않고 실행하려면 아래 옵션을 사용하세요.

9router --no-browser

9Router를 끄려면 실행 중인 터미널에서 Ctrl+C를 누릅니다. 로컬 9Router가 꺼지면 Claude Code도 localhost:20128에 연결할 수 없습니다.

한도가 끝났을 때 무슨 일이 생기나요?

Claude Code는 http://localhost:20128/v1 한 곳으로 요청합니다. claude-backup Combo의 첫 모델이 한도 초과나 공급자 오류를 반환하면 9Router가 다음 모델을 시도합니다. 성공한 공급자와 모델은 Usage에 기록됩니다.

Claude Code 프로세스와 로컬 대화는 그대로 유지됩니다. 다만 요청을 처리하는 모델이 바뀌면 답변 품질, 도구 호출 방식, 지원 기능은 달라질 수 있습니다.

무료 경로를 고를 때 보는 표

경로	비용 판단
9Router 프로그램	MIT 오픈소스, 무료
OpenCode Free	공식 문서상 인증 없는 무료 경로, 제공 모델은 변동 가능
Kiro AI의 `kr/` 모델	공식 문서상 무료 경로, 실제 할당량과 약관은 공급자 정책 확인
Claude Code의 `cc/` 모델	Claude Pro·Max 같은 기존 구독 필요
GLM의 `glm/` 모델	직접 API 키와 과금 조건 확인
Kimi의 `kimi/` 모델	직접 API 키와 요금제 확인
Vertex AI	신규 계정 크레딧 조건과 만료 시점 확인

무료 모델 이름을 외우는 것보다 대시보드에서 지금 활성화된 공급자와 모델을 확인하는 게 정확합니다.

문제 해결

`9router: command not found`

전역 설치 위치와 패키지 설치 여부를 확인합니다.

npm prefix -g
npm list -g 9router --depth=0

목록에 없다면 다시 설치하세요.

npm install -g 9router

전역 명령 경로 문제를 건너뛰고 바로 실행하려면 아래 명령어도 쓸 수 있습니다.

npx 9router

대시보드가 열리지 않음

9Router가 실행 중인지 확인하고 주소를 직접 여세요.

http://localhost:20128/dashboard

다른 포트를 쓰려면 실행할 때 지정합니다.

9router --port 8080

이 경우 Claude Code Endpoint도 http://localhost:8080/v1로 바꿔야 합니다.

Claude Code에서 401 오류가 남

~/.claude/settings.json의 ANTHROPIC_AUTH_TOKEN이 대시보드에서 만든 API 키와 같은지 확인하세요. 키 앞뒤 공백도 지웁니다.

모델을 찾을 수 없다는 오류가 남

Combo에 저장한 모델이 현재 공급자의 모델 목록에 있는지 확인하세요. 무료 공급자 모델은 바뀔 수 있으므로 예전 ID를 직접 입력하기보다 모델 선택 창에서 다시 고르는 편이 빠릅니다.

한도가 끝났는데 무료 모델로 안 넘어감

Combo 전략이 Fallback인지 확인합니다.
Claude 모델 매핑이 단일 모델이 아니라 claude-backup인지 확인합니다.
다음 순서의 공급자 카드가 ACTIVE인지 확인합니다.
Usage에서 첫 모델의 오류와 실제 선택 모델을 확인합니다.

OAuth 연결이 만료됨

Providers에서 해당 공급자를 열고 Reconnect를 실행하세요. 자동 갱신이 실패하거나 공급자가 재로그인을 요구하면 직접 인증해야 합니다.

Usage에 비용이 표시됨

Usage의 비용은 비교용 추정치일 수 있습니다. 실제 청구 여부는 연결한 공급자 계정에서 확인하세요. 무료 경로가 아닌 glm/, kimi/ 같은 직접 API 모델을 넣었다면 공급자 요금이 발생할 수 있습니다.

FAQ

9Router를 설치하면 Claude 구독이 무료가 되나요?

아닙니다. 9Router 자체는 무료지만 기존 Claude 구독이나 유료 API의 비용을 없애주지는 않습니다. Combo에 무료 공급자 모델을 넣었을 때 그 경로만 무료로 사용할 수 있습니다.

Claude 한도가 끝나면 작업 내용이 사라지나요?

Claude Code 프로세스와 로컬 대화는 그대로 남습니다. 다음 모델이 같은 대화 문맥을 받아 처리하지만 모델 특성에 따라 결과는 달라질 수 있습니다.

9Router 터미널을 닫아도 되나요?

안 됩니다. 로컬 서버가 실행 중이어야 Claude Code가 9Router Endpoint에 연결됩니다. 장시간 실행하려면 공식 Docker 문서를 참고하세요.

공급자 키는 어디에 저장되나요?

현재 npm 배포판 기준 macOS와 Linux의 기본 데이터베이스 경로는 ~/.9router/db/data.sqlite입니다. 이 파일과 백업본을 공개 저장소나 공유 폴더에 올리지 마세요.

모든 오류를 무료 모델이 해결하나요?

아닙니다. Fallback은 다음 모델을 시도해 중단을 줄여주지만, 잘못된 API 키, 깨진 설정, 지원하지 않는 도구 호출처럼 원인을 직접 고쳐야 하는 오류도 있습니다. 첫 설정 뒤에는 반드시 Usage 기록으로 실제 경로를 확인하세요.

공식 문서

설치와 기능: https://github.com/decolua/9router#-quick-start
npm 패키지와 CLI 옵션: https://www.npmjs.com/package/9router
Docker 실행: https://github.com/decolua/9router/blob/master/DOCKER.md
공식 사이트: https://9router.com/
문제 신고: https://github.com/decolua/9router/issues