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

USER_GUIDE (Malti)

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

---

---

title: "Gwida għall-Utent" version: 3.8.40 lastUpdated: 2026-06-28

Gwida għall-Utent

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

Gwida kompleta għall-konfigurazzjoni tal-providers, il-ħolqien ta' combos, l-integrazzjoni ta' għodod CLI, u t-tqegħid ta' OmniRoute.

---

Werrej

• Prezzijiet f'Ħarsa Ġenerali
• Każijiet ta' Użu
• Setup tal-Provider
• Integrazzjoni tal-CLI
• Tqegħid (Deployment)
• Mudelli Disponibbli
• Karatteristiċi Avvanzati
• Routing Awtomatiku (Zero-config)
• Integrazzjoni MCP & A2A
• Sistema ta' Ħiliet (Skills)
• Sistema ta' Memorja
• Webhooks
• Aġenti Cloud
• Ġestjoni Programmattika
• CLI Intern
• Applikazzjoni Desktop (Electron)

---

💰 Ħarsa lejn il-Prezzijiet

Livell	Provditur	Piża	Tneħħija tal-Quota	L-Aħjar Għal
💳 SOTTISKRIZZJONI	Claude Code (Pro)	$20/xahar	5h + ġimgħija	Diġà sottokrit
	Codex (Plus/Pro)	$20-200/xahar	5h + ġimgħija	Utenti OpenAI
	GitHub Copilot	$10-19/xahar	Xahrewwa	Utenti GitHub
🔑 API KEY	DeepSeek	Ħlas skont l-użu	L-ebda	Rati irħas
	Groq	Ħlas skont l-użu	L-ebda	Inferenza ultra mgħaġġla
	xAI (Grok)	Ħlas skont l-użu	L-ebda	Rati Grok 4
	Mistral	Ħlas skont l-użu	L-ebda	Mudelli ospitati fl-UE
	Perplexity	Ħlas skont l-użu	L-ebda	Riki mbieraq bil-fittxien
	Together AI	Ħlas skont l-użu	L-ebda	Mudelli b'ħarsien miftuħ
	Fireworks AI	Ħlas skont l-użu	L-ebda	Stampi FLUX malajr
	Cerebras	Ħlas skont l-użu	L-ebda	Veloċità ta' skala wafer
	Cohere	Ħlas skont l-użu	L-ebda	Command R+ RAG
	NVIDIA NIM	Ħlas skont l-użu	L-ebda	Mudelli għall-intrapriża
	Baidu Qianfan	Ħlas skont l-użu	L-ebda	Mudelli ERNIE
💰 RĦAS	GLM-4.7	$0.6/1M	Ta' kuljum fis-10AM	Riserva baġitarja
	MiniMax M2.1	$0.2/1M	5 sigħat lissirqi	L-għażla irħas
	Kimi K2	$9/xahar fiss	10M tokens/xahar	Piża previżibbli
🆓 B'XEJN	Qoder	$0	Limiti tal-provditur japplikaw	Verifika l-katalogu attwali
	Kiro	$0	~50 krediti/xahar	B'xejn ta' Claude

---

🎨 Xi Ġuriex

Ġurija 1: "Għandi sottoskrizzjoni ta' Claude Pro"

Problema: Il-quota ġġorrula mhux użata, limiti ta' rata waqt programmazzjoni intensiva

