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

User Guide (Bahasa Melayu)

🌐 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 · 🇲🇹 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

---

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

Panduan lengkap untuk mengkonfigurasi penyedia, mencipta kombo, mengintegrasikan alat CLI dan menggunakan OmniRoute.

---

Kandungan

• Harga Sepintas Lalu
• Kes Penggunaan
• Persediaan Penyedia
• Penyepaduan CLI
• Pelaksanaan
• Model yang Tersedia
• Ciri Lanjutan
• Penghalaan Automatik (Konfigurasi sifar)
• Penyepaduan MCP & A2A
• Sistem Kemahiran
• Sistem Memori
• Webhook
• Ejen Awan
• Pengurusan Secara Pengaturcaraan
• CLI Dalaman
• Aplikasi Desktop (Electron)

---

💰 Harga Sepintas Lalu

Peringkat	Penyedia	Kos	Penetapan Semula Kuota	Paling Sesuai Untuk
💳 LANGGANAN	Claude Code (Pro)	$20/bulan	5j + mingguan	Sudah melanggan
	Codex (Plus/Pro)	$20-200/bulan	5j + mingguan	Pengguna OpenAI
	GitHub Copilot	$10-19/bulan	Bulanan	Pengguna GitHub
🔑 KUNCI API	DeepSeek	Bayar mengikut penggunaan	Tiada	Penaakulan murah
	Groq	Bayar mengikut penggunaan	Tiada	Inferens ultra pantas
	xAI (Grok)	Bayar mengikut penggunaan	Tiada	Penaakulan Grok 4
	Mistral	Bayar mengikut penggunaan	Tiada	Model yang dihoskan di EU
	Perplexity	Bayar mengikut penggunaan	Tiada	Dipertingkat dengan carian
	Together AI	Bayar mengikut penggunaan	Tiada	Model sumber terbuka
	Fireworks AI	Bayar mengikut penggunaan	Tiada	Imej FLUX pantas
	Cerebras	Bayar mengikut penggunaan	Tiada	Kelajuan skala wafer
	Cohere	Bayar mengikut penggunaan	Tiada	Command R+ RAG
	NVIDIA NIM	Bayar mengikut penggunaan	Tiada	Model perusahaan
	Baidu Qianfan	Bayar mengikut penggunaan	Tiada	Model ERNIE
💰 MURAH	GLM-4.7	$0.6/1M	Setiap hari 10AM	Sandaran bajet
	MiniMax M2.1	$0.2/1M	Bergilir setiap 5 jam	Pilihan termurah
	Kimi K2	$9/bulan kadar tetap	10M token/bulan	Kos yang boleh diramal
🆓 PERCUMA	Qoder	$0	Had penyedia terpakai	Sahkan katalog semasa
	Kiro	$0	~50 kredit/bulan	Claude percuma

---

🎯 Kes Penggunaan

Kes 1: "Saya mempunyai langganan Claude Pro"

Masalah: Kuota tamat tanpa digunakan, had kadar dikenakan semasa pengekodan intensif

Gabungan: "maximize-claude"
  1. cc/claude-opus-4-7        (gunakan langganan sepenuhnya)
  2. glm/glm-4.7               (sandaran murah apabila kuota habis)
  3. if/qwen3.8-max-preview       (pilihan sandaran kecemasan percuma)

Kos bulanan: $20 (langganan) + ~$5 (sandaran) = jumlah $25
berbanding $20 + mencapai had = mengecewakan

Kes 2: "Saya mahukan kos sifar"

Masalah: Tidak mampu membayar langganan, memerlukan AI pengekodan yang boleh dipercayai

Gabungan: "zero-cost"
  1. if/kimi-k2.7-code          (akses percuma yang disenaraikan; had kadar mungkin terpakai)
  2. kr/qwen3-coder-next        (pilihan sandaran percuma Kiro)

Kos bulanan: $0
Kualiti: sahkan model, had, privasi dan SLA untuk beban kerja anda

Kes 3: "Saya memerlukan pengekodan 24/7, tanpa gangguan"

Masalah: Tarikh akhir, tidak mampu mengalami masa henti

Gabungan: "always-on"
  1. cc/claude-opus-4-7        (kualiti terbaik)
  2. cx/gpt-5.5                (langganan kedua)
  3. glm/glm-4.7               (murah, ditetapkan semula setiap hari)
  4. minimax/MiniMax-M2.1      (termurah, ditetapkan semula setiap 5j)
  5. if/deepseek-v4-flash       (akses percuma yang disenaraikan; had kadar mungkin terpakai)

Hasil: 5 lapisan sandaran memperluas daya tahan; ketersediaan huluan tidak dijamin
Kos bulanan: $20-200 (langganan) + $10-20 (sandaran)

Kes 4: "Saya mahukan AI PERCUMA dalam OpenClaw"

Masalah: Memerlukan pembantu AI dalam aplikasi pemesejan, percuma sepenuhnya

Gabungan: "openclaw-free"
  1. if/qwen3.8-max-preview     (akses percuma yang disenaraikan; had kadar mungkin terpakai)
  2. if/deepseek-v4-flash       (akses percuma yang disenaraikan; had kadar mungkin terpakai)
  3. if/kimi-k2.7-code          (akses percuma yang disenaraikan; had kadar mungkin terpakai)

Kos bulanan: $0
Akses melalui: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...

---

📖 Persediaan Penyedia

Untuk menambah sambungan kunci API secara pukal daripada fail CSV atau JSON, gunakan Papan Pemuka → Penyedia → Import daripada fail. Lajur disusun mengikut kedudukan (provider,name,apiKey,baseUrl,priority); provider mestilah telah wujud sebagai penyedia terurus atau nod yang serasi. Lihat Import penyedia daripada fail CSV atau JSON.

🔐 Penyedia Langganan

Claude Code (Pro/Max)

Papan Pemuka → Penyedia → Sambungkan Claude Code
→ Log masuk OAuth → Muat semula token secara automatik
→ Penjejakan kuota 5 jam + mingguan

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

Petua Pro: Gunakan Opus untuk tugas yang rumit, Sonnet untuk kepantasan. OmniRoute menjejaki kuota bagi setiap model!

Laluan yang serasi dengan Claude dan Claude Code mengekalkan tahap usaha penaakulan max untuk model Opus dan Sonnet. Model Haiku tidak menerima tahap usaha max, jadi OmniRoute menurunkan permintaan tersebut kepada bajet penaakulan tinggi sebelum menghantarnya kepada penyedia huluan.

OpenAI Codex (Plus/Pro)

