OmniRoute

무엇인가

OmniRoute는 여러 LLM 제공자를 하나의 엔드포인트 뒤로 묶는 오픈소스 AI 게이트웨이다. MIT 라이선스로 공개되어 있고 TypeScript로 작성됐다. 저장소 설명 기준으로 375개 제공자와 1,400개 이상 모델을 단일 엔드포인트에서 중계하며, 그중 150개 이상이 무료 티어다. Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax 같은 모델 계열을 같은 인터페이스로 호출할 수 있다. 분류상 AI Gateways, 즉 프록시 계층에 속한다. 애플리케이션이 제공자별 SDK와 인증 방식을 각각 다루는 대신, OmniRoute가 그 앞단에서 요청을 받아 적합한 제공자로 넘긴다. Claude Code, Codex, Cursor, OpenCode, Cline, Copilot 같은 코딩 도구가 이 엔드포인트를 통해 동작하도록 붙는다. 데스크톱 앱과 PWA 형태의 실행 방식도 함께 제공된다.

어떻게 동작하나

설계 동기는 무료 티어를 손으로 쌓는 작업의 비용에 있다. 제공자마다 SDK가 다르고, 레이트 리밋이 다르고, 남은 할당량을 파악할 방법도 제각각이다. OmniRoute는 이 문제를 카탈로그로 다룬다. 34개 반복 풀 키에 걸친 467개 무료 티어 항목을 수집하고, 월 예산이 공개된 17개 풀과 Groq의 모델별 상한 5개를 기준으로 토큰 헤드라인을 계산한다. 같은 풀을 공유하는 항목은 중복 제거한다. 지역 신원 확인이 있어야 열리는 할당량(현재 ModelScope)은 별도로 표시하고 헤드라인에 합산하지 않는다. 그 결과는 대시보드 /dashboard/free-tiers 에서 확인할 수 있다. 수치는 2주마다 재감사되며 제공자가 무료 티어를 닫으면 내려가고 새로 열리면 올라간다. 전체 방법론은 docs/reference/FREE_TIERS.md 에 정리되어 있다.

무엇과 다른가

핵심 동작은 할당량을 인식하는 자동 폴백이다. 요청이 들어오면 게이트웨이가 현재 사용 가능한 경로를 평가하고, 소진되거나 거부된 경로 대신 다른 적격 경로로 넘긴다. 여기서 auto 라우팅은 적격 경로가 있어야 성립한다. 새로 설치한 상태에서는 키 없이 쓸 수 있는 대상이 하나도 없을 수 있고, 키가 필요 없는 제공자라도 제3자 클라이언트를 거부할 수 있다. tos: avoid 로 표시된 제공자, 예를 들어 Kiro는 기본적으로 자동 라우팅에서 제외되며 계정을 연결해도 이 설정은 바뀌지 않는다. 압축 계층도 라우팅과 함께 동작한다. RTK와 Caveman 압축이 토큰을 15~95% 절감한다고 저장소는 밝힌다. MCP와 A2A 프로토콜을 통해 외부 도구·에이전트와 연결된다.

어떻게 쓰나

구성 요소는 크게 네 층으로 나뉜다. 첫째는 단일 엔드포인트를 노출하는 게이트웨이 계층이다. 둘째는 제공자·모델·무료 티어를 담는 카탈로그로, /dashboard/free-tiers 페이지와 docs/reference/FREE_TIERS.md 가 이 데이터를 보여준다. 셋째는 RTK와 Caveman 압축 계층이다. 넷째는 MCP·A2A 인터페이스와 데스크톱·PWA 클라이언트다. 연동 예시는 examples/quickstart/ 아래에 Python, Node.js, PHP, cURL용 스크립트로 제공된다. 파트너 경로도 별도로 붙는다. Cheaper Inference는 Chat Completions, /v1/responses, 비전, 도구 호출과 이미지 모델 3종(grok-imagine, nano-banana-pro, nano-banana-2)을 cheaperinference/<model> 형태로 노출한다. Kimi는 kimi-k3 직접 API와 Kimi Code 코딩 플랜(OAuth 및 API 키) 두 경로로 지원된다.

전제와 한계

직접 SDK 통합과 비교하면 차이는 추상화 위치에 있다. 제공자별 클라이언트를 애플리케이션 안에 두면 제공자 교체가 코드 변경을 부르지만, 게이트웨이를 두면 교체가 라우팅 설정 변경으로 끝난다. 대신 홉이 하나 늘고, 게이트웨이가 제공자별 차이를 흡수하지 못하는 기능은 그대로 제약으로 남는다. 단일 제공자 게이트웨이와 비교하면 커버리지와 정책의 트레이드오프가 다르다. OmniRoute는 제공자 계정을 사용자가 직접 가져오는 모델이며, 토큰을 지급하는 것이 아니다. 각 제공자가 자기 한도와 가용성, 약관을 통제한다. tos: avoid 제공자를 자동 라우팅에서 빼는 결정도 커버리지를 줄이는 대신 약관 위반 위험을 줄이는 쪽을 택한 것이다. 무료 티어 수치가 양방향으로 움직인다는 점도 전제로 깔린다.

