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

User Guide (Filipino)

🌐 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 · 🇰🇷 ko · 🇱🇹 lt · 🇱🇻 lv · 🇮🇳 ml · 🇮🇳 mr · 🇲🇾 ms · 🇲🇹 mt · 🇲🇲 my · 🇳🇵 ne · 🇳🇱 nl · 🇳🇴 no · 🇮🇳 or · 🇮🇳 pa · 🇵🇱 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

---

🌐 Mga Wika: 🇺🇸 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á | 🇨🇳 中文 (简体) | 🇹🇼 中文 (繁體)

Kumpletong gabay para sa pag-configure ng mga provider, paggawa ng mga combo, pagsasama ng mga CLI tool, at pag-deploy ng OmniRoute.

---

Talaan ng mga Nilalaman

• Buod ng Pagpepresyo
• Mga Gamit
• Pag-setup ng Provider
• Integrasyon ng CLI
• Pag-deploy
• Mga Available na Model
• Mga Advanced na Feature
• Awtomatikong Pag-route (Walang configuration)
• Integrasyon ng MCP at A2A
• Sistema ng mga Skill
• Sistema ng Memorya
• Mga Webhook
• Mga Cloud Agent
• Pamamahala sa Pamamagitan ng Programa
• Internal na CLI
• Desktop Application (Electron)

---

💰 Buod ng Pagpepresyo

Antas	Provider	Gastos	Pag-reset ng Quota	Pinakamainam Para
💳 SUBSCRIPTION	Claude Code (Pro)	$20/buwan	5 oras + lingguhan	May subscription na
	Codex (Plus/Pro)	$20-200/buwan	5 oras + lingguhan	Mga user ng OpenAI
	GitHub Copilot	$10-19/buwan	Buwanan	Mga user ng GitHub
🔑 API KEY	DeepSeek	Bayad ayon sa paggamit	Wala	Murang pangangatwiran
	Groq	Bayad ayon sa paggamit	Wala	Napakabilis na inference
	xAI (Grok)	Bayad ayon sa paggamit	Wala	Pangangatwiran ng Grok 4
	Mistral	Bayad ayon sa paggamit	Wala	Mga model na naka-host sa EU
	Perplexity	Bayad ayon sa paggamit	Wala	Pinahusay ng paghahanap
	Together AI	Bayad ayon sa paggamit	Wala	Mga open-source na model
	Fireworks AI	Bayad ayon sa paggamit	Wala	Mabilis na mga larawang FLUX
	Cerebras	Bayad ayon sa paggamit	Wala	Bilis sa antas ng wafer
	Cohere	Bayad ayon sa paggamit	Wala	Command R+ RAG
	NVIDIA NIM	Bayad ayon sa paggamit	Wala	Mga model para sa enterprise
	Baidu Qianfan	Bayad ayon sa paggamit	Wala	Mga model na ERNIE
💰 MURA	GLM-4.7	$0.6/1M	Araw-araw, 10AM	Murang backup
	MiniMax M2.1	$0.2/1M	Umiikot kada 5 oras	Pinakamurang opsyon
	Kimi K2	$9/buwan na nakapirmi	10M token/buwan	Nahuhulaang gastos
🆓 LIBRE	Qoder	$0	Nalalapat ang mga limitasyon ng provider	Suriin ang kasalukuyang catalog
	Kiro	$0	~50 credit/buwan	Libreng Claude

---

🎯 Mga Gamit

Kaso 1: "Mayroon akong subscription sa Claude Pro"

Problema: Nag-e-expire ang quota nang hindi nagagamit, at naaabot ang mga limitasyon sa rate habang masinsinang nagko-code

Kombinasyon: "maximize-claude"
  1. cc/claude-opus-4-7        (lubusang gamitin ang subscription)
  2. glm/glm-4.7               (murang backup kapag ubos na ang quota)
  3. if/qwen3.8-max-preview       (libreng pang-emergency na fallback)

Buwanang gastos: $20 (subscription) + ~$5 (backup) = $25 lahat-lahat
kumpara sa $20 + pag-abot sa mga limitasyon = pagkabigo

Kaso 2: "Gusto kong walang gastos"

Problema: Hindi kayang magbayad para sa mga subscription at kailangan ng maaasahang AI para sa pagko-code

Kombinasyon: "zero-cost"
  1. if/kimi-k2.7-code          (nakalistang libreng access; maaaring may mga limitasyon sa rate)
  2. kr/qwen3-coder-next        (libreng fallback ng Kiro)

Buwanang gastos: $0
Kalidad: beripikahin ang model, mga limitasyon, privacy, at SLA para sa iyong workload

Kaso 3: "Kailangan kong mag-code 24/7, nang walang pagkaantala"

Problema: May mga deadline at hindi maaaring magkaroon ng downtime

Kombinasyon: "always-on"
  1. cc/claude-opus-4-7        (pinakamahusay na kalidad)
  2. cx/gpt-5.5                (ikalawang subscription)
  3. glm/glm-4.7               (mura, nagre-reset araw-araw)
  4. minimax/MiniMax-M2.1      (pinakamura, nagre-reset kada 5 oras)
  5. if/deepseek-v4-flash       (nakalistang libreng access; maaaring may mga limitasyon sa rate)

Resulta: Pinalalawak ng 5 fallback layer ang katatagan; hindi garantisado ang availability ng upstream
Buwanang gastos: $20-200 (mga subscription) + $10-20 (backup)

Kaso 4: "Gusto ko ng LIBRENG AI sa OpenClaw"

Problema: Kailangan ng AI assistant sa mga messaging app, nang ganap na libre

Kombinasyon: "openclaw-free"
  1. if/qwen3.8-max-preview     (nakalistang libreng access; maaaring may mga limitasyon sa rate)
  2. if/deepseek-v4-flash       (nakalistang libreng access; maaaring may mga limitasyon sa rate)
  3. if/kimi-k2.7-code          (nakalistang libreng access; maaaring may mga limitasyon sa rate)

Buwanang gastos: $0
I-access sa pamamagitan ng: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...

---

📖 Pag-set Up ng Provider

Para maramihang magdagdag ng mga koneksyon ng API key mula sa isang CSV o JSON file, gamitin ang Dashboard → Providers → Import from file. Nakaayon sa posisyon ang mga column (provider,name,apiKey,baseUrl,priority); dapat umiiral na ang provider bilang isang pinamamahalaang provider o katugmang node. Tingnan ang Pag-import ng mga provider mula sa isang CSV o JSON file.

🔐 Mga Subscription Provider

Claude Code (Pro/Max)

Dashboard → Providers → Connect Claude Code
→ Pag-login gamit ang OAuth → Awtomatikong pag-refresh ng token
→ 5 oras + lingguhang pagsubaybay sa quota

Mga Model:
  cc/claude-opus-4-7
  cc/claude-sonnet-4-6
  cc/claude-haiku-4-5-20251001