Papan Pemuka → Penyedia → Sambungkan Codex
→ Log masuk OAuth (port 1455)
→ Penetapan semula 5 jam + mingguan

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

GitHub Copilot

Papan Pemuka → Penyedia → Sambungkan GitHub
→ OAuth melalui GitHub
→ Penetapan semula bulanan (hari pertama setiap bulan)

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

💰 Penyedia Murah

GLM-4.7 (Ditetapkan semula setiap hari, $0.6/1M)

1. Daftar: Zhipu AI
2. Dapatkan kunci API daripada Coding Plan
3. Papan Pemuka → Tambah Kunci API: Penyedia: glm, Kunci API: your-key

Penggunaan: glm/glm-4.7 — Petua Pro: Coding Plan menawarkan kuota 3× pada 1/7 kos! Ditetapkan semula setiap hari pada 10:00 pagi.

MiniMax M2.1 (Ditetapkan semula setiap 5 jam, $0.20/1M)

1. Daftar: MiniMax
2. Dapatkan kunci API → Papan Pemuka → Tambah Kunci API

Penggunaan: minimax/MiniMax-M2.1 — Petua Pro: Pilihan termurah untuk konteks panjang (1M token)!

Kimi K2 (Kadar tetap $9/bulan)

1. Langgan: Moonshot AI
2. Dapatkan kunci API → Papan Pemuka → Tambah Kunci API

Penggunaan: kimi/kimi-k2.5 — Petua Pro: Kadar tetap $9/bulan untuk 10M token = kos efektif $0.90/1M!

Baidu Qianfan / ERNIE

1. Daftar: Baidu AI Cloud Qianfan
2. Cipta kunci API Qianfan → Papan Pemuka → Tambah Kunci API: Penyedia: qianfan

Penggunaan: qianfan/ernie-5.1, qianfan/ernie-x1.1, atau ID model lain yang serasi dengan OpenAI daripada Qianfan.

🆓 Penyedia PERCUMA

Penyedia percuma tanpa pengesahan mempunyai suis di sebelah Tiada pengesahan diperlukan pada halaman penyedia masing-masing. Mematikannya akan menyahdayakan penyedia tersebut, mengalih keluarnya daripada paparan Penyedia yang dikonfigurasikan/padat, serta mengalih keluar modelnya daripada /v1/models.

Qoder (9 model PERCUMA)

Papan Pemuka → Sambungkan Qoder → Log masuk OAuth → Akses tertakluk pada had penyedia semasa

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 (Claude PERCUMA)

Papan Pemuka → Sambungkan Kiro → AWS Builder ID atau Google/GitHub → ~50 kredit/bulan

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

---

🎨 Kombo

Anda boleh menyusun semula kad kombo secara langsung dalam Papan Pemuka → Kombo dengan menyeret pemegang pada setiap kad. Susunan tersebut disimpan dalam SQLite dan dipulihkan apabila dimuatkan semula.

Contoh 1: Maksimumkan Langganan → Sandaran Murah

Papan Pemuka → Kombo → Cipta Baharu

Nama: premium-coding
Model:
  1. cc/claude-opus-4-7 (Langganan utama)
  2. glm/glm-4.7 (Sandaran murah, $0.6/1M)
  3. minimax/MiniMax-M2.7 (Pilihan terakhir termurah, $0.3/1M)

Gunakan dalam CLI: premium-coding

Contoh 2: Percuma Sahaja (Kos Sifar)

Nama: free-combo
Model:
  1. if/kimi-k2.7-code (disenaraikan dengan akses percuma; had penyedia mungkin dikenakan)
  2. kr/qwen3-coder-next (Pilihan sandaran percuma Kiro)

Kos: kini disenaraikan sebagai $0; terma dan ketersediaan mungkin berubah

---

🔧 Penyepaduan CLI

Cursor IDE

Menggunakan Cursor sebagai klien OmniRoute (halakan sembang Cursor melalui OmniRoute):

Tetapan → Model → Lanjutan:
  URL Asas API OpenAI: http://localhost:20128/v1
  Kunci API OpenAI: [daripada papan pemuka omniroute]
  Model: cc/claude-opus-4-7

Menggunakan OmniRoute sebagai penyedia Cursor (OmniRoute memanggil Cursor huluan): utamakan Papan Pemuka → Penyedia → Cursor → Log masuk dengan Cursor. Dalam Docker, lihat docs/providers/CURSOR-DOCKER.md.

Claude Code

Edit ~/.claude/settings.json:

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

Gunakan titik akhir akar yang serasi dengan Claude di sini. Jangan tambahkan /v1 pada ANTHROPIC_BASE_URL.

Codex CLI

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

OpenClaw

Edit ~/.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" }]
      }
    }
  }
}

Atau gunakan Papan Pemuka: Alat CLI → OpenClaw → Konfigurasi automatik

Cline / Continue / RooCode

Penyedia: Serasi dengan OpenAI
URL Asas: http://localhost:20128/v1
Kunci API: [daripada papan pemuka]
Model: cc/claude-opus-4-7

---

🚀 Pelaksanaan

Pemasangan npm global (Disyorkan)

npm install -g omniroute

# Cipta direktori konfigurasi
mkdir -p ~/.omniroute

# Cipta fail .env (lihat .env.example)
cp .env.example ~/.omniroute/.env

# Mulakan pelayan
omniroute
# Atau dengan port tersuai:
omniroute --port 3000

CLI memuatkan .env secara automatik daripada ~/.omniroute/.env atau ./.env.

Mod dulang

Mulakan OmniRoute dalam dulang sistem:

omniroute serve --tray

Perintah tersebut tamat selepas pelayan dan dulang sedia digunakan.

Pelayan terus berjalan tanpa terminal.

Mod dulang menyokong macOS, Windows dan sesi Linux bergrafik. Mod dulang tidak membuka papan pemuka secara automatik.

Gunakan menu dulang untuk tindakan berikut:

• Buka papan pemuka.
• Buka /dashboard/logs.
• Ubah permulaan automatik.
• Hentikan OmniRoute.

Jangan gabungkan --tray dengan pilihan berikut:

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

Mod ini memerlukan pemilikan proses yang berbeza.

Dayakan permulaan pada log masuk mesin yang seterusnya:

omniroute autostart enable

Permulaan automatik menggunakan mod dulang pada macOS, Windows dan sesi Linux bergrafik. Linux tanpa paparan menggunakan perkhidmatan pengguna systemd yang sedia ada.

Nyahdayakan permulaan semasa log masuk:

omniroute autostart disable

