Cursor, Claude Code, Codex, Gemini CLI는 주소와 비밀을 각자 기억합니다. 공급자가 늘면 한도와 “오늘은 429”가 설정마다 흩어집니다. OmniRoute는 그 일을 내 머신의 OpenAI 호환 입구 하나로 모읍니다. 클라이언트가 기억하는 주소는 http://127.0.0.1:20128/v1 입니다. Claude, GPT, Gemini, DeepSeek와 카탈로그의 다른 모델은 대시보드에서 붙입니다. 라이선스는 MIT이고, 이 글이 따르는 릴리스는 release/v3.8.53 입니다. 포트, 명령, 라우팅은 그 README를 기준으로 하고, 공급자 수는 버전에 따라 움직입니다.
「무료」는 게이트웨이 소프트웨어에 사용료가 없다는 뜻입니다. 한도는 연결한 공급자 계정에 있습니다. 공식은 제3자 무료 등급을 /dashboard/free-tiers 추정치로 보여 주고, 그것은 합계이지 OmniRoute가 주는 토큰이 아니라고 적습니다. 이미 내는 구독도 그 계정 절차로 같은 주소를 공유할 수 있습니다. 정가를 보려면 코딩 도구 월 청구와 OpenRouter 요금을 대조하세요. OpenRouter는 호스팅된 라우터이고, OmniRoute는 내 머신의 게이트웨이입니다.
게이트웨이가 있는 층
내 머신에서만 도는 변환 소켓으로 보면 됩니다. 업스트림은 그대로 OpenAI, Anthropic, Google, DeepSeek 또는 카탈로그의 다른 공급자입니다. 다운스트림은 OpenAI Chat Completions나 Responses를 말하는 클라이언트입니다. v3.8.53 문서 기준은 공급자 약 375곳, 원본 모델 ID 약 1475개이고, 일부에 무료 등급 발견 표시가 있습니다. 이 숫자는 재검토되므로 옛 스크린샷이 아니라 대시보드 카탈로그를 봅니다.
- 열쇠는 두 개입니다.공급자 API key나 OAuth는 OmniRoute 안에만 둡니다. Cursor와 스크립트가 쓰는 것은 Dashboard → Endpoints의 게이트웨이 키입니다.
- 모델 이름은 연결한 뒤에 의미가 있습니다.먼저
/v1/models를 호출하고, 돌아온 ID를 씁니다. README 예는openai/gpt-5.4,glm/glm-5.2처럼 「공급자/모델」입니다. 목록에 실제로 있는 것을 씁니다. - 클라이언트 폭이 넓습니다.Claude Code, Codex, Cursor, Cline, Continue, OpenCode, Copilot, OpenClaw 등이 이름에 있습니다. OpenAI Base URL을 바꿀 수 있으면 주소만 넣으면 됩니다.
omniroute run은 CLI 7개를 띄웁니다.
README 문구는 Bring your own provider accounts입니다. 무료 등급은 가입, 심사, 결제 수단이 필요할 수 있고 닫힐 수도 있습니다. tos: avoid 공급자는 기본적으로 auto에 들어가지 않습니다. 계정을 연결해도 이 정책은 자동으로 바뀌지 않습니다.
처음부터 설치: npm과 Docker
머신에 Node.js가 필요합니다. 짧은 경로는 이렇습니다.
npm install -g omniroute
omniroutenpm warn ERESOLVE와 peer 경고는 문서에서 일단 무시해도 된다고 합니다. 뜨면 http://127.0.0.1:20128 이 대시보드이고, API는 http://127.0.0.1:20128/v1 입니다. 대시보드 없이 프록시만 쓰려면 omniroute serve --headless 또는 OMNIROUTE_HEADLESS=1 입니다.
npm 11은 설치 스크립트를 허용해야 함
npm 11은 패키지 생명주기 스크립트를 막을 수 있습니다. OmniRoute의 postinstall이 돌아야 네이티브 런타임 파일이 준비됩니다. 3.8.53 문서의 허용 목록은 다음과 같습니다.
npm install -g --allow-scripts=omniroute,keytar,onnxruntime-node,@parcel/watcher,@swc/core,protobufjs,esbuild omniroutenpm이 다른 이름을 보여 주면 그 경고의 이름을 씁니다. 허용하면 그 패키지의 설치 스크립트가 실행되므로, 출처를 확인한 뒤에 합니다. CI나 느린 머신은 OMNIROUTE_SKIP_POSTINSTALL=1로 네이티브 SQLite 예열만 건너뜁니다. 바이너리 복사는 그대로 돕니다.
코딩 부하에 맞춰 Docker 메모리를 늘림
문서의 이미지 이름은 여전히 diegosouzapw/omniroute 입니다. :latest는 게시된 최고 안정 SemVer를 따르고 git main은 따르지 않습니다. 남겨 둘 환경은 버전을 고정합니다. 공식 예는 루프백에 바인드합니다.
docker run -d --name omniroute --restart unless-stopped --stop-timeout 40 \
-e OMNIROUTE_MEMORY_MB=8192 --memory=10g \
-p 127.0.0.1:20128:20128 -v omniroute-data:/app/data diegosouzapw/omniroute:latest이미지 기본 힙은 1024MB로, 패널과 짧은 대화에 충분합니다. Claude Code와 Codex는 POST /v1/responses를 씁니다. 긴 컨텍스트에는 더 큰 V8 힙이 필요하고, 부족하면 프로세스가 메모리 치명 오류로 죽습니다. 코딩 에이전트 하나는 위 명령의 힙 8192, 컨테이너 최소 10g입니다. 긴 요청이 겹치면 힙 10240–12288, 컨테이너 12–16g입니다. Apple Silicon은 이미지의 arm64를 씁니다. 볼륨 omniroute-data에 비밀이 있으니 백업과 삭제도 기밀로 다룹니다.
Claude, GPT, Gemini, DeepSeek 연결
대시보드 Providers에서 지금 쓸 자격이 있는 곳을 고르고 API key를 붙이거나 그 계정 절차를 마칩니다. 네 곳의 키는 각 콘솔에서 받습니다. OmniRoute가 대신 개통하지 않습니다.
| 공급자 | 내가 준비할 것 | 넣는 곳 |
|---|---|---|
| OpenAI (GPT) | platform.openai.com의 API key | Providers → OpenAI |
| Anthropic (Claude) | console.anthropic.com의 key, 또는 이미 내는 Claude 구독의 계정 절차 | Providers → Anthropic / 해당 OAuth |
| Gemini | Google AI Studio의 key, 또는 Gemini CLI OAuth | Providers → Gemini |
| DeepSeek | platform.deepseek.com의 API key | Providers → DeepSeek |
무료 등급은 별도 목록이며 이 네 키의 다른 이름이 아닙니다. 첫 실행 마법사에 「무료 공급자 설정」이 나올 수 있고, 그때의 무인증 카탈로그로 목록을 만든 뒤 확인한 것만 연결을 만듭니다. 완료를 눌러도 몰래 추가하지 않습니다. 이름에 오른 적이 있는 것은 Pollinations, Cloudflare AI, SiliconFlow의 DeepSeek 무료 등급 등입니다. 약관, 지역, 아직 있는지는 상대가 정합니다. 옛 「키 없는 Claude」가 tos: avoid이면 기본적으로 auto에 들어가지 않습니다. 쓰기 전에 그날의 Free Tiers에서 자격을 확인합니다.
Gemini Web 같은 쿠키형 공급자는 브라우저 런타임도 필요합니다. npm 패키지에는 Playwright가 있고 Chromium 바이너리는 없습니다. 첫 호출 전에 저장소의 Playwright Chromium 안내를 따르지 않으면 브라우저 층에서 실패합니다.
IDE와 CLI가 주소 하나를 씀
Endpoints에서 게이트웨이 키를 복사한 다음 넣습니다.
Base URL: http://127.0.0.1:20128/v1
API Key: (Dashboard → Endpoints)
Model: autoIDE가 말하기 전에 모델 목록을 확인합니다.
curl http://127.0.0.1:20128/v1/models \
-H "Authorization: Bearer YOUR_KEY"
curl http://127.0.0.1:20128/v1/chat/completions \
-H "Authorization: Bearer YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"auto","messages":[{"role":"user","content":"Hello"}]}'Cursor, Cline, Continue와 OpenAI Base URL을 바꿀 수 있는 플러그인은 이 세 줄이면 됩니다. 사용자 헤더를 못 보내는 클라이언트는 문서의 토큰 호환 주소, 예를 들어 http://127.0.0.1:20128/vscode/YOUR_KEY/chat/completions 를 쓸 수 있습니다. 헤더를 보낼 수 있으면 Authorization: Bearer를 우선합니다.
CLI마다 설정 파일을 손으로 고칠 필요는 없습니다. 공식 한 줄 실행은 그 프로세스에 자격 증명을 넣습니다. Qwen과 Gemini는 일회용 격리 home도 받습니다.
omniroute run claude --model auto
omniroute run codex --model auto
omniroute run gemini --model auto
omniroute configure codexomniroute run은 Claude Code, Codex, Aider, Goose, OpenCode, Qwen Code, Gemini CLI를 덮습니다. configure는 그 도구 자신의 설정에 공급자와 모델을 씁니다. 문서의 대상에는 codex, claude, opencode, qwen, aider, goose, gemini, cline, continue, kilo가 있습니다. --dry-run은 쓸 환경 변수와 인자만 보여 줍니다. --api-key-env NAME은 비밀을 환경 변수 이름에 남겨 셸 기록에 넣지 않습니다.
auto, 폴백, 자동 경로에 안 들어가는 쪽
auto는 이미 연결됐고 자격이 있는 연결 중에서 고릅니다. 아무것도 안 붙인 새 설치는 대상이 없어도 정상입니다. 고른 전략, 공급자, 지연은 응답 헤더 X-OmniRoute-Decision으로 돌아옵니다. 클라이언트 로그보다 이 헤더를 먼저 봅니다.
- 한도를 보는 폴백.한 연결이 한도에 닿으면 아직 여유가 있는 연결로 옮길 수 있습니다. v3.8.53에는 남은 한도로 가중하는 전략이 있고, 같은 대화는 가능하면 원래 연결에 붙잡아 둡니다.
- 구독 경로는 실패하면 멈출 수 있습니다.문서의 subscription 콤보는 이미 내는 구독 한도만 씁니다. 떨어지면 멈추고, 과금되는 다른 키로 새지 않습니다. 유료 API 키와 구독 키를 「아무 데나 폴백」하는 한 콤보에 넣지 마세요.
tos: avoid는 기본적으로 빠집니다.연결 성공이auto소속은 아닙니다. 게이트웨이 키를 모델 하나에 고정하려면 그 키의forcedModel을 쓰고, 클라이언트에 업스트림 주소를 박지 않습니다.
압축은 선택 파이프라인이고 클라이언트에는 투명합니다. 문서는 조합 가능한 엔진으로 설명하고, 실제로 쓴 세트는 X-OmniRoute-Compression에 적힙니다. 얼마나 줄는지는 모델과 요청에 달립니다. README의 구간을 매 요청의 약속으로 보지 마세요. 메모리 기능은 기본적으로 꺼져 있습니다. 자격 증명 마스킹도 선택입니다.
Cloud Mac: 루프백과 SSH
게이트웨이는 켜 둔 Mac에 맞습니다. 20128은 루프백에서 듣고, 노트북은 SSH로 그 포트를 가져옵니다. Cloud Mac은 리전이 고정되고 SSH가 되며, Apple Silicon은 공식 arm64 이미지도 돕니다. 관리 화면을 0.0.0.0에 바인드하지 마세요.
ssh -N -L 20128:127.0.0.1:20128 user@your-cloud-mac터널이 올라오면 노트북의 Cursor나 omniroute run도 http://127.0.0.1:20128/v1을 그대로 씁니다. 로컬로 보이고, 바이트는 클라우드 Mac의 루프백에 닿습니다. 공급자 비밀은 클라우드 볼륨이나 사용자 디렉터리에 두고 Git에는 넣지 않습니다. 같은 머신에서 OpenClaw를 이미 돌리면 모델 주소를 같은 /v1로 향하게 하고, 공급자 키 사본은 게이트웨이에 하나만 둡니다.
패널 로그인이 필요하면 문서에 선택적 OIDC가 있습니다. 비밀번호 로그인은 남습니다. 원격 조작에는 범위가 있는 토큰(connect / contexts / tokens)이 있고, 공식 Remote Mode를 따릅니다. 단계를 아끼려고 대시보드를 공인 IP에 걸지 마세요.
막히면 먼저 볼 곳
/v1/models가 비어 있다.Providers 연결이 성공하지 않았거나, 클라이언트가 공급자 key를 게이트웨이 키 자리에 넣었습니다.auto에 경로가 없다.제외된 공급자만 있거나, 그날 무료 등급에 자격이 없습니다. 동작하는 유료 key를 쓰거나 모델 칸에/v1/models의 구체 ID를 넣습니다.- 전역 설치 뒤 네이티브 모듈을 못 찾는다.npm 11의
--allow-scripts와 경고에 나온 패키지 이름으로 다시 설치합니다. - Docker 안 코딩 에이전트가 중간에 끝난다.
OMNIROUTE_MEMORY_MB와--memory를 코딩 부하 단계로 올립니다. 1024MB는 대시보드용으로 둡니다. - 웹 공급자 첫 요청이 실패한다.Playwright Chromium을 넣은 뒤 다시 시도합니다. 성공하기 전에 라우팅 정책을 바꾸지 않습니다.
- 숫자가 오래됐다.375곳과 1475개 모델 ID는 v3.8.53 문서 당시의 값입니다. 올린 뒤에는 대시보드와 README를 봅니다.
FAQ
짧게 말하면, 소프트웨어는 무료이고 한도는 공급자 쪽이며, 주소는 로컬 20128의 /v1이고, auto는 자격 있는 연결만 쓰며, Docker의 코딩 에이전트는 메모리를 늘리고, 포트는 루프백에 두고 SSH로 전달합니다. 전체 문답은 페이지 머리의 FAQ 구조화 데이터에 있습니다.