Kombinazzjoni: "maximize-claude"
  1. cc/claude-opus-4-7        (uża s-sottoskrizzjoni b'mod sħiħ)
  2. glm/glm-4.7               (riserva rħisa meta l-quota tispiċċa)
  3. if/qwen3.8-max-preview       (riserva bla spiża għall-emerġenza)

Piża ta' kull xahar: $20 (sottoskrizzjoni) + ~$5 (riserva) = $25 totali
vs. $20 + limiti jseħħu = frustrazzjoni

Ġurija 2: "Irrid piża żero"

Problema: Ma nistax naffordja s-sottoskrizzjonijiet, jeħtiġli AI affidabbli għall-programmazzjoni

Kombinazzjoni: "zero-cost"
  1. if/kimi-k2.7-code          (aċċess imniżżel b'xejn; limiti ta' rata jistgħu japplikaw)
  2. kr/qwen3-coder-next        (riserva b'xejn ta' Kiro)

Piża ta' kull xahar: $0
Kwalità: verifika l-mudell, il-limiti, il-privatezza, u l-SLA għal xogħolek

Ġurija 3: "Jeħtiġli programmazzjoni 24/7, bla interruzzjonijiet"

Problema: Skadenzi, ma nistax naffordja waqfa

Kombinazzjoni: "always-on"
  1. cc/claude-opus-4-7        (l-aqwa kwalità)
  2. cx/gpt-5.5                (sottoskrizzjoni oħra)
  3. glm/glm-4.7               (rħisa, ġġedded ta' kuljum)
  4. minimax/MiniMax-M2.1      (irħas, tneħħija ta' 5h)
  5. if/deepseek-v4-flash       (aċċess imniżżel b'xejn; limiti ta' rata jistgħu japplikaw)

Riżultat: 5 saffi ta' riserva jwessgħu r-resiljenza; disponibbiltà ta' l-avvenniet mhijiwa garantita
Piża ta' kull xahar: $20-200 (sottoskrizzjonijiet) + $10-20 (riserva)

Ġurija 4: "Irrid AI B'XEJN fi OpenClaw"

Problema: Jeħtiġli assistent AI f'applikazzjonijiet tal-messaġġi, totalment b'xejn

Kombinazzjoni: "openclaw-free"
  1. if/qwen3.8-max-preview     (aċċess imniżżel b'xejn; limiti ta' rata jistgħu japplikaw)
  2. if/deepseek-v4-flash       (aċċess imniżżel b'xejn; limiti ta' rata jistgħu japplikaw)
  3. if/kimi-k2.7-code          (aċċess imniżżel b'xejn; limiti ta' rata jistgħu japplikaw)

Piża ta' kull xahar: $0
Aċċess permezz ta': WhatsApp, Telegram, Slack, Discord, iMessage, Signal...

---

📖 Tħejjija tal-Fornitur

🔐 Fornituri ta' Abbonament

Claude Code (Pro/Max)

Dashboard → Providers → Connect Claude Code
→ OAuth login → Auto token refresh
→ 5-hour + weekly quota tracking

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

Pro Tip: Uża l-Opus għal komplessi, Sonnet għas-sekondarja. OmniRoute jissorvelja l-kwota għal kull mudell!

It-toroq li huma kompatibbli ma' Claude u Claude Code iżommu l-isforz ta' ħsieb "max" għall-mudelli Opus u Sonnet. Il-mudelli Haiku ma jirċevux il-livell "max" ta' sforz, għalhekk OmniRoute jagħmel downgrade ta' dik it-talba għal baġit ta' ħsieb qawwi qabel ma jibagħthha 'il quddiem.

OpenAI Codex (Plus/Pro)

Dashboard → Providers → Connect Codex
→ OAuth login (port 1455)
→ 5-hour + weekly reset

Models:
  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 via GitHub
→ Monthly reset (1st of month)

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

💰 Fornituri irħas

GLM-4.7 (Reset ta' kuljum, $0.6/1M)

1. Irreġistra: Zhipu AI
2. Ikseb API key minn Coding Plan
3. Dashboard → Add API Key: Provider: glm, API Key: your-key

Uża: glm/glm-4.7 — Pro Tip: Coding Plan joffri 3× kwota b'1/7 l-ispiża! Reset kuljum fil-10:00 AM.

MiniMax M2.1 (Reset ta' 5h, $0.20/1M)

1. Irreġistra: MiniMax
2. Ikseb API key → Dashboard → Add API Key

Uża: minimax/MiniMax-M2.1 — Pro Tip: L-iktar għażla irħisa għal kuntest twil (1M tokens)!

Kimi K2 ($9/xahar flat)

1. Abbona: Moonshot AI
2. Ikseb API key → Dashboard → Add API Key

Uża: kimi/kimi-k2.5 — Pro Tip: $9 fissi fix-xahar għal 10M tokens = spża effettiva ta' $0.90/1M!

Baidu Qianfan / ERNIE

1. Irreġistra: Baidu AI Cloud Qianfan
2. Oħloq API key ta' Qianfan → Dashboard → Add API Key: Provider: qianfan

Uża: qianfan/ernie-5.1, qianfan/ernie-x1.1, jew mudell ieħor kompatibbli ma' OpenAI ta' Qianfan.

🆓 Fornituri B'XEJN

Il-fornituri b'xejn mingħajr awtentikazzjoni għandhom switch ħdejn No authentication required fil-paġna tal-fornitur tagħhom. Meta tneħħih, tkun qed tiddiżattiva dak il-fornitur, tneħħih mill-views ta' Providers configured/compact, u tneħħi l-mudelli tiegħu minn /v1/models.

Qoder (9 Mudelli B'XEJN)

Dashboard → Connect Qoder → OAuth login → Access is subject to current provider limits

Models: 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 B'XEJN)

Dashboard → Connect Kiro → AWS Builder ID or Google/GitHub → ~50 credits/month

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

---

🎨 Kombinazzjonijiet

Tista' terġa' tordna l-karti tal-kombinazzjonijiet direttament f'Dashboard → Combos billi tiġbed il-manku ta' kull karta. L-ordni tiġi mħżuna f'SQLite u terġa' titwaqqaf meta terġa' tibda.

Eżempju 1: Massimizza l-Abbonament → Riserva Irħasa

Dashboard → Combos → Create New

Name: premium-coding
Models:
  1. cc/claude-opus-4-7 (Subscription primary)
  2. glm/glm-4.7 (Cheap backup, $0.6/1M)
  3. minimax/MiniMax-M2.7 (Cheapest fallback, $0.3/1M)

Use in CLI: premium-coding

Eżempju 2: B'XEJN biss (Spiża Ċikka)

Name: free-combo
Models:
  1. if/kimi-k2.7-code (listed free access; provider limits may apply)
  2. kr/qwen3-coder-next (Kiro free fallback)

Cost: currently listed as $0; terms and availability may change

---

🔦 Integrazjoni CLI

Cursor IDE

Użu ta' Cursor bħala klijent OmniRoute (instradi chat ta' Cursor permezz ta' OmniRoute):

Settings → Models → Advanced:
  OpenAI API Base URL: http://localhost:20128/v1
  OpenAI API Key: [mill-dashboard tal-omniroute]
  Model: cc/claude-opus-4-7

Użu ta' OmniRoute bħala fornitur ta' Cursor (OmniRoute jistenna lill-Cursor upstream): prefer Dashboard → Providers → Cursor → Login with Cursor. F'Docker, ara 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"
  }
}

Użu l-endpoint root kompatibbli ma' Claude hawn. Tagħlaqx /v1 ma' 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" }]
      }
    }
  }
}

Jew uża l-Dashboard: CLI Tools → OpenClaw → Auto-config

Cline / Continue / RooCode

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

---

🚀 Twaqqif

npm globali install (Rikomandat)

npm install -g omniroute

# Oħloq direttorju tal-konfigurazzjoni
mkdir -p ~/.omniroute

# Oħloq fajl .env (ara .env.example)
cp .env.example ~/.omniroute/.env

# Beda s-server
omniroute
# Jew b'port abbinali:
omniroute --port 3000

L-CLI awtomatikament jgħabbi .env minn ~/.omniroute/.env jew ./.env.

Triq il-tray

Bedal OmniRoute fil-tray tas-sistema:

omniroute serve --tray

Il-kmand jirritorna wara li s-server u t-tray ikunu lesti.

Is-server jibqa' mingħajr il-terminal.

It-tray mode jappoġġa macOS, Windows, u sessions Linux b'interfaċċi grafika. It-tray mode ma jiftaħx l-dashboard awtomatikament.

Uża l-menu tal-tray għal dawn l-azzjonijiet:

• Ftaħ l-dashboard.
• Ftaħ /dashboard/logs.
• Biddel l-awto-bidu.
• Waqqaf OmniRoute.

Tagħmilx --tray ma' dawn l-għażliet:

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

Dawn il-mudelli jeħtieġu proprjetà differenti tal-proċess.

Ekwiżizzjoni ta' bidu fil-login li jmiss tal-magna:

omniroute autostart enable

L-awto-bidu juża t-tray mode fuq macOS, Windows, u sessions Linux b'interfaċċi grafika. Linux Headless juża s-servizz attwali tal-systemd user.

Tixħirx l-awto-bidu fil-login:

omniroute autostart disable

Tneħħija

Meta m'għadekx teħtieġ OmniRoute, noffrulek żewġ scripts ħfief għat-tneħħija nadifa:

Kmand	Azzjoni
npm run uninstall	Jneħħi l-app tal-sistema iżda jżomm il-DB u l-konfigurazzjonijiet tiegħek f'~/.omniroute.
npm run uninstall:full	Jneħħi l-app U jħassar permanentement il-konfigurazzjonijiet, ċavetti, u databases kollha.

Nota: Biex tħaddem dawn il-kmandi, mur fil-folder tal-proġett OmniRoute (jekk klonjajtu) u ħaddemhom. Barra minn hekk, jekk installat globalment, tista' sempliċement tħaddem npm uninstall -g omniroute.

Twaqqif 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
# Jew: pm2 start npm --name omniroute -- start

Twaqqif PM2 (RAM Baxxa)

Għal servers b'RAM limitata, uża l-għażla tal-limitu tal-memorja:

# B'limitu ta' 512MB (default)
pm2 start npm --name omniroute -- start

# Jew b'limitu tal-memorja abbinali
OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start

