Claude Code 한도 이후에도 작업을 이어가는 OmniRoute 입문 가이드

역할: OmniRoute 설치·연결 검증을 맡는 환경 설정 담당
맥락: OmniRoute가 아직 설치되지 않았을 수 있는 <프로젝트 상황 한 줄>
입력: <운영체제와 셸>, <기술 스택>, <목표 한 줄>
작업: ① 설치 여부 확인 — `command -v omniroute`와 `omniroute --version`을 실행하고 Node.js·npm·Claude Code 버전도 점검하세요. ② 미설치 시 설치 — OmniRoute가 없으면 공식 문서를 확인한 뒤 `npm install -g omniroute@latest`로 설치하고, 서버를 열어 대시보드에서 AI 서비스 연결과 접근 키 생성을 안내하세요. ③ 실제 연결 검증 — `omniroute --version` → `omniroute status` → `omniroute doctor` → `curl http://localhost:20128/v1/models -H "Authorization: Bearer $OMNIROUTE_API_KEY"` → `curl http://localhost:20128/v1/chat/completions -H "Authorization: Bearer $OMNIROUTE_API_KEY" -H "Content-Type: application/json" -d '{"model":"auto","messages":[{"role":"user","content":"연결 확인이라고만 답해줘"}]}'` → 대시보드 요청 로그 순서로 확인하세요. ④ 초보자 안내 — 검증이 모두 끝나면 OmniRoute가 무엇인지, Claude Code 한도 뒤에 어떻게 다음 모델로 넘기는지, 앞으로 어떤 명령으로 시작하면 되는지 쉽게 설명하세요.
제약: 비밀키 값은 출력하거나 파일·프롬프트·저장소에 쓰지 마세요. 지원하지 않는 Node.js 버전과 설치·연결 오류를 건너뛰지 말고, 기존 파일과 테스트를 깨지 마세요.
출력: 실행한 명령, 확인된 Node.js·npm·Claude Code·OmniRoute 버전, 설치 여부, 연결 상태, 변경 파일, 각 검증 결과, 남은 오류와 다음 조치
검증: `omniroute --version`은 설치된 버전을, `omniroute status`는 실행 상태를, `omniroute doctor`는 치명적인 오류가 없는 진단 결과를 보여야 합니다. 인증을 넣은 `/v1/models` 호출에는 연결한 모델 목록이 보여야 하고, `auto` 모델의 짧은 요청에는 실제 응답이 와야 하며, 대시보드 요청 로그에도 같은 요청이 남아야 합니다. 하나라도 실패하면 완료로 보고하지 말고 원인과 다음 조치를 제시하세요.

Quick Start

• 공식 사이트: omniroute.online
• 공식 GitHub: github.com/diegosouzapw/OmniRoute

OmniRoute는 Claude Code와 여러 AI 제공자 사이에서 작동하는 로컬 게이트웨이입니다. Claude 한도가 끝나면 연결해 둔 다른 모델로 요청을 넘기고, 긴 도구 출력은 보내기 전에 줄일 수 있습니다.

용어: 게이트웨이는 Claude Code 요청을 먼저 받아 연결된 AI 모델 중 어디로 보낼지 정하는 중간 서버입니다.

용어: 로컬은 인터넷의 다른 서버가 아니라 지금 쓰는 내 컴퓨터를 뜻합니다.

아래 명령은 버전을 확인하고 OmniRoute를 설치한 뒤 서버를 엽니다. omniroute를 실행한 터미널은 그대로 열어두세요.

용어: Node.js와 npm은 OmniRoute를 실행하고 설치할 때 쓰는 프로그램과 설치 도구입니다.

node --version
npm --version
npm install -g omniroute@latest
omniroute --version
omniroute

성공하면 Node.js, npm, OmniRoute 버전이 보입니다. 마지막 명령 뒤에는 OmniRoute 서버가 열린 상태로 남습니다.

용어: **제공자(Provider)**는 Claude Code 요청을 실제로 처리하는 AI 서비스입니다.

용어: Endpoint는 OmniRoute에 접속할 주소와 인증 키를 쓰는 연결 지점입니다. API 키는 앱이 연결 권한을 확인할 때 쓰는 비밀 문자열입니다.

