이 레포가 무엇을 하는 물건인가.
Claude Code, Cursor, Cline 같은 AI 코딩 도구는 저마다 자기만의 API 키 설정이 필요합니다. OmniRoute는 이 도구들이 모두 연결할 수 있는 하나의 로컬 엔드포인트(http://localhost:20128/v1)를 열어놓고, 그 안에서 "지금 무료 할당량이 남아있는 AI"를 골라 트래픽을 보내 줍니다.
할당량이 소진되면? 다음 프로바이더로 밀리초 단위로 전환합니다 — 코딩 중에 "quota exceeded" 오류를 만날 일이 사라집니다.
OmniRoute가 자처하는 역할은 AI 게이트웨이(Gateway)입니다. 쉽게 말하면, 여러 AI 회사의 API 앞에 붙어서 요청을 받아 알맞은 곳으로 전달하는 "중계 허브"입니다. 집에 설치된 인터넷 공유기가 여러 기기를 하나의 인터넷 회선에 연결해 주듯, OmniRoute는 여러 AI 도구를 하나의 AI 인프라에 연결해 줍니다.
월간 무료 토큰 규모가 어느 정도냐면, OmniRoute가 집계한 40+ 프로바이더 무료 티어 합산이 약 월 16억 토큰입니다. 신규 가입 크레딧까지 합치면 첫 달 21억 토큰에 달합니다. 게다가 토큰 압축 기능으로 실제 전송되는 토큰 수를 최대 95% 줄일 수 있으니, 체감 용량은 훨씬 큽니다.
트렌딩 이유 · 경쟁 대비 장점.
AI 코딩 도구를 진지하게 쓰는 개발자라면 공통적으로 겪는 불편이 있습니다. Claude Code를 쓰다가 할당량이 차면 Cursor로, Cursor도 차면 다시 ChatGPT로 — 매번 설정을 바꾸고 로그인을 반복해야 합니다. OmniRoute는 이 반복 작업을 완전히 없애줍니다.
| 비교 항목 | LiteLLM / OpenRouter | OmniRoute |
|---|---|---|
| 프로바이더 수 | 20~100개 | 236개 |
| 무료 프로바이더 | 1~5개 | 50+개 (11개 영구 무료) |
| 라우팅 전략 | 1~3가지 | 17가지 (priority, weighted, fusion 등) |
| 토큰 압축 | 없음 / 최대 40% | RTK+Caveman 15~95% |
| MCP 서버 내장 | 드물거나 없음 | 87개 툴, 3가지 전송방식 |
| 에이전트 프로토콜 | 없음 | A2A (JSON-RPC 2.0) |
| 데스크탑 앱 | 없음 | Electron 앱 + PWA |
| TLS 스텔스 | 없음 | JA3/JA4 지문 우회 |
OpenRouter 같은 서비스도 여러 모델을 쓸 수 있지만, 무료 할당량이 언제 얼마나 남아있는지 실시간으로 추적하고 자동 전환해 주지는 않습니다. 개발자가 대시보드를 열고 직접 확인하고 설정을 바꿔야 합니다.
또한 대부분의 라우터는 "클라우드 서비스"라 요청이 외부를 경유합니다 — 프롬프트가 어디에 남을지 알 수 없습니다.
OmniRoute는 내 컴퓨터에서 돌아가는 로컬 프록시입니다. 프롬프트가 외부 서비스를 거치지 않고, 내 기계에서 직접 AI 프로바이더로 갑니다. 할당량은 대시보드에서 실시간으로 보이고, 소진되면 자동으로 다음 프로바이더로 전환됩니다.
트렌딩을 탄 핵심 이유는 세 가지입니다. 첫째, Claude Code + 무료 Claude API를 연결하는 실질적인 방법을 제공한다는 점 — Claude Code 구독이 없어도 무료 티어 프로바이더를 통해 Claude를 계속 쓸 수 있습니다. 둘째, 토큰 압축으로 비용을 대폭 아낄 수 있다는 점. 셋째, 설치가 npm install -g omniroute && omniroute 두 줄로 끝나는 간결함입니다.
백엔드·프론트엔드·인프라 한눈에.
| 레이어 | 기술 / 버전 | 역할 |
|---|---|---|
| 프론트엔드 프레임워크 | Next.js 16 (React 19) | 대시보드 UI — 프로바이더 관리, 콤보 설정, 분석, 압축 스튜디오 |
| UI 컴포넌트 | Tailwind CSS 4, lucide-react, @xyflow/react | 스타일링, 아이콘, 플로우 다이어그램 (노드 편집기) |
| 백엔드 서버 | Express 5 | HTTP API 서버 — /v1 엔드포인트, SSE 스트리밍, 프록시 핸들링 |
| 핵심 게이트웨이 | open-sse/ (자체 모듈) | 라우팅 엔진, 압축 파이프라인, 폴백 로직, 프로바이더 어댑터 |
| 런타임 | Node.js 24 | 서버 및 CLI 실행 환경 |
| 데이터 저장 | SQLite (lowdb + sql.js), sqlite-vec | 로컬 DB — 프로바이더 설정, 콤보, 감사 로그. 벡터 저장(메모리) |
| 캐시 / 큐 | Redis (ioredis) — 선택사항 | 레이트 리미팅, 세션 상태 공유 (없으면 인메모리 폴백) |
| 데스크탑 앱 | Electron | Windows / macOS / Linux 네이티브 창 + 시스템 트레이 |
| AI 에이전트 프로토콜 | @modelcontextprotocol/sdk (MCP), A2A (JSON-RPC 2.0) | 외부 에이전트가 OmniRoute를 도구로 사용할 수 있는 서버 |
| 압축 엔진 | Caveman (rule-based), RTK, LLMLingua-2 (ONNX/MobileBERT) | 프롬프트 토큰 압축 — 9가지 엔진 파이프라인 |
| 보안 | jose (JWT/AES-256-GCM), TLS wreq-js (JA3/JA4 스텔스) | API 키 암호화, TLS 지문 우회 |
| 국제화 | next-intl, 42개 로케일 | 다국어 대시보드 UI |
| 테스트 | Vitest, Playwright, Stryker (뮤테이션) | 14,965개 테스트 커버리지 |
| 문서 | Fumadocs (MDX 기반) | 인터랙티브 공식 문서 사이트 |
요청이 어떻게 흘러서 어느 AI에 닿는가.
OmniRoute의 구조를 이해하는 가장 좋은 방법은 "내가 Claude Code에서 질문을 보냈을 때 무슨 일이 일어나는가"를 추적하는 겁니다.
Claude Code에서 메시지를 보내면 다음 순서로 처리됩니다:
① 요청 도착 — src/sse/handlers/chat.ts가 POST /v1/chat/completions를 받습니다. 모델명이 auto나 auto/coding이면 자동 콤보 엔진으로 분기합니다.
② 모델·콤보 결정 — resolveRoutingModel()이 DB에서 설정된 콤보를 가져옵니다. 17가지 전략(priority, round-robin, cost-optimized 등) 중 하나로 다음 프로바이더를 선택합니다.
③ 압축 파이프라인 — open-sse/services/compression/의 9개 엔진이 순서대로 실행됩니다. RTK가 터미널 출력(git diff, 테스트 로그)을 정리하고, Caveman이 프로즈를 요약합니다.
④ 포맷 번역 — open-sse/translator/가 OpenAI 형식 요청을 목적지 프로바이더 형식으로 변환합니다. Claude 형식으로 보낼지, Gemini 형식으로 보낼지 자동 결정됩니다.
⑤ 외부 AI 호출 + SSE 스트리밍 — 실제 API 호출이 나가고, 응답이 토큰 단위로 스트리밍되어 들어옵니다. 실패하면 폴백 루프가 즉시 다음 프로바이더로 재시도합니다.
⑥ 응답 역번역 — 프로바이더 형식의 응답이 다시 OpenAI 형식으로 변환되어 코딩 도구로 돌아갑니다.
auto 모델을 지정하면 OmniRoute가 현재 연결된 모든 프로바이더를 9가지 요소(건강도, 할당량, 비용, 지연, 성공률, 신선도 등)로 실시간 점수화해 최적의 프로바이더를 자동 선택합니다. LKGP(Last Known Good Provider) 전략이 기본이라, 직전에 성공한 프로바이더를 우선합니다 — 불필요한 전환을 최소화해 세션이 자연스럽게 이어집니다.
어떤 폴더가 무슨 일을 하나.
| 파일/폴더 | 역할 |
|---|---|
open-sse/services/combo.ts | 핵심 — 콤보 라우팅 실행. 어떤 프로바이더로 보낼지 결정하고 폴백을 처리하는 두뇌 |
src/sse/handlers/chat.ts | 외부에서 들어오는 채팅 요청의 첫 번째 관문. auto/* 분기 처리 |
open-sse/translator/ | 각 AI 프로바이더별 API 형식 변환. OpenAI↔Claude↔Gemini 상호 번역 |
open-sse/services/compression/ | 9개 압축 엔진. RTK(도구 출력), Caveman(프로즈), LLMLingua-2(ML 기반) |
open-sse/services/accountFallback.ts | 서킷 브레이커·쿨다운·락아웃 3계층 장애 복구 로직 |
src/lib/db/ | SQLite로 프로바이더 설정, 콤보, 감사 로그를 로컬에 저장 |
electron/main.js | 데스크탑 앱의 메인 프로세스. 창·시스템 트레이·서버 라이프사이클 관리 |
docker-compose.yml | base/web/cli/memory/bifrost 프로파일로 구성된 Docker 배포 |
이 레포에서 배울 만한 것 + 어디를 보면 되는지.
OpenAI, Claude, Gemini는 API 형식이 다릅니다. OmniRoute는 open-sse/translator/에서 이를 양방향으로 변환합니다. "공통 인터페이스 뒤에 여러 구현을 숨기는" 어댑터 패턴(Adapter Pattern)의 실전 예제입니다.
읽어볼 파일: open-sse/translator/, open-sse/services/provider.ts
분산 시스템 설계의 핵심 패턴입니다. 외부 서비스가 불안정할 때 무한 재시도 대신 일시적으로 트래픽을 차단해 전체 시스템을 보호합니다. 실제 프로덕션 코드로 배울 수 있습니다.
읽어볼 파일: src/shared/utils/circuitBreaker.ts, docs/architecture/RESILIENCE_GUIDE.md
AI 응답이 실시간으로 흘러오는 스트리밍을 어떻게 구현하는지 배울 수 있습니다. Express의 SSE 응답과 Next.js의 Route Handler가 어떻게 함께 동작하는지 실제 코드로 확인할 수 있습니다.
읽어볼 파일: open-sse/handlers/chatCore/, src/sse/handlers/chat.ts
Anthropic의 Model Context Protocol을 구현한 서버를 직접 볼 수 있습니다. 87개 툴이 어떻게 등록되고 에이전트에게 노출되는지, stdio/HTTP/SSE 3가지 전송방식이 어떻게 다른지 배울 수 있습니다.
읽어볼 파일: open-sse/mcp-server/, docs/frameworks/MCP-SERVER.md
9개의 독립적인 압축 엔진이 파이프라인으로 연결되는 설계입니다. 각 엔진은 공통 인터페이스(id, compress, getConfigSchema)를 구현하고, 레지스트리에 등록됩니다. 플러그인 아키텍처와 파이프라인 패턴을 동시에 배울 수 있습니다.
읽어볼 파일: open-sse/services/compression/engines/registry.ts
코드에서 실제로 보이는 Auto-Combo 흐름:
// src/sse/handlers/chat.ts 에서 auto/* 분기 처리
// 1. 요청 모델명에 "auto/" 접두사가 있으면 가상 콤보 생성
const parsed = parseAutoSuffix(model); // "auto/coding:fast" → {category, tier}
// 2. 현재 연결된 프로바이더들로 가상 콤보 구성 (DB 저장 안 함)
const virtualCombo = createVirtualAutoCombo(parsed.variant, connections);
// 3. 일반 콤보와 같은 엔진으로 라우팅
return handleComboChat(virtualCombo, requestBody, res);돌리려면 무엇이 필요한가.
| 항목 | 요구사항 |
|---|---|
| Node.js | v24 이상 (.node-version 파일 기준). npm 글로벌 설치 필요 |
| OS | macOS · Linux · Windows (데스크탑 앱), Android Termux, ARM64 |
| 메모리 | 최소 512MB RAM. 압축 ML 엔진(LLMLingua-2 ONNX) 사용 시 1GB+ |
| 디스크 | npm install 후 약 200~500MB (node_modules). 데이터는 ./data/에 로컬 저장 |
| 포트 | 기본 20128 (HTTP + 대시보드 통합). 변경 가능 (PORT 환경변수) |
| Redis | 선택사항 — 없으면 인메모리 폴백. 있으면 레이트 리밋·세션 공유 향상 |
| Docker | 선택사항 — docker run diegosouzapw/omniroute. AMD64 + ARM64 지원 |
| API 키 | 최소 0개도 가능 (Pollinations, OpenCode Free는 키 불필요). 유료 프로바이더는 각사 API 키 필요 |
| 인터넷 | 필수 (AI 프로바이더 호출). 프록시·TLS 스텔스 지원으로 차단 환경에서도 동작 |
| Electron 빌드 | 먼저 npm run build 후 cd electron && npm run build. 빌드 툴체인 필요 |
OmniRoute는 자기 집 Wi-Fi 공유기처럼 내 컴퓨터에서 돌아갑니다. 어떤 AI를 쓸지 설정해 두면, 내 코딩 도구들이 모두 이 공유기를 통해 인터넷(AI 프로바이더)에 접속합니다. 공유기가 한 회선이 끊기면 다른 회선으로 자동 전환하듯, OmniRoute도 한 AI 할당량이 차면 다른 AI로 전환합니다.
난이도별로 손에 익히는 단계.
Node.js 24를 설치하고, npm install -g omniroute 후 omniroute를 실행합니다. 브라우저에서 http://localhost:20128 대시보드를 열고, Providers 메뉴에서 "Pollinations"(키 불필요)나 "Kiro AI"를 연결합니다.
확인 목표: curl http://localhost:20128/v1/models로 사용 가능한 모델 목록이 JSON으로 반환되면 성공입니다.
OmniRoute 대시보드에서 "Setup → Claude Code"를 클릭하면 자동 설정 명령어가 나옵니다. 또는 Claude Code에서 직접: claude config set apiUrl http://localhost:20128/v1 후 아무 API 키를 입력합니다(게이트웨이가 대신 인증합니다). 이후 Claude Code가 무료 프로바이더를 통해 동작하는지 확인합니다.
대시보드 → Combo 메뉴에서 새 콤보를 만듭니다. 전략을 priority로 선택하고, 구독 계정 → 유료 API → 저가 API → 무료 프로바이더 순으로 4개 스텝을 추가합니다. 그 콤보를 모델 ID로 지정해 요청을 보내고, 각 단계에서 폴백이 일어나는 것을 Analytics 탭에서 관찰합니다.
대시보드 → Context & Cache → Compression Studio를 엽니다. git diff 출력 결과를 붙여넣고 RTK 엔진으로 압축한 전후 토큰 수를 비교합니다. 이어서 같은 텍스트에 Caveman을 적용해 보고, 두 결과의 차이를 분석합니다.
레포를 클론하고 npm install && npm run dev로 개발 서버를 시작합니다. open-sse/services/compression/engines/에 새 엔진 파일을 만들고 id, compress(), getConfigSchema()를 구현합니다. registry.ts에 등록한 후 Compression Studio에서 새 엔진이 나타나는지 확인합니다.
한 주씩 따라가는 계획.
| 주차 | 주제 | 학습 자료 |
|---|---|---|
| 1주차 | HTTP 프록시·리버스 프록시 기초 | MDN: HTTP 개요 · nginx 프록시 문서 · OmniRoute README Quick Start |
| 2주차 | OpenAI API 형식 이해 + SSE 스트리밍 | OpenAI API Reference · open-sse/handlers/chatCore/ 코드 읽기 |
| 3주차 | 서킷 브레이커·폴백 패턴 (분산 시스템) | Martin Fowler CircuitBreaker · docs/architecture/RESILIENCE_GUIDE.md |
| 4주차 | MCP(Model Context Protocol) 이해 | Anthropic MCP 공식 문서 · open-sse/mcp-server/ · docs/frameworks/MCP-SERVER.md |
| 5주차 | 토큰 압축 알고리즘 (RTK·Caveman) | Caveman GitHub(JuliusBrussee) · RTK GitHub · docs/compression/COMPRESSION_ENGINES.md |
| 6주차 | Next.js App Router + Express 통합 | Next.js 공식 문서 App Router · src/app/ 구조 분석 |
| 7주차 | Electron 데스크탑 앱 구조 | Electron 공식 문서 · electron/README.md · electron/main.js |
| 8주차 | 내 프로젝트에 AI 게이트웨이 이식 | OmniRoute npm 패키지 활용 · @omniroute/opencode-provider 플러그인 |
본문에 나온 용어 빠른 참조.
| 용어 | 의미 |
|---|---|
| AI 게이트웨이 | 여러 AI 프로바이더 앞에서 요청을 받아 알맞은 곳으로 전달하는 중간 서버 |
| 프록시 (Proxy) | 클라이언트와 서버 사이에서 요청을 대신 전달하는 중계 서버. 로컬에서 돌면 "로컬 프록시" |
| 폴백 (Fallback) | 주요 경로가 실패했을 때 자동으로 대체 경로로 전환하는 메커니즘 |
| 콤보 (Combo) | OmniRoute에서 여러 프로바이더를 하나의 폴백 체인으로 묶은 설정. 17가지 전략 선택 가능 |
| RTK 압축 | 터미널 출력(git, 테스트 로그 등)에서 중복·불필요한 내용을 제거하는 압축 엔진 |
| Caveman 압축 | 자연어 텍스트의 군더더기(헤징 표현, 반복 문맥 등)를 제거하는 압축 엔진. 평균 65% 절감 |
| SSE (Server-Sent Events) | 서버에서 클라이언트로 데이터를 실시간 스트리밍하는 단방향 HTTP 기술 |
| MCP | Model Context Protocol. AI가 외부 도구를 표준화된 방식으로 쓸 수 있게 해주는 Anthropic 프로토콜 |
| A2A | Agent-to-Agent. 에이전트끼리 직접 통신하는 프로토콜. JSON-RPC 2.0 기반, 6개 스킬 |
| 서킷 브레이커 | 연속 실패 시 트래픽을 일시 차단해 전체 시스템을 보호하는 패턴 |
| LKGP | Last Known Good Provider. 직전에 성공한 프로바이더를 우선 선택하는 Auto-Combo 기본 전략 |
| TLS 스텔스 | TLS 핸드셰이크 지문(JA3/JA4)을 변조해 특정 국가·네트워크의 AI 차단을 우회하는 기법 |
| Electron | 웹 기술(HTML/CSS/JS)로 데스크탑 앱을 만들 수 있게 해주는 프레임워크. VS Code도 Electron으로 만들어졌습니다 |
| PWA | Progressive Web App. 브라우저에서 앱처럼 설치·사용할 수 있는 웹 애플리케이션 |
| 토큰 (Token) | AI 모델이 텍스트를 처리하는 단위. 영어는 단어 약 0.75개, 한국어는 더 많이 소모. API 비용의 기준 |
| 포맷 번역 | OpenAI, Claude, Gemini 등 각각 다른 API 요청/응답 형식을 서로 변환하는 것 |