Pro Tip: Gamitin ang Opus para sa mga komplikadong gawain at Sonnet para sa bilis. Sinusubaybayan ng OmniRoute ang quota ng bawat model!

Pinapanatili ng mga route na katugma sa Claude at Claude Code ang max na antas ng thinking effort para sa mga model na Opus at Sonnet. Hindi tinatanggap ng mga model na Haiku ang max na antas ng effort, kaya ibinababa ng OmniRoute ang kahilingang iyon sa isang mataas na thinking budget bago ito ipadala sa upstream.

OpenAI Codex (Plus/Pro)

Dashboard → Providers → Connect Codex
→ Pag-login gamit ang OAuth (port 1455)
→ Pag-reset kada 5 oras + lingguhan

Mga Model:
  cx/gpt-5.5
  cx/gpt-5.4
  cx/gpt-5.3-codex
  cx/gpt-5.3-codex-spark

GitHub Copilot

Dashboard → Providers → Connect GitHub
→ OAuth sa pamamagitan ng GitHub
→ Buwanang pag-reset (ika-1 ng buwan)

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

💰 Mga Murang Provider

GLM-4.7 (Araw-araw na pag-reset, $0.6/1M)

1. Mag-sign up: Zhipu AI
2. Kunin ang API key mula sa Coding Plan
3. Dashboard → Add API Key: Provider: glm, API Key: your-key

Gamitin: glm/glm-4.7 — Pro Tip: Nag-aalok ang Coding Plan ng 3× quota sa 1/7 ng halaga! Nire-reset araw-araw nang 10:00 AM.

MiniMax M2.1 (Pag-reset kada 5 oras, $0.20/1M)

1. Mag-sign up: MiniMax
2. Kunin ang API key → Dashboard → Add API Key

Gamitin: minimax/MiniMax-M2.1 — Pro Tip: Pinakamurang opsyon para sa mahabang context (1M token)!

Kimi K2 (Nakapirming $9/buwan)

1. Mag-subscribe: Moonshot AI
2. Kunin ang API key → Dashboard → Add API Key

Gamitin: kimi/kimi-k2.5 — Pro Tip: Ang nakapirming $9/buwan para sa 10M token ay katumbas ng aktuwal na halagang $0.90/1M!

Baidu Qianfan / ERNIE

1. Mag-sign up: Baidu AI Cloud Qianfan
2. Gumawa ng Qianfan API key → Dashboard → Add API Key: Provider: qianfan

Gamitin: qianfan/ernie-5.1, qianfan/ernie-x1.1, o isa pang Qianfan model ID na katugma sa OpenAI.

🆓 Mga LIBRENG Provider

Ang mga libreng provider na hindi nangangailangan ng authentication ay may switch sa tabi ng No authentication required sa kanilang provider page. Kapag in-off ito, madi-disable ang provider na iyon, aalisin ito sa configured/compact na mga view ng Providers, at aalisin ang mga model nito mula sa /v1/models.

Qoder (9 na LIBRENG model)

Dashboard → Connect Qoder → Pag-login gamit ang OAuth → Ang access ay napapailalim sa kasalukuyang mga limitasyon ng provider

Mga Model: 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 (LIBRENG Claude)

Dashboard → Connect Kiro → AWS Builder ID o Google/GitHub → ~50 credit/buwan

Mga Model: kr/claude-sonnet-4.5, kr/claude-haiku-4.5

---

🎨 Mga Combo

Maaari mong baguhin ang pagkakasunod-sunod ng mga combo card nang direkta sa Dashboard → Mga Combo sa pamamagitan ng pag-drag sa handle ng bawat card. Iniimbak ang pagkakasunod-sunod sa SQLite at ibinabalik kapag nag-reload.

Halimbawa 1: I-maximize ang Subscription → Murang Backup

Dashboard → Mga Combo → Gumawa ng Bago

Pangalan: premium-coding
Mga Modelo:
  1. cc/claude-opus-4-7 (Pangunahing subscription)
  2. glm/glm-4.7 (Murang backup, $0.6/1M)
  3. minimax/MiniMax-M2.7 (Pinakamurang fallback, $0.3/1M)

Gamitin sa CLI: premium-coding

Halimbawa 2: Libre Lamang (Walang Gastos)

Pangalan: free-combo
Mga Modelo:
  1. if/kimi-k2.7-code (nakalistang libreng access; maaaring malapat ang mga limitasyon ng provider)
  2. kr/qwen3-coder-next (Libreng fallback ng Kiro)

Gastos: kasalukuyang nakalista bilang $0; maaaring magbago ang mga tuntunin at availability

---

🔧 Integrasyon sa CLI

Cursor IDE

Paggamit sa Cursor bilang OmniRoute client (idaan ang chat ng Cursor sa OmniRoute):

Mga Setting → Mga Modelo → Advanced:
  OpenAI API Base URL: http://localhost:20128/v1
  OpenAI API Key: [mula sa dashboard ng omniroute]
  Modelo: cc/claude-opus-4-7

Paggamit sa OmniRoute bilang Cursor provider (tinatawag ng OmniRoute ang upstream ng Cursor): mas piliin ang Dashboard → Mga Provider → Cursor → Mag-login gamit ang Cursor. Sa Docker, tingnan ang docs/providers/CURSOR-DOCKER.md.

Claude Code

I-edit ang ~/.claude/settings.json:

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

Gamitin dito ang Claude-compatible na root endpoint. Huwag idagdag ang /v1 sa ANTHROPIC_BASE_URL.

Codex CLI

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

OpenClaw

I-edit ang ~/.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" }]
      }
    }
  }
}

O gamitin ang Dashboard: Mga CLI Tool → OpenClaw → Awtomatikong pag-configure

Cline / Continue / RooCode

Provider: OpenAI Compatible
Base URL: http://localhost:20128/v1
API Key: [mula sa dashboard]
Modelo: cc/claude-opus-4-7

---

🚀 Pag-deploy

Pandaigdigang pag-install gamit ang npm (Inirerekomenda)

npm install -g omniroute

# Gumawa ng directory para sa configuration
mkdir -p ~/.omniroute

# Gumawa ng .env file (tingnan ang .env.example)
cp .env.example ~/.omniroute/.env

# Simulan ang server
omniroute
# O gumamit ng custom na port:
omniroute --port 3000

Awtomatikong nilo-load ng CLI ang .env mula sa ~/.omniroute/.env o ./.env.

Tray mode

Simulan ang OmniRoute sa system tray:

omniroute serve --tray

Babalik ang command kapag handa na ang server at tray.

Magpapatuloy ang server nang wala ang terminal.

Sinusuportahan ng tray mode ang macOS, Windows, at mga graphical Linux session. Hindi awtomatikong binubuksan ng tray mode ang dashboard.

Gamitin ang tray menu para sa mga sumusunod na pagkilos:

