OmniRoute는 TypeScript로 작성된 셀프호스팅 AI 게이트웨이다. Docker 한 줄로 띄울 수 있고, OpenAI 호환 엔드포인트 하나로 여러 provider를 통합接入한다. 자동 fallback, 쿼터 추적, 긴 컨텍스트 압축 기능을 갖추고 있다. Claude Code, Cursor, Codex의 base URL을 이쪽으로 가리키기만 하면 모델을 자유롭게 바꿔 쓸 수 있다.
해결하려는 문제
Claude Code, Cursor, Codex 같은 AI 코딩 도구는 기본적으로 단일 provider에 종속되어 있다. 모델을 바꾸려면 설정을 수정해야 하고, 무료 쿼터를 여러 계정에 나눠 쓰려면 rate limit까지 전부 외워야 한다. OmniRoute는 바로 그 추상화 레이어를 없애버린다.
OpenAI 호환 엔드포인트 하나가 여러 provider와 model을 받는다. 일부 provider는 무료 티어를 제공한다. 백엔드에서 자동으로 쿼터를 계산하고, 실패하면 다음으로 넘기고, 긴 컨텍스트는 압축한다. 목표는 "분산된 무료 쿼터"를 하나의 풀로 만드는 것이다.
사용 방법
Docker로 한 줄 배포한다:
docker run -d -p 3500:3500 diegosouzapw/omniroute
서비스는 http://localhost:3500에서 동작한다.
Claude Code나 Cursor의 base URL을 http://localhost:3500/v1로 바꾸고, API key는 아무 값이나 넣으면 된다(OmniRoute가 자체 인증을 처리하므로 이건 그냥 자리 표시용이다).
OpenAI SDK로 직접 호출해도 된다:
import OpenAI from 'openai';
const client = new OpenAI({
baseURL: 'http://localhost:3500/v1',
apiKey: 'any-string',
});
const r1 = await client.chat.completions.create({
model: 'anthropic/claude-sonnet',
messages: [{ role: 'user', content: 'Write a Python quicksort' }],
});
console.log(r1.choices[0].message.content);
호출 체인이 호출자에게는 투명하게 보인다. SDK는 수정할 필요 없다.
동작 원리(아키텍처)
세 가지 핵심 모듈로 구성된다:
1. Provider Adapter 레이어. 여러 provider(OpenAI, Anthropic, Gemini)의 API 차이를 통일된 인터페이스로 정규화한다. 한 번만 작성해두면 이후 provider 교체 시 코드 수정이 없다.
2. Quota Tracker + Fallback Router. 각 provider의 남은 쿼터를 실시간으로 추적한다. 요청이 들어오면 먼저 쿼터를 확인하고, 잔여량이 있으면 발송한다. 실패하거나 rate limit에 걸리면 정책(라운드로빈, 우선순위, cost-aware)에 따라 다음 provider로 전환한다. 일반 프록시와의 가장 큰 차이점은 "어느 provider가 거의 한계에 가까운지" 알고 있다는 점이다.
3. 압축 레이어. 요청 전에 system prompt와 컨텍스트를 압축하고, 응답 후에는 도구 호출 결과를 압축한다. README에 따르면 유의미한 비율의 토큰을 절약한다고 한다.
흐름: Client → 압축 레이어 → Router(쿼터 확인)→ Provider Adapter → 외부 API → 압축 후 반환.
장점과 단점
장점:
- OpenAI 호환 엔드포인트라 기존 도구를 그대로 연동할 수 있다.
- 여러 provider를 지원하며(자세한 목록은 공식 문서 참고), 중국어권 사용자 입장에서 매력적인 선택지가 많다.
- TypeScript 풀스택 셀프호스팅에 Docker 한 줄 배포까지, 진입 장벽이 낮다.
- Claude Code, Codex, Cursor, OpenCode, Cline 등 주요 AI 코딩 도구와 호환된다.
- MCP 프로토콜을 지원한다.
단점:
- README의 마케팅성 수치를 주의 깊게 봐야 한다. "월 ~1.51B 무료 tokens 집계" 같은 숫자는 모든 무료 티어를 단순 합산한 값이지 실제 가용량이 아니다. 실제로는 각 provider의 ToS와 rate limit에 달려 있다.
- 셀프호스팅이라는 것은 곧 직접 서비스를 돌리고, 쿼터를 모니터링하고, 각 API key를 갱신해야 한다는 뜻이다. 운영 비용이 0은 아니다.
- 여러 provider에 의존하기 때문에 어느 한 곳이라도 ToS가 바뀌면 영향을 받는다. 특정 provider가 무료 티어를 종료하면 라우팅 경로가 비어버린다.
- 압축 레이어는 코딩 에이전트 시나리오에서 효과적이지만, 길고 복잡한 대화에서는 품질 손실이 있을 수 있다. 압축률이 높을수록 정보 손실도 커진다.
이런 사용자에게 추천 / 비추천
추천 대상:
- 여러 provider의 무료 쿼터를 활용해보고 싶은 개인 개발자
- Claude Code나 Cursor를 쓰면서国产 모델로 전환하고 싶은 사용자
- 데이터 흐름을 직접 통제하는 걸 좋아하는 셀프호스팅 마니아
- AI 에이전트 라우팅 레이어를 커스터마이징하려는 팀
비추천 대상:
- 엔터프라이즈 운영 환경 — 무료 티어의 안정성에는 SLA가 없다
- 단일 provider만 쓰고 쿼터도 충분한 사람 — 오히려 복잡도만 늘어난다
- 지연 시간에 민감한 고빈도 운영 시나리오 — 게이트웨이를 한 번 더 거치면 그만큼 지연이 추가된다
편집자의 생각
OmniRoute는本质上 OpenRouter의 오픈소스 셀프호스팅 버전이다. 핵심 가치는 "1.51B tokens" 같은 과장된 숫자가 아니라, "AI 코딩 도구가 반드시 단일 provider에 묶여야 한다"는 제약을 깨뜨렸다는 데 있다.
사용자 입장에서 가장 실질적인 의미: Cursor나 Claude Code 안에서 DeepSeek, GLM, Kimi 같은 모델의 무료 티어로 전환할 수 있다. Anthropic의 IP 제한이나 쿼터 동결 걱정을 덜 수 있다는 점에서保险 같은 역할을 한다.
과거 LiteLLM 류 프로젝트와의 차이점은 OmniRoute가 AI 코딩 에이전트 시나리오에 특화됐다는 것이다. 컨텍스트 압축과 쿼터 인지 fallback을 추가했다. 이 두 기능은 예전에는 Cloudflare AI Gateway, Portkey 같은 엔터프라이즈 API 게이트웨이에만 있던 것이고, 이제 Docker 컨테이너 하나로 개인도 돌릴 수 있게 됐다. 진입 장벽이 "SaaS 구매"에서 "이미지 하나 pull"로 낮아진 것이다.
아직 확인이 필요한 부분: 정확한 지원 provider 수와 무료 티어 가용성(소규모 provider 상당수는 집계 사이트나 2차 래퍼일 가능성이 있어 안정성이 의문이다), 핵심 메인테이너의 활동성(1인 프로젝트의 bus factor는 1), 코드 생성 품질에 대한 압축의 구체적 영향은 더 많은 벤치마크가 필요하다.