# Jew uża ecosystem.config.js
pm2 start ecosystem.config.js

Oħloq 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

# Bini ta' stampa (default = runner-cli b'codex/claude/droid installat minn qabel)
docker build -t omniroute:cli .

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

Għall-mod host-integrated b'binaries CLI, ara t-taqsima Docker fil-dokumentazzjoni ewlenija.

Void Linux (xbps-src)

L-utenti tal-Void Linux jistgħu jippakkjaw u jinstallaw OmniRoute b'mod nattiv jużand il-framework tal-kross-kompilazzjoni xbps-src. Dan jawtomatizza l-bini standalone tal-Node/js flimkien mal-better-sqlite3 native bindings meħtieġa.

Ara l-mudell xbps-src

# Fajl tal-mudell għal '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() {
	# Iddetermina l-arqa CPU tal-mira għal 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) Installa d-dipendenzi kollha – omitti l-scripts
	NODE_ENV=development npm ci --ignore-scripts

	# 2) Bni l-bundle standalone Next.js
	npm run build

	# 3) Kopja l-assetti statiċi fil-standalone
	cp -r .next/static .next/standalone/.next/static
	[ -d public ] && cp -r public .next/standalone/public || true

	# 4) Ġabar il-binding nativ 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) Poġġi l-binding imġabar fil-bundle standalone
	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) Neħħi l-bundles ta' @img speċifiċi għall-arqa
	rm -rf .next/standalone/node_modules/@img

	# 7) Kopja d-dipendenzi runtime tal-pino li ġew omessi mill-analiżi statika 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

	# Prevjeni t-tneħħija ta' direttorji vojta tal-app router Next.js mill-hook post-install
	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
}

Varjabbli tal-Ambjent

