옴니라우트(OmniRoute) 설치 가이드 — 클로드 코드 한도 걸려도 자동 전환 + 공식 무료 키 제공자 14곳 · 약관 주의 12곳

클로드 코드 쓰다가 사용량 한도에 자주 걸리시나요? 옴니라우트(OmniRoute)는 AI 제공자 375곳(무료 150곳 이상)을 주소 하나로 묶어 주는 무료 오픈소스 도구예요(MIT, 깃허브 별 8.5만, 2026-11-08 기준). 한 곳이 한도에 차면 연결해 둔 다른 모델로 자동으로 넘겨서 작업을 이어 가요.
이 페이지에 README 공식 설치 명령어, 공식 무료 키를 받을 수 있는 제공자 14곳, 약관 때문에 피하는 게 좋은 제공자 12곳, 클로드 코드 연결법을 정리했어요.

한눈에 보기

• 옴니라우트가 토큰을 공짜로 주는 게 아니에요. README에도 "제공자마다 직접 가입하고 키를 받아 연결하라, 한도와 약관은 각 제공자가 정한다"고 적혀 있어요.

설치 — 명령어 한 줄

1) 설치하고 실행 (README 공식 명령)

npm install -g omniroute
omniroute

• 실행하면 브라우저에서 대시보드가 열려요: http://localhost:20128
• -g(전역)로 깔면 어느 폴더에서든 omniroute 명령을 쓸 수 있어요. 이 방법을 기본으로 쓰세요.

npm 11 이상에서 설치 스크립트가 막히면 (README 안내 그대로)

npm install -g --allow-scripts=omniroute,keytar,onnxruntime-node,@parcel/watcher,@swc/core,protobufjs,esbuild omniroute

도커로 돌리고 싶으면

docker run -d --name omniroute --restart unless-stopped -p 127.0.0.1:20128:20128 -v omniroute-data:/app/data diegosouzapw/omniroute:latest

실제로 해 보기 — 대시보드에서 무료 제공자 연결

1. 왼쪽 메뉴 공급자(Providers)를 누르면 합계 0/375 · 프리 티어 0/156처럼 연결할 수 있는 제공자가 전부 보여요.

1. 프리 티어를 누르면 무료 등급이 있는 제공자만 모아 보여요.

1. 연결할 제공자(예: Gemini (Google AI Studio))를 누르고 연결 추가 → 받은 API 키를 붙여 넣고 저장. 무료 모델만 가져오기를 켜면 유료 모델은 건너뛰어요.

1. 2~3곳 이상 연결해 두면, 한 곳이 한도에 차도 model: auto가 다음 제공자로 넘겨요.

클로드 코드에 연결하기

방법 1 — 명령 한 줄로 실행 (README 공식)

omniroute run claude --model gemini/gemini-2.5-flash

• 실제로 실행해 보면(--dry-run) 클로드 코드가 ANTHROPIC_BASE_URL=http://localhost:20128 과 지정한 모델로 켜지도록 환경을 맞춰 줘요. 설정 파일은 건드리지 않아요.
• --model에는 대시보드에 연결한 제공자의 모델 이름을 넣으세요.

방법 2 — 항상 옴니라우트를 거치게 (CLI-TOOLS 문서)

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:20128",
    "ANTHROPIC_AUTH_TOKEN": "sk-your-omniroute-key"
  }
}

• 위 내용을 ~/.claude/settings.json에 넣어요. 키는 대시보드 → 엔드포인트에서 복사해요.
• 원래대로 돌리려면 이 두 줄만 지우면 돼요.

잘 연결됐는지 확인

curl http://localhost:20128/v1/models -H "Authorization: Bearer YOUR_KEY"

공식 무료 키 받는 제공자 14곳

옴니라우트 공식 문서(Free Tiers Guide 2026-10-11, Free Tiers 표 2026-10-18)에 나온 값이에요. 무료 등급은 자주 바뀌니 가입할 때 각 사이트에서 다시 확인하세요.

매달 다시 채워지는 무료 사용량 (10곳)

가입하면 한 번 주는 크레딧 (4곳)

• 추천 조합(공식 문서 예시): Gemini + Groq를 먼저 연결하고, 여유가 있으면 Mistral · Cloudflare를 더하세요.
• 무료 사용량 합계는 대시보드 무료 티어 예산(/dashboard/free-tiers) 화면에서 볼 수 있어요.

약관 주의 — 피하는 게 좋은 제공자 12곳

옴니라우트 카탈로그가 tos: avoid로 표시한 곳이에요. 이 제공자들은 자동 라우팅에서 기본으로 빠져 있고, 계정을 연결해도 그 설정이 풀리지 않아요.

• 구독 계정 로그인(OAuth)이나 웹 쿠키로 연결하는 방식은 약관 문제가 생기기 쉬워서 이 가이드에서는 다루지 않아요. 공식 사이트에서 받은 API 키로 연결하는 것만 쓰세요.

바로 쓰는 프롬프트

클로드 코드에 그대로 붙여 넣으세요.

npm install -g omniroute 로 옴니라우트를 설치하고 실행해 줘. 대시보드 주소(localhost:20128)가 열리는지 확인하고, 안 되면 원인을 찾아서 고쳐 줘

내 ~/.claude/settings.json 을 먼저 백업하고, ANTHROPIC_BASE_URL 을 http://localhost:20128 로 바꿔서 클로드 코드가 옴니라우트를 거치게 설정해 줘. 키는 내가 붙여 넣을게. 되돌리는 방법도 알려 줘

curl 로 http://localhost:20128/v1/models 를 불러서 지금 연결된 무료 모델 목록을 표로 정리해 줘. 키는 내가 줄게

옴니라우트 대시보드에 Gemini, Groq 를 연결했어. 둘 중 하나가 한도에 차면 다른 쪽으로 넘어가는 콤보를 만드는 순서를 화면 메뉴 이름 그대로 단계별로 알려 줘

이렇게 쓰면 좋아요

1. 무료 제공자 2~3곳만 먼저 연결하세요. 하나만 연결하면 그곳이 한도에 찼을 때 넘어갈 곳이 없어요.
2. 평소엔 원래 쓰던 클로드 그대로 쓰고, 한도에 걸릴 때만 omniroute run claude로 켜도 돼요.
3. 회사 코드·개인정보는 무료 등급에 보내기 전에 각 제공자의 데이터 정책(학습 사용 여부)을 확인하세요.
4. 대시보드 제공업체 할당량 메뉴에서 어디서 얼마나 썼는지 볼 수 있어요.

자주 묻는 질문

• 설치만 하면 바로 무료로 쓸 수 있나요? → 아니요. 처음엔 연결된 제공자가 없어서 답이 안 나와요. 위 목록에서 키를 받아 1곳 이상 연결해야 해요.
• 클로드(앤트로픽) 모델이 무료가 되나요? → 아니요. 한도에 걸렸을 때 다른 회사의 무료 모델로 넘겨서 작업을 이어 가는 도구예요.
• 윈도우에서도 되나요? → 네. Node.js가 있으면 같은 명령으로 깔려요. 도커도 돼요.
• 지우고 싶어요 → npm uninstall -g omniroute, 그리고 settings.json에 넣은 두 줄을 지우세요.

링크

• 저장소: https://github.com/cheaper-inference/OmniRoute
• 무료 등급 안내(공식): Free Tiers Guide
• 제공자별 무료 사용량·약관 표(공식): Free Tiers Reference
• 홈페이지: https://omniroute.online