• Buksan ang dashboard.
• Buksan ang /dashboard/logs.
• Baguhin ang awtomatikong pagsisimula.
• Ihinto ang OmniRoute.

Huwag pagsamahin ang --tray sa mga sumusunod na opsyon:

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

Nangangailangan ang mga mode na ito ng magkakaibang pagmamay-ari ng proseso.

Paganahin ang pagsisimula sa susunod na pag-login sa machine:

omniroute autostart enable

Ginagamit ng awtomatikong pagsisimula ang tray mode sa macOS, Windows, at mga graphical Linux session. Ginagamit ng headless Linux ang umiiral na systemd user service.

Huwag paganahin ang pagsisimula sa pag-login:

omniroute autostart disable

Pag-uninstall

Kapag hindi mo na kailangan ang OmniRoute, nagbibigay kami ng dalawang mabilis na script para sa malinis na pagtanggal:

Command	Pagkilos
npm run uninstall	Tinatanggal ang system app ngunit pinapanatili ang iyong DB at mga configuration sa ~/.omniroute.
npm run uninstall:full	Tinatanggal ang app AT permanenteng binubura ang lahat ng configuration, key, at database.

Paalala: Upang patakbuhin ang mga command na ito, pumunta sa folder ng proyektong OmniRoute (kung na-clone mo ito) at patakbuhin ang mga ito. Bilang alternatibo, kung pandaigdigang naka-install, maaari mo lamang patakbuhin ang npm uninstall -g omniroute.

Pag-deploy sa 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
# O: pm2 start npm --name omniroute -- start

Pag-deploy gamit ang PM2 (Mababang Memory)

Para sa mga server na may limitadong RAM, gamitin ang opsyon para sa limitasyon ng memory:

# May limitasyong 512MB (default)
pm2 start npm --name omniroute -- start

# O may custom na limitasyon ng memory
OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start

# O gamit ang ecosystem.config.js
pm2 start ecosystem.config.js

Gumawa ng 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

# Buuin ang image (default = runner-cli na may naka-preinstall na codex/claude/droid)
docker build -t omniroute:cli .

# Portable mode (inirerekomenda)
docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli

Para sa host-integrated mode na may mga CLI binary, tingnan ang seksyong Docker sa pangunahing dokumentasyon.

Void Linux (xbps-src)

Maaaring i-package at i-install ng mga user ng Void Linux ang OmniRoute nang native gamit ang xbps-src cross-compilation framework. Ina-automate nito ang standalone build ng Node.js kasama ang mga kinakailangang native binding ng better-sqlite3.

Tingnan ang template ng xbps-src

# Template file para sa 'omniroute'
pkgname=omniroute
version=3.8.0
revision=1
hostmakedepends="nodejs python3 make"
depends="openssl"
short_desc="Pangkalahatang AI gateway na may matalinong routing para sa maraming LLM provider"
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() {
	# Tukuyin ang target na CPU architecture para sa node-gyp
	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) I-install ang lahat ng dependency – laktawan ang mga script
	NODE_ENV=development npm ci --ignore-scripts

	# 2) I-build ang standalone bundle ng Next.js
	npm run build

	# 3) Kopyahin ang mga static asset sa standalone
	cp -r .next/static .next/standalone/.next/static
	[ -d public ] && cp -r public .next/standalone/public || true

	# 4) I-compile ang native binding ng 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) Ilagay ang na-compile na binding sa standalone bundle
	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) Alisin ang mga bundle ng sharp na partikular sa architecture
	rm -rf .next/standalone/node_modules/@img

	# 7) Kopyahin ang mga runtime dependency ng pino na hindi isinama ng static analysis ng Next.js:
	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

	# Pigilan ang post-install hook na alisin ang mga walang-lamang directory ng Next.js app router
	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
}

Mga Environment Variable

