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

Claude Code자동화읽는 데 10분2026-08-06 갱신

Quick Start

Claude Code 한도가 끝날 때마다 도구를 닫고 모델을 바꾸지 않아도 됩니다. 9Router에 주 모델과 백업 모델을 순서대로 묶어두면 한도 초과나 라우팅 가능한 오류가 생겼을 때 다음 모델로 요청을 넘깁니다.

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

STEP 1. 9Router 설치: 3분

9Router CLI는 Node.js 18 이상에서 실행됩니다. 먼저 버전을 확인하세요.

node --version
npm --version

Node.js가 준비돼 있다면 9Router를 전역 설치하고 바로 실행합니다.

npm install -g 9router
9router

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

http://localhost:20128/dashboard

확인 방법: 터미널에 서버 주소가 표시되고 대시보드에 Providers, Combos, CLI Tools 메뉴가 보이면 설치가 끝난 겁니다.

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

STEP 2. 로컬 대시보드 잠그기: 2분

로그인 화면이 나오면 초기 비밀번호로 접속한 뒤 Profile → Security에서 바로 바꾸세요. 별도 설정이 없을 때 공식 문서에 적힌 초기 비밀번호는 123456입니다.

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

확인 방법: 비밀번호를 바꾼 뒤 새 비밀번호로 다시 로그인됩니다.

STEP 3. 백업 공급자 연결: 5분

대시보드에서 Providers를 열고 백업으로 쓸 공급자를 연결합니다.

  • 가장 빠른 시작: OpenCode Free를 연결합니다. 공식 문서 기준으로 별도 인증이 없고 모델 목록을 자동으로 가져옵니다.
  • Claude 계열 무료 백업: Kiro AI를 연결합니다. 화면에 나오는 AWS Builder ID, Google, GitHub 같은 로그인 방식 중 하나를 고릅니다.
  • 기존 Claude 구독을 먼저 쓰려면 Claude Code도 연결하고 OAuth 로그인을 마칩니다.

무료라는 말은 9Router 자체와 선택한 무료 공급자 경로에만 해당합니다. 9Router가 유료 API를 무료로 바꾸지는 않습니다. 공식 문서 기준으로 glm/ 직접 연결과 kimi/ 직접 연결은 유료 백업이고, 무료 GLM 예시는 Kiro 경로인 kr/glm-5입니다. Gemini 무료 제공 여부도 공급자 정책에 따라 달라지므로 대시보드에 실제로 표시되는 연결 상태와 할당량을 확인하세요.

확인 방법: 연결한 공급자 카드가 활성 상태로 바뀌고 모델 선택 창에 해당 모델이 나타납니다.

Providers에서 OpenCode Free와 Kiro AI의 연결 상태를 확인하는 화면 예시

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

Endpoint 메뉴의 API Keys에서 Create Key를 누릅니다. 이름은 알아보기 쉽게 정하세요.

claude-local

생성된 키를 복사합니다. 이 키는 비밀번호처럼 다루고 문서나 공개 저장소에 넣지 마세요.

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

STEP 5. Fallback Combo 만들기: 5분

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

claude-backup

기존 Claude 구독을 먼저 쓰고 무료 백업으로 넘길 때는 모델을 아래 순서로 넣습니다.

1. cc/claude-sonnet-4-6
2. kr/claude-sonnet-4.5
3. kr/glm-5
4. OpenCode Free에서 현재 제공되는 코딩 모델

cc/claude-sonnet-4-6이 모델 선택 창에 없으면 cc/로 시작하는 현재 Sonnet 모델을 고르세요. OpenCode Free 모델 ID는 자동으로 바뀔 수 있으니 직접 입력하지 말고 선택 창에서 고르는 편이 안전합니다.

Claude 구독 없이 무료 공급자만 쓰려면 첫 번째 cc/ 모델을 빼고 Kiro 또는 OpenCode Free 모델부터 넣습니다.

전략은 Fallback — try in order를 선택하세요. Round Robin은 요청마다 모델을 돌려 쓰는 방식이라 한도 소진 뒤에만 바꾸려는 목적과 다릅니다. Fusion은 여러 모델과 판정 모델을 한 번에 호출하므로 무료 백업용 설정이 아닙니다.

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

한도 뒤에만 다음 모델로 넘기는 Fallback과 매 요청마다 모델을 바꾸는 Round Robin 비교

claude-backup Combo에서 Fallback 전략과 모델 순서를 설정하는 화면 예시

STEP 6. Claude Code 설치: 3분

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

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

확인 방법: 버전 번호가 출력되면 준비가 끝났습니다.

STEP 7. Claude Code를 9Router에 연결: 5분

대시보드에서 CLI Tools → Claude Code를 엽니다.

  • Endpoint는 http://localhost:20128/v1을 고릅니다.
  • API Key는 STEP 4에서 만든 claude-local을 고릅니다.
  • Sonnet, Opus, Haiku 모델 매핑은 모두 claude-backup을 고릅니다.
  • 마지막으로 Apply를 누릅니다.

적용하면 9Router가 ~/.claude/settings.json의 기존 값을 읽고 9Router 연결 항목을 합쳐 저장합니다. 원래 설정을 별도 파일로 복사해두고 싶다면 Apply를 누르기 전에 직접 백업하세요. 대시보드에서 자동 적용이 안 될 때만 아래 형식으로 직접 저장합니다.

{
  "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"
  }
}

확인 방법: Claude Code 카드에 Connected와 현재 Endpoint가 표시됩니다.

