Claude Code, Cursor 또는 자체 Agent에서 base_url 하나만 바꾸면 Claude, GPT, Gemini, DeepSeek, Kimi 등 수백 개 모델을 단일 OpenAI 호환 API로 전환할 수 있습니다—이는 OpenRouter만의 기능이 아닙니다. OmniRoute는 2026년 GitHub에서 가장 빠르게 성장하는 오픈소스 AI 게이트웨이 중 하나입니다: MIT 라이선스, 셀프 호스팅, 카탈로그 290+ 프로바이더, 500+ 모델(90+ 무료 티어). 이 가이드는 개요, 첫 API 호출, Claude Code 연동, 프로덕션 보안 체크리스트를 다룹니다.
OmniRoute란 무엇이며 무엇을 해결하는가
요약하면: OmniRoute는 자신의 머신에서 실행되는 LLM 리버스 프록시입니다. 업스트림에는 통합 /v1/chat/completions(및 Anthropic /v1/messages, Gemini /v1beta/models 등)를 노출하고, 다운스트림에는 프로바이더 API 키, OAuth 구독, 무료 풀을 연결합니다.
일반적인 사용 사례
- 다중 키 폴백: Claude 구독 한도 도달 시
- 단일 Agent 진입점: Claude Code, Cursor, Cline이 감사 로그 공유
- 데이터 내부 유지: 요청 경로에 제3자 프록시 없음
- 예산 및 할당량: Auto Combo 예산 라우팅 가이드 참조
OmniRoute vs OpenRouter vs LiteLLM
| 항목 | OmniRoute | OpenRouter | LiteLLM Proxy |
|---|---|---|---|
| 호스팅 | 셀프 호스팅 | 클라우드 SaaS | 셀프 호스팅(Python) |
| 과금 | 프로바이더 요금 + 자체 인프라 | 선불 토큰 + ~5.5% 충전 수수료 | 프로바이더 요금 + 자체 인프라 |
| 카탈로그 | 290+ 프로바이더 / 500+ 모델 | 300+ 호스팅 모델 | 설정에 따름 |
| 적합 대상 | 로컬 게이트웨이, 복수 구독, 예산 관리 | 빠른 실험, 운영 부담 없음 | 최소 Python 프록시 |
토큰 단가표는 OpenRouter 가격 비교를, Agent 요청 예산은 Auto Combo 예산 라우팅을 참조하세요.
설치 및 시작(Docker / npm)
Docker(권장)
docker run -d --name omniroute \
-p 20128:20128 \
-v omniroute-data:/data \
diegosouzapw/omniroutehttp://localhost:20128 → /dashboard를 엽니다.
npm(로컬 빠른 시험)
npm install -g omniroute
omniroute클라우드 Mac 팁
Zilmac 클라우드 Mac에서 OmniRoute를 실행하면 고정 IP와 SSH 접근이 가능합니다—LLM 게이트웨이와 xcodebuild를 동일 또는 별도 호스트에서 함께 사용하세요.
Dashboard 4단계
- API Key 생성—모든 클라이언트는
Authorization: Bearer <key>사용. - 프로바이더 연결—OAuth, API 키 붙여넣기, 또는 무료 no-auth 풀(시험용만).
- 클라이언트 지정—
http://<host>:20128/v1로 설정. - 사용량 모니터링—키 없는 관리 경로는
401반환.
전체 모델 목록: GET /v1/models
export OMNI_KEY="your-omniroute-api-key"
curl -s http://localhost:20128/v1/models \
-H "Authorization: Bearer $OMNI_KEY" | jq '.data | length'첫 API 호출(curl / Python / Node)
모델 ID는 provider/model 형식을 사용하세요. 접두사 생략 시 자동 추가될 수 있으며, 불일치 시 400을 반환합니다.
curl
curl -s http://localhost:20128/v1/chat/completions \
-H "Authorization: Bearer $OMNI_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"anthropic/claude-sonnet-4-6","messages":[{"role":"user","content":"Explain OmniRoute in one sentence"}],"max_tokens":256}'Python
from openai import OpenAI
client = OpenAI(api_key="your-key", base_url="http://localhost:20128/v1")
print(client.chat.completions.create(
model="openai/gpt-5.4",
messages=[{"role": "user", "content": "Hello"}],
).choices[0].message.content)스트리밍
curl -N http://localhost:20128/v1/chat/completions \
-H "Authorization: Bearer $OMNI_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"deepseek/deepseek-chat","messages":[{"role":"user","content":"Count to 5"}],"stream":true}'Anthropic Messages
네이티브 Anthropic 클라이언트는 POST /v1/messages를 사용할 수 있습니다. 전체 엔드포인트: API Reference.
auto/* 의도 별칭 및 폴백
auto/best-coding 같은 별칭은 할당량 내 건강한 모델을 선택—프로바이더 교체 시 클라이언트 변경 불필요. 프로덕션에서는 예산 라우팅으로 원치 않는 무료 티어 폴백을 방지하세요.
curl -s http://localhost:20128/v1/chat/completions \
-H "Authorization: Bearer $OMNI_KEY" -H "Content-Type: application/json" \
-d '{"model":"auto/best-coding","messages":[{"role":"user","content":"quicksort"}]}'Claude Code, Cursor, Copilot
| 클라이언트 | 설정 | 참고 |
|---|---|---|
| Claude Code | ANTHROPIC_BASE_URL=http://host:20128 | OAuth 또는 API 라우팅 |
| Cursor | OpenAI Base URL 재정의 → /v1 | OmniRoute 키를 API 키로 |
| Cline / Continue | OpenAI 호환 프로바이더 | auto/best-coding 시도 |
프로덕션 및 보안 체크리스트
- 최신 릴리스(v3.8.50+)로 업그레이드; 기본 비밀번호 제거;
- TLS 없이 포트
20128을 공용 인터넷에 노출하지 말 것; - 멤버별 API 키, 토큰 한도, IP 허용 목록;
- 무료 풀은 폴백용만;
/data볼륨 백업.
자주 묻는 질문
400 model not found?
provider/model 철자와 Dashboard 프로바이더 연결을 확인하세요. auto/best-free로 체인을 검증하세요.
로컬 Ollama?
예—POST /v1/api/chat으로 로컬 모델을 동일 라우팅 테이블에 통합합니다.
OpenRouter와 함께 사용?
예—OmniRoute는 OpenRouter를 다운스트림 프로바이더로 처리해 하이브리드 구성이 가능합니다.
모델은 게이트웨이, 빌드는 클라우드 Mac
OmniRoute가 LLM을 선택하고, iOS/macOS 파이프라인에는 Xcode가 필요합니다. Zilmac 클라우드 Mac은 서명, 공증, TestFlight를 Agent 워크플로와 함께 처리합니다.