OmniRoute 설치 방법: 빠른 시작과 Claude Code 설정

OmniRoute는 OpenAI 호환 AI 게이트웨이입니다. 여러 업스트림 모델 제공자를 하나의 로컬 API 뒤에 모아 주므로 Claude Code, Codex CLI, IDE 확장, 직접 만든 스크립트를 한 번만 설정하면 됩니다. 이 문서는 설치부터 첫 요청 성공까지의 가장 짧은 경로이며, 주제별 전체 가이드는 별도 사이트에서 관리합니다.

이 두 주소를 기억하세요

대시보드: http://localhost:20128
OpenAI 호환 Base URL: http://localhost:20128/v1

클라이언트에는 대시보드 주소가 아니라 두 번째 주소를 입력합니다.

사전 준비

Node.js >=22.22.2 <23 또는 >=24.0.0 <27이며 Node.js 24 LTS를 권장합니다. 이 범위를 벗어나면 대시보드가 빈 화면으로 보이거나 네이티브 모듈 오류가 날 수 있습니다. 필요하면 먼저 Node.js 설치를 진행하세요.
로컬 포트 20128이 비어 있어야 합니다.
OmniRoute로 라우팅할 업스트림 제공자 계정 또는 키가 최소 하나 있어야 합니다.

설치 및 실행

방법 하나를 고르세요.

# npm(권장)
npm install -g omniroute
omniroute

# Docker
docker run -d --name omniroute -p 20128:20128 diegosouzapw/omniroute:latest

OmniRoute GitHub Releases에서 Windows, macOS, Linux용 Desktop 설치 파일을 내려받을 수도 있습니다. :latest는 가장 최근에 게시된 안정 릴리스를 가리키므로, 재현 가능한 배포가 필요하면 정확한 버전을 고정하세요.

실행한 뒤 http://localhost:20128을 엽니다. 로그인 비밀번호는 INITIAL_PASSWORD 환경 변수로 정해집니다. 업스트림의 셀프 호스팅 구성에서는 첫 실행 때 생성되어 로그에 출력되며, Docker에서는 docker logs omniroute | grep -i password로 찾을 수 있습니다. 서비스를 네트워크에 노출하기 전에 반드시 직접 정한 강력한 비밀번호로 바꾸세요.

제공자 연결과 키 생성

대시보드에서 Providers → Add Provider로 이동해 제공자를 연결합니다.
API Keys 페이지에서 새 키를 만들어 보관하세요. 한 번만 표시됩니다. 이 키는 클라이언트가 OmniRoute에 접근하기 위한 것이며 업스트림 제공자의 키가 아닙니다.

업스트림 문서에는 키 없이 쓸 수 있는 무료 제공자도 나와 있습니다. 가용성과 약관은 수시로 바뀌므로 사용하기 전에 해당 서비스의 약관을 직접 확인하세요.

서비스 확인

export OMNIROUTE_API_KEY="API Keys 페이지에서 만든 키를 붙여 넣으세요"

curl http://localhost:20128/v1/models \
  -H "Authorization: Bearer ${OMNIROUTE_API_KEY}"

모델 목록이 돌아오면 OpenAI 호환 엔드포인트와 인증이 모두 정상입니다. 이어서 최소 채팅 요청을 보내 모델이 실제로 라우팅되는지 확인합니다.

curl http://localhost:20128/v1/chat/completions \
  -H "Authorization: Bearer ${OMNIROUTE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [{ "role": "user", "content": "Reply with ok." }]
  }'

auto를 쓰면 OmniRoute가 속도, 비용, 가용성에 따라 제공자를 고릅니다. /v1/models가 돌려준 특정 모델 ID를 써도 됩니다.

도구 연결

OpenAI 형식을 지원하는 도구라면 다음 값을 입력합니다.

Base URL: http://localhost:20128/v1
API Key:  직접 만든 OmniRoute 키
Model:    auto

OmniRoute에는 한 줄로 실행하는 명령도 있습니다. 예를 들어 omniroute launch-codex --model auto가 있고, 일반 형식인 omniroute run <target>은 claude, codex, aider, goose, opencode, qwen, gemini를 지원합니다. HagiCode에서 Agent CLI를 쓰려면 먼저 AI Agent CLI 설치를 마치세요.

자주 발생하는 문제

대시보드가 빈 화면이거나 지원하지 않는 Node.js 버전 경고가 뜰 때: Node.js 24 LTS로 바꾸고 npm install -g omniroute를 다시 실행한 뒤 omniroute를 실행하세요.
npm 11에서 better-sqlite3를 찾지 못할 때: npm 11은 선택적 의존성의 설치 스크립트를 기본으로 막습니다. 문제 해결 가이드대로 직접 다시 빌드하세요.
macOS에서 slice is not valid mach-o file이 나올 때: $(npm root -g)/omniroute/app에서 npm rebuild better-sqlite3를 실행한 뒤 다시 시작하세요.