Claude Code의 Endpoint와 API Key, Sonnet Opus Haiku 모델을 Combo에 매핑하는 화면 예시

STEP 8. 연결 테스트: 2분

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

claude

아래 문장을 복사해 보냅니다.

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

응답이 오면 대시보드의 Usage에서 실제로 사용된 공급자와 모델을 확인합니다. 주 모델의 한도가 끝나거나 라우팅 가능한 오류가 나면 Combo의 다음 모델로 넘어갑니다. 모든 오류가 fallback 대상은 아니며 인증 실패나 잘못된 설정은 직접 고쳐야 합니다.

확인 방법: Claude Code 응답과 Usage 기록이 모두 생기면 연결이 끝난 겁니다.

Claude Code의 연결 성공 응답과 9Router Usage 라우팅 기록을 함께 확인하는 예시

STEP 9. Cursor와 다른 코딩 도구 연결: 3분

9Router는 OpenAI 호환 Endpoint도 제공합니다. Cursor, Cline, Continue처럼 사용자 지정 OpenAI Endpoint를 받는 도구에는 아래 값을 넣습니다.

Base URL: http://localhost:20128/v1
API Key: <대시보드에서 만든 API 키>
Model: claude-backup

Codex와 Antigravity처럼 별도 설정 방식이 있는 도구는 대시보드의 CLI Tools 안내를 따르세요. IDE 트래픽을 가로채는 MITM 기능은 고급 설정입니다. 사용 전에 해당 도구의 정책과 계정 조건을 확인해야 합니다.

확인 방법: 각 도구에서 짧은 테스트 요청을 보낸 뒤 9Router Usage에 기록이 생깁니다.

STEP 10. 업데이트와 재실행: 1분

최신 버전으로 올릴 때는 같은 패키지를 다시 설치합니다.

npm install -g 9router@latest

브라우저를 자동으로 열지 않고 실행하려면 아래 옵션을 씁니다.

9router --no-browser

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

9Router가 실제로 하는 일

용어: Router는 코딩 도구의 요청을 받아 설정된 AI 공급자 중 하나로 전달하는 중간 서버입니다.

Claude Code는 http://localhost:20128/v1 한 곳에 요청합니다. 9Router는 Combo의 순서, 공급자 상태, 오류 종류를 보고 어느 모델로 보낼지 정합니다. OAuth 토큰 갱신, 형식 변환, 사용량 기록도 같은 로컬 서버에서 처리합니다.

Fallback은 대화를 새로 만드는 기능이 아닙니다. Claude Code 프로세스는 그대로 있고 다음 요청을 다른 모델이 처리합니다. 모델이 바뀌면 답변 품질이나 도구 사용 방식은 달라질 수 있습니다.

무료로 쓸 때 꼭 구분할 것

경로 비용 판단
9Router 프로그램 MIT 오픈소스, 무료
OpenCode Free 공식 문서상 인증 없는 무료 경로, 제공 모델은 변동 가능
Kiro의 kr/ 모델 공식 문서상 무료 경로, 실제 할당량과 약관은 공급자 정책 확인
Claude Code의 cc/ 모델 Claude Pro/Max 같은 기존 구독 필요
GLM의 glm/ 모델 직접 API 키와 과금 조건 확인
Kimi의 kimi/ 모델 직접 API 키와 요금제 확인
Gemini 계열 연결 방식별 무료 할당량과 현재 정책 확인

핵심은 무료 모델 이름을 외우는 게 아닙니다. 대시보드에서 지금 활성화된 공급자와 할당량을 확인하고 Combo 순서를 정하는 겁니다.

문제 해결

9router: command not found

설치가 끝났는데 명령을 못 찾으면 터미널을 다시 열고 확인합니다.

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

9Router가 목록에 없다면 npm install -g 9router를 다시 실행하세요.

대시보드가 열리지 않음

9Router가 실행 중인지 확인하고 주소를 직접 엽니다.

http://localhost:20128/dashboard

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

9router --port 8080

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

Claude Code에서 401 오류가 남

~/.claude/settings.json의 ANTHROPIC_AUTH_TOKEN이 대시보드 API 키와 같은지 확인하세요. 키 앞뒤에 공백이 들어가도 실패합니다.

한도가 끝났는데 모델이 안 바뀜

Combo 전략이 Fallback인지 확인하세요. Claude Code 모델 매핑에 단일 모델이 아니라 Combo 이름 claude-backup이 들어가야 합니다. 다음 모델의 공급자도 활성 상태여야 합니다.

OAuth 연결이 만료됨

Providers에서 해당 공급자를 열고 Reconnect를 실행하세요. 9Router가 자동 갱신을 시도하지만 재로그인이 필요한 경우도 있습니다.

무료라고 했는데 비용이 표시됨

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

FAQ

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

아닙니다. 9Router 자체는 무료지만 Claude 구독이나 유료 API의 비용을 없애주지는 않습니다. 무료 공급자를 연결하고 Combo에 넣었을 때 해당 경로만 무료로 쓸 수 있습니다.

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

Claude Code 프로세스와 로컬 대화는 그대로 유지됩니다. 다음 요청을 백업 모델이 처리하므로 모델 특성에 따라 답변은 달라질 수 있습니다.

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

안 됩니다. 로컬 서버가 실행 중이어야 Claude Code가 Endpoint에 연결됩니다. 장시간 쓸 거라면 Docker나 운영체제 서비스로 실행하는 방식을 공식 문서에서 확인하세요.

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

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

공식 문서

가이드 전체 보기