Variable	Default	Paglalarawan
JWT_SECRET	omniroute-default-secret-change-me	Lihim sa pag-sign ng JWT (palitan sa production)
INITIAL_PASSWORD	CHANGEME	Password para sa unang pag-login
DATA_DIR	~/.omniroute	Direktoryo ng data (db, paggamit, mga log)
PORT	default ng framework	Port ng serbisyo (20128 sa mga halimbawa)
HOSTNAME	default ng framework	Host na ibi-bind (default ng Docker ang 0.0.0.0)
NODE_ENV	default ng runtime	Itakda sa production para sa deployment
NEXT_PUBLIC_BASE_URL	http://localhost:20128	Pampublikong base URL na ipinapakita sa dashboard at inilalantad sa server (pumapalit sa lumang BASE_URL)
NEXT_PUBLIC_CLOUD_URL	https://omniroute.dev	Base URL ng endpoint para sa cloud sync (pumapalit sa lumang CLOUD_URL)
API_KEY_SECRET	endpoint-proxy-api-key-secret	HMAC secret para sa mga nabuong API key
REQUIRE_API_KEY	false	Ipatupad ang Bearer API key sa /v1/*
ALLOW_API_KEY_REVEAL	false	Payagan ang mga authenticated na user ng dashboard na ipakita ang buong nakaimbak na value ng API key kapag hiniling
PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES	70	Dalas ng server-side refresh para sa naka-cache na data ng Provider Limits; nagpapasimula pa rin ng manual sync ang mga refresh button sa UI
DISABLE_SQLITE_AUTO_BACKUP	false	I-disable ang mga awtomatikong SQLite snapshot bago ang write/import/restore; gumagana pa rin ang mga manual backup
APP_LOG_TO_FILE	true	Pinapagana ang pag-output ng application at audit log sa disk
AUTH_COOKIE_SECURE	false	Piliting gamitin ang Secure auth cookie (sa likod ng HTTPS reverse proxy)
CLOUDFLARED_BIN	hindi nakatakda	Gumamit ng kasalukuyang cloudflared binary sa halip na managed download
CLOUDFLARED_PROTOCOL	http2	Transport para sa mga managed na Quick Tunnel (http2, quic, o auto)
OMNIROUTE_MEMORY_MB	512	Limitasyon ng Node.js heap sa MB
PROMPT_CACHE_MAX_SIZE	50	Pinakamataas na bilang ng mga entry sa prompt cache
SEMANTIC_CACHE_MAX_SIZE	100	Pinakamataas na bilang ng mga entry sa semantic cache

Para sa kumpletong sanggunian ng mga environment variable, tingnan ang README.

---

📊 Mga Available na Modelo

Tingnan ang lahat ng available na modelo

Ang listahan sa ibaba ay pinili mula sa open-sse/config/providerRegistry.ts para sa v3.8.0. Ang mga cloud catalog (Gemini, OpenRouter, atbp.) ay dinamikong sini-sync — para sa buong live catalog, buksan ang Dashboard → Providers → [provider] → Available Models o tawagin ang GET /api/models/catalog.

Kung hindi na napapanahon ang built-in na listahan ng isang provider, gamitin ang Import from /models sa pahinang iyon (o i-enable ang Auto-Sync) upang kunin ang live upstream catalog. Na-verify ito sa v3.8.50 para sa LLM7.io (gemini-3.1-flash-lite) at UncloseAI (solidrust/Hermes-3-Llama-3.1-8B-AWQ); nanatiling limitado ng upstream ang anonymous na access sa Pollinations sa parehong yugto ng pagsubok.

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 (+ mga antas ng effort: 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/) — LIBRENG OAuth: gamitin ang live catalog na ipinapakita sa ilalim ng Dashboard → Providers → Kiro → Available Models. Nakadepende ang availability sa account at plano.

Qoder (if/) — LIBRENG 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/buwan na flat rate o batay sa paggamit: kimi/kimi-k2.6, kimi/kimi-k2.5

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

Groq (groq/) — Napakabilis: 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/) — Native na 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/) — Naka-host sa EU: mistral/mistral-large-latest, mistral/mistral-medium-3-5, mistral/mistral-small-latest, mistral/devstral-latest, mistral/codestral-latest

Perplexity (pplx/) — Pinahusay ng search: pplx/sonar-deep-research, pplx/sonar-reasoning-pro, pplx/sonar-pro, pplx/sonar

Together AI (together/) — Open-source: together/meta-llama/Llama-3.3-70B-Instruct-Turbo-Free (libre), 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/) — Mabilis na inference: 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/) — Wafer-scale: cerebras/zai-glm-4.7, cerebras/gpt-oss-120b

Cohere (cohere/) — Nakatuon sa 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/) — Para sa enterprise: 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/): Live na sini-sync ayon sa API key mula sa Google — walang static na listahan. Magkonekta ng key sa Dashboard → Providers, pagkatapos ay gamitin ang Available Models upang i-import ang kasalukuyang catalog (hal. gemini/gemini-3-pro, gemini/gemini-3-flash).

Iba pang compatible na provider (mga napili): cohere, databricks, snowflake, together, vertex, alibaba, alibaba-cn, bedrock (sa pamamagitan ng aws-bedrock), azure-ai, openrouter (passthrough catalog), siliconflow, hyperbolic, huggingface, featherless-ai, cloudflare-ai, scaleway, deepinfra, vercel-ai-gateway, bazaarlink, friendliai, nous-research, reka, volcengine, ai21, gigachat. Ang bawat isa ay nagpapanatili ng sarili nitong listahan ng modelo sa providerRegistry.ts at maaaring awtomatikong i-sync kapag naglalantad ang provider ng /models endpoint.

Tandaan tungkol sa mga model ID: Gumagamit ang OmniRoute ng mga ID na native sa provider (claude-opus-4-8, gpt-5.5, glm-5.1, MiniMax-M2.7, kimi-k2.5, grok-4.20-0309-reasoning). May mga ID na may dotted na mga bersyon dahil iyon ang format na inaasahan ng upstream API. Kung wala sa listahan sa itaas ang isang modelo, patakbuhin ang omniroute models --search <term> o tawagin ang GET /api/models/catalog upang kumpirmahin ang availability.

---

🧩 Mga Advanced na Feature

Mga Custom na Modelo

Magdagdag ng anumang model ID sa anumang provider nang hindi naghihintay ng update sa app:

# Sa pamamagitan ng 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"}'

# Ilista: curl http://localhost:20128/api/provider-models?provider=openai
# Alisin: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-5.2"

O gamitin ang Dashboard: Providers → [Provider] → Custom Models.

Mga tala:

• Ang OpenRouter at mga provider na compatible sa OpenAI/Anthropic ay pinamamahalaan lamang mula sa Available Models. Ang manu-manong pagdaragdag, pag-import, at awtomatikong pag-sync ay napupunta lahat sa iisang listahan ng mga available na modelo, kaya walang hiwalay na seksyong Custom Models para sa mga provider na iyon.
• Ang seksyong Custom Models ay para sa mga provider na hindi naglalantad ng pinamamahalaang pag-import ng mga available na modelo.

Pag-chain ng mga OmniRoute Peer

Maaaring magdagdag ng isa pang OmniRoute gateway bilang isang Custom OpenAI-compatible na provider. Gamitin ang /v1 base URL ng peer at isang nakalaang API key na may pinakamababang pribilehiyo na ibinigay ng peer na iyon.

Para sa mga reciprocal o multi-hop chain, i-enable ang opt-in na loop guard sa bawat gateway:

# 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

Tanging ang mga request na ipinadala sa isang tahasang naka-allowlist na peer URL ang makatatanggap ng X-OmniRoute-Peer-Trace header. Tatanggihan ng gateway ang inuulit na instance ID o naubos nang hop budget gamit ang HTTP 508 Loop Detected; walang matatanggap na peer metadata ang mga karaniwang upstream provider.

Ang peer chaining ay hindi database replication o host failover. Nagpapanatili ang bawat gateway ng hiwalay na SQLite state, mga cache, rate counter, at session. Gumamit ng reverse proxy na may health check o client failover para sa active/passive o active/active availability, at huwag kailanman i-mount ang iisang SQLite database sa maraming tumatakbong OmniRoute instance.

Mga Nakalaang Route ng Provider

Direktang i-route ang mga request sa isang partikular na provider nang may validation ng modelo:

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

Awtomatikong idinaragdag ang prefix ng provider kung wala ito. Magbabalik ng 400 ang mga hindi tumutugmang modelo.

Configuration ng Network Proxy

# Itakda ang global proxy
curl -X PUT http://localhost:20128/api/settings/proxy \
  -d '{"global": {"type":"http","host":"proxy.example.com","port":"8080"}}'

# Proxy para sa bawat provider
curl -X PUT http://localhost:20128/api/settings/proxy \
  -d '{"providers": {"openai": {"type":"socks5","host":"proxy.example.com","port":"1080"}}}'

# Subukan ang proxy
curl -X POST http://localhost:20128/api/settings/proxy/test \
  -d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}'

Pagkakasunud-sunod ng prayoridad: Partikular sa key → Partikular sa combo → Partikular sa provider → Global → Environment.

API ng Catalog ng Modelo

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

Nagbabalik ng mga modelong pinangkat ayon sa provider at may mga uri (chat, embedding, image).

Cloud Sync

• I-sync ang mga provider, combo, at setting sa iba't ibang device
• Awtomatikong pag-sync sa background na may timeout + fail-fast
• Piliin ang server-side na NEXT_PUBLIC_BASE_URL/NEXT_PUBLIC_CLOUD_URL sa production

Cloudflare Quick Tunnel

• Available sa Dashboard → Endpoints para sa Docker at iba pang self-hosted deployment
• Gumagawa ng pansamantalang https://*.trycloudflare.com URL na nagfo-forward sa iyong kasalukuyang OpenAI-compatible na /v1 endpoint
• Sa unang pag-enable, ini-install lamang ang cloudflared kapag kinakailangan; muling ginagamit ng mga susunod na restart ang parehong pinamamahalaang binary
• Hindi awtomatikong ibinabalik ang mga Quick Tunnel pagkatapos ng pag-restart ng OmniRoute o container; muling i-enable ang mga ito mula sa dashboard kapag kinakailangan
• Pansamantala ang mga tunnel URL at nagbabago sa tuwing ihihinto/sisimulan mo ang tunnel
• Bilang default, gumagamit ang mga pinamamahalaang Quick Tunnel ng HTTP/2 transport upang maiwasan ang maiingay na babala tungkol sa QUIC UDP buffer sa mga container na may limitadong resource
• Itakda ang CLOUDFLARED_PROTOCOL=quic o auto kung nais mong i-override ang pinamamahalaang pagpili ng transport
• Itakda ang CLOUDFLARED_BIN kung mas gusto mong gumamit ng paunang naka-install na cloudflared binary sa halip na ang pinamamahalaang download
• Maaaring ipakita o itago ang mga panel ng Cloudflare Quick Tunnel, Tailscale Funnel, at ngrok Tunnel sa Settings → Appearance. Ang pagtatago ng panel ay hindi nagpapahinto sa tumatakbong tunnel.

Katalinuhan ng LLM Gateway (Phase 9)

• Semantic Cache — Awtomatikong nagka-cache ng mga non-streaming na response na may temperature=0 (i-bypass gamit ang X-OmniRoute-No-Cache: true)
• Request Idempotency — Nagde-deduplicate ng mga request sa loob ng 5s sa pamamagitan ng Idempotency-Key o X-Request-Id header
• Pagsubaybay sa Progreso — Mga opt-in na SSE event: progress event sa pamamagitan ng X-OmniRoute-Progress: true header

---

Translator Playground

I-access sa pamamagitan ng Dashboard → Translator. I-debug at i-visualize kung paano isinasalin ng OmniRoute ang mga API request sa pagitan ng mga provider.

Mode	Layunin
Playground	Pumili ng source/target format, mag-paste ng request, at agad na makita ang isinaling output
Chat Tester	Magpadala ng mga live na chat message sa pamamagitan ng proxy at suriin ang buong cycle ng request/response
Test Bench	Magpatakbo ng mga batch test sa maraming kumbinasyon ng format upang tiyakin ang kawastuhan ng pagsasalin
Live Monitor	Subaybayan ang mga real-time na pagsasalin habang dumadaloy ang mga request sa proxy

Mga gamit:

• I-debug kung bakit pumapalya ang isang partikular na kumbinasyon ng client/provider
• Tiyaking naisasalin nang tama ang mga thinking tag, tool call, at system prompt
• Ihambing ang mga pagkakaiba ng format sa OpenAI, Claude, Gemini, at mga format ng Responses API

---

Mga Estratehiya sa Routing

I-configure sa pamamagitan ng Dashboard → Settings → Routing. Ipinapakita ng dashboard ang anim na pinakaginagamit na strategy; internally, mas malawak na hanay ang sinusuportahan ng mga combo at ng auto-router.

Mga strategy na makikita sa dashboard (account-level routing):

Strategy	Paglalarawan
Fill First	Gumagamit ng mga account ayon sa priority — pinangangasiwaan ng primary account ang lahat ng request hanggang hindi na ito available
Round Robin	Salit-salitang ginagamit ang lahat ng account nang may nako-configure na sticky limit (default: 3 tawag bawat account)
P2C (Power of Two Choices)	Pumipili ng 2 random na account at nagru-route sa mas healthy — binabalanse ang load habang isinasaalang-alang ang health
Random	Random na pumipili ng account para sa bawat request gamit ang Fisher-Yates shuffle
Least Used	Nagru-route sa account na may pinakalumang lastUsedAt timestamp, na pantay na namamahagi ng traffic
Cost Optimized	Nagru-route sa account na may pinakamababang priority value, na nag-o-optimize para sa mga provider na may pinakamababang gastos

Mga advanced combo at auto strategy (nako-configure bawat combo o sa pamamagitan ng mga auto/* prefix — tingnan ang AUTO-COMBO.md):

• priority — mahigpit na pagkakasunod-sunod, hindi kailanman gumagamit ng round-robin
• weighted — proporsyonal na paghahati ng traffic batay sa mga per-model weight
• fill-first — ginagamit ang unang model hanggang maabot ang mga limitasyon
• round-robin / strict-random / random
• p2c (Power of Two Choices)
• least-used at cost-optimized
• auto — score-driven sa lahat ng candidate
• lkgp (Last Known Good Provider) — nananatili sa huling matagumpay na provider, pagkatapos ay gumagamit ng mga fallback rule
• context-optimized — pinipili ang model na may pinakamalaking libreng context window
• context-relay — pinagkakawing ang mga long-context model para sa mga follow-up turn

External Sticky Session Header

Para sa external session affinity (halimbawa, mga Claude Code/Codex agent sa likod ng mga reverse proxy), ipadala ang:

X-Session-Id: your-session-key

Tinatanggap din ng OmniRoute ang x_session_id at ibinabalik ang aktwal na session key sa X-OmniRoute-Session-Id.

Kung gumagamit ka ng Nginx at nagpapadala ng mga header na underscore-form, i-enable ang:

underscores_in_headers on;

Mga Wildcard Model Alias

Gumawa ng mga wildcard pattern upang muling i-map ang mga pangalan ng model:

Pattern: claude-sonnet-*     →  Target: cc/claude-sonnet-4-6
Pattern: gpt-*               →  Target: gh/gpt-5.3-codex

Sinusuportahan ng mga wildcard ang * (anumang mga character) at ? (iisang character).

Mga Fallback Chain

Magtakda ng mga global fallback chain na nalalapat sa lahat ng request:

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

---

Resilience at Mga Circuit Breaker

I-configure sa pamamagitan ng Dashboard → Settings → Resilience.

Nagpapatupad ang OmniRoute ng provider-level resilience gamit ang limang component:

1. Request Queue at Pacing — System-level na paghubog sa mga request:

   • Requests Per Minute (RPM) — Maximum na bilang ng request bawat minuto para sa bawat account
   • Min Time Between Requests — Minimum na pagitan sa milliseconds sa pagitan ng mga request
   • Max Concurrent Requests — Maximum na bilang ng sabay-sabay na request para sa bawat account

2. Connection Cooldown — Configuration para sa bawat auth type para sa isang connection pagkatapos ng mga failure na maaaring i-retry:

   • Base Cooldown — Default na cooldown window para sa mga upstream failure na maaaring i-retry
   • Use Upstream Retry Hints — Sinusunod ang mga authoritative na Retry-After o reset hint kapag ibinigay
   • Max Backoff Steps — Maximum na exponential backoff level para sa mga paulit-ulit na failure

3. Provider Circuit Breaker — Sinusubaybayan ang mga end-to-end na provider failure, minamarkahan ang isang provider bilang degraded kapag naabot ang naka-configure na warning threshold, at binubuksan ang breaker kapag naabot ang naka-configure na failure threshold:

   • Degradation Threshold — Magkakasunod na provider failure bago pumasok sa DEGRADED
   • Failure Threshold — Magkakasunod na provider failure bago pumasok sa OPEN
   • Reset Timeout — Palugit bago muling subukan ang provider
   • CLOSED (Healthy) — Normal na dumadaloy ang mga request
   • DEGRADED — Patuloy na dumadaloy ang mga request habang sinusubaybayan ang tumataas na bilang ng mga failure
   • OPEN — Pansamantalang bina-block ang provider pagkatapos ng mga paulit-ulit na failure
   • HALF_OPEN — Sinusuri kung nakarekober na ang provider

   Ang mga connection-scoped na 429 rate limit ay nananatili sa Connection Cooldown at hindi ibinibilang sa provider breaker.

   Ang runtime state ng provider breaker ay ipinapakita lamang sa Dashboard → Health.

4. Wait For Cooldown — Kung nagko-cooldown na ang bawat candidate connection, maaaring hintayin ng OmniRoute ang pinakamaagang cooldown at awtomatikong subukang muli ang parehong client request.

5. Rate Limit Auto-Detection — Kapag nagbalik ang mga upstream provider ng tahasang mga wait window, ino-override ng mga hint na iyon ang lokal na connection cooldown kapag naka-enable ang setting.

Pro Tip: Gamitin ang page na Health upang siyasatin at i-reset ang mga aktibong provider breaker pagkatapos ng outage. Configuration lamang ang binabago ng page na Resilience.

---

Pag-export / Pag-import ng Database

Pamahalaan ang mga database backup sa Dashboard → Settings → System & Storage.

Aksyon	Paglalarawan
I-export ang Database	Dina-download ang kasalukuyang SQLite database bilang isang .sqlite file
I-export Lahat (.tar.gz)	Dina-download ang buong backup archive na kinabibilangan ng: database, mga setting, combo, mga koneksyon sa provider (walang kredensyal), metadata ng API key
I-import ang Database	Nag-a-upload ng .sqlite file upang palitan ang kasalukuyang database. Awtomatikong gumagawa ng backup bago mag-import maliban kung DISABLE_SQLITE_AUTO_BACKUP=true

# API: I-export ang database
curl -o backup.sqlite http://localhost:20128/api/db-backups/export

# API: I-export lahat (buong archive)
curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll

# API: I-import ang database
curl -X POST http://localhost:20128/api/db-backups/import \
  -F "file=@backup.sqlite"

Pagpapatunay sa Pag-import: Sinusuri ang na-import na file para sa integridad (SQLite pragma check), mga kinakailangang table (provider_connections, provider_nodes, combos, api_keys), at laki (maximum na 100MB).

Mga Gamit:

• Ilipat ang OmniRoute sa pagitan ng mga machine
• Gumawa ng mga external backup para sa disaster recovery
• Magbahagi ng mga configuration sa mga miyembro ng team (i-export lahat → ibahagi ang archive)

---

Dashboard ng Mga Setting

Nakaayos ang pahina ng mga setting sa 7 tab para sa madaling pag-navigate:

Tab	Nilalaman
Pangkalahatan	Mga tool sa system storage, default na behavior, visibility ng Endpoint tunnel
Hitsura	Mga kontrol sa theme (light/dark/system), visibility ng sidebar, mga panel toggle para sa mga tunnel card ng Cloudflare/Tailscale/ngrok
AI	Thinking budget (passthrough / auto-strip / custom / adaptive — tingnan ang THINKING_BUDGET.md), global system prompt, mga istatistika ng prompt cache
Seguridad	Mga setting ng Login/Password, IP Access Control, API auth para sa /models, Provider Blocking, proteksyon laban sa prompt injection
Routing	Global na routing strategy (Fill First / Round Robin / P2C / Random / Least Used / Cost Optimized), mga wildcard model alias, mga fallback chain, mga default ng combo
Resilience	Request queue, cooldown ng koneksyon, configuration ng provider breaker, at behavior ng paghihintay sa cooldown
Advanced	Global na configuration ng proxy (HTTP/SOCKS5), mga proxy override para sa bawat provider

Hindi na inuulit ng Pangkalahatan ang mga read-only na tala tungkol sa logging at cache. Ang mga setting para sa retention at optimization ng database ay pinapanatili sa pamamagitan ng /api/settings/database; gumagamit ang manu-manong pag-clear ng cache ng DELETE /api/cache. Ang mga limitasyon sa bilang ng row ng request log at proxy log ay kinokontrol ng CALL_LOGS_TABLE_MAX_ROWS at PROXY_LOGS_TABLE_MAX_ROWS.

---

Pamamahala ng Mga Gastos at Badyet

I-access sa pamamagitan ng Dashboard → Mga Gastos.

Tab	Layunin
Badyet	Magtakda ng mga limitasyon sa paggastos para sa bawat API key gamit ang pang-araw-araw/panglingguhan/buwanang badyet at real-time na pagsubaybay
Pagpepresyo	Tingnan at i-edit ang mga entry sa pagpepresyo ng model — gastos sa bawat 1K input/output token para sa bawat provider

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

# API: Kunin ang kasalukuyang status ng badyet
curl http://localhost:20128/api/usage/budget

Pagsubaybay sa Gastos: Itinatala ng bawat request ang paggamit ng token at kinakalkula ang gastos gamit ang table ng pagpepresyo. Tingnan ang mga breakdown sa Dashboard → Paggamit ayon sa provider, model, at API key.

---

Transkripsyon ng Audio

Sinusuportahan ng OmniRoute ang transkripsyon ng audio sa pamamagitan ng endpoint na compatible sa OpenAI:

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

# Halimbawa gamit ang 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"

Ang deepgram/nova-3 ang native na Deepgram route at nangangailangan ito ng Deepgram API key. Kung OpenRouter lamang ang naka-configure, gamitin ang openrouter/deepgram/nova-3.

Mga provider ng Speech-to-Text (transkripsyon):

• openai/ (compatible sa whisper)
• groq/ (Groq Whisper Turbo)
• deepgram/ (Nova family)
• assemblyai/
• nvidia/ (Parakeet, Canary)
• huggingface/ (mga variant ng whisper)
• qwen/

Mga provider ng Text-to-Speech (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/

Mga sinusuportahang format ng audio para sa transkripsyon: mp3, wav, m4a, flac, ogg, webm. Nakadepende sa provider ang mga format ng output ng TTS (mp3, wav, opus, pcm, mulaw).

---

Mga Strategy sa Pagbabalanse ng Combo

I-configure ang pagbabalanse para sa bawat combo sa Dashboard → Mga Combo → Gumawa/Mag-edit → Strategy.

Estratehiya	Paglalarawan
Round-Robin	Salit-salitang umiikot sa mga modelo nang sunud-sunod
Priority	Palaging sinusubukan muna ang unang modelo; lilipat lang kapag may error
Random	Pumipili ng random na modelo mula sa combo para sa bawat kahilingan
Weighted	Nagruruta nang proporsyonal batay sa nakatalagang timbang ng bawat modelo
Least-Used	Nagruruta sa modelong may pinakakaunting kamakailang kahilingan (gumagamit ng mga sukatan ng combo)
Cost-Optimized	Nagruruta sa pinakamurang available na modelo (gumagamit ng talahanayan ng pagpepresyo)

Maaaring itakda ang mga global na default ng combo sa Dashboard → Settings → Routing → Combo Defaults. Bilang default, minamana ng mga timeout ng target ng combo ang kasalukuyang timeout ng kahilingan. Gamitin lang ang Target timeout (seconds) sa mga default ng combo o sa isang indibidwal na combo kapag kailangan ng mas maikling limitasyon sa bawat target upang mas mabilis na ma-trigger ang fallback.

Kailangang tahasang i-enable ang mga zero-latency na pag-optimize ng combo. Panatilihing naka-disable ang Zero-latency optimizations upang maiwasang paunahan ng mga feature na ito sa latency ang mga fallback na target, laktawan ang mga target batay sa kasaysayan ng TTFT, o i-compress ang mga fallback na kahilingan; kapag in-enable ito, papayagan ang naka-configure na hedging, mga predictive na paglaktaw batay sa TTFT, at maagap na pag-compress ng fallback upang ipagpalit ang katapatan ng pagruruta/kahilingan para sa mas mababang tail latency.

I-disable ang Reasoning token buffer kapag nangangailangan ang mga upstream provider ng mahihigpit na limitasyon sa max_tokens / maxOutputTokens. Kapag naka-enable, nagdaragdag lang ang pagruruta ng combo ng karagdagang puwang para sa reasoning model para sa mga modelong may kilalang output cap at hindi binabago ang limitasyon ng token ng client kapag ang ligtas na buffered value ay lalampas sa cap na iyon. Kung ang limitasyon ng client ay lampas na sa isang kilalang cap, ibinababa ito ng OmniRoute sa cap na iyon bago ipadala ang upstream na kahilingan.

---

Dashboard ng Kalagayan

I-access sa pamamagitan ng Dashboard → Health. Real-time na pangkalahatang-ideya ng kalagayan ng system na may 6 na card:

Card	Ipinapakita Nito
System Status	Uptime, bersyon, paggamit ng memory, directory ng data
Provider Health	Runtime state ng global na circuit breaker ng provider
Rate Limits	Mga aktibong cooldown ng koneksyon sa bawat account at natitirang oras
Active Lockouts	Mga aktibong lockout na nakasaklaw sa modelo at pansamantalang pagbubukod
Signature Cache	Mga stat ng deduplication cache (mga aktibong key, hit rate)
Latency Telemetry	Pagsasama-sama ng p50/p95/p99 latency sa bawat provider

Pro Tip: Awtomatikong nagre-refresh ang pahina ng Health bawat 10 segundo. Gamitin ang card ng circuit breaker upang matukoy kung aling mga provider ang nakararanas ng mga problema.

---

🤖 Awtomatikong Pagruruta (Walang configuration)

Kasama sa OmniRoute ang isang awtomatikong router na nakabatay sa score na pumipili ng pinakamahusay na modelo para sa bawat kahilingan mula sa lahat ng nakakonektang provider — walang combo na kailangang imantini. Ipadala lang ang kahilingan gamit ang isa sa mga prefix na auto/*, at bubuo ang OmniRoute ng virtual na combo habang tumatakbo, na nagbibigay ng score sa mga kandidato batay sa latency, gastos, success rate, pagiging angkop sa context, pagiging angkop ng modelo sa gawain, mga kamakailang pagkabigo, quota, at estado ng circuit breaker.

Prefix	Ino-optimize para sa
auto	Balanseng default (latency × gastos × success rate)
auto/coding	Mga gawain sa coding: inuuna ang Claude, GPT-5, GLM, Kimi, Qwen Coder, at mga coder ng DeepSeek
auto/cheap	Pinakamababang $/token, tumatanggap ng mas mataas na latency
auto/fast	Pinakamababang latency, hindi isinasaalang-alang ang gastos
auto/offline	Mga local-only na provider (Ollama, vLLM, llama.cpp) — kapaki-pakinabang para sa mga air-gapped na setup
auto/smart	Inuuna ang kalidad ng reasoning (Opus, GPT-5 xhigh, R1, GLM 5.1 reasoning)
auto/lkgp	"Huling Kilalang Mahusay na Provider" — nananatili sa huling matagumpay na provider, pagkatapos ay bumabalik sa mga panuntunan

Halimbawa:

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": "Refactor this Python function" }],
    "stream": true
  }'

Ganap na inilalarawan ang awtomatikong router sa AUTO-COMBO.md — kabilang ang kung paano isaayos ang mga scoring weight, i-blacklist ang mga provider, at siyasatin ang mga desisyon sa pagruruta sa Dashboard → Auto Combo.

---

🔌 Integrasyon ng MCP at A2A

Ang OmniRoute ay parehong MCP server (Model Context Protocol) at A2A server (Agent-to-Agent JSON-RPC 2.0). Maaaring direktang tawagin ng anumang MCP-compatible na IDE o agent host ang mga tool ng OmniRoute — walang kinakailangang karagdagang wrapper.

Mga transport ng MCP

• SSE: http://localhost:20128/api/mcp/sse
• Streamable HTTP: http://localhost:20128/api/mcp/stream
• stdio: omniroute --mcp (para sa mga IDE plugin na mas gustong gumamit ng stdio)

Ikonekta ang Claude Desktop

I-edit ang ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o ang katumbas nito sa Windows/Linux:

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

Ikonekta ang Cursor / Continue / VS Code MCP

Gamitin ang SSE URL na http://localhost:20128/api/mcp/sse at isang Bearer API key na binuo sa Dashboard → API Keys.

Mga scope

Kasalukuyang tumutukoy ang MCP ng 32 pinangalanang scope. Maaaring limitahan ang bawat Bearer key sa mga partikular na scope — tingnan ang MCP-SERVER.md para sa opisyal na imbentaryo ng mga scope at tool, at ang A2A-SERVER.md para sa JSON-RPC schema.

---

🧠 Sistema ng Skills

Nagbibigay ang OmniRoute ng napapalawak na skill framework (src/lib/skills/) upang makapagpatakbo ang mga agent at ang A2A endpoint ng mga routine na partikular sa domain (hal. code-review, summarize, extract-facts, web-research).

• Marketplace UI — Mag-browse at mag-install ng mga skill mula sa Dashboard → Skills
• Mga scope kada key — Limitahan kung aling mga API key ang maaaring gumamit ng partikular na mga skill
• Mga custom na skill — Maglagay ng TypeScript file sa src/lib/a2a/skills/, irehistro ito, at maaari na agad itong gamitin sa pamamagitan ng A2A

Kumpletong sanggunian: SKILLS.md.

---

💾 Sistema ng Memory

Nagpapanatili ang OmniRoute ng pangmatagalang memory ng pag-uusap gamit ang hybrid retrieval:

• SQLite FTS5 para sa paghahanap gamit ang keyword sa mga nakaraang turn
• Qdrant vector store (opsyonal) para sa semantic recall
• Awtomatikong pagkuha ng mga fact — binubuod ang mga entity, kagustuhan, at desisyon pagkatapos ng bawat session at iniimbak sa table na memory_facts
• Ang mga memory ay nakahiwalay ayon sa bawat API key at bawat session

Pamahalaan ang mga memory sa Dashboard → Memory (maghanap, mag-edit, mag-export, mag-purge). Hinahayaan ng HTTP interface (/api/memory/*) ang mga agent na magpadala at mag-query ng mga fact sa pamamagitan ng program — tingnan ang MEMORY.md.

---

🔔 Mga Webhook

Mag-subscribe sa mga event ng OmniRoute para sa real-time na pagsubaybay at automation.

• Gumawa ng webhook sa Dashboard → Webhooks na may target URL at HMAC signing secret
• Mga available na event: request.completed, request.failed, provider.unavailable, budget.exceeded, combo.switched, circuit_breaker.opened, circuit_breaker.closed
• Kasama sa bawat payload ang X-OmniRoute-Signature (HMAC-SHA256) para sa beripikasyon
• Mga retry: 3 pagtatangka na may exponential backoff, pagkatapos ay ililipat sa dead-letter queue

Kumpletong schema sa WEBHOOKS.md.

---

☁️ Mga Cloud Agent

Naka-integrate ang OmniRoute sa mga cloud coding agent (OpenAI Codex Cloud, Devin, Jules, Antigravity) upang makapagpadala ka ng mga matagal na task mula sa parehong dashboard na namamahala sa iyong lokal na routing.

• Gumawa ng mga task sa Dashboard → Cloud Agents o sa pamamagitan ng POST /api/v1/agents/tasks
• Subaybayan ang status, mga log, at mga artifact ng bawat task
• Gumamit ng sarili mong API key para sa bawat provider — hindi kailanman lumalabas ang mga credential sa instance ng OmniRoute

Kumpletong sanggunian: CLOUD_AGENT.md.

---

🛠️ Pamamahala sa Pamamagitan ng Program

Maaari mong pamahalaan ang bawat resource ng OmniRoute (mga provider, combo, key, setting) sa pamamagitan ng HTTP gamit ang isang Bearer key na may manage scope.

Buuin ang key sa Dashboard → API Keys → New Key → Scope: manage, pagkatapos ay:

# Ilista ang mga provider
curl http://localhost:20128/api/providers \
  -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY"

# Magdagdag ng koneksyon sa provider
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" }'

# Gumawa ng combo
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" }] }'

# Ilista/gumawa ng mga API key
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"] }'

Tingnan ang API_REFERENCE.md para sa kumpletong catalog ng endpoint at mga schema ng request/response.

---

💻 Panloob na CLI

Ang OmniRoute ay may kasamang panloob na CLI (omniroute …) para sa pag-setup, mga diagnostic, at pagkontrol sa runtime. Hiwalay ito sa pahina ng "Mga CLI Tool" sa dashboard, na nagko-configure ng mga third-party na CLI (Claude Code, Cursor, Codex, Cline, …) upang makakonekta ang mga ito sa OmniRoute.

omniroute setup                    # Interaktibong wizard (password, mga provider, mga combo)
omniroute setup --non-interactive  # Angkop para sa CI
omniroute doctor                   # Mga diagnostic sa kalagayan (data dir, DB, mga provider, mga port)
omniroute providers available      # Ilista ang mga sinusuportahang provider
omniroute providers list           # Ilista ang mga naka-configure na koneksyon
omniroute providers test <id>      # Subukan nang live ang koneksyon sa provider
omniroute combos list              # Ilista ang mga combo
omniroute combos switch <name>     # Itakda ang default na combo
omniroute models                   # Ilista ang mga available na modelo (--json, --search)
omniroute keys add | list | remove # Pamahalaan ang mga API key mula sa terminal
omniroute backup                   # Gumawa ng snapshot ng config + DB
omniroute restore [<timestamp>]    # Mag-restore mula sa isang snapshot
omniroute health                   # Detalyadong kalagayan (mga breaker, cache, memory)
omniroute quota                    # Paggamit ng quota ng provider
omniroute mcp status               # Katayuan ng MCP server
omniroute a2a status               # Katayuan ng A2A server
omniroute tunnel list|create|stop  # Mga Cloudflare/Tailscale/ngrok tunnel
omniroute reset-password           # I-reset ang admin password
omniroute --mcp                    # Simulan ang MCP server sa pamamagitan ng stdio
omniroute --port 3000              # Simulan ang server sa isang custom na port

Tip: ipares ang omniroute doctor --json sa iyong monitoring tool upang makatanggap ng alerto kapag may hindi maayos na koneksyon sa provider.

---

🖥️ Desktop Application (Electron)

Available ang OmniRoute bilang native na desktop application para sa Windows, macOS, at Linux.

Pag-install

# Mula sa electron directory:
cd electron
npm install

# Development mode (kumokonekta sa tumatakbong Next.js dev server):
npm run dev

# Production mode (gumagamit ng standalone build):
npm start

Pagbuo ng mga Installer

cd electron
npm run build          # Kasalukuyang platform
npm run build:win      # Windows (.exe NSIS)
npm run build:mac      # macOS (.dmg universal)
npm run build:linux    # Linux (.AppImage)

Output → electron/dist-electron/

Mga Pangunahing Feature

Feature	Paglalarawan
Kahandaan ng Server	Pino-poll ang server bago ipakita ang window (walang blangkong screen)
System Tray	I-minimize sa tray, baguhin ang port, o isara mula sa tray menu
Pamamahala ng Port	Baguhin ang server port mula sa tray (awtomatikong nire-restart ang server)
Content Security Policy	Mahigpit na CSP sa pamamagitan ng mga session header
Iisang Instance	Isang app instance lamang ang maaaring tumakbo sa bawat oras
Offline Mode	Gumagana ang naka-bundle na Next.js server nang walang internet

Mga Environment Variable

Variable	Default	Paglalarawan
OMNIROUTE_PORT	20128	Port ng server
OMNIROUTE_MEMORY_MB	512	Limitasyon ng Node.js heap (64–16384 MB)

📖 Kumpletong dokumentasyon: electron/README.md