OmniRoute로 Claude Code와 Codex를 한 엔드포인트에 묶기

개요

Claude Code, Codex, Cursor를 함께 쓰면 모델 설정이 도구마다 흩어집니다. API 키도 여러 곳에 들어가고, 무료 한도나 fallback 상태를 한 화면에서 보기 어렵습니다.

OmniRoute는 이 지점을 한곳에 묶는 AI gateway입니다. 공식 README 기준으로 http://localhost:20128/v1 엔드포인트 하나에 Claude Code, Codex, Cursor, Cline, Copilot 같은 도구를 붙이고, 뒤쪽 provider와 모델 선택은 OmniRoute가 담당합니다. 직접 돌려보지는 않았습니다. 문서 기준으로 정리했습니다.

시스템 아키텍처

흐름은 단순합니다.

• 개발 도구: Claude Code, Codex, Cursor 같은 클라이언트.
• OmniRoute: OpenAI 호환 /v1 endpoint, API key, provider, combo, fallback 관리.
• 모델 공급자: Anthropic, OpenAI, Gemini, DeepSeek, Groq, Mistral 등.
• 대시보드: 사용량, provider 연결, CLI 설정, free tier 상태 확인.

저라면 여러 CLI를 동시에 쓰는 개인 서버 환경에서 먼저 봅니다. 앞서 정리한 Docker 설치 흐름과 비슷하게, 한 번 띄워 놓고 여러 도구가 같은 주소를 보게 만드는 구조입니다. 관련 Docker 기본 작업은 https://windowshyun.tistory.com/48 글 흐름과 같이 보면 됩니다.

1. 핵심 가치와 라우팅 구조

OmniRoute가 내세우는 핵심은 세 가지입니다.

• endpoint 단일화: 도구마다 provider 설정을 반복하지 않고 http://localhost:20128/v1 하나를 사용.
• fallback: provider 한도가 끝나거나 실패할 때 combo 순서에 맞춰 다음 모델로 이동.
• 사용량 확인: dashboard에서 free tier, provider, CLI tool 설정을 같이 확인.

공식 README에는 265 providers, 90+ free providers, RTK + Caveman compression, MCP/A2A 지원이 적혀 있습니다. 무료 토큰 숫자는 provider 약관과 계정 상태에 따라 달라질 수 있으니 운영 비용 계산에 그대로 넣으면 위험합니다. 저는 이 부분을 할인 정보보다 라우팅 구조로 보는 쪽이 낫다고 봅니다.

2. 설치와 준비

Node.js 22.22.2 이상 또는 24.x가 필요합니다. npm 설치는 아래처럼 진행합니다.

npm install -g omniroute
omniroute

서버나 Docker 환경이면 공식 Docker image를 쓸 수 있습니다.

docker run -d   --name omniroute   --restart unless-stopped   --stop-timeout 40   -p 20128:20128   -v omniroute-data:/app/data   diegosouzapw/omniroute:latest

처음 설정은 dashboard에서 provider를 연결하고 Endpoint page에서 API key를 만들면 됩니다. 외부에 열 계획이면 NEXT_PUBLIC_BASE_URL, reverse proxy, TLS, 관리자 비밀번호를 먼저 확인해주시면 됩니다.

3. CLI 도구 연결과 엔드포인트

OpenAI 호환 도구는 보통 아래 값을 봅니다.

Base URL: http://localhost:20128/v1
API Key: <OMNIROUTE_API_KEY>
Model: auto

Codex 설정 예시는 이렇습니다.

model: auto
apiKey: <OMNIROUTE_API_KEY>
apiBaseUrl: http://localhost:20128/v1

Claude Code는 Anthropic gateway root를 씁니다. 문서에서는 /v1을 붙이지 말라고 적고 있습니다.

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:20128",
    "ANTHROPIC_AUTH_TOKEN": "<OMNIROUTE_API_KEY>"
  }
}

설정을 파일에 직접 쓰기 싫다면 omniroute setup-codex, omniroute setup-claude, omniroute setup-cline 같은 명령을 확인하시면 됩니다. remote server에 붙일 때는 --remote <url> --api-key <key> 옵션이 문서에 나와 있습니다.

4. 적용 환경

잘 맞는 경우입니다.

• Claude Code와 Codex를 같이 쓰는 개발 환경.
• provider API key가 여러 개로 늘어난 환경.
• 무료 한도, 구독 한도, fallback 순서를 한 화면에서 보고 싶은 경우.
• 로컬 PC보다 VPS나 Docker에 gateway를 올려 두는 쪽이 편한 경우.

굳이 필요 없는 경우도 있습니다. ChatGPT나 Claude 앱 하나만 쓰고, API key를 여러 도구에 나눠 넣을 일이 없다면 OmniRoute가 한 층 더 늘어납니다. 이게 전부입니다.

확인

설치 뒤에는 아래 순서로 확인하시면 됩니다.

omniroute doctor
curl http://localhost:20128/v1/models -H "Authorization: Bearer <OMNIROUTE_API_KEY>"

omniroute doctor에서 fail 항목이 없고, /v1/models 응답에 모델 목록이 나오면 기본 연결은 정상입니다.