브라우저에서 http://localhost:20128을 여세요. Providers에서 사용할 제공자를 연결하고 Endpoints에서 OmniRoute API 키를 하나 만듭니다.

아래 명령은 새 터미널에서 API 키를 현재 작업에만 넣고 Claude Code를 엽니다. <...> 부분만 바꾸세요.

export OMNIROUTE_API_KEY="<Dashboard → Endpoints에서 복사한 키>"
omniroute launch

성공하면 Claude Code 입력 화면이 열립니다.

Claude Code가 열리면 문서 맨 위의 복사해서 바로 시작하는 프롬프트를 펼치세요. <...> 부분만 바꿔 붙여넣으면 됩니다.

STEP 1. 실행 환경 확인: 3분

이 단계에서는 설치 오류를 막기 위해 Node.js, npm, Claude Code 버전을 먼저 확인합니다.

npm 공개판 v3.8.48은 Node.js 22.x 또는 24.x~26.x를 지원합니다. 23.x는 지원 범위가 아닙니다.

아래 명령은 현재 Node.js와 npm 버전을 확인합니다.

node --version
npm --version

성공하면 두 줄에 각각 설치된 버전이 보입니다.

Claude Code가 없다면 공식 설치 문서의 npm 경로를 쓰면 됩니다. 현재 Claude Code npm 패키지도 Node.js 22 이상이 필요합니다.

아래 명령은 Claude Code를 설치하고 버전을 확인합니다.

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

성공하면 설치가 끝난 뒤 Claude Code 버전이 보입니다.

Node.js 버전이 맞지 않으면 Node.js 공식 다운로드에서 지원 버전으로 바꾸세요. 그다음 터미널을 다시 엽니다.

STEP 2. OmniRoute 설치하고 서버 열기: 5분

이 단계에서는 OmniRoute를 설치하고 Claude Code 요청을 받을 로컬 서버를 엽니다.

아래 npm 명령으로 OmniRoute를 설치합니다. 이어서 버전을 확인하고 서버를 엽니다.

npm install -g omniroute@latest
omniroute --version
omniroute

성공하면 OmniRoute 버전이 보입니다. 마지막 명령 뒤에는 서버 실행 화면이 남습니다.

용어: Base URL은 Claude Code가 요청을 보내기 시작할 기본 주소입니다.

용어: 포트는 같은 컴퓨터에서 어떤 프로그램으로 연결할지 구분하는 번호입니다.

서버가 열리면 아래 주소를 씁니다.

Claude Code용 주소에는 /v1을 붙이지 않습니다. Claude Code가 /v1/messages를 직접 붙입니다.

아래 명령은 새 터미널에서 서버 상태와 설치 문제를 확인합니다.

omniroute status
omniroute doctor

성공하면 실행 상태와 진단 결과가 보입니다. omniroute doctor에 치명적인 오류가 없고 대시보드가 열리면 다음 단계로 넘어가세요.

STEP 3. 제공자와 API 키 연결하기: 5분

이 단계에서는 실제 AI 모델로 요청을 보내기 위해 제공자와 Endpoint용 API 키를 연결합니다.

용어: OAuth는 비밀키를 복사하지 않고 계정 로그인으로 연결 권한을 주는 방식입니다.

용어: 무료 tier는 제공자가 일정 사용량을 돈 없이 쓸 수 있게 열어 둔 구간입니다.

대시보드에서 Providers를 열고 사용할 제공자를 연결하세요. 연결 방식은 API 키, OAuth, 인증 없는 무료 경로처럼 제공자마다 다릅니다.

공식 v3.8.48 빠른 시작은 Kiro AI와 OpenCode Free를 예시로 듭니다. 무료 조건과 자동화 허용 범위는 바뀔 수 있으니 대시보드 정보와 이용약관을 먼저 확인하세요.

한 제공자만 연결해도 요청을 보낼 수 있습니다. 자동 전환까지 쓰려면 성격이 다른 경로를 두 개 이상 연결하는 편이 낫습니다.

• 첫 경로: 평소 쓰는 구독 또는 품질 우선 모델
• 두 번째 경로: 저비용 API 모델
• 마지막 경로: 사용 조건을 확인한 무료 tier

이제 Endpoints에서 API 키를 만드세요. 키는 생성 직후 복사하고 프롬프트, 저장소, 캡처 화면에 넣지 마세요.