Menyahpasang

Apabila anda tidak lagi memerlukan OmniRoute, kami menyediakan dua skrip pantas untuk penyingkiran yang bersih:

Perintah	Tindakan
npm run uninstall	Mengalih keluar aplikasi sistem tetapi mengekalkan DB dan konfigurasi anda dalam ~/.omniroute.
npm run uninstall:full	Mengalih keluar aplikasi DAN memadamkan semua konfigurasi, kunci dan pangkalan data secara kekal.

Nota: Untuk menjalankan perintah ini, pergi ke folder projek OmniRoute (jika anda mengklonkannya) dan jalankan perintah tersebut. Sebagai alternatif, jika dipasang secara global, anda hanya perlu menjalankan npm uninstall -g omniroute.

Pelaksanaan 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
# Atau: pm2 start npm --name omniroute -- start

Pelaksanaan PM2 (Memori Rendah)

Untuk pelayan dengan RAM terhad, gunakan pilihan had memori:

# Dengan had 512MB (lalai)
pm2 start npm --name omniroute -- start

# Atau dengan had memori tersuai
OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start

# Atau menggunakan ecosystem.config.js
pm2 start ecosystem.config.js

Cipta 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

# Bina imej (lalai = runner-cli dengan codex/claude/droid diprapasang)
docker build -t omniroute:cli .

# Mod mudah alih (disyorkan)
docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli

Untuk mod bersepadu dengan hos yang mempunyai binari CLI, lihat bahagian Docker dalam dokumentasi utama.

Void Linux (xbps-src)

Pengguna Void Linux boleh membungkus dan memasang OmniRoute secara natif menggunakan rangka kerja kompilasi silang xbps-src. Ini mengautomatikkan binaan kendiri Node.js bersama pengikatan natif better-sqlite3 yang diperlukan.

Lihat templat xbps-src

# Fail templat untuk '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() {
	# Tentukan seni bina CPU sasaran untuk 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) Pasang semua kebergantungan – langkau skrip
	NODE_ENV=development npm ci --ignore-scripts

	# 2) Bina berkas kendiri Next.js
	npm run build

	# 3) Salin aset statik ke dalam berkas kendiri
	cp -r .next/static .next/standalone/.next/static
	[ -d public ] && cp -r public .next/standalone/public || true

	# 4) Kompil pengikatan natif 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) Letakkan pengikatan yang dikompil ke dalam berkas kendiri
	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) Alih keluar berkas sharp khusus seni bina
	rm -rf .next/standalone/node_modules/@img

	# 7) Salin kebergantungan masa jalan pino yang diabaikan oleh analisis statik 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

	# Cegah penyingkiran direktori penghala aplikasi Next.js yang kosong oleh cangkuk pascapemasangan
	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
}

Pemboleh Ubah Persekitaran