설치 절차는 README의 📦 Install 절과 🆓 Install, connect a provider, then route through one endpoint 절로 나뉜다. 순서는 설치, 제공자 연결, 단일 엔드포인트 라우팅이다. 붙여넣기용 퀵스타트 스크립트는 Python, Node.js, PHP, cURL 네 가지로 examples/quickstart/ 아래에 있다. 제공자를 고르기 전에 Free Tiers Guide를 읽는 것이 전제로 깔린다. 실패하기 쉬운 지점은 auto 라우팅이다. auto는 적격 경로가 있어야 성립하고, 새로 설치한 상태에서는 키 없이 쓸 수 있는 대상이 하나도 없을 수 있다. 키가 필요 없는 제공자라도 제3자 클라이언트를 거부할 수 있다. tos: avoid로 표시된 제공자, 예를 들어 Kiro는 기본적으로 자동 라우팅에서 제외되며 계정을 연결해도 이 설정은 바뀌지 않는다. 따라서 설치 직후에는 자격 증명을 먼저 연결하고, 대시보드 /dashboard/free-tiers에서 어떤 풀이 적격인지 확인한 뒤 라우팅을 켜는 순서가 안전하다. 전체 방법론은 docs/reference/FREE_TIERS.md에 있다.

버전 표기는 README의 로드맵 절에 `v3.9.0 LTS`를 향한다고 적혀 있다. The Gateway Keeps Growing 절과 ✨ What's New 절이 릴리스 흐름을 보여주고, 저장소 설명은 900명 이상의 기여자를 언급한다. 구버전 정리나 마이그레이션 절차는 README에 없다. 따라서 특정 버전에서 다른 버전으로 옮기는 경로는 릴리스 노트와 로드맵을 직접 확인해야 한다. LTS라는 표기는 해석상 장기 지원 라인을 유지하겠다는 의도로 읽히지만, README가 그 정의나 지원 기간을 명시하지는 않으므로 계약으로 받아들이면 안 된다. 카탈로그 쪽 변동은 버전과 별개로 움직인다. 무료 티어 수치는 2주마다 재감사되어 제공자가 티어를 닫으면 내려가고 새로 열면 올라간다. 즉 게이트웨이 버전이 고정되어 있어도 헤드라인 숫자는 달라질 수 있다.

README가 제시하는 수치는 두 축이다. 하나는 압축이다. RTK와 Caveman 압축이 토큰을 15~95% 절감한다고 저장소는 밝힌다. 다른 하나는 무료 티어 합산이다. 월 약 1.62B 토큰이라는 헤드라인은 OmniRoute가 지급하는 토큰이 아니라 별도로 자격을 갖춘 제3자 무료 티어의 추정 합계다. 이 값은 34개 반복 풀 키에 걸친 467개 무료 티어 항목에서, 월 예산이 공개된 17개 풀과 Groq의 모델별 상한 5개를 기준으로 계산한다. 같은 풀을 공유하는 항목은 중복 제거한다. 지역 신원 확인이 있어야 열리는 할당량(현재 ModelScope)은 별도로 표시하고 약 6M을 헤드라인에 합산하지 않는다. 계산 방식이 보수적인 이유는 과대 계산을 피하기 위해서다. 압축은 라우팅과 직교하는 절감 축이라, 어느 제공자로 가든 적용된다.

전제는 명확하다. 제공자 계정을 사용자가 직접 가져와야 하고, 각 제공자가 자기 한도와 가용성, 약관을 통제한다. auto 라우팅은 적격 경로가 있어야 성립하며, tos: avoid로 표시된 제공자는 계정을 연결해도 자동 라우팅에서 빠진다. 지역 신원 확인이 필요한 할당량은 헤드라인에서 분리된다. 판단 기준은 조건으로 갈린다. 여러 제공자를 오가며 비용을 낮추고 제공자 교체를 설정 변경으로 끝내려는 조건이면 게이트웨이 계층을 두는 편이 맞다. 반대로 단일 제공자로 충분하거나 제공자 고유 기능을 그대로 써야 하는 조건이면 직접 SDK 통합이 홉을 줄인다. 무료 티어 수치가 양방향으로 움직인다는 점 때문에, 그 숫자를 고정 예산의 근거로 삼는 조건에서는 이 도구가 맞지 않는다.