아래 명령은 복사한 키를 현재 터미널에만 넣습니다.

export OMNIROUTE_API_KEY="<Endpoints에서 복사한 키>"

성공하면 오류 없이 다음 입력 줄로 돌아옵니다. 실제 키 값은 다시 출력하지 마세요.

아래 명령은 OmniRoute가 보여주는 모델 목록을 불러옵니다.

curl http://localhost:20128/v1/models \
  -H "Authorization: Bearer $OMNIROUTE_API_KEY"

성공하면 응답의 data 또는 models 목록에 연결한 모델이 보입니다.

아래 명령은 auto 모델로 짧은 연결 확인 요청을 보냅니다.

curl http://localhost:20128/v1/chat/completions \
  -H "Authorization: Bearer $OMNIROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"auto","messages":[{"role":"user","content":"연결 확인이라고만 답해줘"}]}'

성공하면 응답 본문에 짧은 답이 보입니다. 대시보드 요청 로그에도 같은 요청이 남습니다.

요청이 실패하면 아래 명령으로 각 제공자의 연결 상태를 확인하세요.

omniroute providers list
omniroute providers test-all

성공하면 연결된 제공자 목록과 테스트 결과가 보입니다. 실패 항목이 있으면 해당 제공자의 인증과 이용 조건부터 다시 확인하세요.

STEP 4. 숫자를 정확히 이해하기: 3분

이 단계에서는 과장된 숫자에 속지 않도록 제공자 수와 무료 사용량의 뜻을 나눠 봅니다.

용어: 토큰은 AI가 글을 읽고 만드는 양을 세는 작은 단위입니다.

npm 공개판 v3.8.48의 공식 문서는 전체 제공자 250개, 무료 tier 90개 이상을 적고 있습니다. 250개가 모두 무료라는 뜻은 아닙니다.

같은 버전의 무료 tier 문서는 매달 반복되는 무료량을 약 15.4억 토큰으로 계산합니다. README는 같은 값을 약 16억 토큰으로 반올림해 적습니다.

이 숫자는 한 계정에 한 번에 주는 양이 아닙니다. 40개가 넘는 제공자가 공식 문서에 적어 둔 무료 상한을 중복 없이 더한 추정치입니다.

첫 달에만 주는 가입 크레딧은 매달 반복되는 무료량과 다릅니다. 무료 tier가 끝나거나 조건이 바뀌면 합계도 내려갑니다. 설치된 버전의 대시보드 수치를 최종값으로 보세요.

STEP 5. Claude Code를 OmniRoute로 실행하기: 3분

이 단계에서는 Claude Code 요청이 OmniRoute를 거치도록 실행합니다.

가장 간단한 방법은 omniroute launch입니다. 이 명령은 OmniRoute 상태를 확인하고 필요한 주소와 인증 값을 넣은 뒤 claude를 실행합니다. 별도 설정 파일은 쓰지 않습니다.

아래 명령은 Endpoint 키를 넣고 Claude Code를 엽니다.

export OMNIROUTE_API_KEY="<Endpoints에서 복사한 키>"
omniroute launch

성공하면 Claude Code 입력 화면이 열립니다.

용어: dry-run은 실제 변경 없이 예정된 결과만 보여 주는 시험 실행입니다.

용어: 프로필은 특정 제공자나 모델의 연결 설정을 이름별로 저장한 묶음입니다.

아래 명령은 모델별 프로필을 만들기 전에 결과를 미리 보여 줍니다.

omniroute setup-claude --dry-run

성공하면 만들 예정인 프로필 정보가 보이고 실제 파일은 바뀌지 않습니다.

아래 명령은 모델 ID의 일부를 기준으로 사용할 제공자나 모델을 좁힌 뒤 그 프로필로 실행합니다.

omniroute setup-claude --only "<provider 또는 model ID 일부>"
omniroute launch --profile "<생성된 프로필 이름>"

성공하면 프로필 이름이 보이고 그 프로필로 Claude Code가 열립니다.

setup-claude는 ~/.claude/profiles/<이름>/settings.json을 만듭니다. 인증 값은 프로필에 쓰지 않으니 명령 출력의 프로필 이름을 그대로 사용하세요.