Varjabbli	Default	Deskrizzjoni
JWT_SECRET	omniroute-default-secret-change-me	Sigriet għat-tiffirma tal-JWT (biddel fil-produzzjoni)
INITIAL_PASSWORD	CHANGEME	Password tal-ewwel login
DATA_DIR	~/.omniroute	Direttorju tad-dejta (db, użu, logħob)
PORT	default tal-frawwerk	Port tas-servizz (20128 fil-eżempji)
HOSTNAME	default tal-frawwerk	Jorbot il-host (Docker default għal 0.0.0.0)
NODE_ENV	default runtime	Waħħal production għat-twaqqif
NEXT_PUBLIC_BASE_URL	http://localhost:20128	URL pubbliku bażiċi murija lill-dashboard u esposta lis-sserver (tissostitwixxi l-BASE_URL antika)
NEXT_PUBLIC_CLOUD_URL	https://omniroute.dev	URL bażiċi tal-endpoint tal-sinkronizzazzjoni cloud (tissostitwixxi l-CLOUD_URL antika)
API_KEY_SECRET	endpoint-proxy-api-key-secret	Sigriet HMAC għall-API keys ġenerati
REQUIRE_API_KEY	false	Infurza Bearer API key fuq /v1/*
ALLOW_API_KEY_REVEAL	false	Tippermetti lill-utenti tal-dashboard awtentikati jikxfu l-valuri kompluti tal-API key洢żżati meta jitolbuhom
PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES	70	Frekwenza tal-ġdid tas-server għad-dejta tal-Provider Limits maħżuna; il-buttuni tal-ġdid tal-UI għadhom jistimulaw is-sinkronizzazzjoni manwali
DISABLE_SQLITE_AUTO_BACKUP	false	Tixħirx il-prints awtomatiċi SQLite qabel il-kitbiet/importazzjoni/rkupru; il-backups manwali għadhom jaħdmu
APP_LOG_TO_FILE	true	Jippermetti l-output tal-log tal-applikazzjoni u tal-awditjar fuq il-disk
AUTH_COOKIE_SECURE	false	Tifforza cookie Secure tal-awtentikazzjoni (wara reverse proxy HTTPS)
CLOUDFLARED_BIN	ma twarrabx	Uża binarju cloudflared eżistenti minflok l-downloads immaniġġjati
CLOUDFLARED_PROTOCOL	http2	Trasport għat-Quick Tunnels immaniġġjati (http2, quic, jew auto)
OMNIROUTE_MEMORY_MB	512	Limitu tal-heap tal-Node.js f'MB
PROMPT_CACHE_MAX_SIZE	50	Daqs massimu ta' dħul tal-cache tal-prompt
SEMANTIC_CACHE_MAX_SIZE	100	Daqs massimu ta' dħul tal-cache semantiku

Għar-riferenza sħiħa tal-varjabbli tal-ambjent, ara l-README.

📊 Mudelli Disponibbli

Uri l-mudelli kollha disponibbli

Il-lista ta' hawn taħt ġiet magħżula minn open-sse/config/providerRegistry.ts għal v3.8.0. Il-katalaġi tal-cloud (Gemini, OpenRouter, eċċ.) jiġu ssinkronizzati b'mod dinamiku — għall-katalaġi sħiħ ħaj issir miftuħ il- Dashboard → Providers → [provider] → Available Models jew sejjaħ GET /api/models/catalog.

Jekk il-lista interna ta' provajder mmur, uża Import from /models fuq dik il-paġna (jew ippermetti Auto-Sync) biex tġib il-katalaġi tal-upstream ħaj. Dan ġie vverifikat fil-v3.8.50 għal LLM7.io (gemini-3.1-flash-lite) u UncloseAI (solidrust/Hermes-3-Llama-3.1-8B-AWQ); l-aċċess anonimu ta' Pollinations baqa' limited mill-upstream waqt l-istess test pass.

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 (+ livelli ta' sforz: 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/) — FREE OAuth: uża l-katalaġi ħaj murien taħt Dashboard → Providers → Kiro → Available Models. Il-disponibbiltà tiddependi fuq il-kont u l-pjan.

Qoder (if/) — FREE 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/xahar flat jew per-use: kimi/kimi-k2.6, kimi/kimi-k2.5

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

Groq (groq/) — Ultra-fast: 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 nattiv: 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/) — Hosted fl-UE: mistral/mistral-large-latest, mistral/mistral-medium-3-5, mistral/mistral-small-latest, mistral/devstral-latest, mistral/codestral-latest

Perplexity (pplx/) — Bis-searċi: 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 (b'xejn), 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/) — Inferrenzi veloċi: 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/) — Fokus fuq 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/) — 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:399b

Gemini (Google Cloud gemini/): Issinkronizzat ħaj skont il-API key minn Google — ebda lista statika. Qabbad key fil- Dashboard → Providers imbagħad uża Available Models biex timporta l-katalaġi attwali (pereż. gemini/gemini-3-pro, gemini/gemini-3-flash).

Provajderi kompatibbli oħra (magħżula): cohere, databricks, snowflake, together, vertex, alibaba, alibaba-cn, bedrock (permezz ta' aws-bedrock), azure-ai, openrouter (katalaġi pass-through), siliconflow, hyperbolic, huggingface, featherless-ai, cloudflare-ai, scaleway, deepinfra, vercel-ai-gateway, bazaarlink, friendliai, nous-research, reka, volcengine, ai21, gigachat. Kull wieħed iżomm il-lista tal-mudelli tiegħu stess fil-providerRegistry.ts u jista' jiġi ssinkronizzat awtomatikament meta l-provajder jiżvela endpoint /models.

Nota dwar l-IDs tal-mudelli: OmniRoute juża IDs nattivi tal-provajder (claude-opus-4-8, gpt-5.5, glm-5.1, MiniMax-M2.7, kimi-k2.5, groq-4.20-0309-reasoning). Xi IDs jinkludu versjonijiet bil-punti għaliex hekk qed tistenna l-API ta' fuq. Jekk mudelli mhux elenkat hawn fuq, ħdimt omniroute models --search <term> jew sejjaħ GET /api/models/catalog biex tikkonferma d-disponibbiltà.

---

🧩 Caratteristiċi Avvanzati

Mudelli personalizzati

Żid kwalunkwe mudell ID mal-fornitur kwalunkwe mingħajr ma tistenna aġġornament tal-app:

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

# Lista: curl http://localhost:20128/api/provider-models?provider=openai
# Neħħi: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-5.2"

Jew uża l-Dashboard: Fornituri → [Fornitur] → Mudelli personalizzati.

Noti:

• OpenRouter u fornituri kompatibbli mal-OpenAI/Anthropic humaġġestiti biss mill-Mudelli Disponibbli. It-tħ添, importazzjoni u sinkronizzazzjoni awtomatika kollha jispiċċaw fl-istess lista tal-mudelli disponibbli, hekk li m'hemm l-ebda sezzjoni separata għal Mudelli personalizzati għal dawk il-fornituri.
• Is-Sezzjoni Mudelli personalizzati hija maħsuba għal fornituri li ma jurux importazzjonijiet tal-mudelli disponibbliġestiti.

Katina ta' Peers OmniRoute

Tista' tiġi miżjuda peer OmniRoute oħra bħala fornititur Kompatibbli mal-OpenAI personalizzat. Uża l-URL bażiċi /v1 tal-peer u API key dedikata, b'privileġġ minimu, mogħtija minn dik il-peer.

Għal katini reċiproki jew multi-hop, fil-permess il-guard tal-loop fuq kull bieb:

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

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

It-talbiet biss li jintbagħtu lejn URL peer li huwa ċar permess jirċievu l-intestatura X-OmniRoute-Peer-Trace. Bieb jirrifjuta ID tal-istanza ripetut jew baġit hop fi tmiemu b'HTTP 508 Loop Detected; il-fornituri upstream ordinarji ma jirċievu l-ebda metadata tal-peer.

Il-katina tal-peers mhijiex replikazzjoni tal-base tad-data jew failover tal-host. Kull bieb iżżomm stat indipendenti SQLite, buffers, kontijiet tal-miżura, u sessions. Uża prokri tal-inverżjoni b'saħħa ċċekkjata jew client failover għal disponibbiltà attiva/passiva jew attiva/attiva, u qatt twaħħal base tad-data SQLite f'ħafna istanzi OmniRoute qed jitħaddtu.

Rotot tal-Furnitur Ddedikati

Roti t-talbiet direttament lejn fornitur speċifiku b'validazzjoni tal-mudell:

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

Il-prefiss tal-furnitur jiġi miżjud awtomatikament jekk nieqas. Mudelli ma jidhinx jirritornaw 400.

Konfigurazzjoni tal-Proxy tan-Netwerk

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

# Proxy għal kull fornitur
curl -X PUT http://localhost:20128/api/settings/proxy \
  -d '{"providers": {"openai": {"type":"socks5","host":"proxy.example.com","port":"1080"}}}'

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

Preċedenza: Speċifiku għal ċavetta → Speċifiku għal combo → Speċifiku għal fornitur → Globali → Ambjent.

Katalog tal-Mudelli API

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

Jirritorna mudelli maġguppati skont il-furnitur b'tipi (chat, embedding, image).

Sinkronizzazzjoni Sħab

• Isinkronizza fornituri, combos, u settingi bejn l-apparati
• Sinkronizzazzjoni awtomatika ta' wara b'timeout + fail-fast
• Agħżel server-side NEXT_PUBLIC_BASE_URL/NEXT_PUBLIC_CLOUD_URL fil-produzzjoni

Tunnel Quick Cloudflare

• Disponibbli fil-Dashboard → Tmiem għal Docker u deplojamenti oħra host personali
• Joħloq URL temporanju https://*.trycloudflare.com li jwassal lejn il-punt ta' tilħiq attwali mal-OpenAI kompatibbli /v1
• L-ewwel tiftaħ tinstalla cloudflared biss meta jkun meħtieġ; tiftaħiet wara jużaw l-istess binarjuġestit
• Tunnel Quick mhumix awtomatikament restawrati wara restart ta' OmniRoute jew kontenitur; terġa' tiftaħhom mid-dashbord meta tixtieq
• URLs tal-tunnel huma temporanji u jinbidlu kull meta tieqaf/tibda t-tunnel
• Tunnel Quick ġestiti jgħaddu b'ħin transport HTTP/2 biex jitwarrbu twigganijiet tal-buffer QUIC UDP fil-konteniturijiet ristretti
• Isettja CLOUDFLARED_PROTOCOL=quic jew auto jekk trid toverride l-għażla tal-transport ġestita
• Isettja CLOUDFLARED_BIN jekk tippreferi tuża binarju cloudflared preinstallat minflok li tniżżel il-ġestit
• Panelli tal-tunnel Cloudflare Quick, Tailscale Funnel, u ngrok Tunnel jistgħu juru jew jinħbew fil-Settings → Tidwir. Ma turiwsa ma waqfu tunnel li qed jimxi.

Intelligenza tal-Bieb LLM (Fażi 9)

• Buffer Semantiku — Jħaffer b'mod awtomatiku risponsi mhux stramming, b'temperature=0 (tħares b' X-OmniRoute-No-Cache: true)
• Idempotenzi tal-Talba — Jinfirek talbiet fi żmien 5s permezz ta' Idempotency-Key jew intestatura X-Request-Id
• Traċċar tal-Progress — Fil-permess SSE event: progress events permezz ta' intestatura X-OmniRoute-Progress: true

---

Torkbar tal-Vertu

Aċċess permezz Dashboard → Vertu. Debug u viżwalizza kif OmniRoute jivverifika talbiet API bejn il-fornituri.

Mod	Skop
Torkbar	Agħżel formati sors/sib, pastja talba, u ara l-output ivverifikat mill-ewwel
Tester ta' Ħbubija	Ittebgħa messaġġi ħbubija ħajjin permezz tal-proxy u spezzjon iċ-ċiklu sħiħ tal-ħlas/tirrispondi
Bank tal-Prova	Itella' testijiet fuq ħafna kombinazzjonijiet ta' format biex tivverifika l-korrettezza tal-vertu
Monitor Ħaj	Ara vetrifikazzjonijiet real-time kif it-talbiet imorru permezz tal-proxy

Każijiet tal-Użu:

• Debug għaliex kombonjazzjoni speċifika ta' client/furnitur tifailja
• Verifika li tagħbijiet tal-ħsieb, sejħiet tal-għodda, u prompts tas-sistema jivverifikaw b'mod korrett
• Qabbel differenzi tal-format bejn formati OpenAI, Claude, Gemini, u Responses API

---

Strateġiji tar-Rutjar

Konfigurazzjoni permezz Dashboard → Settings → Rutjar. Il-dashboard turi l-istrateġiji l-aktar użati; combos u l-awtorutjar internament tħallas ħafna strateġiji oħra.

Strateġiji viżibbli fil-dashboard (rutjar ta' livell ta' kont):

Istrateġija	Deskrizzjoni
Mimmi l-Ewwel	Juża l-kontijiet b'ordni ta' prijorità — il-kont primarju jitratta it-talbiet kollha sakemm ma jkunx disponibbli
Ronda tal-Qiegħ	Idur mal-kontijiet kollha b'limitu stikxu konfigurabbli (default: 3 sejħiet għal kull kont)
P2C (Is-Tagħżil tal-Ħumas tal-Għażla)	Jagħżel 2 kontijiet bi prijorità u jivverifika l-aktar b'saħħa — ibilanċja l-piż b'għarfien tal-saħħa
Accidental	Jagħżel kont għal kull talba b'modAccidental billi juża t-tħawwil tal-Fisher-Yates
L-iktar Użat	Jivverifika lejn il-kont b'timistamp ta' lastUsedAt l-aktar qadim, jixerrid it-traffiku b'mod uniformi
Ottimizzat għall-Ispejjeż	Jivverifika lejn il-kont b'l-iktar valur ta' prijorità baxx, joqroq għal fornituri b'ispejjeż baxxi

Strateġiji avvanzati u awto għal combo (konfigurabbli għal kull kombo jew permezz ta' prefissi auto/* — ara AUTO-COMBO.md):

• priority — ordni strett, qatt mhuwa ronda tal-qiegħ
• weighted — tinqasam traffiku proporzjonali skont piżijiet għal kull mudell
• fill-first — jivvasta l-ewwel mudell sakemm jilħqu l-limiti
• round-robin / strict-random / random
• p2c (Is-Tagħżil tal-Ħumas tal-Għażla)
• least-used u cost-optimized
• auto — skor imexxi fost il-kandidati kollha
• lkgp (Il-Fornitur Tafu l-Aħħar tajjeb) — jipponi lejn il-furnitur li rnexxielu l-aħħar, imbagħad jaqa' fuq ir-regoli
• context-optimized — jagħżel il-mudell bil-f㶞 kbar ħielsa
• context-relay — jirringan mudelli b'konstellazzjoni twila għal dawriet li jmiss

Intestatura Sessione Barra

Għal affinità ta' sessione barra (per eżempju, aġenti Claude Code/Codex wara prokri tal-inverżjoni), bagħat:

X-Session-Id: your-session-key

OmniRoute jirċievi wkoll x_session_id u jirritorna l-ċavetta effettiva tas-sessione f'X-OmniRoute-Session-Id.

Jekk tuża Nginx u tibgħat intestaturi b'underscore, fil-permess:

underscores_in_headers on;

Aliases tal-Mudell bil-Wildcards

Oħloq patterns biex tiddetermina mill-ġdid ismijiet tal-mudelli:

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

Wildcards jappoġġjau * (kwalunkwe karattri) u ? (karattru wieħed).

Katini tal-Ħalluka

Definixxi katini globali tal-ħalluka li japplikaw għat-talbiet kollha:

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

---

Reżiljenza u Kburijiet tal-Kuritur

Konfigurazzjoni permezz Dashboard → Settings → Reżiljenza.

OmniRoute jimplimenta reżiljenza ta' livell tal-furnitur b'ħames komponenti:

1. Queue tal-Talba u Pacing — Formazzjoni tat-talba ta' livell tas-sistema:

   • Talbiet Fil-Minuta (RPM) — Talbiet massimi fil-minuta għal kull kont
   • Ħin Minimu bejn it-Talbiet — Tnoss minimu f'millisekondi bejn it-talbiet
   • Talbiet Massimi Konkorrenti — Talbiet simultanji massimi għal kull kont

2. Cooldown tal-Ġonta — Konfigurazzjoni għal kull tip ta' awtentikazzjoni għal konnessjoni waħda wara fallimenti li jistgħu jerġgħu jsiru:

   • Cooldown Bażi — Tnoss tal-cooldown default għal fallimenti upstream li jistgħu jerġgħu jsiru
   • Uża Dowżuni tal-Riprova Upstream — Jirrispetta dowżuni ewlenin Retry-After jew dowżuni tat-twaqqif meta jinġiebu
   • Passi massimi tal-Backoff — Livell massimu tal-backoff esponenzjali għal fallimenti ripetuti

3. Kuritur tal-Furnitur — Jitrakka l-fallimenti tal-furnitur minn tmiem sa tmiem, jimmarka furnitur b'mod degradat fil-limitu tal-warnja konfigurat, u jiftaħ il-kuritur meta jilħaq il-limitu tal-fallimenti konfigurat:

   • Limitu tal-Ħsara — Fallimenti konsekuttivi tal-furnitur qabel ma jidħlu fi DEGRADED
   • Limitu tal-Falliment — Fallimenti konsekuttivi tal-furnitur qabel ma jidħlu fi OPEN
   • Ħin qabel ir-Riżett — Tnoss qabel ma jittestja mill-ġdid il-furnitur
   • CLOSED (B'Saħħa) — It-talbiet imorru normalment
   • DEGRADED — It-talbiet għadhom imorru waqt li l-fallimenti mgħollijin jittraċċraw
   • OPEN — Il-furnitur huwa mblukkat temporanjament wara fallimenti ripetuti
   • HALF_OPEN — Ittestjar jekk irkupra il-furnitur

   Limiti tar-rata 429 li jiskopru ġonta jibqgħu f'Cooldown tal-Ġonta u ma jgħoddux lejn il-kuritur tal-furnitur.

   L-istat runtime tal-kuritur tal-furnitur jidher biss fil-Dashboard → Saħħa.

4 Stenna għal Cooldown — Jekk kull konnessjoni kandidata diġa' tkun qed tistenna, OmniRoute jista' jistenna l-ewwel cooldown u jerġa' jipprova l-istess talba tal-client awtomatikament.

5. Għarfien Awtomatiku tal-Miżura — Meta fornituri upstream jirritornaw tnoss tal-attendi ċari, id-dowżuni tagħhom jaħbu fuq il-cooldown tal-Ġonta lokali meta l-impostazzjoni tkun fil-permess.

Parir ta' Pert: Uża l-paġna Saħħa biex tispezzjonaw u tissellafa kurituri tal-furnitur ħajjin wara qtugħ. Il-paġna Reżiljenza tbiddel biss il-konfigurazzjoni.

---

Esportazzjoni / Importazzjoni tal-Base tad-Data

Ġestija backup tal-base tad-data fil-Dashboard → Settings → Sistema u Stoccar.

Azjoni	Deskrizzjoni
Esporta l-Base tad-Data	Niżżel il-base tad-data SQLite attwali bħala fajl .sqlite
Esporta Kollha (.tar.gz)	Niżżel arċiv backup sħiħ li jinkludi: base tad-data, settingi, combos, konnessjonijiet tal-furnitur (bl-ebda kredenzjali), metadata tal-API key
Importa Base tad-Data	Tella' fajl .sqlite biex tissostitwixxi l-base tad-data attwali. Backup qabel l-importazzjoni jiġi ġenerat awtomatikament sakemm DISABLE_SQLITE_AUTO_BACKUP=true

# API: Esporta base tad-data
curl -o backup.sqlite http://localhost:20128/api/db-backups/export

# API: Esporta kollha (arċiv sħiħ)
curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll

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

Validazzjoni Importazzjoni: Il-fajl importat jiġi validat għall-integrità (SQLite pragma check), tabelli meħtieġa (provider_connections, provider_nodes, combos, api_keys), u daqs (massimu 100MB).

Każijiet tal-Użu:

• Tmigra OmniRoute bejn il-magni
• Oħloq backups esterni għal tħaris tad-diżastri
• Tqassam il-konfigurazzjonijiet bejn membri tal-tim (esporta kollha → qassam l-arċiv)

---

Dashboard tal-Settingi

Il-paġna tal-settingi hija organizzata f'7 tabs għal navigazzjoni faċli:

Tab	Kontenut
Ġenerali	Għodod tal-istoccar tal-sistema, imġieba default, Vetrifikazzjoni tat-Tunnel tal-Endpoint
Tidwir	Kontrolli tat-Tema (skur/ċar/sistema), vetrifikazzjoni tal-sidebar, panelli tal-toggle għal karti tal-tunnel Cloudflare/Tailscale/ngrok
AI	Budget tal-ħsieb (pass-through / auto-strip / personalizzat / adattiv — ara THINKING_BUDGET.md), prompt globali tas-sistema, statistika tal-cache tal-prompt
Sikurezza	Impostazzjonijiet ta' Login/Password, Kontroll tal-Aċċess IP, Awtentikazzjoni API għal /models, Tixrid tal-Furnitur, Gwardja kontra l-inġettjar tal-prompt
Rutjar	Istrateġija globali tal-rutjar (Mimmi l-Ewwel / Ronda tal-Qiegħ / P2C / Accidental / L-iktar Użat / Ottimizzat għall-Ispejjeż), aliases tal-mudell bil-wildcards, katini tal-ħalluka, defaults tal-combo
Reżiljenza	Queue tal-talba, cooldown tal-Ġonta, konfigurazzjoni tal-kuritur tal-furnitur, u imġieba tal-istenna għal cooldown
Avvanzat	Konfigurazzjoni tal-proxy globali (HTTP/SOCKS5), override tal-proxy għal kull fornitur

Ġenerali ma jidduplikax noti biss għall-logging u cache. Ġestija ta' ritenzjoni tal-base tad-data u ottimizzazzjoni huma preservati permezz /api/settings/database; tneħħija tal-cache manwali tuża DELETE /api/cache. Limiti tal-linji tal-log tal-ħlas u tal-proxy huma kkontrollati minn CALL_LOGS_TABLE_MAX_ROWS u PROXY_LOGS_TABLE_MAX_ROWS.

---

Spejjeż u Ġestjoni tal-Budget

Aċċess permezz Dashboard → Spejjeż.

Tab	Skop
Budget	Isettja limiti tal-ħlas għal kull API key b'budgets ta' kuljum/ġimgħa/xahar u traċċar real-time
Prezzijiet	Ara u editja d-dħul tal-prezzijiet tal-mudell — piż għal 1K tokens input/output għal kull fornitur

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

# API: Ħu stat attwali tal-budget
curl http://localhost:20128/api/usage/budget

Traċċar tal-Ispejjeż: Kull talba tivvintar l-użu tat-token u tikkalkola l-ispiż permezz tal-tabella tal-prezzijiet. Ara s-suzzjonijiet fil-Dashboard → Użu skont il-furnitur, il-mudell, u l-API key.

---

Traskrizzjoni tal-Awdjo

OmniRoute jappoġġja traskrizzjoni tal-awdjo permezz tal-punt ta' tilħiq kompatibbli mal-OpenAI:

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

# Eżempju b'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 hija r-rotta nattiva ta' Deepgram u teħtieġ API key ta' Deepgram. Jekk biss OpenRouter ġie konfigurat, uża openrouter/deepgram/nova-3.

Fornituri tal-Kelma għat-Test (traskrizzjoni):

• openai/ (kompatibbli mal-whisper)
• groq/ (Groq Whisper Turbo)
• deepgram/ (familja Nova)
• assemblyai/
• nvidia/ (Parakeet, Canary)
• huggingface/ (varianti tal-whisper)
• qwen/

Fornituri tal-Test għall-Kelma (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/

Formati awdjo appoġġjati għall-traskrizzjoni: mp3, wav, m4a, flac, ogg, webm. Il-formati tal-output TTS jiddependu mill-fornitur (mp3, wav, opus, pcm, mulaw).

---

Strateġiji tal-Bilanċ tal-Kombo

Konfigurazzjoni tal-bilanċ għal kull kombo fil-Dashboard → Combos → Ħolqien/Edizzjoni → Istrateġija.

Istrateġija	Deskrizzjoni
Ronda tal-Qiegħ	Idur mal-mudelli b'mod konsekuttiv
Prijorità	Dejjem jipprova l-ewwel mudell; jaqa' biss fil-każ ta' żball
Accidental	Jagħżel mudell accidental mill-kombo għal kull talba
Piziżżat	Jivverifika b'mod proporzjonali skont il-piżijiet assenjati għal kull mudell
L-iktar Użat	Jivverifika lejn il-mudell bil-ftit talbiet reċenti (jjuża metrics tal-kombo)
Ottimizzat għall-Ispejjeż	Jivverifika lejn l-iktar mudell irħas disponibbli (jjuża tabella tal-prezzijiet)

Defaults globali tal-kombo jistgħu jinstabu fil-Dashboard → Settings → Rutjar → Defaults tal-Kombo. It-timeouts tal-kombo intrist minn it-timeout tal-talba attwali b'mod default. Uża Timeout tal-mira (sekondi) fil-defaults tal-kombo jew kombo individwali biss meta limitu iqsar għal kull mira għandu jikkanċella fallback aktar mgħaġġel.

Ottimizzazzjonijiet tal-kombo b'latebja zero huma fil-permess. Ħalli Ottimizzazzjonijiet b'latebja zero mhux fil-permess biex tevita li dawn il-karatteristiċi tal-atebjija jiġru mal-miri tal-fallback, jaqsmu miri skont l-istorja tal-TTFT, jew jissikksaw talbiet fallback; jekk jitlesta jippermetti hedging konfigurat, skip predictor tal-TTFT, u s-sikksar proattiv tal-fallback biex itttrasferixxi l-fedelta tal-rotja/talba għal atebja eqsar ta' pont.

Fil-permess Buffer tal-Token tar-Raguna meta fornituri upstream jeħtieġu limiti stretti max_tokens / maxOutputTokens. Meta miftuħ, il-rotja tal-kombo iżżid biss spazju ta' prijorità tal-mudell tar-raguna għal mudelli b'limitu magħruf tal-output u tħalli l-limitu tal-token tal-client inbidel meta l-valur sikur tal-buffer jaqbeż dak il-limitu. Jekk il-limitu tal-client diġa' huwa 'l fuq minn limitu magħruf, OmniRoute iwaħħalhu għal dak il-limitu qabel ma jibagħat it-talba upstream.

---

Dashboard tas-Saħħa

Aċċess permezz Dashboard → Saħħa. Ġabra real-time tal-istat tas-sistema b'6 karti:

Karta	Ulied juru
Istat tas-Sistema	Ħin mixgħul, verżjoni, użu tal-memorja, direttorju tad-data
Saħħa tal-Furnitur	Istat runtime tal-kuritur globali tal-furnitur
Miżuri tar-Rata	Cooldowns attivi tal-Ġonta għal kull kont b'ħin fadal
Blokkamenti Attivi	Blokkamenti ta' skop tal-mudell attivi u eskluzjonijiet temporanji
Buffer tal-Firma	Statistika tal-cache tal-iskoppjar (ċavetti attivi, rata ta' hit)
Telemetria l-atebjija	Ġabra l-atebjija p50/p95/p99 għal kull fornitur

Parir ta' Pert: Il-paġna Saħħa tixtaq awtomatikament kull 10 sekondi. Uża l-karta tal-kuritur biex tidentifika liema fornituri qed jesperjenzaw problemi.

---

🤖 Awto-Routjar (B’ebda konfigurazzjoni)

OmniRoute jittrasmetti b’awto-router mmexxi b’iskor li jagħżel l-aħjar mudell għal kull talba fost il-provdituri kollha konnessi — l-ebda kombo x’tżomm. Agħti biss it-talba b’wieħed mill-prefissi auto/* u l-Omniroute se jkabbar kombo virtwali fuq il-post, billi jskora l-kandidati skont id-dewmien, l-ispiża, ir-rata ta’ suċċess, l-adattament tal-kuntest, l-adattament tal-mudell għall-impjiegi, it-telf reċenti, il-kwota, u l-kundizzjonijiet tal-ksur tal-ċirkuwitu.

Prefiss	Jottimizza għal
auto	Default bilanċjat (dewmien × ispiża × rata ta’ suċċесс)
auto/coding	Xogħlijiet tal-kodifikazzjoni: jippreferixxi Claude, GPT-5, GLM, Kimi, Qwen Coder, il-kodifikaturi DeepSeek
auto/cheap	L-iqsar $/token, jaccetta aktar dewmien
auto/fast	L-iqsar dewmien, injora l-ispiża
auto/offline	Provdituri biss lokali (Ollama, vLLM, llama.cpp) — utli għal ambjenti mħottas
auto/smart	Kwalità tar-ragunament l-ewwel (Opus, GPT-5 xhigh, R1, ragunament GLM 5.1)
auto/lkgp	"Provdituri Magħrufa Tajbin ta’ l-Aħħar" — imwaħħal mal-aħħar provditur ta’ suċċесс, imbagħad jirrikorri għar-regoli

Eżempju:

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 dan il-funzjoni Python" }],
    "stream": true
  }'

L-awto-router huwa deskritt b’mod sħiħ f’AUTO-COMBO.md — inkluż kif tista’ taġġusta l-piżijiet tal-iskor, tissanzjona provdituri, u tispezzjona d-deċiżjonijiet tar-routjar f’Dashboard → Auto Combo.

---

🔌 Integrazzjoni MCP & A2A

L-Omniroute huwa kemm server MCP (Protokoll tal-Kuntest tal-Mudell) kif ukoll server A2A (Agent-to-Agent JSON-RPC 2.0). Kwalunkwe IDE jew provditur tal-aġenti kompatibbli mal-MCP jista’ sejjaħ għall-għodod tal-Omniroute direttament — l-ebda wrapper addizzjonali meħtieġ.

Trasporti MCP

• SSE: http://localhost:20128/api/mcp/sse
• Streamable HTTP: http://localhost:20128/api/mcp/stream
• stdio: omniroute --mcp (għal plugins tal-IDE li jippreferixxu l-stdio)

Konnetti Claude Desktop

Editja ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) jew l-ekwivalenti fuq Windows/Linux:

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

Konnetti Cursor / Continue / VS Code MCP

Ipprovdilhom l-URL SSE http://localhost:20128/api/mcp/sse u API key ġenerata f’Dashboard → API Keys.

Ambiti

L-MCP bħalissa jiddefinixxi 32 ambitu magħruf. Kull Bearer key jista’ jiġi limitat għal ambitti speċifiċi — ara MCP-SERVER.md għall-inventarju awtorevoli tal-ambiti u l-għodod, u A2A-SERVER.md għas-skema JSON-RPC.

---

🧩 Sistema ta' Ħiliet

OmniRoute toffri qafas ta' ħiliet estensibbli (src/lib/skills/) sabiex l-agenti u l-punt tat-tmiem A2A jistgħu jwettqu rutini speċifiċi għal domini (eż. code-review, summarize, extract-facts, web-research).

• Interfaċi tal-Marketplace — Stenna u tinstalla ħiliet minn Dashboard → Ħiliet
• Ambiti fuq iċ-ċavetta — Irstrinġu liema ċavetti tal-API jistgħu jsejħu liema ħiliet
• Ħiliet personalizzati — Waqqa' fajl TypeScript f' src/lib/a2a/skills/, irreġistrah, u immedjatament isir invokabbli permezz tal-A2A

Referenza sħiħa: SKILLS.md.

---

💾 Sistema tal-Memorja

OmniRoute jippreżerva memorja twila tal-konverżazzjoni b'retrieval ibridu:

• SQLite FTS5 għal tiftixa bil-kelma mal-turns li għaddew
• Ħażna vetturali ta' Qdrant (għażla) għal tifkira semantika
• Spezzjoni awtomatika tal-fatti — L-entitajiet, il-preferenzi, u d-deċiżjonijiet jiġu rrasummjati wara kull session u maħżuna fil- memory_facts
• Il-memorji huma skopjati skont iċ-ċavetta tal-API u skont is-sessjoni

Immaniġġja l-mororji f' Dashboard → Memorja (tiftixa, teditja, esportazzjoni, tneħħija). L-isuperfiċi HTTP (/api/memory/*) tippermetti lill-agenti jippromwovu u jistaqsu l-fatti b'mod programmatiku — ara MEMORY.md.

---

🔔 Webhooks

Abbona għall-avvenimenti tal-OmniRoute għal monitoraġġ u awtomazzjoni f'ħin reali.

• Oħloq webhook f' Dashboard → Webhooks b'URL ta' skop u sigriet tal-iffirma HMAC
• L-avvenimenti disponibbli: request.completed, request.failed, provider.unavailable, budget.exceeded, combo.switched, circuit_breaker.opened, circuit_breaker.closed
• Kull payload jinkludi X-OmniRoute-Signature (HMAC-SHA256) għal verifika
• Storji: 3 attentat b'retroċessjoniment esponenzjali, imbagħad il-queue tal-mewt

Is-sema sħiħa f' WEBHOOKS.md.

---

☁️ Aġenti tal-Cloud

OmniRoute jintegra ma' aġenti tal-kodiċi tal-cloud (OpenAI Codex Cloud, Devin, Jules, Antigravity) sabiex tista' tiddispatchja xogħlijiet li jdumu fit-tul minn l-istess dashboard li tiġġestixxi r-rotta lokali tiegħek.

• Oħloq xogħlijiet f' Dashboard → Aġenti tal-Cloud jew permezz ta' POST /api/v1/agents/tasks
• Iġbor l-istatus, il-logs, u l-artifatti għal kull xogħol
• Ġib ċavetta tal-API tiegħek stess għal kull fornitur — il-kredenzjali qatt ma ħarġu minn l-istanza tal-OmniRoute

Referenza sħiħa: CLOUD_AGENT.md.

---

🛠️Ġestjoni Programmatika

Tista' timmaniġġja kull riżorsa tal-OmniRoute (fornituri, kombos, ċavetti, settings) permezz ta' HTTP billi tuża ċavetta Bearer b' l-ambitu manage.

Ġenera l-ċavetta f' Dashboard → Ċavetti tal-API → Ċavetta Ġdida → Ambitu: manage, imbagħad:

# Lista tal-fornituri
curl http://localhost:20128/api/providers \
  -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY"

# Żid konnessjoni mal-fornitur
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" }'

# Oħloq 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" }] }'

# Lista/ħoloq ċavetti tal-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"] }'

Ara API_REFERENCE.md għall-katalgu sħiħ tal-punti tat-tmiem u l-isemi tal-istedina/rispons.

---

💻 CLI Interna

OmniRoute jipprovdi CLI intern (omniroute …) għat-twaqqif, dijanjostika, u kontroll waqt l-isfond. Dan huwa separat mill-paġna "Għodod CLI" fil-dashboard, li tikkonfigura CLIs ta' parti terza (Claude Code, Cursor, Codex, Cline, …) sabiex ikunu jistgħu jikkomunikaw ma' OmniRoute.

omniroute setup                    # Wizard interattiv (password, fornituri, kombinazzjonijiet)
omniroute setup --non-interactive  # Ħaġar għal CI
omniroute doctor                   # Dijanjostika tas-saħħa (dir. tad-dett, DB, fornituri, portijiet)
omniroute providers available      # Elenka l-fornituri appoġġjati
omniroute providers list           # Elenka konnessjonijiet ikkonfigurati
omniroute providers test <id>      # Test ħaj ta' konnessjoni ta' fornitur
omniroute combos list              # Elenka l-kombinazzjonijiet
omniroute combos switch <name>     # Waqqaf kombinazzjoni default
omniroute models                   # Elenka mudelli disponibbli (--json, --search)
omniroute keys add | list | remove # Ġestixxi ċav API mill-terminal
omniroute backup                   # Fenfas ta' konfigurazzjoni + DB
omniroute restore [<timestamp>]    # Irrestorja minn fenfas
omniroute health                   # Saħħa dettaljata (breakers, cache, memorja)
omniroute quota                    # Użu tal-kwota tal-fornitur
omniroute mcp status               # Statut tal-server MCP
omniroute a2a status               # Statut tal-server A2A
omniroute tunnel list|create|stop  # Tunelli Cloudflare/Tailscale/ngrok
omniroute reset-password           # Ġeddid il-password tal-amministratur
omniroute --mcp                    # Daħħal server MCP permezz ta' stdio
omniroute --port 3000              # Daħħal il-server fuq port personaliżżat

Parir: għaqqad omniroute doctor --json mal-għodda ta' monitoraġġ tiegħek biex twissi meta konnessjonijiet tal-fornituri m'humiex fl-isħun.

---

🖥️ Applikazzjoni Desktop (Electron)

OmniRoute huwa disponibbli bħala applikazzjoni desktop nattiva għal Windows, macOS, u Linux.

Twaqqif

# Mill-dir. electron:
cd electron
npm install

# Modalità żvilupp (għaqqad ma' server Next.js ta' żvilupp li qed jaħdem):
npm run dev

# Modalità produzzjoni (tuża build standard):
npm start

Twaqqif ta' Installaturi

cd electron
npm run build          # Pjattaforma attwali
npm run build:win      # Windows (.exe NSIS)
npm run build:mac      # macOS (.dmg universali)
npm run build:linux    # Linux (.AppImage)

Output → electron/dist-electron/

Karatteristiċi Ċav

Karatteristika	Twaħħal
Disponibbiltà tal-Server	Jivverifika qabel ma juri l-fenestra (bla skrin bħal din)
Tray tal-Isistema	Naqqas għal-tray, ibdel il-port, ħarba minn menu tray
Ġestjoni tal-Port	Ibdel port tal-server minn tray (ijerra mill-ġdid awtomatikament)
Politika ta' Sigurtà tal-Kontenut	CSP ristrett permezz ta' intestaturi session
Munzell Wieħed	Biss wieħed mill-app jeħtieġ jaħdem f'ħin wieħed
Modalità Offline	Is-server NextRoute inklux jaħdem mingħajr internet

Variabbli tal-Ambjent

Variabbja	Default	Twaħħal
OMNIROUTE_PORT	20128	Port tal-server
OMNIROUTE_MEMORY_MB	512	Limitu tal-ħira Node.js (64–16384 MB)

📖 Dokumentazzjoni sħiħa: electron/README.md