Pemboleh ubah	Lalai	Penerangan
JWT_SECRET	omniroute-default-secret-change-me	Rahsia penandatanganan JWT (ubah dalam persekitaran produksi)
INITIAL_PASSWORD	CHANGEME	Kata laluan log masuk pertama
DATA_DIR	~/.omniroute	Direktori data (pangkalan data, penggunaan, log)
PORT	lalai rangka kerja	Port perkhidmatan (20128 dalam contoh)
HOSTNAME	lalai rangka kerja	Hos pengikatan (Docker menggunakan 0.0.0.0 secara lalai)
NODE_ENV	lalai masa jalan	Tetapkan kepada production untuk pengerahan
NEXT_PUBLIC_BASE_URL	http://localhost:20128	URL asas awam yang dipaparkan pada papan pemuka dan didedahkan kepada pelayan (menggantikan BASE_URL lama)
NEXT_PUBLIC_CLOUD_URL	https://omniroute.dev	URL asas titik akhir penyegerakan awan (menggantikan CLOUD_URL lama)
API_KEY_SECRET	endpoint-proxy-api-key-secret	Rahsia HMAC untuk kunci API yang dijana
REQUIRE_API_KEY	false	Wajibkan kunci API Bearer pada /v1/*
ALLOW_API_KEY_REVEAL	false	Benarkan pengguna papan pemuka yang disahkan untuk mendedahkan nilai penuh kunci API yang disimpan apabila diminta
PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES	70	Kekerapan penyegaran sisi pelayan untuk data Had Penyedia yang dicache; butang segar semula UI masih mencetuskan penyegerakan manual
DISABLE_SQLITE_AUTO_BACKUP	false	Lumpuhkan petikan SQLite automatik sebelum penulisan/import/pemulihan; sandaran manual masih berfungsi
APP_LOG_TO_FILE	true	Dayakan output log aplikasi dan audit ke cakera
AUTH_COOKIE_SECURE	false	Paksa kuki pengesahan Secure (di belakang proksi songsang HTTPS)
CLOUDFLARED_BIN	tidak ditetapkan	Gunakan binari cloudflared sedia ada dan bukannya muat turun terurus
CLOUDFLARED_PROTOCOL	http2	Pengangkutan untuk Quick Tunnels terurus (http2, quic, atau auto)
OMNIROUTE_MEMORY_MB	512	Had timbunan Node.js dalam MB
PROMPT_CACHE_MAX_SIZE	50	Bilangan maksimum entri cache gesaan
SEMANTIC_CACHE_MAX_SIZE	100	Bilangan maksimum entri cache semantik

Untuk rujukan lengkap pemboleh ubah persekitaran, lihat README.

---

📊 Model yang Tersedia

Lihat semua model yang tersedia

Senarai di bawah dipilih susun daripada open-sse/config/providerRegistry.ts untuk v3.8.0. Katalog awan (Gemini, OpenRouter, dan sebagainya) disegerakkan secara dinamik — untuk katalog langsung yang lengkap, buka Papan Pemuka → Penyedia → [penyedia] → Model yang Tersedia atau panggil GET /api/models/catalog.

Jika senarai terbina dalam bagi sesuatu penyedia sudah tidak sepadan, gunakan Import daripada /models pada halaman tersebut (atau dayakan Segerak Automatik) untuk mendapatkan katalog huluan langsung. Perkara ini telah disahkan dalam v3.8.50 untuk LLM7.io (gemini-3.1-flash-lite) dan UncloseAI (solidrust/Hermes-3-Llama-3.1-8B-AWQ); akses tanpa nama Pollinations masih dihadkan oleh pihak huluan semasa pusingan ujian yang sama.

Claude Code (cc/) — OAuth Pro/Max: 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/) — OAuth Plus/Pro: cx/gpt-5.5 (+ tahap usaha: 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 PERCUMA: gunakan katalog langsung yang dipaparkan di bawah Papan Pemuka → Penyedia → Kiro → Model yang Tersedia. Ketersediaan bergantung pada akaun dan pelan.

Qoder (if/) — OAuth PERCUMA: 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/bulan kadar tetap atau mengikut penggunaan: kimi/kimi-k2.6, kimi/kimi-k2.5

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

Groq (groq/) — Amat pantas: 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 natif: 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/) — Dihoskan di EU: mistral/mistral-large-latest, mistral/mistral-medium-3-5, mistral/mistral-small-latest, mistral/devstral-latest, mistral/codestral-latest

Perplexity (pplx/) — Dipertingkat dengan carian: pplx/sonar-deep-research, pplx/sonar-reasoning-pro, pplx/sonar-pro, pplx/sonar

Together AI (together/) — Sumber terbuka: together/meta-llama/Llama-3.3-70B-Instruct-Turbo-Free (percuma), 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/) — Inferens pantas: 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/) — Skala wafer: cerebras/zai-glm-4.7, cerebras/gpt-oss-120b

Cohere (cohere/) — Berfokuskan 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/) — Perusahaan: 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/): Disegerakkan secara langsung bagi setiap kunci API daripada Google — tiada senarai statik. Sambungkan kunci dalam Papan Pemuka → Penyedia, kemudian gunakan Model yang Tersedia untuk mengimport katalog semasa (contohnya gemini/gemini-3-pro, gemini/gemini-3-flash).

Penyedia serasi lain (terpilih): cohere, databricks, snowflake, together, vertex, alibaba, alibaba-cn, bedrock (melalui aws-bedrock), azure-ai, openrouter (katalog laluan terus), siliconflow, hyperbolic, huggingface, featherless-ai, cloudflare-ai, scaleway, deepinfra, vercel-ai-gateway, bazaarlink, friendliai, nous-research, reka, volcengine, ai21, gigachat. Setiap penyedia menyelenggara senarai modelnya sendiri dalam providerRegistry.ts dan boleh disegerakkan secara automatik apabila penyedia menyediakan titik akhir /models.

Nota tentang ID model: OmniRoute menggunakan ID natif penyedia (claude-opus-4-8, gpt-5.5, glm-5.1, MiniMax-M2.7, kimi-k2.5, grok-4.20-0309-reasoning). Sesetengah ID mengandungi versi bertitik kerana itulah format yang dijangkakan oleh API huluan. Jika sesuatu model tidak disenaraikan di atas, jalankan omniroute models --search <term> atau akses GET /api/models/catalog untuk mengesahkan ketersediaannya.

---

🧩 Ciri Lanjutan

Model Tersuai

Tambahkan sebarang ID model kepada mana-mana penyedia tanpa perlu menunggu kemas kini aplikasi:

# Melalui 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"}'

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

Atau gunakan Papan Pemuka: Penyedia → [Penyedia] → Model Tersuai.

Nota:

• Penyedia yang serasi dengan OpenRouter dan OpenAI/Anthropic hanya diurus daripada Model Tersedia. Penambahan manual, import dan penyegerakan automatik semuanya dimasukkan ke dalam senarai model tersedia yang sama, jadi tiada bahagian Model Tersuai yang berasingan untuk penyedia tersebut.
• Bahagian Model Tersuai ditujukan untuk penyedia yang tidak menyediakan import model tersedia yang terurus.

Merantaikan Rakan OmniRoute

Gerbang OmniRoute lain boleh ditambahkan sebagai penyedia Tersuai yang serasi dengan OpenAI. Gunakan URL asas /v1 rakan tersebut dan kunci API khusus dengan keistimewaan minimum yang dikeluarkan oleh rakan itu.

Untuk rantaian timbal balik atau berbilang lompatan, dayakan pelindung gelung ikut serta pada setiap gerbang:

# 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

Hanya permintaan yang dihantar ke URL rakan yang disenaraibenarkan secara jelas akan menerima pengepala X-OmniRoute-Peer-Trace. Gerbang menolak ID tika yang berulang atau apabila belanjawan lompatan habis dengan HTTP 508 Loop Detected; penyedia huluan biasa tidak menerima metadata rakan.

Perantaian rakan bukan replikasi pangkalan data atau failover hos. Setiap gerbang menyimpan keadaan SQLite, cache, pembilang kadar dan sesi secara berasingan. Gunakan proksi songsang dengan pemeriksaan kesihatan atau failover klien untuk ketersediaan aktif/pasif atau aktif/aktif, dan jangan sekali-kali lekapkan satu pangkalan data SQLite pada berbilang tika OmniRoute yang sedang berjalan.

Laluan Penyedia Khusus

Halakan permintaan secara terus kepada penyedia tertentu dengan pengesahan model:

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

Awalan penyedia ditambahkan secara automatik jika tiada. Model yang tidak sepadan mengembalikan 400.

Konfigurasi Proksi Rangkaian

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

# Proksi bagi setiap penyedia
curl -X PUT http://localhost:20128/api/settings/proxy \
  -d '{"providers": {"openai": {"type":"socks5","host":"proxy.example.com","port":"1080"}}}'

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

Keutamaan: Khusus kunci → Khusus kombo → Khusus penyedia → Global → Persekitaran.

API Katalog Model

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

Mengembalikan model yang dikumpulkan mengikut penyedia bersama jenis (chat, embedding, image).

Penyegerakan Awan

• Segerakkan penyedia, kombo dan tetapan merentas peranti
• Penyegerakan latar belakang automatik dengan tamat masa + gagal pantas
• Utamakan NEXT_PUBLIC_BASE_URL/NEXT_PUBLIC_CLOUD_URL pada bahagian pelayan dalam pengeluaran

Terowong Pantas Cloudflare

• Tersedia dalam Papan Pemuka → Titik Akhir untuk Docker dan penggunaan hos kendiri yang lain
• Mencipta URL https://*.trycloudflare.com sementara yang memajukan trafik ke titik akhir /v1 semasa anda yang serasi dengan OpenAI
• Pengaktifan pertama memasang cloudflared hanya apabila diperlukan; mula semula berikutnya menggunakan semula binari terurus yang sama
• Terowong Pantas tidak dipulihkan secara automatik selepas OmniRoute atau bekas dimulakan semula; dayakan semula daripada papan pemuka apabila diperlukan
• URL terowong bersifat sementara dan berubah setiap kali anda menghentikan/memulakan terowong
• Terowong Pantas terurus menggunakan pengangkutan HTTP/2 secara lalai untuk mengelakkan amaran hingar penimbal UDP QUIC dalam bekas yang terhad
• Tetapkan CLOUDFLARED_PROTOCOL=quic atau auto jika anda mahu mengatasi pilihan pengangkutan terurus
• Tetapkan CLOUDFLARED_BIN jika anda lebih suka menggunakan binari cloudflared yang telah dipasang berbanding muat turun terurus
• Panel Terowong Pantas Cloudflare, Tailscale Funnel dan Terowong ngrok boleh dipaparkan atau disembunyikan dalam Tetapan → Penampilan. Menyembunyikan panel tidak menghentikan terowong yang sedang berjalan.

Kecerdasan Gerbang LLM (Fasa 9)

• Cache Semantik — Menyimpan respons tanpa penstriman dengan temperature=0 secara automatik (langkau dengan X-OmniRoute-No-Cache: true)
• Keidempotenan Permintaan — Menyahduplikasi permintaan dalam tempoh 5s melalui pengepala Idempotency-Key atau X-Request-Id
• Penjejakan Kemajuan — Acara SSE event: progress ikut serta melalui pengepala X-OmniRoute-Progress: true

---

Ruang Uji Penterjemah

Akses melalui Papan Pemuka → Penterjemah. Nyahpepijat dan visualisasikan cara OmniRoute menterjemahkan permintaan API antara penyedia.

Mod	Tujuan
Ruang Uji	Pilih format sumber/sasaran, tampal permintaan dan lihat output yang diterjemahkan dengan serta-merta
Penguji Sembang	Hantar mesej sembang langsung melalui proksi dan periksa kitaran permintaan/respons yang lengkap
Meja Ujian	Jalankan ujian kelompok merentas berbilang gabungan format untuk mengesahkan ketepatan terjemahan
Pemantau Langsung	Perhatikan terjemahan masa nyata semasa permintaan mengalir melalui proksi

Kes penggunaan:

• Nyahpepijat sebab gabungan klien/penyedia tertentu gagal
• Sahkan bahawa tag pemikiran, panggilan alat dan gesaan sistem diterjemahkan dengan betul
• Bandingkan perbezaan format antara format OpenAI, Claude, Gemini dan Responses API

---

Strategi Penghalaan

Konfigurasikan melalui Dashboard → Settings → Routing. Papan pemuka menyediakan enam strategi yang paling kerap digunakan; gabungan dan penghala automatik menyokong set yang lebih luas secara dalaman.

Strategi yang kelihatan pada papan pemuka (penghalaan peringkat akaun):

Strategi	Penerangan
Isi Dahulu	Menggunakan akaun mengikut keutamaan — akaun utama mengendalikan semua permintaan sehingga tidak tersedia
Giliran Bergilir	Mengitar semua akaun dengan had kekal yang boleh dikonfigurasikan (lalai: 3 panggilan bagi setiap akaun)
P2C (Kuasa Dua Pilihan)	Memilih 2 akaun secara rawak dan menghala ke akaun yang lebih sihat — mengimbangi beban dengan mengambil kira tahap kesihatan
Rawak	Memilih akaun secara rawak bagi setiap permintaan menggunakan kocokan Fisher-Yates
Paling Kurang Digunakan	Menghala ke akaun dengan cap masa lastUsedAt paling lama, lalu mengagihkan trafik secara sekata
Dioptimumkan untuk Kos	Menghala ke akaun dengan nilai keutamaan paling rendah, lalu mengoptimumkan penggunaan penyedia berkos paling rendah

Strategi gabungan dan automatik lanjutan (boleh dikonfigurasikan bagi setiap gabungan atau melalui awalan auto/* — lihat AUTO-COMBO.md):

• priority — susunan ketat, tidak pernah menggunakan giliran bergilir
• weighted — pembahagian trafik berkadar berdasarkan pemberat setiap model
• fill-first — menggunakan model pertama sehingga had dicapai
• round-robin / strict-random / random
• p2c (Kuasa Dua Pilihan)
• least-used dan cost-optimized
• auto — berasaskan skor merentas semua calon
• lkgp (Penyedia Terakhir yang Diketahui Baik) — menetapkan penyedia terakhir yang berjaya, kemudian kembali kepada peraturan sandaran
• context-optimized — memilih model dengan tetingkap konteks bebas terbesar
• context-relay — merantaikan model berkonteks panjang untuk giliran susulan

Pengepala Sesi Kekal Luaran

Untuk perkaitan sesi luaran (contohnya, ejen Claude Code/Codex di belakang proksi songsang), hantar:

X-Session-Id: your-session-key

OmniRoute turut menerima x_session_id dan mengembalikan kunci sesi berkuat kuasa dalam X-OmniRoute-Session-Id.

Jika anda menggunakan Nginx dan menghantar pengepala dalam bentuk garis bawah, dayakan:

underscores_in_headers on;

Alias Model Kad Bebas

Cipta corak kad bebas untuk memetakan semula nama model:

Corak: claude-sonnet-*     →  Sasaran: cc/claude-sonnet-4-6
Corak: gpt-*               →  Sasaran: gh/gpt-5.3-codex

Kad bebas menyokong * (sebarang aksara) dan ? (satu aksara).

Rantaian Sandaran

Takrifkan rantaian sandaran global yang digunakan merentas semua permintaan:

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

---

Ketahanan & Pemutus Litar

Konfigurasikan melalui Dashboard → Settings → Resilience.

OmniRoute melaksanakan ketahanan peringkat penyedia dengan lima komponen:

1. Baris Gilir & Penjarakan Permintaan — Pembentukan permintaan peringkat sistem:

   • Permintaan Seminit (RPM) — Permintaan maksimum seminit bagi setiap akaun
   • Masa Minimum Antara Permintaan — Jeda minimum dalam milisaat antara permintaan
   • Permintaan Serentak Maksimum — Permintaan serentak maksimum bagi setiap akaun

2. Tempoh Bertenang Sambungan — Konfigurasi mengikut jenis pengesahan untuk satu sambungan selepas kegagalan yang boleh dicuba semula:

   • Tempoh Bertenang Asas — Tetingkap tempoh bertenang lalai bagi kegagalan huluan yang boleh dicuba semula
   • Gunakan Petunjuk Percubaan Semula Huluan — Mematuhi Retry-After berautoriti atau petunjuk tetapan semula apabila diberikan
   • Langkah Undur Maksimum — Tahap undur eksponen maksimum bagi kegagalan berulang

3. Pemutus Litar Penyedia — Menjejaki kegagalan penyedia hujung ke hujung, menandai penyedia sebagai terjejas pada ambang amaran yang dikonfigurasikan dan membuka pemutus apabila ambang kegagalan yang dikonfigurasikan dicapai:

   • Ambang Kemerosotan — Bilangan kegagalan penyedia berturut-turut sebelum memasuki DEGRADED
   • Ambang Kegagalan — Bilangan kegagalan penyedia berturut-turut sebelum memasuki OPEN
   • Tamat Masa Tetapan Semula — Tetingkap masa sebelum penyedia diuji semula
   • CLOSED (Sihat) — Permintaan mengalir seperti biasa
   • DEGRADED — Permintaan masih mengalir sementara peningkatan kegagalan dijejaki
   • OPEN — Penyedia disekat buat sementara waktu selepas kegagalan berulang
   • HALF_OPEN — Menguji sama ada penyedia telah pulih

   Had kadar 429 bagi sambungan kekal dalam Tempoh Bertenang Sambungan dan tidak dikira terhadap pemutus penyedia.

   Keadaan masa jalan pemutus penyedia hanya dipaparkan pada Dashboard → Health.

4. Tunggu Tempoh Bertenang — Jika setiap sambungan calon sedang berada dalam tempoh bertenang, OmniRoute boleh menunggu tempoh bertenang yang paling awal tamat dan mencuba semula permintaan klien yang sama secara automatik.

5. Pengesanan Automatik Had Kadar — Apabila penyedia huluan mengembalikan tetingkap menunggu yang jelas, petunjuk tersebut mengatasi tempoh bertenang sambungan setempat apabila tetapan ini didayakan.

Petua Profesional: Gunakan halaman Health untuk memeriksa dan menetapkan semula pemutus penyedia aktif selepas gangguan. Halaman Resilience hanya mengubah konfigurasi.

---

Eksport / Import Pangkalan Data

Urus sandaran pangkalan data dalam Dashboard → Settings → System & Storage.

Tindakan	Penerangan
Eksport Pangkalan Data	Memuat turun pangkalan data SQLite semasa sebagai fail .sqlite
Eksport Semua (.tar.gz)	Memuat turun arkib sandaran penuh yang merangkumi: pangkalan data, tetapan, kombo, sambungan penyedia (tanpa kelayakan), metadata kunci API
Import Pangkalan Data	Memuat naik fail .sqlite untuk menggantikan pangkalan data semasa. Sandaran praimport dicipta secara automatik melainkan DISABLE_SQLITE_AUTO_BACKUP=true

# API: Eksport pangkalan data
curl -o backup.sqlite http://localhost:20128/api/db-backups/export

# API: Eksport semua (arkib penuh)
curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll

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

Pengesahan Import: Fail yang diimport disahkan untuk integriti (semakan pragma SQLite), jadual yang diperlukan (provider_connections, provider_nodes, combos, api_keys), dan saiz (maksimum 100MB).

Kes Penggunaan:

• Memindahkan OmniRoute antara mesin
• Mencipta sandaran luaran untuk pemulihan bencana
• Berkongsi konfigurasi antara ahli pasukan (eksport semua → kongsi arkib)

---

Papan Pemuka Tetapan

Halaman tetapan disusun kepada 7 tab untuk memudahkan navigasi:

Tab	Kandungan
Umum	Alat storan sistem, tingkah laku lalai, keterlihatan terowong endpoint
Penampilan	Kawalan tema (cerah/gelap/sistem), keterlihatan bar sisi, togol panel untuk kad terowong Cloudflare/Tailscale/ngrok
AI	Belanjawan pemikiran (laluan terus / buang automatik / tersuai / adaptif — lihat THINKING_BUDGET.md), gesaan sistem global, statistik cache gesaan
Keselamatan	Tetapan log masuk/kata laluan, Kawalan Akses IP, pengesahan API untuk /models, Penyekatan Penyedia, perlindungan suntikan gesaan
Penghalaan	Strategi penghalaan global (Isi Dahulu / Giliran Bergilir / P2C / Rawak / Paling Kurang Digunakan / Dioptimumkan Kos), alias model kad bebas, rantaian sandaran, lalai kombo
Ketahanan	Baris gilir permintaan, tempoh bertenang sambungan, konfigurasi pemutus penyedia, dan tingkah laku tunggu-tempoh-bertenang
Lanjutan	Konfigurasi proksi global (HTTP/SOCKS5), penggantian proksi bagi setiap penyedia

Bahagian Umum tidak lagi menduplikasi nota pengelogan dan cache baca sahaja. Tetapan pengekalan dan pengoptimuman pangkalan data dikekalkan melalui /api/settings/database; pengosongan cache secara manual menggunakan DELETE /api/cache. Had baris log permintaan dan proksi dikawal oleh CALL_LOGS_TABLE_MAX_ROWS dan PROXY_LOGS_TABLE_MAX_ROWS.

---

Pengurusan Kos & Belanjawan

Akses melalui Papan Pemuka → Kos.

Tab	Tujuan
Belanjawan	Tetapkan had perbelanjaan bagi setiap kunci API dengan belanjawan harian/mingguan/bulanan dan penjejakan masa nyata
Harga	Lihat dan edit entri harga model — kos bagi setiap 1K token input/output untuk setiap penyedia

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

# API: Dapatkan status belanjawan semasa
curl http://localhost:20128/api/usage/budget

Penjejakan Kos: Setiap permintaan merekodkan penggunaan token dan mengira kos menggunakan jadual harga. Lihat pecahan dalam Papan Pemuka → Penggunaan mengikut penyedia, model, dan kunci API.

---

Transkripsi Audio

OmniRoute menyokong transkripsi audio melalui endpoint yang serasi dengan OpenAI:

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

# Contoh dengan 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 ialah laluan Deepgram natif dan memerlukan kunci API Deepgram. Jika hanya OpenRouter dikonfigurasikan, gunakan openrouter/deepgram/nova-3.

Penyedia Pertuturan-ke-Teks (transkripsi):

• openai/ (serasi dengan whisper)
• groq/ (Groq Whisper Turbo)
• deepgram/ (keluarga Nova)
• assemblyai/
• nvidia/ (Parakeet, Canary)
• huggingface/ (varian whisper)
• qwen/

Penyedia Teks-ke-Pertuturan (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/

Format audio yang disokong untuk transkripsi: mp3, wav, m4a, flac, ogg, webm. Format output TTS bergantung pada penyedia (mp3, wav, opus, pcm, mulaw).

---

Strategi Pengimbangan Kombo

Konfigurasikan pengimbangan bagi setiap kombo dalam Papan Pemuka → Kombo → Cipta/Edit → Strategi.

Strategi	Penerangan
Round-Robin	Menggilirkan model secara berurutan
Priority	Sentiasa mencuba model pertama; beralih hanya apabila berlaku ralat
Random	Memilih model secara rawak daripada kombo untuk setiap permintaan
Weighted	Menghalakan secara berkadar berdasarkan wajaran yang ditetapkan bagi setiap model
Least-Used	Menghalakan kepada model dengan bilangan permintaan terkini paling sedikit (menggunakan metrik kombo)
Cost-Optimized	Menghalakan kepada model tersedia yang paling murah (menggunakan jadual harga)

Tetapan lalai kombo global boleh ditetapkan dalam Dashboard → Settings → Routing → Combo Defaults. Tamat masa sasaran kombo mewarisi tamat masa permintaan semasa secara lalai. Gunakan Target timeout (seconds) pada tetapan lalai kombo atau kombo individu hanya apabila had per sasaran yang lebih pendek perlu mencetuskan peralihan dengan lebih pantas.

Pengoptimuman kombo kependaman sifar perlu didayakan secara pilihan. Biarkan Zero-latency optimizations dinyahdayakan untuk menghalang ciri kependaman ini daripada bersaing dengan sasaran peralihan, melangkau sasaran berdasarkan sejarah TTFT, atau memampatkan permintaan peralihan; mendayakannya membolehkan pelindungan nilai yang dikonfigurasikan, pelangkauan TTFT ramalan dan pemampatan peralihan proaktif untuk menukar ketepatan penghalaan/permintaan demi kependaman hujung yang lebih rendah.

Nyahdayakan Reasoning token buffer apabila penyedia huluan memerlukan had max_tokens / maxOutputTokens yang ketat. Apabila didayakan, penghalaan kombo hanya menambahkan ruang tambahan model penaakulan untuk model dengan had output yang diketahui dan membiarkan had token klien tidak berubah apabila nilai penimbal selamat akan melebihi had tersebut. Jika had klien sudah melebihi had yang diketahui, OmniRoute mengehadkannya kepada had tersebut sebelum menghantar permintaan huluan.

---

Papan Pemuka Kesihatan

Akses melalui Dashboard → Health. Gambaran keseluruhan kesihatan sistem masa nyata dengan 6 kad:

Kad	Perkara yang Ditunjukkan
System Status	Masa operasi, versi, penggunaan memori, direktori data
Provider Health	Keadaan masa jalan pemutus litar penyedia global
Rate Limits	Tempoh bertenang sambungan aktif bagi setiap akaun berserta baki masa
Active Lockouts	Sekatan aktif mengikut model dan pengecualian sementara
Signature Cache	Statistik cache penyahduplikasian (kunci aktif, kadar padanan)
Latency Telemetry	Pengagregatan kependaman p50/p95/p99 bagi setiap penyedia

Petua Profesional: Halaman Kesihatan dimuat semula secara automatik setiap 10 saat. Gunakan kad pemutus litar untuk mengenal pasti penyedia yang sedang mengalami masalah.

---

🤖 Penghalaan Automatik (Konfigurasi sifar)

OmniRoute disertakan dengan penghala automatik berasaskan skor yang memilih model terbaik untuk setiap permintaan merentas semua penyedia yang disambungkan — tiada gabungan yang perlu diselenggarakan. Hanya hantar permintaan menggunakan salah satu awalan auto/* dan OmniRoute akan membentuk gabungan maya secara dinamik dengan memberikan skor kepada calon berdasarkan kependaman, kos, kadar kejayaan, kesesuaian konteks, kesesuaian model untuk tugasan, kegagalan terkini, kuota dan keadaan pemutus litar.

Awalan	Dioptimumkan untuk
auto	Lalai seimbang (kependaman × kos × kadar kejayaan)
auto/coding	Tugas pengekodan: mengutamakan Claude, GPT-5, GLM, Kimi, Qwen Coder, pengekod DeepSeek
auto/cheap	$/token terendah, menerima kependaman lebih tinggi
auto/fast	Kependaman terendah, mengabaikan kos
auto/offline	Penyedia setempat sahaja (Ollama, vLLM, llama.cpp) — berguna untuk persediaan terasing
auto/smart	Mengutamakan kualiti penaakulan (Opus, GPT-5 xhigh, R1, penaakulan GLM 5.1)
auto/lkgp	"Penyedia Baik Terakhir Diketahui" — dikunci kepada penyedia terakhir yang berjaya, kemudian kembali kepada peraturan

Contoh:

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": "Faktorkan semula fungsi Python ini" }],
    "stream": true
  }'

Penghala automatik diterangkan sepenuhnya dalam AUTO-COMBO.md — termasuk cara melaraskan pemberat skor, menyenaraihitamkan penyedia dan memeriksa keputusan penghalaan dalam Papan Pemuka → Gabungan Automatik.

---

🔌 Penyepaduan MCP & A2A

OmniRoute ialah pelayan MCP (Protokol Konteks Model) dan juga pelayan A2A (JSON-RPC 2.0 Ejen-ke-Ejen). Mana-mana IDE atau hos ejen yang serasi dengan MCP boleh memanggil alat OmniRoute secara terus — tiada pembalut tambahan diperlukan.

Pengangkutan MCP

• SSE: http://localhost:20128/api/mcp/sse
• HTTP Boleh Distrim: http://localhost:20128/api/mcp/stream
• stdio: omniroute --mcp (untuk pemalam IDE yang mengutamakan stdio)

Sambungkan Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) atau fail yang setara pada Windows/Linux:

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

Sambungkan Cursor / Continue / VS Code MCP

Gunakan URL SSE http://localhost:20128/api/mcp/sse dan kunci API Bearer yang dijana dalam Papan Pemuka → Kunci API.

Skop

MCP kini mentakrifkan 32 skop bernama. Setiap kunci Bearer boleh dihadkan kepada skop tertentu — lihat MCP-SERVER.md untuk inventori skop dan alat yang berwibawa serta A2A-SERVER.md untuk skema JSON-RPC.

---

🧠 Sistem Kemahiran

OmniRoute menyediakan rangka kerja kemahiran yang boleh diperluas (src/lib/skills/) supaya ejen dan titik akhir A2A boleh menjalankan rutin khusus domain (contohnya code-review, summarize, extract-facts, web-research).

• UI Marketplace — Semak imbas dan pasang kemahiran melalui Papan Pemuka → Kemahiran
• Skop setiap kunci — Hadkan kemahiran yang boleh digunakan oleh setiap kunci API
• Kemahiran tersuai — Letakkan fail TypeScript dalam src/lib/a2a/skills/, daftarkannya, dan kemahiran itu boleh digunakan serta-merta melalui A2A

Rujukan penuh: SKILLS.md.

---

💾 Sistem Memori

OmniRoute mengekalkan memori perbualan jangka panjang dengan pengambilan hibrid:

• SQLite FTS5 untuk carian kata kunci merentas pertukaran perbualan terdahulu
• Storan vektor Qdrant (pilihan) untuk ingatan semantik
• Pengekstrakan fakta automatik — entiti, keutamaan dan keputusan diringkaskan selepas setiap sesi dan disimpan dalam jadual memory_facts
• Memori diskopkan mengikut kunci API dan sesi

Urus memori dalam Papan Pemuka → Memori (cari, edit, eksport, hapuskan). Antara muka HTTP (/api/memory/*) membolehkan ejen menghantar dan mendapatkan fakta secara pemprograman — lihat MEMORY.md.

---

🔔 Webhook

Langgan peristiwa OmniRoute untuk pemantauan dan automasi masa nyata.

• Cipta webhook dalam Papan Pemuka → Webhook dengan URL sasaran dan rahsia tandatangan HMAC
• Peristiwa yang tersedia: request.completed, request.failed, provider.unavailable, budget.exceeded, combo.switched, circuit_breaker.opened, circuit_breaker.closed
• Setiap muatan mengandungi X-OmniRoute-Signature (HMAC-SHA256) untuk pengesahan
• Percubaan semula: 3 percubaan dengan sela masa eksponen, kemudian dihantar ke baris gilir surat mati

Skema penuh dalam WEBHOOKS.md.

---

☁️ Ejen Awan

OmniRoute bersepadu dengan ejen pengekodan awan (OpenAI Codex Cloud, Devin, Jules, Antigravity) supaya anda boleh menghantar tugas yang berjalan lama daripada papan pemuka yang sama yang mengendalikan penghalaan setempat anda.

• Cipta tugas dalam Papan Pemuka → Ejen Awan atau melalui POST /api/v1/agents/tasks
• Jejaki status, log dan artifak bagi setiap tugas
• Gunakan kunci API anda sendiri bagi setiap penyedia — bukti kelayakan tidak pernah meninggalkan tika OmniRoute

Rujukan penuh: CLOUD_AGENT.md.

---

🛠️ Pengurusan Secara Pemprograman

Anda boleh mengurus setiap sumber OmniRoute (penyedia, kombo, kunci, tetapan) melalui HTTP menggunakan kunci Bearer dengan skop manage.

Jana kunci dalam Papan Pemuka → Kunci API → Kunci Baharu → Skop: manage, kemudian:

# Senaraikan penyedia
curl http://localhost:20128/api/providers \
  -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY"

# Tambahkan sambungan penyedia
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" }'

# Cipta kombo
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" }] }'

# Senaraikan/cipta kunci 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"] }'

Lihat API_REFERENCE.md untuk katalog titik akhir serta skema permintaan/respons yang lengkap.

---

💻 CLI Dalaman

OmniRoute menyediakan CLI dalaman (omniroute …) untuk persediaan, diagnostik dan kawalan masa jalan. Ini berasingan daripada halaman "Alat CLI" dalam papan pemuka, yang mengkonfigurasi CLI pihak ketiga (Claude Code, Cursor, Codex, Cline, …) supaya alat tersebut boleh berkomunikasi dengan OmniRoute.

omniroute setup                    # Bestari interaktif (kata laluan, penyedia, gabungan)
omniroute setup --non-interactive  # Sesuai untuk CI
omniroute doctor                   # Diagnostik kesihatan (direktori data, DB, penyedia, port)
omniroute providers available      # Senaraikan penyedia yang disokong
omniroute providers list           # Senaraikan sambungan yang dikonfigurasi
omniroute providers test <id>      # Uji sambungan penyedia secara langsung
omniroute combos list              # Senaraikan gabungan
omniroute combos switch <name>     # Tetapkan gabungan lalai
omniroute models                   # Senaraikan model yang tersedia (--json, --search)
omniroute keys add | list | remove # Urus kekunci API daripada terminal
omniroute backup                   # Ambil petikan konfigurasi + DB
omniroute restore [<timestamp>]    # Pulihkan daripada petikan
omniroute health                   # Kesihatan terperinci (pemutus, cache, memori)
omniroute quota                    # Penggunaan kuota penyedia
omniroute mcp status               # Status pelayan MCP
omniroute a2a status               # Status pelayan A2A
omniroute tunnel list|create|stop  # Terowong Cloudflare/Tailscale/ngrok
omniroute reset-password           # Tetapkan semula kata laluan pentadbir
omniroute --mcp                    # Mulakan pelayan MCP melalui stdio
omniroute --port 3000              # Mulakan pelayan pada port tersuai

Petua: gandingkan omniroute doctor --json dengan alat pemantauan anda untuk memberikan amaran tentang sambungan penyedia yang tidak sihat.

---

🖥️ Aplikasi Desktop (Electron)

OmniRoute tersedia sebagai aplikasi desktop natif untuk Windows, macOS dan Linux.

Pemasangan

# Daripada direktori electron:
cd electron
npm install

# Mod pembangunan (sambung kepada pelayan pembangunan Next.js yang sedang berjalan):
npm run dev

# Mod pengeluaran (menggunakan binaan kendiri):
npm start

Membina Pemasang

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

Output → electron/dist-electron/

Ciri Utama

Ciri	Penerangan
Kesediaan Pelayan	Meninjau pelayan sebelum memaparkan tetingkap (tiada skrin kosong)
Talam Sistem	Minimumkan ke talam, tukar port, keluar melalui menu talam
Pengurusan Port	Tukar port pelayan melalui talam (pelayan dimulakan semula secara automatik)
Dasar Keselamatan Kandungan	CSP ketat melalui pengepala sesi
Kejadian Tunggal	Hanya satu kejadian aplikasi boleh berjalan pada satu masa
Mod Luar Talian	Pelayan Next.js yang digabungkan berfungsi tanpa internet

Pemboleh Ubah Persekitaran

Pemboleh Ubah	Lalai	Penerangan
OMNIROUTE_PORT	20128	Port pelayan
OMNIROUTE_MEMORY_MB	512	Had timbunan Node.js (64–16384 MB)

📖 Dokumentasi penuh: electron/README.md