OmniRoute/docs/i18n/ko/docs/guides/USER_GUIDE.md

User Guide (한국어)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇮🇳 hi · 🇭🇷 hr · 🇭🇺 hu · 🇦🇲 hy · 🇮🇩 id · 🇳🇬 ig · 🇮🇹 it · 🇯🇵 ja · 🇬🇪 ka · 🇰🇭 km · 🇮🇳 kn · 🇱🇹 lt · 🇱🇻 lv · 🇮🇳 ml · 🇮🇳 mr · 🇲🇾 ms · 🇲🇹 mt · 🇲🇲 my · 🇳🇵 ne · 🇳🇱 nl · 🇳🇴 no · 🇮🇳 or · 🇮🇳 pa · 🇵🇭 phi · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇱🇰 si · 🇸🇰 sk · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW

---

🌐 언어: 🇺🇸 English | 🇪🇹 አማርኛ | 🇸🇦 العربية | 🇦🇿 Azərbaycan dili | 🇧🇬 Български | 🇧🇩 বাংলা | 🇨🇿 Čeština | 🇩🇰 Dansk | 🇩🇪 Deutsch | 🇬🇷 Ελληνικά | 🇪🇸 Español | 🇪🇪 Eesti | 🇮🇷 فارسی | 🇫🇮 Suomi | 🇫🇷 Français | 🇮🇪 Gaeilge | 🇮🇳 ગુજરાતી | 🇳🇬 Hausa | 🇮🇱 עברית | 🇮🇳 हिन्दी | 🇭🇷 Hrvatski | 🇭🇺 Magyar | 🇦🇲 Հայերեն | 🇮🇩 Bahasa Indonesia | 🇳🇬 Igbo | 🇮🇹 Italiano | 🇯🇵 日本語 | 🇬🇪 ქართული | 🇰🇭 ខ្មែរ | 🇮🇳 ಕನ್ನಡ | 🇰🇷 한국어 | 🇱🇹 Lietuvių | 🇱🇻 Latviešu | 🇮🇳 മലയാളം | 🇮🇳 मराठी | 🇲🇾 Bahasa Melayu | 🇲🇹 Malti | 🇲🇲 မြန်မာ | 🇳🇵 नेपाली | 🇳🇱 Nederlands | 🇳🇴 Norsk | 🇮🇳 ଓଡ଼ିଆ | 🇮🇳 ਪੰਜਾਬੀ | 🇵🇭 Filipino | 🇵🇱 Polski | 🇵🇹 Português (Portugal) | 🇧🇷 Português (Brasil) | 🇷🇴 Română | 🇷🇺 Русский | 🇱🇰 සිංහල | 🇸🇰 Slovenčina | 🇸🇮 Slovenščina | 🇷🇸 Српски | 🇸🇪 Svenska | 🇰🇪 Kiswahili | 🇮🇳 தமிழ் | 🇮🇳 తెలుగు | 🇹🇭 ไทย | 🇹🇷 Türkçe | 🇺🇦 Українська | 🇵🇰 اردو | 🇺🇿 Oʻzbekcha | 🇻🇳 Tiếng Việt | 🇳🇬 Yorùbá | 🇨🇳 中文 (简体) | 🇹🇼 中文 (繁體)

프로바이더 구성, 콤보 생성, CLI 도구 통합 및 OmniRoute 배포를 위한 완전한 가이드입니다.

---

목차

• 요금 한눈에 보기
• 사용 사례
• 제공업체 설정
• CLI 통합
• 배포
• 사용 가능한 모델
• 고급 기능
• 자동 라우팅(설정 불필요)
• MCP 및 A2A 통합
• 스킬 시스템
• 메모리 시스템
• 웹훅
• 클라우드 에이전트
• 프로그래밍 방식 관리
• 내부 CLI
• 데스크톱 애플리케이션(Electron)

---

💰 요금 한눈에 보기

등급	제공업체	비용	할당량 초기화	가장 적합한 용도
💳 구독	Claude Code (Pro)	월 $20	5시간 + 매주	이미 구독 중인 사용자
	Codex (Plus/Pro)	월 $20~200	5시간 + 매주	OpenAI 사용자
	GitHub Copilot	월 $10~19	매월	GitHub 사용자
🔑 API 키	DeepSeek	사용량 기반 과금	없음	저렴한 추론
	Groq	사용량 기반 과금	없음	초고속 추론
	xAI (Grok)	사용량 기반 과금	없음	Grok 4 추론
	Mistral	사용량 기반 과금	없음	EU에서 호스팅되는 모델
	Perplexity	사용량 기반 과금	없음	검색 증강
	Together AI	사용량 기반 과금	없음	오픈 소스 모델
	Fireworks AI	사용량 기반 과금	없음	빠른 FLUX 이미지 생성
	Cerebras	사용량 기반 과금	없음	웨이퍼 규모의 속도
	Cohere	사용량 기반 과금	없음	Command R+ RAG
	NVIDIA NIM	사용량 기반 과금	없음	엔터프라이즈 모델
	Baidu Qianfan	사용량 기반 과금	없음	ERNIE 모델
💰 저렴함	GLM-4.7	100만 개당 $0.6	매일 오전 10시	저렴한 백업
	MiniMax M2.1	100만 개당 $0.2	5시간 단위 순환 초기화	가장 저렴한 옵션
	Kimi K2	월 $9 정액제	월 1,000만 토큰	예측 가능한 비용
🆓 무료	Qoder	$0	제공업체 제한 적용	현재 카탈로그 확인
	Kiro	$0	월 약 50크레딧	무료 Claude

---

🎯 사용 사례

사례 1: "Claude Pro를 구독 중입니다"

문제: 할당량이 사용되지 않은 채 만료되고, 집중적으로 코딩할 때 속도 제한이 발생함

조합: "maximize-claude"
  1. cc/claude-opus-4-7        (구독을 최대한 활용)
  2. glm/glm-4.7               (할당량 소진 시 사용할 저렴한 백업)
  3. if/qwen3.8-max-preview       (비상시 사용할 무료 대체 모델)

월간 비용: $20(구독) + 약 $5(백업) = 총 $25
비교: $20 + 한도 도달 = 불편함

사례 2: "비용을 전혀 지출하고 싶지 않습니다"

문제: 구독료를 감당할 수 없지만 안정적인 AI 코딩이 필요함

조합: "zero-cost"
  1. if/kimi-k2.7-code          (무료 액세스로 등록됨; 속도 제한이 적용될 수 있음)
  2. kr/qwen3-coder-next        (Kiro 무료 대체 모델)

월간 비용: $0
품질: 워크로드에 적합한 모델, 제한 사항, 개인정보 보호 및 SLA를 확인하세요

사례 3: "중단 없이 연중무휴로 코딩해야 합니다"

문제: 마감 기한 때문에 중단 시간을 감당할 수 없음

조합: "always-on"
  1. cc/claude-opus-4-7        (최고 품질)
  2. cx/gpt-5.5                (두 번째 구독)
  3. glm/glm-4.7               (저렴하며 매일 초기화)
  4. minimax/MiniMax-M2.1      (가장 저렴하며 5시간마다 초기화)
  5. if/deepseek-v4-flash       (무료 액세스로 등록됨; 속도 제한이 적용될 수 있음)

결과: 5단계 대체 계층으로 복원력 향상; 업스트림 가용성은 보장되지 않음
월간 비용: $20~200(구독) + $10~20(백업)

사례 4: "OpenClaw에서 무료 AI를 사용하고 싶습니다"

문제: 메시징 앱에서 완전히 무료인 AI 어시스턴트가 필요함

조합: "openclaw-free"
  1. if/qwen3.8-max-preview     (무료 액세스로 등록됨; 속도 제한이 적용될 수 있음)
  2. if/deepseek-v4-flash       (무료 액세스로 등록됨; 속도 제한이 적용될 수 있음)
  3. if/kimi-k2.7-code          (무료 액세스로 등록됨; 속도 제한이 적용될 수 있음)

월간 비용: $0
접근 방법: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...

---

📖 공급자 설정

CSV 또는 JSON 파일에서 API 키 연결을 일괄 추가하려면 대시보드 → 공급자 → 파일에서 가져오기를 사용하세요. 열은 위치에 따라 지정됩니다(provider,name,apiKey,baseUrl,priority). provider는 관리형 공급자 또는 호환 노드로 이미 존재해야 합니다. CSV 또는 JSON 파일에서 공급자 가져오기를 참조하세요.