아래 명령은 프로필 없이 주소와 인증 값을 직접 넣어 Claude Code를 엽니다. Claude용 Base URL에는 /v1을 붙이지 않습니다.

export ANTHROPIC_BASE_URL="http://localhost:20128"
export ANTHROPIC_AUTH_TOKEN="$OMNIROUTE_API_KEY"
claude

성공하면 Claude Code 입력 화면이 열립니다.

아래 프롬프트는 파일을 건드리지 않고 연결만 확인합니다.

현재 작업은 연결 확인입니다.
프로젝트 파일은 수정하지 마세요.
사용 가능한 도구를 한 줄로 요약하고 "OmniRoute 연결 확인 완료"라고 답해 주세요.

성공하면 지정한 답이 오고 대시보드 요청 로그에 기록이 생깁니다.

STEP 6. 자동 전환 경로 만들기: 5분

이 단계에서는 첫 모델이 막혀도 다음 모델로 이어지도록 자동 전환 순서를 만듭니다.

용어: combo는 먼저 쓸 모델과 실패했을 때 넘길 모델을 순서대로 묶은 설정입니다.

대시보드에서 Combos를 열고 아래 순서로 경로를 만드세요.

1. 첫 칸에는 평소 사용할 구독 또는 품질 우선 모델을 둡니다.
2. 다음 칸에는 저비용 API 모델을 둡니다.
3. 마지막 칸에는 현재 이용약관을 확인한 무료 모델을 둡니다.
4. 순서대로 소진하려면 priority 또는 fill-first 전략을 고릅니다.
5. 저장한 뒤 대시보드에 표시되는 combo 모델 ID를 복사합니다.

처음부터 많은 모델을 넣지 마세요. 세 경로만 연결해도 어느 단계에서 실패하는지 찾기 쉽습니다.

아래 명령은 서버와 각 제공자의 연결 상태를 확인합니다.

omniroute status
omniroute providers list
omniroute providers test-all

성공하면 서버 상태, 제공자 목록, 연결 테스트 결과가 차례로 보입니다.

실제 전환을 시험해야 한다면 첫 경로를 잠시 끄세요. 짧은 연결 확인 요청을 한 번 보낸 뒤 바로 복원하면 됩니다.

같은 요청을 모든 제공자와 계정에 반복해서 보내지 마세요. 무료량만 줄어듭니다.

STEP 7. 토큰 압축 켜기: 5분

이 단계에서는 긴 도구 출력을 줄이되 중요한 내용이 빠지지 않는지 확인합니다.

용어: Preview는 실제 설정을 바꾸기 전에 원문과 압축 결과를 비교하는 미리보기 화면입니다.

용어: RTK와 Caveman은 긴 출력이나 문장을 줄이는 OmniRoute 압축 방식입니다.

대시보드에서 Context & Cache를 열면 압축 모드와 Preview를 확인할 수 있습니다.

RTK와 Caveman이 같은 입력을 모두 줄일 수 있을 때 공식 계산의 평균은 89.2%입니다. 모든 요청이나 모든 입력·출력 토큰이 같은 비율로 줄어든다는 뜻은 아닙니다.

짧은 프롬프트나 이미 압축된 코드는 거의 줄지 않을 수 있습니다.

처음에는 아래 순서로 확인하세요.

1. Preview에 실제 작업에서 나온 긴 로그를 붙입니다.
2. 원문과 압축문에서 오류, 경고, 파일명, 숫자가 남았는지 비교합니다.
3. 기본 작업은 Lite로 시작합니다.
4. 테스트 로그와 빌드 출력이 긴 작업에만 RTK 또는 Stacked를 씁니다.
5. 결과가 어긋나면 즉시 Off로 되돌립니다.

코드, URL, 파일 경로, JSON을 보호하는 규칙이 있어도 결과가 항상 같다고 단정하면 안 됩니다. 중요한 배포, 보안 점검, 데이터 이동 작업에서는 원문을 먼저 보존하세요.

STEP 8. 안전하게 운영하기: 3분

이 단계에서는 비밀키와 비용을 지키면서 OmniRoute를 운영합니다.

OmniRoute 서버와 설정은 기본적으로 내 컴퓨터에서 돌아갑니다. 요청은 선택된 외부 AI 제공자에게 전달됩니다. 로컬 게이트웨이를 써도 프롬프트까지 내 컴퓨터 안에만 남는 건 아닙니다.