🔐 구독형 공급자

Claude Code (Pro/Max)

대시보드 → 공급자 → Claude Code 연결
→ OAuth 로그인 → 토큰 자동 갱신
→ 5시간 + 주간 할당량 추적

모델:
  cc/claude-opus-4-7
  cc/claude-sonnet-4-6
  cc/claude-haiku-4-5-20251001

프로 팁: 복잡한 작업에는 Opus를, 속도가 중요할 때는 Sonnet을 사용하세요. OmniRoute는 모델별 할당량을 추적합니다!

Claude 및 Claude Code 호환 경로는 Opus와 Sonnet 모델의 max 사고 노력을 유지합니다. Haiku 모델은 max 노력 단계를 지원하지 않으므로, OmniRoute는 요청을 업스트림으로 보내기 전에 높은 사고 예산으로 낮춰 조정합니다.

OpenAI Codex (Plus/Pro)

대시보드 → 공급자 → Codex 연결
→ OAuth 로그인(포트 1455)
→ 5시간 + 주간 초기화

모델:
  cx/gpt-5.5
  cx/gpt-5.4
  cx/gpt-5.3-codex
  cx/gpt-5.3-codex-spark

GitHub Copilot

대시보드 → 공급자 → GitHub 연결
→ GitHub를 통한 OAuth
→ 매월 초기화(매월 1일)

모델:
  gh/gpt-5.5
  gh/gpt-5.4
  gh/claude-sonnet-4.6
  gh/claude-opus-4.7
  gh/gemini-3.1-pro-preview

💰 저렴한 공급자

GLM-4.7 (매일 초기화, $0.6/1M)

1. 가입: Zhipu AI
2. Coding Plan에서 API 키 받기
3. 대시보드 → API 키 추가: 공급자: glm, API 키: your-key

사용: glm/glm-4.7 — 프로 팁: Coding Plan은 1/7 가격으로 3배의 할당량을 제공합니다! 매일 오전 10시에 초기화됩니다.

MiniMax M2.1 (5시간마다 초기화, $0.20/1M)

1. 가입: MiniMax
2. API 키 받기 → 대시보드 → API 키 추가

사용: minimax/MiniMax-M2.1 — 프로 팁: 긴 컨텍스트(1M 토큰)를 위한 가장 저렴한 옵션입니다!

Kimi K2 (월 $9 정액)

1. 구독: Moonshot AI
2. API 키 받기 → 대시보드 → API 키 추가

사용: kimi/kimi-k2.5 — 프로 팁: 10M 토큰에 월 $9 고정이므로 실질 비용은 $0.90/1M입니다!

Baidu Qianfan / ERNIE

1. 가입: Baidu AI Cloud Qianfan
2. Qianfan API 키 생성 → 대시보드 → API 키 추가: 공급자: qianfan

사용: qianfan/ernie-5.1, qianfan/ernie-x1.1 또는 다른 Qianfan OpenAI 호환 모델 ID.

🆓 무료 공급자

인증이 필요 없는 무료 공급자의 공급자 페이지에는 인증 필요 없음 옆에 스위치가 있습니다. 이 스위치를 끄면 해당 공급자가 비활성화되고, 구성된 공급자 보기 및 간단히 보기에서 제거되며, 해당 모델도 /v1/models에서 제거됩니다.

Qoder (무료 모델 9개)

대시보드 → Qoder 연결 → OAuth 로그인 → 액세스에는 현재 공급자 제한이 적용됨

모델: if/qwen3.8-max-preview, if/qwen3.7-max, if/qwen3.7-plus, if/kimi-k3, if/kimi-k2.7-code, if/glm-5.2, if/deepseek-v4-pro, if/deepseek-v4-flash, if/minimax-m3

Kiro (Claude 무료)

대시보드 → Kiro 연결 → AWS Builder ID 또는 Google/GitHub → 월 약 50크레딧

모델: kr/claude-sonnet-4.5, kr/claude-haiku-4.5

---

🎨 콤보

각 카드의 핸들을 드래그하여 대시보드 → 콤보에서 콤보 카드의 순서를 직접 변경할 수 있습니다. 순서는 SQLite에 저장되며 다시 로드할 때 복원됩니다.

예시 1: 구독 최대 활용 → 저렴한 백업

대시보드 → 콤보 → 새로 만들기

이름: premium-coding
모델:
  1. cc/claude-opus-4-7 (구독 기본 모델)
  2. glm/glm-4.7 (저렴한 백업, $0.6/1M)
  3. minimax/MiniMax-M2.7 (가장 저렴한 대체 모델, $0.3/1M)

CLI에서 사용: premium-coding

예시 2: 무료 전용(비용 없음)

이름: free-combo
모델:
  1. if/kimi-k2.7-code (무료 액세스로 표시됨, 제공업체 제한이 적용될 수 있음)
  2. kr/qwen3-coder-next (Kiro 무료 대체 모델)

비용: 현재 $0로 표시됨. 약관 및 이용 가능 여부는 변경될 수 있음

---

🔧 CLI 통합

Cursor IDE

Cursor를 OmniRoute 클라이언트로 사용(Cursor 채팅을 OmniRoute를 통해 라우팅):

설정 → 모델 → 고급:
  OpenAI API 기본 URL: http://localhost:20128/v1
  OpenAI API 키: [OmniRoute 대시보드에서 가져오기]
  모델: cc/claude-opus-4-7

OmniRoute를 Cursor 제공업체로 사용(OmniRoute가 업스트림 Cursor를 호출):
대시보드 → 제공업체 → Cursor → Cursor로 로그인을 권장합니다. Docker에서는 docs/providers/CURSOR-DOCKER.md를 참조하세요.

Claude Code

~/.claude/settings.json을 편집합니다.

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:20128",
    "ANTHROPIC_AUTH_TOKEN": "your-omniroute-api-key"
  }
}

여기서는 Claude 호환 루트 엔드포인트를 사용하세요. ANTHROPIC_BASE_URL에 /v1을 추가하지 마세요.

Codex CLI

export OPENAI_BASE_URL="http://localhost:20128"
export OPENAI_API_KEY="your-omniroute-api-key"
codex "your prompt"

OpenClaw

~/.openclaw/openclaw.json을 편집합니다.

{
  "agents": {
    "defaults": {
      "model": { "primary": "omniroute/if/kimi-k2.7-code" }
    }
  },
  "models": {
    "providers": {
      "omniroute": {
        "baseUrl": "http://localhost:20128/v1",
        "apiKey": "your-omniroute-api-key",
        "api": "openai-completions",
        "models": [{ "id": "if/kimi-k2.7-code", "name": "Kimi K2.7 Code" }]
      }
    }
  }
}

또는 대시보드 사용: CLI 도구 → OpenClaw → 자동 구성

Cline / Continue / RooCode

제공업체: OpenAI 호환
기본 URL: http://localhost:20128/v1
API 키: [대시보드에서 가져오기]
모델: cc/claude-opus-4-7

---

🚀 배포

전역 npm 설치(권장)

npm install -g omniroute

# 구성 디렉터리 생성
mkdir -p ~/.omniroute

# .env 파일 생성(.env.example 참조)
cp .env.example ~/.omniroute/.env

# 서버 시작
omniroute
# 또는 사용자 지정 포트 사용:
omniroute --port 3000

CLI는 ~/.omniroute/.env 또는 ./.env에서 .env를 자동으로 로드합니다.

트레이 모드

시스템 트레이에서 OmniRoute를 시작합니다.

omniroute serve --tray

서버와 트레이가 준비되면 명령이 반환됩니다.

터미널을 닫아도 서버는 계속 실행됩니다.

트레이 모드는 macOS, Windows 및 그래픽 Linux 세션을 지원합니다. 트레이 모드에서는 대시보드가 자동으로 열리지 않습니다.

트레이 메뉴에서 다음 작업을 수행할 수 있습니다.

• 대시보드를 엽니다.
• /dashboard/logs를 엽니다.
• 자동 시작 설정을 변경합니다.
• OmniRoute를 중지합니다.

--tray를 다음 옵션과 함께 사용하지 마세요.

• --daemon
• --log
• --no-recovery

이러한 모드에는 서로 다른 프로세스 소유권이 필요합니다.

다음 시스템 로그인 시 자동으로 시작되도록 설정합니다.

omniroute autostart enable

자동 시작은 macOS, Windows 및 그래픽 Linux 세션에서 트레이 모드를 사용합니다. 헤드리스 Linux에서는 기존 systemd 사용자 서비스를 사용합니다.

로그인 시 자동 시작을 비활성화합니다.

omniroute autostart disable

제거

OmniRoute가 더 이상 필요하지 않은 경우, 깔끔하게 제거할 수 있도록 두 가지 빠른 스크립트를 제공합니다.

명령	작업
npm run uninstall	시스템 앱을 제거하지만 ~/.omniroute의 DB와 구성은 유지합니다.
npm run uninstall:full	앱을 제거하고 모든 구성, 키 및 데이터베이스를 영구적으로 삭제합니다.

참고: 이 명령을 실행하려면 OmniRoute 프로젝트 폴더로 이동한 후(복제한 경우) 실행하세요. 또는 전역으로 설치한 경우 npm uninstall -g omniroute를 실행하면 됩니다.

VPS 배포

git clone https://github.com/diegosouzapw/OmniRoute.git
cd OmniRoute && npm install && npm run build

export JWT_SECRET="your-secure-secret-change-this"
export INITIAL_PASSWORD="your-password"
export DATA_DIR="/var/lib/omniroute"
export PORT="20128"
export HOSTNAME="0.0.0.0"
export NODE_ENV="production"
export NEXT_PUBLIC_BASE_URL="http://localhost:20128"
export API_KEY_SECRET="endpoint-proxy-api-key-secret"

npm run start
# 또는: pm2 start npm --name omniroute -- start

PM2 배포(낮은 메모리)

RAM이 제한된 서버에서는 메모리 제한 옵션을 사용하세요.

# 512MB 제한 사용(기본값)
pm2 start npm --name omniroute -- start

# 또는 사용자 지정 메모리 제한 사용
OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start

# 또는 ecosystem.config.js 사용
pm2 start ecosystem.config.js

ecosystem.config.js를 생성합니다.

module.exports = {
  apps: [
    {
      name: "omniroute",
      script: "npm",
      args: "start",
      env: {
        NODE_ENV: "production",
        OMNIROUTE_MEMORY_MB: "512",
        JWT_SECRET: "your-secret",
        INITIAL_PASSWORD: "your-password",
      },
      node_args: "--max-old-space-size=512",
      max_memory_restart: "300M",
    },
  ],
};

Docker

# 이미지 빌드(기본값 = codex/claude/droid가 사전 설치된 runner-cli)
docker build -t omniroute:cli .

# 포터블 모드(권장)
docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli

CLI 바이너리를 사용하는 호스트 통합 모드에 대해서는 기본 문서의 Docker 섹션을 참조하세요.

Void Linux (xbps-src)

Void Linux 사용자는 xbps-src 크로스 컴파일 프레임워크를 사용하여 OmniRoute를 네이티브로 패키징하고 설치할 수 있습니다. 이 프레임워크는 필수 better-sqlite3 네이티브 바인딩과 함께 Node.js 독립 실행형 빌드를 자동화합니다.

xbps-src 템플릿 보기

# 'omniroute'용 템플릿 파일
pkgname=omniroute
version=3.8.0
revision=1
hostmakedepends="nodejs python3 make"
depends="openssl"
short_desc="Universal AI gateway with smart routing for multiple LLM providers"
maintainer="zenobit <zenobit@disroot.org>"
license="MIT"
homepage="https://github.com/diegosouzapw/OmniRoute"
distfiles="https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz"
checksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b
system_accounts="_omniroute"
omniroute_homedir="/var/lib/omniroute"
export NODE_ENV=production
export npm_config_engine_strict=false
export npm_config_loglevel=error
export npm_config_fund=false
export npm_config_audit=false

do_build() {
	# node-gyp의 대상 CPU 아키텍처 결정
	local _gyp_arch
	case "$XBPS_TARGET_MACHINE" in
		aarch64*) _gyp_arch=arm64 ;;
		armv7*|armv6*) _gyp_arch=arm ;;
		i686*) _gyp_arch=ia32 ;;
		*) _gyp_arch=x64 ;;
	esac

	# 1) 모든 의존성 설치 – 스크립트 건너뛰기
	NODE_ENV=development npm ci --ignore-scripts

	# 2) Next.js 독립 실행형 번들 빌드
	npm run build

	# 3) 정적 자산을 독립 실행형 번들로 복사
	cp -r .next/static .next/standalone/.next/static
	[ -d public ] && cp -r public .next/standalone/public || true

	# 4) better-sqlite3 네이티브 바인딩 컴파일
	local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
	(cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")

	# 5) 컴파일된 바인딩을 독립 실행형 번들에 배치
	local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
	mkdir -p "$_bs3_release"
	cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"

	# 6) 아키텍처별 sharp 번들 제거
	rm -rf .next/standalone/node_modules/@img

	# 7) Next.js 정적 분석에서 누락된 pino 런타임 의존성 복사:
	for _mod in pino-abstract-transport split2 process-warning; do
		cp -r "node_modules/$_mod" .next/standalone/node_modules/
	done
}

do_check() {
	npm run test:unit
}

do_install() {
	vmkdir usr/lib/omniroute/.next
	vcopy .next/standalone/. usr/lib/omniroute/.next/standalone

	# 설치 후 훅이 비어 있는 Next.js 앱 라우터 디렉터리를 제거하지 않도록 방지
	for _d in \
		.next/standalone/.next/server/app/dashboard \
		.next/standalone/.next/server/app/dashboard/settings \
		.next/standalone/.next/server/app/dashboard/providers; do
		touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
	done

	cat > "${WRKDIR}/omniroute" <<'EOF'
#!/bin/sh
export PORT="${PORT:-20128}"
export DATA_DIR="${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}"
export APP_LOG_TO_FILE="${APP_LOG_TO_FILE:-false}"
mkdir -p "${DATA_DIR}"
exec node /usr/lib/omniroute/.next/standalone/server.js "$@"
EOF
	vbin "${WRKDIR}/omniroute"
}

post_install() {
	vlicense LICENSE
}

환경 변수