• .env, API 키, 고객 정보는 프롬프트에 넣지 않습니다.
• 무료 tier의 개인용, 자동화, 대리 접속 제한을 확인합니다.
• 20128 포트를 인터넷에 그대로 공개하지 않습니다.
• 원격 서버로 옮길 때는 HTTPS와 권한 범위를 좁힌 접근 키를 씁니다.
• 유료 제공자를 연결했다면 대시보드의 비용 한도와 사용량 한도를 먼저 설정합니다.
• 작업 전후에 git status와 테스트 결과를 직접 확인합니다.

아래 명령은 문제 원인과 실시간 로그를 확인합니다. 자동 수정보다 진단을 먼저 보세요.

omniroute doctor
omniroute logs --follow

성공하면 진단 결과와 새 로그가 터미널에 이어서 보입니다.

FAQ

npm install -g omniroute가 Node 버전 오류로 멈춥니다

OmniRoute 공개판 v3.8.48의 지원 범위는 Node.js 22.x 또는 24.x~26.x입니다. node --version을 확인하고 지원 버전으로 바꾼 뒤 다시 설치하세요.

omniroute를 실행했는데 20128 포트를 이미 쓴다고 나옵니다

아래 명령은 OmniRoute를 3000 포트로 열고 같은 포트로 Claude Code를 실행합니다.

omniroute --port 3000
omniroute launch --port 3000

성공하면 대시보드 주소가 http://localhost:3000으로 바뀝니다.

Claude Code가 OmniRoute를 거치지 않습니다

ANTHROPIC_BASE_URL 끝에 /v1이 붙어 있다면 빼세요. Claude Code를 완전히 종료한 뒤 omniroute launch로 다시 여세요.

401 또는 인증 오류가 납니다

아래 명령은 Endpoint에서 만든 키가 현재 터미널에 들어 있는지만 확인합니다. 실제 키 값은 출력하지 않습니다.

if [ -n "$OMNIROUTE_API_KEY" ]; then printf 'OMNIROUTE_API_KEY is set\n'; else printf 'OMNIROUTE_API_KEY is missing\n'; fi

성공하면 OMNIROUTE_API_KEY is set 또는 OMNIROUTE_API_KEY is missing이 보입니다.

setup-claude가 프로필을 만들지 못합니다

아래 명령은 프로필 생성 계획과 OmniRoute 모델 목록을 확인합니다. OmniRoute 서버를 먼저 실행해 두세요.

omniroute setup-claude --dry-run
curl http://localhost:20128/v1/models \
  -H "Authorization: Bearer $OMNIROUTE_API_KEY"

성공하면 만들 예정인 프로필 정보와 연결된 모델 목록이 보입니다.

자동 전환이 일어나지 않습니다

활성 제공자가 하나뿐이거나 combo에 대체 경로가 없을 수 있습니다. Providers에서 연결 상태를 확인하고 Combos에서 두 번째 경로를 추가하세요.

압축을 켰는데 토큰이 거의 줄지 않습니다

짧은 프롬프트, 코드 중심 입력, 이미 정리된 로그는 줄일 부분이 적습니다. Preview에 실제 긴 테스트나 빌드 출력을 넣어 비교하세요.

무료인데 결제가 발생할 수 있나요

OmniRoute 자체는 MIT 오픈소스지만 연결한 제공자의 과금은 별개입니다. 무료량을 넘겼을 때 자동 과금되는 API 키가 combo에 들어 있으면 비용이 생길 수 있습니다.

유료 경로를 연결하기 전에 비용 한도와 사용량 한도를 설정하세요.

공식 자료

• OmniRoute 공식 사이트
• OmniRoute GitHub 저장소
• v3.8.48 README와 Quick Start
• v3.8.48 설치 가이드
• Claude Code 연결 가이드
• CLI 통합 명령 목록
• 무료 tier 산정 방식
• 압축 모드와 절감 범위
• Claude Code 공식 설치 문서

이 자료가 도움됐다면

이런 AI 활용 자료를 인스타그램에 계속 올리고 있습니다.

• : 다음 자료를 가장 먼저 받아볼 수 있습니다
• 따라 하다 막힌 부분은 릴스 댓글로 남겨주세요. 다음 자료를 만들 때 참고합니다