변수	기본값	설명
JWT_SECRET	omniroute-default-secret-change-me	JWT 서명 시크릿(프로덕션 환경에서는 변경)
INITIAL_PASSWORD	CHANGEME	최초 로그인 비밀번호
DATA_DIR	~/.omniroute	데이터 디렉터리(db, 사용량, 로그)
PORT	프레임워크 기본값	서비스 포트(예시에서는 20128)
HOSTNAME	프레임워크 기본값	바인딩 호스트(Docker 기본값은 0.0.0.0)
NODE_ENV	런타임 기본값	배포 시 production으로 설정
NEXT_PUBLIC_BASE_URL	http://localhost:20128	대시보드에 표시되고 서버에 노출되는 공개 기본 URL(기존 BASE_URL 대체)
NEXT_PUBLIC_CLOUD_URL	https://omniroute.dev	클라우드 동기화 엔드포인트 기본 URL(기존 CLOUD_URL 대체)
API_KEY_SECRET	endpoint-proxy-api-key-secret	생성된 API 키의 HMAC 시크릿
REQUIRE_API_KEY	false	/v1/*에서 Bearer API 키 사용 강제
ALLOW_API_KEY_REVEAL	false	인증된 대시보드 사용자가 요청 시 저장된 API 키 전체 값을 표시할 수 있도록 허용
PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES	70	캐시된 Provider Limits 데이터의 서버 측 갱신 주기. UI 새로 고침 버튼으로 수동 동기화 가능
DISABLE_SQLITE_AUTO_BACKUP	false	쓰기/가져오기/복원 전 자동 SQLite 스냅샷 비활성화. 수동 백업은 계속 사용 가능
APP_LOG_TO_FILE	true	애플리케이션 및 감사 로그를 디스크에 출력하도록 설정
AUTH_COOKIE_SECURE	false	Secure 인증 쿠키 강제 적용(HTTPS 리버스 프록시 사용 시)
CLOUDFLARED_BIN	설정되지 않음	관리형 다운로드 대신 기존 cloudflared 바이너리 사용
CLOUDFLARED_PROTOCOL	http2	관리형 Quick Tunnels용 전송 프로토콜(http2, quic 또는 auto)
OMNIROUTE_MEMORY_MB	512	Node.js 힙 제한(MB)
PROMPT_CACHE_MAX_SIZE	50	최대 프롬프트 캐시 항목 수
SEMANTIC_CACHE_MAX_SIZE	100	최대 시맨틱 캐시 항목 수

전체 환경 변수 참조는 README를 확인하세요.

---

📊 사용 가능한 모델

사용 가능한 모든 모델 보기

아래 목록은 v3.8.0의 open-sse/config/providerRegistry.ts를 기반으로 선별되었습니다. 클라우드 카탈로그(Gemini, OpenRouter 등)는 동적으로 동기화됩니다. 전체 실시간 카탈로그를 보려면 Dashboard → Providers → [provider] → Available Models를 열거나 GET /api/models/catalog을 호출하세요.

제공자의 기본 제공 목록이 최신 상태와 달라진 경우, 해당 페이지에서 Import from /models를 사용하거나 Auto-Sync를 활성화하여 업스트림의 실시간 카탈로그를 가져오세요. 이는 LLM7.io(gemini-3.1-flash-lite) 및 UncloseAI(solidrust/Hermes-3-Llama-3.1-8B-AWQ)에 대해 v3.8.50에서 검증되었습니다. 같은 테스트 과정에서 Pollinations의 익명 액세스는 여전히 업스트림 제한을 받았습니다.

Claude Code (cc/) — Pro/Max OAuth: cc/claude-opus-4-8, cc/claude-opus-4-7, cc/claude-opus-4-6, cc/claude-opus-4-5-20251101, cc/claude-sonnet-4-6, cc/claude-sonnet-4-5-20250929, cc/claude-haiku-4-5-20251001

Codex (cx/) — Plus/Pro OAuth: cx/gpt-5.5 (+ 추론 노력 수준: gpt-5.5-xhigh, gpt-5.5-high, gpt-5.5-medium, gpt-5.5-low), cx/gpt-5.4, cx/gpt-5.4-mini, cx/gpt-5.3-codex, cx/gpt-5.3-codex-spark

GitHub Copilot (gh/) — OAuth: gh/gpt-5.5, gh/gpt-5.4, gh/gpt-5.4-mini, gh/gpt-5-mini, gh/gpt-5.3-codex, gh/claude-opus-4.7, gh/claude-opus-4.6, gh/claude-opus-4-5-20251101, gh/claude-sonnet-4.6, gh/claude-sonnet-4.5, gh/claude-haiku-4.5, gh/gemini-3.1-pro-preview, gh/gemini-3-flash-preview, gh/oswe-vscode-prime

Kiro (kr/) — 무료 OAuth: Dashboard → Providers → Kiro → Available Models 아래에 표시되는 실시간 카탈로그를 사용하세요. 이용 가능 여부는 계정 및 요금제에 따라 달라집니다.

Qoder (if/) — 무료 OAuth: if/qwen3.8-max-preview, if/qwen3.7-max, if/qwen3.7-plus, if/kimi-k3, if/kimi-k2.7-code, if/glm-5.2, if/deepseek-v4-pro, if/deepseek-v4-flash, if/minimax-m3

GLM (glm/, glm-cn/, zai/, glmt/) — $0.2–0.6/1M: glm/glm-5.1, glm/glm-5, glm/glm-5-turbo, glm/glm-4.7, glm/glm-4.7-flash, glm/glm-4.6, glm/glm-4.6v, glm/glm-4.5, glm/glm-4.5v, glm/glm-4.5-air

MiniMax (minimax/, minimax-cn/) — $0.2/1M: minimax/MiniMax-M2.7, minimax/MiniMax-M2.7-highspeed, minimax/MiniMax-M2.5, minimax/MiniMax-M2.5-highspeed

Kimi (kimi/, kimi-coding/, kimi-coding-apikey/) — 월 $9 정액제 또는 사용량 기반: kimi/kimi-k2.6, kimi/kimi-k2.5

DeepSeek (ds/) — API 키: ds/deepseek-v4-pro, ds/deepseek-v4-flash

Groq (groq/) — 초고속: groq/llama-3.3-70b-versatile, groq/meta-llama/llama-4-maverick-17b-128e-instruct, groq/qwen/qwen3-32b, groq/openai/gpt-oss-120b

xAI (xai/) — Grok 네이티브: xai/grok-4.3, xai/grok-4.20-multi-agent-0309, xai/grok-4.20-0309-reasoning, xai/grok-4.20-0309-non-reasoning

Mistral (mistral/) — EU 호스팅: mistral/mistral-large-latest, mistral/mistral-medium-3-5, mistral/mistral-small-latest, mistral/devstral-latest, mistral/codestral-latest

Perplexity (pplx/) — 검색 보강형: pplx/sonar-deep-research, pplx/sonar-reasoning-pro, pplx/sonar-pro, pplx/sonar

Together AI (together/) — 오픈 소스: together/meta-llama/Llama-3.3-70B-Instruct-Turbo-Free (무료), together/meta-llama/Llama-Vision-Free, together/deepseek-ai/DeepSeek-R1-Distill-Llama-70B-Free, together/deepseek-ai/DeepSeek-R1, together/Qwen/Qwen3-235B-A22B, together/meta-llama/Llama-4-Maverick-17B-128E-Instruct-FP8

Fireworks AI (fireworks/) — 빠른 추론: fireworks/accounts/fireworks/models/kimi-k2p6, fireworks/accounts/fireworks/models/minimax-m2p7, fireworks/accounts/fireworks/models/qwen3p6-plus, fireworks/accounts/fireworks/models/glm-5p1, fireworks/accounts/fireworks/models/deepseek-v4-pro

Cerebras (cerebras/) — 웨이퍼 스케일: cerebras/zai-glm-4.7, cerebras/gpt-oss-120b

Cohere (cohere/) — RAG 중심: cohere/command-a-reasoning-08-2025, cohere/command-a-vision-07-2025, cohere/command-a-03-2025, cohere/command-r-08-2024

NVIDIA NIM (nvidia/) — 엔터프라이즈: nvidia/z-ai/glm-5.1, nvidia/minimaxai/minimax-m2.7, nvidia/google/gemma-4-31b-it, nvidia/mistralai/mistral-small-4-119b-2603, nvidia/mistralai/mistral-large-3-675b-instruct-2512, nvidia/qwen/qwen3.5-397b-a17b, nvidia/deepseek-ai/deepseek-v4-pro, nvidia/openai/gpt-oss-120b, nvidia/nvidia/nemotron-3-super-120b-a12b

Baidu Qianfan (qianfan/) — ERNIE: qianfan/ernie-5.1, qianfan/ernie-5.0-thinking-latest, qianfan/ernie-x1.1

Ollama Cloud (ollama-cloud/): ollama-cloud/deepseek-v4-pro, ollama-cloud/deepseek-v4-flash, ollama-cloud/kimi-k2.6, ollama-cloud/glm-5.1, ollama-cloud/minimax-m2.7, ollama-cloud/gemma4:31b, ollama-cloud/qwen3.5:397b

Gemini (Google Cloud gemini/): Google에서 API 키별로 실시간 동기화되므로 정적 목록은 없습니다. Dashboard → Providers에서 키를 연결한 다음 Available Models를 사용하여 현재 카탈로그를 가져오세요(예: gemini/gemini-3-pro, gemini/gemini-3-flash).

기타 호환 제공자(일부): cohere, databricks, snowflake, together, vertex, alibaba, alibaba-cn, bedrock(aws-bedrock을 통해), azure-ai, openrouter(패스스루 카탈로그), siliconflow, hyperbolic, huggingface, featherless-ai, cloudflare-ai, scaleway, deepinfra, vercel-ai-gateway, bazaarlink, friendliai, nous-research, reka, volcengine, ai21, gigachat. 각 제공자는 providerRegistry.ts에서 자체 모델 목록을 관리하며, 제공자가 /models 엔드포인트를 노출하는 경우 자동으로 동기화할 수 있습니다.

모델 ID 참고: OmniRoute는 제공자 네이티브 ID(claude-opus-4-8, gpt-5.5, glm-5.1, MiniMax-M2.7, kimi-k2.5, grok-4.20-0309-reasoning)를 사용합니다. 일부 ID에 점으로 구분된 버전이 포함되는 이유는 업스트림 API가 해당 형식을 요구하기 때문입니다. 모델이 위에 나열되어 있지 않은 경우 omniroute models --search <term>을 실행하거나 GET /api/models/catalog을 호출하여 이용 가능 여부를 확인하세요.

---

🧩 고급 기능

사용자 지정 모델

앱 업데이트를 기다리지 않고 모든 공급자에 원하는 모델 ID를 추가할 수 있습니다.

# API 사용
curl -X POST http://localhost:20128/api/provider-models \
  -H "Content-Type: application/json" \
  -d '{"provider": "openai", "modelId": "gpt-5.2", "modelName": "GPT-5.2"}'

# 목록: curl http://localhost:20128/api/provider-models?provider=openai
# 제거: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-5.2"

또는 대시보드에서 Providers → [Provider] → Custom Models를 사용하세요.

참고:

• OpenRouter 및 OpenAI/Anthropic 호환 공급자는 Available Models에서만 관리됩니다. 수동 추가, 가져오기, 자동 동기화는 모두 동일한 사용 가능 모델 목록에 반영되므로, 이러한 공급자에는 별도의 Custom Models 섹션이 없습니다.
• Custom Models 섹션은 관리형 사용 가능 모델 가져오기를 제공하지 않는 공급자를 위한 것입니다.

OmniRoute 피어 연결

다른 OmniRoute 게이트웨이를 Custom OpenAI-compatible 공급자로 추가할 수 있습니다. 피어의 /v1 기본 URL과 해당 피어에서 발급한 전용 최소 권한 API 키를 사용하세요.

상호 또는 다중 홉 체인의 경우 모든 게이트웨이에서 옵트인 루프 가드를 활성화하세요.

# gateway-a
OMNIROUTE_INSTANCE_ID=gateway-a
OMNIROUTE_PEER_URLS=http://gateway-b:20128/v1
OMNIROUTE_PEER_MAX_HOPS=4

# gateway-b
OMNIROUTE_INSTANCE_ID=gateway-b
OMNIROUTE_PEER_URLS=http://gateway-a:20128/v1
OMNIROUTE_PEER_MAX_HOPS=4

명시적으로 허용 목록에 등록된 피어 URL로 전송된 요청에만 X-OmniRoute-Peer-Trace 헤더가 포함됩니다. 게이트웨이는 반복된 인스턴스 ID 또는 소진된 홉 예산을 HTTP 508 Loop Detected로 거부하며, 일반 업스트림 공급자에는 피어 메타데이터가 전달되지 않습니다.

피어 연결은 데이터베이스 복제나 호스트 장애 조치가 아닙니다. 각 게이트웨이는 독립적인 SQLite 상태, 캐시, 속도 카운터 및 세션을 유지합니다. 액티브/패시브 또는 액티브/액티브 가용성을 위해 상태 검사가 적용된 역방향 프록시나 클라이언트 장애 조치를 사용하고, 하나의 SQLite 데이터베이스를 실행 중인 여러 OmniRoute 인스턴스에 마운트하지 마세요.

전용 공급자 경로

모델 검증을 거쳐 특정 공급자로 요청을 직접 라우팅합니다.

POST http://localhost:20128/v1/providers/openai/chat/completions
POST http://localhost:20128/v1/providers/openai/embeddings
POST http://localhost:20128/v1/providers/fireworks/images/generations

공급자 접두사가 없으면 자동으로 추가됩니다. 일치하지 않는 모델은 400을 반환합니다.

네트워크 프록시 구성

# 전역 프록시 설정
curl -X PUT http://localhost:20128/api/settings/proxy \
  -d '{"global": {"type":"http","host":"proxy.example.com","port":"8080"}}'

# 공급자별 프록시
curl -X PUT http://localhost:20128/api/settings/proxy \
  -d '{"providers": {"openai": {"type":"socks5","host":"proxy.example.com","port":"1080"}}}'

# 프록시 테스트
curl -X POST http://localhost:20128/api/settings/proxy/test \
  -d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}'

우선순위: 키별 → 콤보별 → 공급자별 → 전역 → 환경.

모델 카탈로그 API

curl http://localhost:20128/api/models/catalog

유형(chat, embedding, image)과 함께 공급자별로 그룹화된 모델을 반환합니다.

클라우드 동기화

• 여러 기기 간에 공급자, 콤보 및 설정 동기화
• 시간 초과 및 빠른 실패가 적용된 자동 백그라운드 동기화
• 프로덕션에서는 서버 측 NEXT_PUBLIC_BASE_URL/NEXT_PUBLIC_CLOUD_URL 사용 권장

Cloudflare Quick Tunnel

• Docker 및 기타 자체 호스팅 배포의 Dashboard → Endpoints에서 사용할 수 있습니다.
• 현재 OpenAI 호환 /v1 엔드포인트로 전달되는 임시 https://*.trycloudflare.com URL을 생성합니다.
• 처음 활성화할 때만 필요한 경우 cloudflared를 설치하며, 이후 재시작 시에는 동일한 관리형 바이너리를 재사용합니다.
• Quick Tunnel은 OmniRoute 또는 컨테이너를 재시작한 후 자동으로 복원되지 않습니다. 필요할 때 대시보드에서 다시 활성화하세요.
• 터널 URL은 일시적이며 터널을 중지하고 시작할 때마다 변경됩니다.
• 관리형 Quick Tunnel은 리소스가 제한된 컨테이너에서 불필요한 QUIC UDP 버퍼 경고를 방지하기 위해 기본적으로 HTTP/2 전송을 사용합니다.
• 관리형 전송 방식을 재정의하려면 CLOUDFLARED_PROTOCOL=quic 또는 auto로 설정하세요.
• 관리형 다운로드 대신 사전 설치된 cloudflared 바이너리를 사용하려면 CLOUDFLARED_BIN을 설정하세요.
• Cloudflare Quick Tunnel, Tailscale Funnel 및 ngrok Tunnel 패널은 Settings → Appearance에서 표시하거나 숨길 수 있습니다. 패널을 숨겨도 실행 중인 터널은 중지되지 않습니다.

LLM 게이트웨이 인텔리전스(9단계)

• 시맨틱 캐시 — 비스트리밍, temperature=0 응답을 자동으로 캐시합니다(X-OmniRoute-No-Cache: true로 우회).
• 요청 멱등성 — Idempotency-Key 또는 X-Request-Id 헤더를 통해 5초 이내의 요청을 중복 제거합니다.
• 진행 상황 추적 — X-OmniRoute-Progress: true 헤더를 통해 옵트인 SSE event: progress 이벤트를 제공합니다.

---

변환기 플레이그라운드

Dashboard → Translator에서 액세스할 수 있습니다. OmniRoute가 공급자 간 API 요청을 변환하는 방식을 디버깅하고 시각화하세요.

모드	용도
Playground	소스/대상 형식을 선택하고 요청을 붙여 넣어 변환된 출력을 즉시 확인합니다
Chat Tester	프록시를 통해 실시간 채팅 메시지를 전송하고 전체 요청/응답 주기를 검사합니다
Test Bench	여러 형식 조합에 대해 일괄 테스트를 실행하여 변환의 정확성을 검증합니다
Live Monitor	요청이 프록시를 통과할 때 실시간 변환을 모니터링합니다

사용 사례:

• 특정 클라이언트/공급자 조합이 실패하는 이유 디버깅
• 사고 태그, 도구 호출 및 시스템 프롬프트가 올바르게 변환되는지 확인
• OpenAI, Claude, Gemini 및 Responses API 형식 간의 차이 비교

---

라우팅 전략

대시보드 → 설정 → 라우팅에서 구성합니다. 대시보드에는 가장 많이 사용되는 6가지 전략이 표시되며, 콤보와 자동 라우터는 내부적으로 더 다양한 전략을 지원합니다.

대시보드에 표시되는 전략(계정 수준 라우팅):

전략	설명
우선 채우기	우선순위에 따라 계정을 사용하며, 기본 계정이 사용할 수 없게 될 때까지 모든 요청을 처리합니다
라운드 로빈	구성 가능한 고정 제한에 따라 모든 계정을 순환합니다(기본값: 계정당 3회 호출)
P2C(두 선택지의 힘)	2개의 계정을 무작위로 선택한 후 더 정상적인 계정으로 라우팅하여 상태를 고려하면서 부하를 분산합니다
무작위	Fisher-Yates 셔플을 사용하여 각 요청에 대한 계정을 무작위로 선택합니다
최소 사용	lastUsedAt 타임스탬프가 가장 오래된 계정으로 라우팅하여 트래픽을 고르게 분산합니다
비용 최적화	우선순위 값이 가장 낮은 계정으로 라우팅하여 가장 저렴한 공급자를 사용하도록 최적화합니다

고급 콤보 및 자동 전략(콤보별로 또는 auto/* 접두사를 통해 구성 가능 — AUTO-COMBO.md 참조):

• priority — 엄격한 순서를 따르며 라운드 로빈을 사용하지 않음
• weighted — 모델별 가중치에 따른 비례적 트래픽 분배
• fill-first — 제한에 도달할 때까지 첫 번째 모델을 우선 사용
• round-robin / strict-random / random
• p2c(두 선택지의 힘)
• least-used 및 cost-optimized
• auto — 모든 후보를 점수에 따라 선택
• lkgp(마지막으로 정상 작동한 공급자) — 마지막으로 성공한 공급자에 고정한 후 규칙에 따라 폴백
• context-optimized — 사용 가능한 컨텍스트 창이 가장 큰 모델을 선택
• context-relay — 후속 턴을 위해 긴 컨텍스트 모델을 연계

외부 고정 세션 헤더

외부 세션 선호도(예: 리버스 프록시 뒤의 Claude Code/Codex 에이전트)를 사용하려면 다음을 전송합니다.

X-Session-Id: your-session-key

OmniRoute는 x_session_id도 허용하며, 실제 적용된 세션 키를 X-OmniRoute-Session-Id로 반환합니다.

Nginx를 사용하고 밑줄 형식의 헤더를 전송하는 경우 다음을 활성화합니다.

underscores_in_headers on;

와일드카드 모델 별칭

모델 이름을 다시 매핑하려면 와일드카드 패턴을 생성합니다.

패턴: claude-sonnet-*     →  대상: cc/claude-sonnet-4-6
패턴: gpt-*               →  대상: gh/gpt-5.3-codex

와일드카드는 *(임의의 문자들)와 ?(단일 문자)를 지원합니다.

폴백 체인

모든 요청에 적용되는 전역 폴백 체인을 정의합니다.

체인: production-fallback
  1. cc/claude-opus-4-7
  2. gh/gpt-5.3-codex
  3. glm/glm-4.7

---

복원력 및 회로 차단기

대시보드 → 설정 → 복원력에서 구성합니다.

OmniRoute는 다음 5가지 구성 요소를 통해 공급자 수준의 복원력을 구현합니다.

1. 요청 대기열 및 페이싱 — 시스템 수준의 요청 조정:

   • 분당 요청 수(RPM) — 계정당 분당 최대 요청 수
   • 요청 간 최소 시간 — 요청 사이의 최소 간격(밀리초)
   • 최대 동시 요청 수 — 계정당 최대 동시 요청 수

2. 연결 쿨다운 — 재시도 가능한 실패 이후 단일 연결에 적용되는 인증 유형별 구성:

   • 기본 쿨다운 — 재시도 가능한 업스트림 실패에 적용되는 기본 쿨다운 시간
   • 업스트림 재시도 힌트 사용 — 제공되는 경우 권위 있는 Retry-After 또는 재설정 힌트를 따름
   • 최대 백오프 단계 — 반복 실패 시 적용되는 최대 지수 백오프 수준

3. 공급자 회로 차단기 — 공급자의 엔드투엔드 실패를 추적하고, 구성된 경고 임계값에서 공급자를 성능 저하 상태로 표시하며, 구성된 실패 임계값에 도달하면 차단기를 엽니다.

   • 성능 저하 임계값 — DEGRADED 상태로 전환되기 전까지 허용되는 연속 공급자 실패 횟수
   • 실패 임계값 — OPEN 상태로 전환되기 전까지 허용되는 연속 공급자 실패 횟수
   • 재설정 제한 시간 — 공급자를 다시 테스트하기 전까지의 시간
   • CLOSED(정상) — 요청이 정상적으로 처리됨
   • DEGRADED — 증가한 실패를 추적하는 동안에도 요청이 계속 처리됨
   • OPEN — 반복된 실패 후 공급자가 일시적으로 차단됨
   • HALF_OPEN — 공급자가 복구되었는지 테스트 중

   연결 범위의 429 속도 제한은 연결 쿨다운에 유지되며 공급자 차단기 집계에는 포함되지 않습니다.

   공급자 차단기의 런타임 상태는 대시보드 → 상태에만 표시됩니다.

4. 쿨다운 대기 — 모든 후보 연결이 이미 쿨다운 중인 경우, OmniRoute는 가장 먼저 종료되는 쿨다운까지 기다린 후 동일한 클라이언트 요청을 자동으로 다시 시도할 수 있습니다.

5. 속도 제한 자동 감지 — 업스트림 공급자가 명시적인 대기 시간을 반환하면, 이 설정이 활성화된 경우 해당 힌트가 로컬 연결 쿨다운보다 우선합니다.

유용한 팁: 장애 발생 후 상태 페이지에서 실시간 공급자 차단기를 검사하고 재설정할 수 있습니다. 복원력 페이지에서는 구성만 변경할 수 있습니다.

---

데이터베이스 내보내기/가져오기

대시보드 → 설정 → 시스템 및 스토리지에서 데이터베이스 백업을 관리합니다.

작업	설명
데이터베이스 내보내기	현재 SQLite 데이터베이스를 .sqlite 파일로 다운로드합니다
전체 내보내기 (.tar.gz)	데이터베이스, 설정, 콤보, 제공자 연결(자격 증명 제외), API 키 메타데이터가 포함된 전체 백업 아카이브를 다운로드합니다
데이터베이스 가져오기	.sqlite 파일을 업로드하여 현재 데이터베이스를 교체합니다. DISABLE_SQLITE_AUTO_BACKUP=true가 아니면 가져오기 전 백업이 자동으로 생성됩니다

# API: 데이터베이스 내보내기
curl -o backup.sqlite http://localhost:20128/api/db-backups/export

# API: 전체 내보내기(전체 아카이브)
curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll

# API: 데이터베이스 가져오기
curl -X POST http://localhost:20128/api/db-backups/import \
  -F "file=@backup.sqlite"

가져오기 검증: 가져온 파일은 무결성(SQLite pragma 검사), 필수 테이블(provider_connections, provider_nodes, combos, api_keys), 크기(최대 100MB)를 기준으로 검증됩니다.

사용 사례:

• 머신 간 OmniRoute 마이그레이션
• 재해 복구를 위한 외부 백업 생성
• 팀원 간 구성 공유(전체 내보내기 → 아카이브 공유)

---

설정 대시보드

설정 페이지는 쉽게 탐색할 수 있도록 7개의 탭으로 구성되어 있습니다.

탭	내용
일반	시스템 스토리지 도구, 기본 동작, 엔드포인트 터널 표시 여부
외관	테마 제어(라이트/다크/시스템), 사이드바 표시 여부, Cloudflare/Tailscale/ngrok 터널 카드의 패널 토글
AI	추론 예산(그대로 전달 / 자동 제거 / 사용자 지정 / 적응형 — THINKING_BUDGET.md 참조), 전역 시스템 프롬프트, 프롬프트 캐시 통계
보안	로그인/비밀번호 설정, IP 액세스 제어, /models용 API 인증, 제공자 차단, 프롬프트 인젝션 방어
라우팅	전역 라우팅 전략(Fill First / Round Robin / P2C / Random / Least Used / Cost Optimized), 와일드카드 모델 별칭, 폴백 체인, 콤보 기본값
복원력	요청 대기열, 연결 쿨다운, 제공자 회로 차단기 구성 및 쿨다운 대기 동작
고급	전역 프록시 구성(HTTP/SOCKS5), 제공자별 프록시 재정의

일반 탭에는 더 이상 읽기 전용 로깅 및 캐시 참고 사항이 중복 표시되지 않습니다. 데이터베이스 보존 및 최적화 설정은 /api/settings/database를 통해 유지되며, 수동 캐시 삭제에는 DELETE /api/cache를 사용합니다. 요청 및 프록시 로그의 최대 행 수는 CALL_LOGS_TABLE_MAX_ROWS 및 PROXY_LOGS_TABLE_MAX_ROWS로 제어됩니다.

---

비용 및 예산 관리

대시보드 → 비용을 통해 액세스합니다.

탭	용도
예산	일간/주간/월간 예산으로 API 키별 지출 한도를 설정하고 실시간으로 추적합니다
가격	제공자별 입력/출력 토큰 1,000개당 비용을 나타내는 모델 가격 항목을 조회하고 편집합니다

# API: 예산 설정
curl -X POST http://localhost:20128/api/usage/budget \
  -H "Content-Type: application/json" \
  -d '{"keyId": "key-123", "limit": 50.00, "period": "monthly"}'

# API: 현재 예산 상태 가져오기
curl http://localhost:20128/api/usage/budget

비용 추적: 모든 요청은 토큰 사용량을 기록하고 가격표를 사용하여 비용을 계산합니다. 대시보드 → 사용량에서 제공자, 모델 및 API 키별 세부 내역을 확인할 수 있습니다.

---

오디오 전사

OmniRoute는 OpenAI 호환 엔드포인트를 통한 오디오 전사를 지원합니다.

POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data

# curl 사용 예시
curl -X POST http://localhost:20128/v1/audio/transcriptions \
  -H "Authorization: Bearer your-api-key" \
  -F "file=@audio.mp3" \
  -F "model=openai/whisper-1"

deepgram/nova-3은 네이티브 Deepgram 경로이며 Deepgram API 키가 필요합니다. OpenRouter만 구성되어 있다면 openrouter/deepgram/nova-3을 사용하세요.

음성-텍스트 변환(전사) 제공자:

• openai/ (Whisper 호환)
• groq/ (Groq Whisper Turbo)
• deepgram/ (Nova 제품군)
• assemblyai/
• nvidia/ (Parakeet, Canary)
• huggingface/ (Whisper 변형)
• qwen/

텍스트-음성 변환(POST /v1/audio/speech) 제공자:

• openai/ (tts-1, tts-1-hd)
• hyperbolic/
• deepgram/ (Aura)
• nvidia/ (Magpie TTS)
• elevenlabs/
• huggingface/
• inworld/
• cartesia/
• playht/
• kie/
• aws-polly/
• xiaomi-mimo/
• coqui/, tortoise/
• qwen/

전사에 지원되는 오디오 형식: mp3, wav, m4a, flac, ogg, webm. TTS 출력 형식은 제공자에 따라 다릅니다(mp3, wav, opus, pcm, mulaw).

---

콤보 밸런싱 전략

대시보드 → 콤보 → 생성/편집 → 전략에서 콤보별 밸런싱을 구성합니다.

전략	설명
라운드 로빈	모델을 순차적으로 순환합니다
우선순위	항상 첫 번째 모델을 시도하며, 오류가 발생한 경우에만 대체 모델을 사용합니다
무작위	각 요청마다 콤보에서 무작위 모델을 선택합니다
가중치 기반	모델별로 할당된 가중치에 비례하여 라우팅합니다
최소 사용량	최근 요청 수가 가장 적은 모델로 라우팅합니다(콤보 메트릭 사용)
비용 최적화	사용 가능한 가장 저렴한 모델로 라우팅합니다(가격표 사용)

전역 콤보 기본값은 대시보드 → 설정 → 라우팅 → 콤보 기본값에서 설정할 수 있습니다. 콤보 대상 제한 시간은 기본적으로 현재 요청 제한 시간을 상속합니다. 대상별 제한 시간을 더 짧게 설정하여 대체 모델로 더 빠르게 전환해야 하는 경우에만 콤보 기본값 또는 개별 콤보의 **대상 제한 시간 (초)**을 사용하세요.

지연 시간 없는 콤보 최적화는 사용자가 직접 활성화해야 합니다. 지연 시간 관련 기능이 대체 대상을 동시에 호출하거나, TTFT 기록을 기반으로 대상을 건너뛰거나, 대체 요청을 압축하지 않도록 하려면 지연 시간 없는 최적화를 비활성화 상태로 두세요. 이를 활성화하면 구성된 헤징, 예측 기반 TTFT 건너뛰기 및 선제적 대체 요청 압축을 사용하여 라우팅/요청 충실도를 낮추는 대신 긴 꼬리 지연 시간을 줄일 수 있습니다.

업스트림 제공자가 엄격한 max_tokens / maxOutputTokens 제한을 요구하는 경우 추론 토큰 버퍼를 비활성화하세요. 활성화하면 콤보 라우팅은 출력 한도가 알려진 모델에만 추론 모델용 여유분을 추가하며, 안전하게 버퍼링된 값이 해당 한도를 초과할 경우 클라이언트 토큰 제한을 변경하지 않습니다. 클라이언트 제한이 이미 알려진 한도를 초과하는 경우 OmniRoute는 업스트림 요청을 보내기 전에 해당 한도까지 낮춥니다.

---

상태 대시보드

대시보드 → 상태를 통해 액세스할 수 있습니다. 6개의 카드로 구성된 실시간 시스템 상태 개요입니다.

카드	표시되는 정보
시스템 상태	가동 시간, 버전, 메모리 사용량, 데이터 디렉터리
제공자 상태	전역 제공자 회로 차단기의 런타임 상태
속도 제한	계정별 활성 연결 쿨다운 및 남은 시간
활성 잠금	활성 모델 범위 잠금 및 일시적 제외
서명 캐시	중복 제거 캐시 통계(활성 키, 적중률)
지연 시간 텔레메트리	제공자별 p50/p95/p99 지연 시간 집계

전문가 팁: 상태 페이지는 10초마다 자동으로 새로 고쳐집니다. 회로 차단기 카드를 사용하여 문제가 발생한 제공자를 파악하세요.

---

🤖 자동 라우팅(설정 불필요)

OmniRoute는 연결된 모든 제공자에서 각 요청에 가장 적합한 모델을 선택하는 점수 기반 자동 라우터를 기본 제공합니다. 유지 관리할 조합이 필요하지 않습니다. auto/* 접두사 중 하나를 사용하여 요청을 보내기만 하면 OmniRoute가 지연 시간, 비용, 성공률, 컨텍스트 적합성, 작업에 대한 모델 적합도, 최근 실패, 할당량, 서킷 브레이커 상태를 기준으로 후보에 점수를 매겨 즉석에서 가상 조합을 구성합니다.

접두사	최적화 대상
auto	균형 잡힌 기본값(지연 시간 × 비용 × 성공률)
auto/coding	코딩 작업: Claude, GPT-5, GLM, Kimi, Qwen Coder, DeepSeek 코더를 우선
auto/cheap	토큰당 비용 최소화, 더 높은 지연 시간 허용
auto/fast	지연 시간 최소화, 비용 무시
auto/offline	로컬 전용 제공자(Ollama, vLLM, llama.cpp) — 에어갭 환경에 유용
auto/smart	추론 품질 우선(Opus, GPT-5 xhigh, R1, GLM 5.1 reasoning)
auto/lkgp	"마지막으로 정상 작동한 제공자" — 마지막으로 성공한 제공자에 고정한 후 규칙 기반으로 대체

예시:

curl -X POST http://localhost:20128/v1/chat/completions \
  -H "Authorization: Bearer $OMNIROUTE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto/coding",
    "messages": [{ "role": "user", "content": "이 Python 함수를 리팩터링해 주세요" }],
    "stream": true
  }'

자동 라우터에 관한 전체 설명은 AUTO-COMBO.md에서 확인할 수 있습니다. 여기에는 점수 가중치를 조정하고, 제공자를 블랙리스트에 추가하며, Dashboard → Auto Combo에서 라우팅 결정을 확인하는 방법이 포함되어 있습니다.

---

🔌 MCP 및 A2A 통합

OmniRoute는 MCP 서버(Model Context Protocol)이자 A2A 서버(Agent-to-Agent JSON-RPC 2.0)입니다. MCP 호환 IDE 또는 에이전트 호스트에서 추가 래퍼 없이 OmniRoute 도구를 직접 호출할 수 있습니다.

MCP 전송 방식

• SSE: http://localhost:20128/api/mcp/sse
• 스트리밍 가능 HTTP: http://localhost:20128/api/mcp/stream
• stdio: omniroute --mcp(stdio를 선호하는 IDE 플러그인용)

Claude Desktop 연결

~/Library/Application Support/Claude/claude_desktop_config.json(macOS) 또는 Windows/Linux의 해당 파일을 편집합니다.

{
  "mcpServers": {
    "omniroute": {
      "command": "omniroute",
      "args": ["--mcp"]
    }
  }
}

Cursor / Continue / VS Code MCP 연결

SSE URL http://localhost:20128/api/mcp/sse과 Dashboard → API Keys에서 생성한 Bearer API 키를 사용합니다.

범위

MCP는 현재 이름이 지정된 32개의 범위를 정의합니다. 각 Bearer 키를 특정 범위로 제한할 수 있습니다. 공식 범위 및 도구 목록은 MCP-SERVER.md를, JSON-RPC 스키마는 A2A-SERVER.md를 참조하세요.

---

🧠 스킬 시스템

OmniRoute는 에이전트와 A2A 엔드포인트가 도메인별 루틴(예: code-review, summarize, extract-facts, web-research)을 실행할 수 있도록 확장 가능한 스킬 프레임워크(src/lib/skills/)를 제공합니다.

• 마켓플레이스 UI — 대시보드 → 스킬에서 스킬 탐색 및 설치
• 키별 범위 — 각 API 키가 호출할 수 있는 스킬 제한
• 사용자 정의 스킬 — TypeScript 파일을 src/lib/a2a/skills/에 추가하고 등록하면 A2A를 통해 즉시 호출 가능

전체 레퍼런스: SKILLS.md.

---

💾 메모리 시스템

OmniRoute는 하이브리드 검색을 활용해 장기 대화 메모리를 영구 저장합니다.

• 과거 대화 내용의 키워드 검색을 위한 SQLite FTS5
• 의미 기반 검색을 위한 Qdrant 벡터 저장소(선택 사항)
• 자동 사실 추출 — 각 세션이 끝나면 개체, 선호 사항, 결정 사항을 요약하여 memory_facts 테이블에 저장
• 메모리는 API 키별 및 세션별로 범위가 지정됨

대시보드 → 메모리에서 메모리를 관리할 수 있습니다(검색, 편집, 내보내기, 삭제). HTTP 인터페이스(/api/memory/*)를 통해 에이전트가 프로그래밍 방식으로 사실을 추가하고 조회할 수 있습니다. 자세한 내용은 MEMORY.md를 참조하세요.

---

🔔 웹훅

실시간 모니터링 및 자동화를 위해 OmniRoute 이벤트를 구독할 수 있습니다.

• 대시보드 → 웹훅에서 대상 URL 및 HMAC 서명 비밀 키를 사용해 웹훅 생성
• 사용 가능한 이벤트: request.completed, request.failed, provider.unavailable, budget.exceeded, combo.switched, circuit_breaker.opened, circuit_breaker.closed
• 모든 페이로드에는 검증을 위한 X-OmniRoute-Signature(HMAC-SHA256)가 포함됨
• 재시도: 지수 백오프 방식으로 3회 시도한 후 데드 레터 큐로 이동

전체 스키마는 WEBHOOKS.md를 참조하세요.

---

☁️ 클라우드 에이전트

OmniRoute는 클라우드 코딩 에이전트(OpenAI Codex Cloud, Devin, Jules, Antigravity)와 통합되어 로컬 라우팅을 처리하는 동일한 대시보드에서 장시간 실행되는 작업을 전달할 수 있습니다.

• 대시보드 → 클라우드 에이전트 또는 POST /api/v1/agents/tasks를 통해 작업 생성
• 작업별 상태, 로그 및 아티팩트 추적
• 제공자별로 자체 API 키 사용 — 자격 증명은 OmniRoute 인스턴스 외부로 절대 전송되지 않음

전체 레퍼런스: CLOUD_AGENT.md.

---

🛠️ 프로그래밍 방식의 관리

manage 범위가 있는 Bearer 키를 사용하여 HTTP를 통해 모든 OmniRoute 리소스(제공자, 콤보, 키, 설정)를 관리할 수 있습니다.

대시보드 → API 키 → 새 키 → 범위: manage에서 키를 생성한 후 다음 명령을 실행하세요.

# 제공자 목록 조회
curl http://localhost:20128/api/providers \
  -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY"

# 제공자 연결 추가
curl -X POST http://localhost:20128/api/providers \
  -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "provider": "openai", "apiKey": "sk-...", "name": "main" }'

# 콤보 생성
curl -X POST http://localhost:20128/api/combos \
  -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "premium", "strategy": "priority", "models": [{ "model": "cc/claude-opus-4-7" }, { "model": "glm/glm-5.1" }] }'

# API 키 목록 조회/생성
curl http://localhost:20128/api/keys -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY"
curl -X POST http://localhost:20128/api/keys -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY" \
  -d '{ "name": "ci-bot", "scopes": ["chat"] }'

전체 엔드포인트 목록과 요청/응답 스키마는 API_REFERENCE.md를 참조하세요.

---

💻 내부 CLI

OmniRoute는 설정, 진단 및 런타임 제어를 위한 내부 CLI(omniroute …)를 제공합니다. 이는 타사 CLI(Claude Code, Cursor, Codex, Cline, …)가 OmniRoute와 통신할 수 있도록 구성하는 대시보드의 "CLI Tools" 페이지와는 별개입니다.

omniroute setup                    # 대화형 마법사(비밀번호, 공급자, 콤보)
omniroute setup --non-interactive  # CI 친화적 모드
omniroute doctor                   # 상태 진단(데이터 디렉터리, DB, 공급자, 포트)
omniroute providers available      # 지원되는 공급자 목록 표시
omniroute providers list           # 구성된 연결 목록 표시
omniroute providers test <id>      # 공급자 연결 실시간 테스트
omniroute combos list              # 콤보 목록 표시
omniroute combos switch <name>     # 기본 콤보 설정
omniroute models                   # 사용 가능한 모델 목록 표시(--json, --search)
omniroute keys add | list | remove # 터미널에서 API 키 관리
omniroute backup                   # 구성 + DB 스냅샷 생성
omniroute restore [<timestamp>]    # 스냅샷에서 복원
omniroute health                   # 상세 상태(차단기, 캐시, 메모리)
omniroute quota                    # 공급자 할당량 사용량
omniroute mcp status               # MCP 서버 상태
omniroute a2a status               # A2A 서버 상태
omniroute tunnel list|create|stop  # Cloudflare/Tailscale/ngrok 터널
omniroute reset-password           # 관리자 비밀번호 재설정
omniroute --mcp                    # stdio를 통해 MCP 서버 시작
omniroute --port 3000              # 사용자 지정 포트에서 서버 시작

팁: 비정상적인 공급자 연결에 대한 알림을 받으려면 omniroute doctor --json을 모니터링 도구와 함께 사용하세요.

---

🖥️ 데스크톱 애플리케이션(Electron)

OmniRoute는 Windows, macOS 및 Linux용 네이티브 데스크톱 애플리케이션으로 제공됩니다.

설치

# electron 디렉터리에서:
cd electron
npm install

# 개발 모드(실행 중인 Next.js 개발 서버에 연결):
npm run dev

# 프로덕션 모드(독립 실행형 빌드 사용):
npm start

설치 프로그램 빌드

cd electron
npm run build          # 현재 플랫폼
npm run build:win      # Windows(.exe NSIS)
npm run build:mac      # macOS(.dmg 유니버설)
npm run build:linux    # Linux(.AppImage)

출력 → electron/dist-electron/

주요 기능

기능	설명
서버 준비 상태	창을 표시하기 전에 서버 폴링(빈 화면 방지)
시스템 트레이	트레이로 최소화, 포트 변경, 트레이 메뉴에서 종료
포트 관리	트레이에서 서버 포트 변경(서버 자동 재시작)
콘텐츠 보안 정책	세션 헤더를 통한 제한적인 CSP
단일 인스턴스	한 번에 하나의 앱 인스턴스만 실행 가능
오프라인 모드	번들된 Next.js 서버가 인터넷 없이 작동

환경 변수

변수	기본값	설명
OMNIROUTE_PORT	20128	서버 포트
OMNIROUTE_MEMORY_MB	512	Node.js 힙 제한(64–16384 MB)

📖 전체 문서: electron/README.md