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

User Guide (Türkçe)

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

---

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

Sağlayıcıları yapılandırma, kombinasyonlar oluşturma, CLI araçlarını entegre etme ve OmniRoute'u dağıtma konusunda eksiksiz kılavuz.

---

İçindekiler

• Bir Bakışta Fiyatlandırma
• Kullanım Senaryoları
• Sağlayıcı Kurulumu
• CLI Entegrasyonu
• Dağıtım
• Kullanılabilir Modeller
• Gelişmiş Özellikler
• Otomatik Yönlendirme (Sıfır Yapılandırma)
• MCP ve A2A Entegrasyonu
• Yetenek Sistemi
• Bellek Sistemi
• Webhook'lar
• Bulut Aracıları
• Programatik Yönetim
• Dahili CLI
• Masaüstü Uygulaması (Electron)

---

💰 Bir Bakışta Fiyatlandırma

Katman	Sağlayıcı	Maliyet	Kota Sıfırlama	En Uygun Olduğu Alan
💳 ABONELİK	Claude Code (Pro)	$20/ay	5 sa. + haftalık	Zaten abone olanlar
	Codex (Plus/Pro)	$20-200/ay	5 sa. + haftalık	OpenAI kullanıcıları
	GitHub Copilot	$10-19/ay	Aylık	GitHub kullanıcıları
🔑 API ANAHTARI	DeepSeek	Kullanım başına ödeme	Yok	Ucuz akıl yürütme
	Groq	Kullanım başına ödeme	Yok	Ultra hızlı çıkarım
	xAI (Grok)	Kullanım başına ödeme	Yok	Grok 4 akıl yürütmesi
	Mistral	Kullanım başına ödeme	Yok	AB'de barındırılan modeller
	Perplexity	Kullanım başına ödeme	Yok	Aramayla zenginleştirilmiş
	Together AI	Kullanım başına ödeme	Yok	Açık kaynaklı modeller
	Fireworks AI	Kullanım başına ödeme	Yok	Hızlı FLUX görüntüleri
	Cerebras	Kullanım başına ödeme	Yok	Wafer ölçeğinde hız
	Cohere	Kullanım başına ödeme	Yok	Command R+ RAG
	NVIDIA NIM	Kullanım başına ödeme	Yok	Kurumsal modeller
	Baidu Qianfan	Kullanım başına ödeme	Yok	ERNIE modelleri
💰 UCUZ	GLM-4.7	$0.6/1M	Her gün saat 10.00	Bütçe dostu yedek
	MiniMax M2.1	$0.2/1M	5 saatlik kayan dönem	En ucuz seçenek
	Kimi K2	Sabit $9/ay	10M token/ay	Öngörülebilir maliyet
🆓 ÜCRETSİZ	Qoder	$0	Sağlayıcı limitleri geçerlidir	Güncel kataloğu doğrulayın
	Kiro	$0	~50 kredi/ay	Ücretsiz Claude

---

🎯 Kullanım Senaryoları

Senaryo 1: "Claude Pro aboneliğim var"

Sorun: Kota kullanılmadan sona eriyor, yoğun kodlama sırasında hız limitlerine takılıyor

Kombinasyon: "maximize-claude"
  1. cc/claude-opus-4-7        (aboneliği tam olarak kullan)
  2. glm/glm-4.7               (kota tükendiğinde ucuz yedek)
  3. if/qwen3.8-max-preview       (ücretsiz acil durum alternatifi)

Aylık maliyet: $20 (abonelik) + ~$5 (yedek) = toplam $25
$20 ödeyip limitlere takılmak yerine = daha az hayal kırıklığı

Senaryo 2: "Sıfır maliyet istiyorum"

Sorun: Abonelikleri karşılayamıyorum, güvenilir yapay zekâ destekli kodlamaya ihtiyacım var

Kombinasyon: "zero-cost"
  1. if/kimi-k2.7-code          (ücretsiz erişim listeleniyor; hız limitleri geçerli olabilir)
  2. kr/qwen3-coder-next        (ücretsiz Kiro alternatifi)

Aylık maliyet: $0
Kalite: iş yükünüz için modeli, limitleri, gizliliği ve SLA'yı doğrulayın

Senaryo 3: "Kesintisiz, 7/24 kodlama yapmam gerekiyor"

Sorun: Son teslim tarihleri var, kesinti yaşama lüksüm yok

Kombinasyon: "always-on"
  1. cc/claude-opus-4-7        (en iyi kalite)
  2. cx/gpt-5.5                (ikinci abonelik)
  3. glm/glm-4.7               (ucuz, günlük sıfırlanır)
  4. minimax/MiniMax-M2.1      (en ucuz, 5 saatte sıfırlanır)
  5. if/deepseek-v4-flash       (ücretsiz erişim listeleniyor; hız limitleri geçerli olabilir)

Sonuç: 5 yedek katmanı dayanıklılığı artırır; üst kaynakların kullanılabilirliği garanti edilmez
Aylık maliyet: $20-200 (abonelikler) + $10-20 (yedek)

Senaryo 4: "OpenClaw'da ÜCRETSİZ yapay zekâ istiyorum"

Sorun: Mesajlaşma uygulamalarında tamamen ücretsiz bir yapay zekâ asistanına ihtiyacım var

Kombinasyon: "openclaw-free"
  1. if/qwen3.8-max-preview     (ücretsiz erişim listeleniyor; hız limitleri geçerli olabilir)
  2. if/deepseek-v4-flash       (ücretsiz erişim listeleniyor; hız limitleri geçerli olabilir)
  3. if/kimi-k2.7-code          (ücretsiz erişim listeleniyor; hız limitleri geçerli olabilir)

Aylık maliyet: $0
Şunlar üzerinden erişim: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...

---

📖 Sağlayıcı Kurulumu

Bir CSV veya JSON dosyasından toplu olarak API anahtarı bağlantıları eklemek için Kontrol Paneli → Sağlayıcılar → Dosyadan içe aktar seçeneğini kullanın. Sütunlar konuma dayalıdır (provider,name,apiKey,baseUrl,priority); provider, yönetilen bir sağlayıcı veya uyumlu bir düğüm olarak zaten mevcut olmalıdır. Bkz. Sağlayıcıları bir CSV veya JSON dosyasından içe aktarma.

🔐 Abonelik Sağlayıcıları

Claude Code (Pro/Max)

Kontrol Paneli → Sağlayıcılar → Claude Code'u Bağla
→ OAuth ile oturum açma → Otomatik token yenileme
→ 5 saatlik + haftalık kota takibi

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

Profesyonel İpucu: Karmaşık görevler için Opus'u, hız için Sonnet'i kullanın. OmniRoute kotayı model bazında takip eder!

Claude ve Claude Code uyumlu rotalar, Opus ve Sonnet modelleri için max düşünme eforunu korur. Haiku modelleri max efor katmanını kabul etmez; bu nedenle OmniRoute, isteği üst sağlayıcıya göndermeden önce yüksek bir düşünme bütçesine düşürür.

OpenAI Codex (Plus/Pro)

Kontrol Paneli → Sağlayıcılar → Codex'i Bağla
→ OAuth ile oturum açma (port 1455)
→ 5 saatlik + haftalık sıfırlama

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

GitHub Copilot

Kontrol Paneli → Sağlayıcılar → GitHub'ı Bağla
→ GitHub üzerinden OAuth
→ Aylık sıfırlama (ayın 1'inde)

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

💰 Ucuz Sağlayıcılar

GLM-4.7 (Günlük sıfırlama, $0.6/1M)

1. Kaydolun: Zhipu AI
2. Coding Plan'den API anahtarını alın
3. Kontrol Paneli → API Anahtarı Ekle: Sağlayıcı: glm, API Anahtarı: your-key

Kullanım: glm/glm-4.7 — Profesyonel İpucu: Coding Plan, maliyetin 1/7'sine 3 kat kota sunar! Her gün saat 10:00'da sıfırlanır.

MiniMax M2.1 (5 saatte bir sıfırlama, $0.20/1M)

1. Kaydolun: MiniMax
2. API anahtarını alın → Kontrol Paneli → API Anahtarı Ekle

Kullanım: minimax/MiniMax-M2.1 — Profesyonel İpucu: Uzun bağlam için en ucuz seçenek (1M token)!

Kimi K2 (Aylık sabit $9)

1. Abone olun: Moonshot AI
2. API anahtarını alın → Kontrol Paneli → API Anahtarı Ekle

Kullanım: kimi/kimi-k2.5 — Profesyonel İpucu: 10M token için aylık sabit $9 = 1M başına efektif $0.90 maliyet!

Baidu Qianfan / ERNIE

1. Kaydolun: Baidu AI Cloud Qianfan
2. Bir Qianfan API anahtarı oluşturun → Kontrol Paneli → API Anahtarı Ekle: Sağlayıcı: qianfan

Kullanım: qianfan/ernie-5.1, qianfan/ernie-x1.1 veya başka bir Qianfan OpenAI uyumlu model kimliği.

🆓 ÜCRETSİZ Sağlayıcılar

Kimlik doğrulaması gerektirmeyen ücretsiz sağlayıcıların sağlayıcı sayfasında Kimlik doğrulaması gerekli değil seçeneğinin yanında bir anahtar bulunur. Bu anahtarı kapatmak ilgili sağlayıcıyı devre dışı bırakır, Sağlayıcılar'ın yapılandırılmış/kompakt görünümlerinden kaldırır ve modellerini /v1/models üzerinden kaldırır.

Qoder (9 ÜCRETSİZ model)

Kontrol Paneli → Qoder'ı Bağla → OAuth ile oturum açma → Erişim, sağlayıcının mevcut sınırlarına tabidir

Modeller: 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 ÜCRETSİZ)

Kontrol Paneli → Kiro'yu Bağla → AWS Builder ID veya Google/GitHub → Ayda yaklaşık 50 kredi

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

---

🎨 Kombolar

Kombo kartlarını doğrudan Kontrol Paneli → Kombolar bölümünde, her karttaki tutamacı sürükleyerek yeniden sıralayabilirsiniz. Sıralama SQLite'ta saklanır ve yeniden yükleme sırasında geri yüklenir.

Örnek 1: Aboneliği En Üst Düzeye Çıkarma → Ucuz Yedek

Kontrol Paneli → Kombolar → Yeni Oluştur

Ad: premium-coding
Modeller:
  1. cc/claude-opus-4-7 (Birincil abonelik)
  2. glm/glm-4.7 (Ucuz yedek, $0.6/1M)
  3. minimax/MiniMax-M2.7 (En ucuz geri dönüş seçeneği, $0.3/1M)

CLI'da kullanın: premium-coding

Örnek 2: Yalnızca Ücretsiz (Sıfır Maliyet)

Ad: free-combo
Modeller:
  1. if/kimi-k2.7-code (ücretsiz erişim olarak listelenmiştir; sağlayıcı sınırları geçerli olabilir)
  2. kr/qwen3-coder-next (Ücretsiz Kiro geri dönüş seçeneği)

Maliyet: şu anda $0 olarak listelenmektedir; koşullar ve kullanılabilirlik değişebilir

---

🔧 CLI Entegrasyonu

Cursor IDE

Cursor'ı bir OmniRoute istemcisi olarak kullanma (Cursor sohbetini OmniRoute üzerinden yönlendirin):

Ayarlar → Modeller → Gelişmiş:
  OpenAI API Temel URL'si: http://localhost:20128/v1
  OpenAI API Anahtarı: [OmniRoute kontrol panelinden]
  Model: cc/claude-opus-4-7

OmniRoute'u bir Cursor sağlayıcısı olarak kullanma (OmniRoute, Cursor üst hizmetini çağırır): tercihen Kontrol Paneli → Sağlayıcılar → Cursor → Cursor ile Giriş Yap yolunu kullanın. Docker'da docs/providers/CURSOR-DOCKER.md belgesine bakın.

Claude Code

~/.claude/settings.json dosyasını düzenleyin:

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

Burada Claude uyumlu kök uç noktayı kullanın. ANTHROPIC_BASE_URL sonuna /v1 eklemeyin.

Codex CLI

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

OpenClaw

~/.openclaw/openclaw.json dosyasını düzenleyin:

{
  "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" }]
      }
    }
  }
}

Veya Kontrol Panelini kullanın: CLI Araçları → OpenClaw → Otomatik yapılandırma

Cline / Continue / RooCode

Sağlayıcı: OpenAI Uyumlu
Temel URL: http://localhost:20128/v1
API Anahtarı: [kontrol panelinden]
Model: cc/claude-opus-4-7

---

🚀 Dağıtım

Global npm kurulumu (Önerilen)

npm install -g omniroute

# Yapılandırma dizinini oluşturun
mkdir -p ~/.omniroute

# .env dosyasını oluşturun (.env.example dosyasına bakın)
cp .env.example ~/.omniroute/.env

# Sunucuyu başlatın
omniroute
# Veya özel bir port ile:
omniroute --port 3000

CLI, .env dosyasını ~/.omniroute/.env veya ./.env konumundan otomatik olarak yükler.

Sistem tepsisi modu

OmniRoute'u sistem tepsisinde başlatın:

omniroute serve --tray

Komut, sunucu ve sistem tepsisi hazır olduktan sonra tamamlanır.

Sunucu, terminal olmadan çalışmaya devam eder.

Sistem tepsisi modu macOS, Windows ve grafiksel Linux oturumlarını destekler. Sistem tepsisi modu kontrol panelini otomatik olarak açmaz.

Şu işlemler için sistem tepsisi menüsünü kullanın:

• Kontrol panelini açma.
• /dashboard/logs sayfasını açma.
• Otomatik başlatma ayarını değiştirme.
• OmniRoute'u durdurma.

--tray seçeneğini şu seçeneklerle birlikte kullanmayın:

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

Bu modlar farklı işlem sahipliği gerektirir.

Bir sonraki makine oturum açılışında başlatmayı etkinleştirin:

omniroute autostart enable

Otomatik başlatma, macOS, Windows ve grafiksel Linux oturumlarında sistem tepsisi modunu kullanır. Başsız Linux, mevcut systemd kullanıcı hizmetini kullanır.

Oturum açılışında başlatmayı devre dışı bırakın:

omniroute autostart disable

Kaldırma

OmniRoute'a artık ihtiyacınız kalmadığında, temiz bir kaldırma işlemi için iki hızlı betik sunuyoruz:

Komut	İşlem
npm run uninstall	Sistem uygulamasını kaldırır ancak ~/.omniroute içindeki veritabanınızı ve yapılandırmalarınızı korur.
npm run uninstall:full	Uygulamayı kaldırır VE tüm yapılandırmaları, anahtarları ve veritabanlarını kalıcı olarak siler.

Not: Bu komutları çalıştırmak için OmniRoute proje klasörüne gidin (projeyi klonladıysanız) ve komutları çalıştırın. Alternatif olarak, global olarak kurduysanız yalnızca npm uninstall -g omniroute komutunu çalıştırabilirsiniz.

VPS Dağıtımı

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

PM2 Dağıtımı (Düşük Bellek)

Sınırlı RAM'e sahip sunucular için bellek sınırı seçeneğini kullanın:

# 512MB sınırıyla (varsayılan)
pm2 start npm --name omniroute -- start

# Veya özel bir bellek sınırıyla
OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start

# Veya ecosystem.config.js kullanarak
pm2 start ecosystem.config.js

ecosystem.config.js dosyasını oluşturun:

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

# İmajı derleyin (varsayılan = codex/claude/droid önceden yüklenmiş runner-cli)
docker build -t omniroute:cli .

# Taşınabilir mod (önerilen)
docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli

CLI ikili dosyalarıyla ana sistemle entegre mod için ana belgelerdeki Docker bölümüne bakın.

Void Linux (xbps-src)

Void Linux kullanıcıları, xbps-src çapraz derleme çerçevesini kullanarak OmniRoute'u yerel olarak paketleyip kurabilir. Bu işlem, gerekli better-sqlite3 yerel bağlamalarıyla birlikte bağımsız Node.js derlemesini otomatikleştirir.

xbps-src şablonunu görüntüle

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

do_build() {
	# node-gyp için hedef CPU mimarisini belirle
	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) Tüm bağımlılıkları kur – betikleri atla
	NODE_ENV=development npm ci --ignore-scripts

	# 2) Bağımsız Next.js paketini derle
	npm run build

	# 3) Statik varlıkları bağımsız pakete kopyala
	cp -r .next/static .next/standalone/.next/static
	[ -d public ] && cp -r public .next/standalone/public || true

	# 4) better-sqlite3 yerel bağlamasını derle
	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) Derlenen bağlamayı bağımsız pakete yerleştir
	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) Mimariye özgü sharp paketlerini kaldır
	rm -rf .next/standalone/node_modules/@img

	# 7) Next.js statik analizinin dahil etmediği pino çalışma zamanı bağımlılıklarını kopyala:
	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

	# Boş Next.js uygulama yönlendiricisi dizinlerinin kurulum sonrası kancası tarafından kaldırılmasını önle
	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
}

Ortam Değişkenleri

Değişken	Varsayılan	Açıklama
JWT_SECRET	omniroute-default-secret-change-me	JWT imzalama gizli anahtarı (üretim ortamında değiştirin)
INITIAL_PASSWORD	CHANGEME	İlk oturum açma parolası
DATA_DIR	~/.omniroute	Veri dizini (veritabanı, kullanım verileri, günlükler)
PORT	framework varsayılanı	Hizmet portu (örneklerde 20128)
HOSTNAME	framework varsayılanı	Bağlanılacak ana makine (Docker varsayılan olarak 0.0.0.0 kullanır)
NODE_ENV	çalışma zamanı varsayılanı	Dağıtım için production olarak ayarlayın
NEXT_PUBLIC_BASE_URL	http://localhost:20128	Kontrol panelinde gösterilen ve sunucuya sağlanan genel temel URL (eski BASE_URL değişkeninin yerini alır)
NEXT_PUBLIC_CLOUD_URL	https://omniroute.dev	Bulut eşitleme uç noktasının temel URL'si (eski CLOUD_URL değişkeninin yerini alır)
API_KEY_SECRET	endpoint-proxy-api-key-secret	Oluşturulan API anahtarları için HMAC gizli anahtarı
REQUIRE_API_KEY	false	/v1/* üzerinde Bearer API anahtarını zorunlu kılar
ALLOW_API_KEY_REVEAL	false	Kimliği doğrulanmış kontrol paneli kullanıcılarının, saklanan API anahtarlarının tam değerlerini isteğe bağlı görmesini sağlar
PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES	70	Önbelleğe alınmış Sağlayıcı Limitleri verilerinin sunucu tarafında yenilenme sıklığı; kullanıcı arayüzündeki yenileme düğmeleri manuel eşitlemeyi yine de tetikler
DISABLE_SQLITE_AUTO_BACKUP	false	Yazma/içe aktarma/geri yükleme öncesindeki otomatik SQLite anlık görüntülerini devre dışı bırakır; manuel yedeklemeler çalışmaya devam eder
APP_LOG_TO_FILE	true	Uygulama ve denetim günlüğü çıktısının diske yazılmasını etkinleştirir
AUTH_COOKIE_SECURE	false	Secure kimlik doğrulama çerezini zorunlu kılar (HTTPS ters proxy arkasında)
CLOUDFLARED_BIN	ayarlanmamış	Yönetilen indirme yerine mevcut bir cloudflared ikili dosyasını kullanır
CLOUDFLARED_PROTOCOL	http2	Yönetilen Hızlı Tüneller için aktarım protokolü (http2, quic veya auto)
OMNIROUTE_MEMORY_MB	512	MB cinsinden Node.js yığın bellek sınırı
PROMPT_CACHE_MAX_SIZE	50	İstem önbelleğindeki azami girdi sayısı
SEMANTIC_CACHE_MAX_SIZE	100	Anlamsal önbellekteki azami girdi sayısı

Ortam değişkenlerinin tam listesi için README dosyasına bakın.

---

📊 Kullanılabilir Modeller

Tüm kullanılabilir modelleri görüntüleyin

Aşağıdaki liste, v3.8.0 için open-sse/config/providerRegistry.ts dosyasından derlenmiştir. Bulut katalogları (Gemini, OpenRouter vb.) dinamik olarak eşitlenir — güncel kataloğun tamamı için Dashboard → Providers → [provider] → Available Models yolunu açın veya GET /api/models/catalog çağrısını yapın.

Bir sağlayıcının yerleşik listesi güncelliğini yitirmişse canlı üst kaynak kataloğunu çekmek için bu sayfadaki Import from /models seçeneğini kullanın (veya Auto-Sync özelliğini etkinleştirin). Bu durum, LLM7.io (gemini-3.1-flash-lite) ve UncloseAI (solidrust/Hermes-3-Llama-3.1-8B-AWQ) için v3.8.50 sürümünde doğrulanmıştır; aynı test sürecinde Pollinations'ın anonim erişimi üst kaynak tarafından kısıtlanmaya devam etmiştir.

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 (+ efor düzeyleri: 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/) — ÜCRETSİZ OAuth: Dashboard → Providers → Kiro → Available Models altında gösterilen canlı kataloğu kullanın. Kullanılabilirlik hesaba ve plana bağlıdır.

Qoder (if/) — ÜCRETSİZ 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/) — Aylık sabit $9 veya kullanım başına ödeme: kimi/kimi-k2.6, kimi/kimi-k2.5

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

Groq (groq/) — Ultra hızlı: 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/) — Yerel Grok: xai/grok-4.3, xai/grok-4.20-multi-agent-0309, xai/grok-4.20-0309-reasoning, xai/grok-4.20-0309-non-reasoning

Mistral (mistral/) — AB'de barındırılır: mistral/mistral-large-latest, mistral/mistral-medium-3-5, mistral/mistral-small-latest, mistral/devstral-latest, mistral/codestral-latest

Perplexity (pplx/) — Aramayla geliştirilmiş: pplx/sonar-deep-research, pplx/sonar-reasoning-pro, pplx/sonar-pro, pplx/sonar

Together AI (together/) — Açık kaynak: together/meta-llama/Llama-3.3-70B-Instruct-Turbo-Free (ücretsiz), 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/) — Hızlı çıkarım: 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/) — Yonga plakası ölçeğinde: cerebras/zai-glm-4.7, cerebras/gpt-oss-120b

Cohere (cohere/) — RAG odaklı: 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/) — Kurumsal: nvidia/z-ai/glm-5.1, nvidia/minimaxai/minimax-m2.7, nvidia/google/gemma-4-31b-it, nvidia/mistralai/mistral-small-4-119b-2603, nvidia/mistralai/mistral-large-3-675b-instruct-2512, nvidia/qwen/qwen3.5-397b-a17b, nvidia/deepseek-ai/deepseek-v4-pro, nvidia/openai/gpt-oss-120b, nvidia/nvidia/nemotron-3-super-120b-a12b

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

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

Gemini (Google Cloud gemini/): Google'dan API anahtarı başına canlı olarak eşitlenir — statik liste yoktur. Dashboard → Providers bölümünde bir anahtar bağlayın, ardından güncel kataloğu içe aktarmak için Available Models seçeneğini kullanın (ör. gemini/gemini-3-pro, gemini/gemini-3-flash).

Diğer uyumlu sağlayıcılar (seçili): cohere, databricks, snowflake, together, vertex, alibaba, alibaba-cn, bedrock (aws-bedrock aracılığıyla), azure-ai, openrouter (doğrudan aktarılan katalog), siliconflow, hyperbolic, huggingface, featherless-ai, cloudflare-ai, scaleway, deepinfra, vercel-ai-gateway, bazaarlink, friendliai, nous-research, reka, volcengine, ai21, gigachat. Her biri providerRegistry.ts içinde kendi model listesini tutar ve sağlayıcı bir /models uç noktası sunduğunda otomatik olarak eşitlenebilir.

Model kimlikleri hakkında not: OmniRoute, sağlayıcıya özgü kimlikleri (claude-opus-4-8, gpt-5.5, glm-5.1, MiniMax-M2.7, kimi-k2.5, grok-4.20-0309-reasoning) kullanır. Bazı kimlikler noktalı sürümler içerir; çünkü üst kaynak API bunları bu biçimde bekler. Bir model yukarıda listelenmiyorsa kullanılabilirliğini doğrulamak için omniroute models --search <term> komutunu çalıştırın veya GET /api/models/catalog uç noktasına istek gönderin.

---

🧩 Gelişmiş Özellikler

Özel Modeller

Uygulama güncellemesini beklemeden herhangi bir sağlayıcıya herhangi bir model kimliği ekleyin:

# API aracılığıyla
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"}'

# Listele: curl http://localhost:20128/api/provider-models?provider=openai
# Kaldır: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-5.2"

Veya Kontrol Panelini kullanın: Sağlayıcılar → [Sağlayıcı] → Özel Modeller.

Notlar:

• OpenRouter ve OpenAI/Anthropic uyumlu sağlayıcılar yalnızca Kullanılabilir Modeller üzerinden yönetilir. Manuel ekleme, içe aktarma ve otomatik eşitlemenin tümü aynı kullanılabilir model listesine eklenir; bu nedenle bu sağlayıcılar için ayrı bir Özel Modeller bölümü yoktur.
• Özel Modeller bölümü, yönetilen kullanılabilir model içe aktarımlarını sunmayan sağlayıcılar içindir.

OmniRoute Eşlerini Zincirleme

Başka bir OmniRoute ağ geçidi, Özel OpenAI uyumlu bir sağlayıcı olarak eklenebilir. Eşin /v1 temel URL'sini ve o eş tarafından verilmiş, yalnızca gerekli yetkilere sahip özel bir API anahtarını kullanın.

Karşılıklı veya çok atlamalı zincirler için her ağ geçidinde isteğe bağlı döngü korumasını etkinleştirin:

# 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

Yalnızca açıkça izin verilenler listesine eklenmiş bir eş URL'sine gönderilen istekler X-OmniRoute-Peer-Trace üst bilgisini alır. Bir ağ geçidi, yinelenen bir örnek kimliğini veya tükenmiş atlama bütçesini HTTP 508 Loop Detected ile reddeder; sıradan yukarı akış sağlayıcıları hiçbir eş meta verisi almaz.

Eş zincirleme, veritabanı çoğaltma veya ana makine yük devretme değildir. Her ağ geçidi bağımsız SQLite durumu, önbellekler, hız sayaçları ve oturumlar tutar. Etkin/pasif veya etkin/etkin kullanılabilirlik için sağlık denetimli bir ters proxy ya da istemci yük devretmesi kullanın ve tek bir SQLite veritabanını asla çalışan birden fazla OmniRoute örneğine bağlamayın.

Özel Sağlayıcı Rotaları

İstekleri model doğrulamasıyla doğrudan belirli bir sağlayıcıya yönlendirin:

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

Eksikse sağlayıcı öneki otomatik olarak eklenir. Eşleşmeyen modeller 400 döndürür.

Ağ Proxy'si Yapılandırması

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

# Sağlayıcı başına proxy
curl -X PUT http://localhost:20128/api/settings/proxy \
  -d '{"providers": {"openai": {"type":"socks5","host":"proxy.example.com","port":"1080"}}}'

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

Öncelik: Anahtara özel → Kombinasyona özel → Sağlayıcıya özel → Genel → Ortam.

Model Kataloğu API'si

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

Sağlayıcıya göre gruplandırılmış modelleri türleriyle (chat, embedding, image) döndürür.

Bulut Eşitleme

• Sağlayıcıları, kombinasyonları ve ayarları cihazlar arasında eşitleyin
• Zaman aşımı ve hızlı hata verme özellikli otomatik arka plan eşitlemesi
• Üretim ortamında sunucu tarafı NEXT_PUBLIC_BASE_URL/NEXT_PUBLIC_CLOUD_URL değerlerini tercih edin

Cloudflare Hızlı Tüneli

• Docker ve diğer kendi sunucunuzda barındırılan dağıtımlar için Kontrol Paneli → Uç Noktalar bölümünde kullanılabilir
• Geçerli OpenAI uyumlu /v1 uç noktanıza yönlendiren geçici bir https://*.trycloudflare.com URL'si oluşturur
• İlk etkinleştirmede cloudflared yalnızca gerektiğinde yüklenir; sonraki yeniden başlatmalarda aynı yönetilen ikili dosya yeniden kullanılır
• Hızlı Tüneller, OmniRoute veya kapsayıcı yeniden başlatıldıktan sonra otomatik olarak geri yüklenmez; gerektiğinde kontrol panelinden yeniden etkinleştirin
• Tünel URL'leri geçicidir ve tüneli her durdurup başlattığınızda değişir
• Yönetilen Hızlı Tüneller, kısıtlı kapsayıcılarda gürültülü QUIC UDP arabellek uyarılarını önlemek için varsayılan olarak HTTP/2 aktarımını kullanır
• Yönetilen aktarım seçimini geçersiz kılmak istiyorsanız CLOUDFLARED_PROTOCOL=quic veya auto olarak ayarlayın
• Yönetilen indirme yerine önceden yüklenmiş bir cloudflared ikili dosyası kullanmayı tercih ediyorsanız CLOUDFLARED_BIN değerini ayarlayın
• Cloudflare Hızlı Tünel, Tailscale Funnel ve ngrok Tünel panelleri Ayarlar → Görünüm bölümünde gösterilebilir veya gizlenebilir. Bir paneli gizlemek, çalışan bir tüneli durdurmaz.

LLM Ağ Geçidi Zekâsı (Aşama 9)

• Anlamsal Önbellek — Akışsız ve temperature=0 olan yanıtları otomatik olarak önbelleğe alır (X-OmniRoute-No-Cache: true ile atlayın)
• İstek Yinelenmesini Önleme — Idempotency-Key veya X-Request-Id üst bilgisi aracılığıyla 5 saniye içindeki istekleri tekilleştirir
• İlerleme Takibi — X-OmniRoute-Progress: true üst bilgisi aracılığıyla isteğe bağlı SSE event: progress olayları sağlar

---

Çevirici Deneme Alanı

Kontrol Paneli → Çevirici üzerinden erişin. OmniRoute'un sağlayıcılar arasındaki API isteklerini nasıl çevirdiğini hata ayıklayın ve görselleştirin.

Mod	Amaç
Deneme Alanı	Kaynak/hedef biçimlerini seçin, bir istek yapıştırın ve çevrilmiş çıktıyı anında görün
Sohbet Testi	Proxy üzerinden canlı sohbet mesajları gönderin ve tüm istek/yanıt döngüsünü inceleyin
Test Tezgâhı	Çevirinin doğruluğunu onaylamak için birden fazla biçim kombinasyonunda toplu testler çalıştırın
Canlı İzleme	İstekler proxy üzerinden akarken gerçek zamanlı çevirileri izleyin

Kullanım alanları:

• Belirli bir istemci/sağlayıcı kombinasyonunun neden başarısız olduğunu hata ayıklayın
• Düşünme etiketlerinin, araç çağrılarının ve sistem istemlerinin doğru çevrildiğini doğrulayın
• OpenAI, Claude, Gemini ve Responses API biçimleri arasındaki biçim farklılıklarını karşılaştırın

---

Yönlendirme Stratejileri

Dashboard → Ayarlar → Yönlendirme üzerinden yapılandırın. Dashboard en çok kullanılan altı stratejiyi gösterir; kombinasyonlar ve otomatik yönlendirici dahili olarak daha geniş bir kümeyi destekler.

Dashboard'da görünen stratejiler (hesap düzeyinde yönlendirme):

Strateji	Açıklama
İlkini Doldur	Hesapları öncelik sırasına göre kullanır — birincil hesap kullanılamaz hâle gelene kadar tüm istekleri işler
Sıralı Döngü	Yapılandırılabilir bir kalıcılık sınırıyla tüm hesaplar arasında sırayla geçiş yapar (varsayılan: hesap başına 3 çağrı)
P2C (İki Seçeneğin Gücü)	Rastgele 2 hesap seçer ve isteği daha sağlıklı olana yönlendirir — sağlık durumunu dikkate alarak yükü dengeler
Rastgele	Fisher-Yates karıştırmasını kullanarak her istek için rastgele bir hesap seçer
En Az Kullanılan	İstekleri en eski lastUsedAt zaman damgasına sahip hesaba yönlendirerek trafiği eşit dağıtır
Maliyet Optimizasyonlu	İstekleri en düşük öncelik değerine sahip hesaba yönlendirerek en düşük maliyetli sağlayıcıları tercih eder

Gelişmiş kombinasyon ve otomatik stratejiler (kombinasyon başına veya auto/* önekleri aracılığıyla yapılandırılabilir — bkz. AUTO-COMBO.md):

• priority — katı sıralama uygular, asla sıralı döngü kullanmaz
• weighted — model başına ağırlıklara göre orantılı trafik dağılımı
• fill-first — sınırlara ulaşılana kadar ilk modeli kullanır
• round-robin / strict-random / random
• p2c (İki Seçeneğin Gücü)
• least-used ve cost-optimized
• auto — tüm adaylar arasında puana dayalı seçim yapar
• lkgp (Son Bilinen İyi Sağlayıcı) — son başarılı sağlayıcıya sabitler, ardından kurallara geri döner
• context-optimized — en geniş boş bağlam penceresine sahip modeli seçer
• context-relay — takip eden turlar için uzun bağlamlı modelleri zincirler

Harici Kalıcı Oturum Başlığı

Harici oturum yakınlığı için (örneğin, ters proxy'lerin arkasındaki Claude Code/Codex aracıları) şunu gönderin:

X-Session-Id: oturum-anahtarınız

OmniRoute ayrıca x_session_id değerini kabul eder ve etkin oturum anahtarını X-OmniRoute-Session-Id içinde döndürür.

Nginx kullanıyor ve alt çizgi biçimli başlıklar gönderiyorsanız şunu etkinleştirin:

underscores_in_headers on;

Joker Karakterli Model Takma Adları

Model adlarını yeniden eşlemek için joker karakterli desenler oluşturun:

Desen: claude-sonnet-*     →  Hedef: cc/claude-sonnet-4-6
Desen: gpt-*               →  Hedef: gh/gpt-5.3-codex

Joker karakterler * (herhangi bir karakter dizisi) ve ? (tek bir karakter) kullanımını destekler.

Geri Dönüş Zincirleri

Tüm isteklere uygulanan genel geri dönüş zincirleri tanımlayın:

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

---

Dayanıklılık ve Devre Kesiciler

Dashboard → Ayarlar → Dayanıklılık üzerinden yapılandırın.

OmniRoute, beş bileşenle sağlayıcı düzeyinde dayanıklılık uygular:

1. İstek Kuyruğu ve Hız Denetimi — Sistem düzeyinde istek biçimlendirme:

   • Dakika Başına İstek (RPM) — Hesap başına dakikadaki maksimum istek sayısı
   • İstekler Arasındaki Minimum Süre — İstekler arasındaki milisaniye cinsinden minimum aralık
   • Maksimum Eşzamanlı İstek — Hesap başına maksimum eşzamanlı istek sayısı

2. Bağlantı Bekleme Süresi — Yeniden denenebilir hatalardan sonra tek bir bağlantı için kimlik doğrulama türü başına yapılandırma:

   • Temel Bekleme Süresi — Yeniden denenebilir üst kaynak hataları için varsayılan bekleme süresi penceresi
   • Üst Kaynağın Yeniden Deneme İpuçlarını Kullan — Sağlandığında yetkili Retry-After veya sıfırlama ipuçlarını dikkate alır
   • Maksimum Geri Çekilme Adımı — Tekrarlanan hatalar için maksimum üstel geri çekilme düzeyi

3. Sağlayıcı Devre Kesicisi — Uçtan uca sağlayıcı hatalarını izler, yapılandırılmış uyarı eşiğinde sağlayıcıyı bozulmuş olarak işaretler ve yapılandırılmış hata eşiğine ulaşıldığında kesiciyi açar:

   • Bozulma Eşiği — DEGRADED durumuna geçmeden önceki ardışık sağlayıcı hatası sayısı
   • Hata Eşiği — OPEN durumuna geçmeden önceki ardışık sağlayıcı hatası sayısı
   • Sıfırlama Zaman Aşımı — Sağlayıcının yeniden test edilmesinden önce geçecek süre
   • CLOSED (Sağlıklı) — İstekler normal şekilde akar
   • DEGRADED — Artan hatalar izlenirken istekler akmaya devam eder
   • OPEN — Tekrarlanan hatalardan sonra sağlayıcı geçici olarak engellenir
   • HALF_OPEN — Sağlayıcının düzelip düzelmediği test edilir

   Bağlantı kapsamındaki 429 hız sınırları Bağlantı Bekleme Süresi kapsamında kalır ve sağlayıcı devre kesicisine dâhil edilmez.

   Sağlayıcı devre kesicisinin çalışma zamanı durumu yalnızca Dashboard → Sağlık bölümünde gösterilir.

4. Bekleme Süresini Bekle — Tüm aday bağlantılar zaten bekleme süresindeyse OmniRoute, en erken sona erecek bekleme süresini bekleyebilir ve aynı istemci isteğini otomatik olarak yeniden deneyebilir.

5. Hız Sınırını Otomatik Algılama — Üst kaynak sağlayıcılar açık bekleme pencereleri döndürdüğünde ve ayar etkinleştirildiğinde bu ipuçları yerel bağlantı bekleme süresini geçersiz kılar.

Uzman İpucu: Bir kesintiden sonra etkin sağlayıcı devre kesicilerini incelemek ve sıfırlamak için Sağlık sayfasını kullanın. Dayanıklılık sayfası yalnızca yapılandırmayı değiştirir.

---

Veritabanını Dışa / İçe Aktarma

Veritabanı yedeklerini Dashboard → Ayarlar → Sistem ve Depolama bölümünden yönetin.

Eylem	Açıklama
Veritabanını Dışa Aktar	Geçerli SQLite veritabanını bir .sqlite dosyası olarak indirir
Tümünü Dışa Aktar (.tar.gz)	Şunları içeren tam bir yedekleme arşivi indirir: veritabanı, ayarlar, kombinasyonlar, sağlayıcı bağlantıları (kimlik bilgileri olmadan), API anahtarı meta verileri
Veritabanını İçe Aktar	Geçerli veritabanını değiştirmek için bir .sqlite dosyası yükler. DISABLE_SQLITE_AUTO_BACKUP=true olmadığı sürece içe aktarma öncesinde otomatik olarak bir yedek oluşturulur

# API: Veritabanını dışa aktar
curl -o backup.sqlite http://localhost:20128/api/db-backups/export

# API: Tümünü dışa aktar (tam arşiv)
curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll

# API: Veritabanını içe aktar
curl -X POST http://localhost:20128/api/db-backups/import \
  -F "file=@backup.sqlite"

İçe Aktarma Doğrulaması: İçe aktarılan dosyanın bütünlüğü (SQLite pragma denetimi), gerekli tabloları (provider_connections, provider_nodes, combos, api_keys) ve boyutu (en fazla 100 MB) doğrulanır.

Kullanım Alanları:

• OmniRoute'u makineler arasında taşıma
• Olağanüstü durum kurtarma için harici yedekler oluşturma
• Yapılandırmaları ekip üyeleri arasında paylaşma (tümünü dışa aktar → arşivi paylaş)

---

Ayarlar Panosu

Ayarlar sayfası, kolay gezinme amacıyla 7 sekme hâlinde düzenlenmiştir:

Sekme	İçerik
Genel	Sistem depolama araçları, varsayılan davranış, uç nokta tüneli görünürlüğü
Görünüm	Tema denetimleri (açık/koyu/sistem), kenar çubuğu görünürlüğü, Cloudflare/Tailscale/ngrok tünel kartlarına yönelik panel geçişleri
Yapay Zekâ	Düşünme bütçesi (değiştirmeden iletme / otomatik çıkarma / özel / uyarlanabilir — bkz. THINKING_BUDGET.md), genel sistem istemi, istem önbelleği istatistikleri
Güvenlik	Oturum açma/parola ayarları, IP erişim denetimi, /models için API kimlik doğrulaması, sağlayıcı engelleme, istem enjeksiyonu koruması
Yönlendirme	Genel yönlendirme stratejisi (Önce Doldur / Döngüsel / P2C / Rastgele / En Az Kullanılan / Maliyet Optimizasyonlu), joker karakterli model takma adları, geri dönüş zincirleri, varsayılan kombinasyon ayarları
Dayanıklılık	İstek kuyruğu, bağlantı bekleme süresi, sağlayıcı devre kesici yapılandırması ve bekleme süresinin dolmasını bekleme davranışı
Gelişmiş	Genel proxy yapılandırması (HTTP/SOCKS5), sağlayıcı başına proxy geçersiz kılmaları

Genel sekmesi artık salt okunur günlük kaydı ve önbellek notlarını yinelemez. Veritabanı saklama ve optimizasyon ayarları /api/settings/database aracılığıyla kalıcı hâle getirilir; önbelleğin manuel olarak temizlenmesi için DELETE /api/cache kullanılır. İstek ve proxy günlüklerindeki satır sınırları CALL_LOGS_TABLE_MAX_ROWS ve PROXY_LOGS_TABLE_MAX_ROWS tarafından denetlenir.

---

Maliyet ve Bütçe Yönetimi

Pano → Maliyetler üzerinden erişin.

Sekme	Amaç
Bütçe	Günlük/haftalık/aylık bütçeler ve gerçek zamanlı izleme ile her API anahtarı için harcama sınırları belirleyin
Fiyatlandırma	Model fiyatlandırma kayıtlarını görüntüleyin ve düzenleyin — sağlayıcı başına her 1K giriş/çıkış token'ının maliyeti

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

# API: Geçerli bütçe durumunu al
curl http://localhost:20128/api/usage/budget

Maliyet Takibi: Her istek, token kullanımını günlüğe kaydeder ve fiyatlandırma tablosunu kullanarak maliyeti hesaplar. Sağlayıcı, model ve API anahtarına göre dökümleri Pano → Kullanım bölümünde görüntüleyin.

---

Ses Transkripsiyonu

OmniRoute, OpenAI uyumlu uç nokta üzerinden ses transkripsiyonunu destekler:

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

# curl ile örnek
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, yerel Deepgram rotasıdır ve bir Deepgram API anahtarı gerektirir. Yalnızca OpenRouter yapılandırılmışsa openrouter/deepgram/nova-3 kullanın.

Konuşmadan Metne (transkripsiyon) sağlayıcıları:

• openai/ (whisper uyumlu)
• groq/ (Groq Whisper Turbo)
• deepgram/ (Nova ailesi)
• assemblyai/
• nvidia/ (Parakeet, Canary)
• huggingface/ (whisper varyantları)
• qwen/

Metinden Konuşmaya (POST /v1/audio/speech) sağlayıcıları:

• 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/

Transkripsiyon için desteklenen ses biçimleri: mp3, wav, m4a, flac, ogg, webm. TTS çıktı biçimleri sağlayıcıya bağlıdır (mp3, wav, opus, pcm, mulaw).

---

Kombinasyon Dengeleme Stratejileri

Kombinasyon başına dengeleme ayarlarını Pano → Kombinasyonlar → Oluştur/Düzenle → Strateji bölümünde yapılandırın.

Strateji	Açıklama
Round-Robin	Modeller arasında sırayla geçiş yapar
Öncelik	Her zaman ilk modeli dener; yalnızca hata durumunda diğer modele geçer
Rastgele	Her istek için kombinasyondan rastgele bir model seçer
Ağırlıklı	Model başına atanan ağırlıklara göre orantılı olarak yönlendirir
En Az Kullanılan	En az yakın tarihli isteğe sahip modele yönlendirir (kombinasyon metriklerini kullanır)
Maliyet Odaklı	Kullanılabilir en ucuz modele yönlendirir (fiyatlandırma tablosunu kullanır)

Genel kombinasyon varsayılanları Dashboard → Settings → Routing → Combo Defaults bölümünden ayarlanabilir. Kombinasyon hedefi zaman aşımları, varsayılan olarak geçerli istek zaman aşımını devralır. Yalnızca hedef başına daha kısa bir sınırın diğer hedefe daha hızlı geçişi tetiklemesi gerektiğinde, kombinasyon varsayılanlarında veya tek bir kombinasyonda Target timeout (seconds) seçeneğini kullanın.

Sıfır gecikmeli kombinasyon optimizasyonları isteğe bağlıdır. Bu gecikme özelliklerinin alternatif hedefleri eş zamanlı denemesini, TTFT geçmişine göre hedefleri atlamasını veya alternatif istekleri sıkıştırmasını önlemek için Zero-latency optimizations seçeneğini devre dışı bırakın; etkinleştirildiğinde, yapılandırılmış korumalı isteklerin, tahmine dayalı TTFT atlamalarının ve proaktif alternatif sıkıştırmanın daha düşük kuyruk gecikmesi karşılığında yönlendirme/istek doğruluğundan ödün vermesine izin verilir.

Üst sağlayıcılar katı max_tokens / maxOutputTokens sınırları gerektirdiğinde Reasoning token buffer seçeneğini devre dışı bırakın. Etkinleştirildiğinde kombinasyon yönlendirmesi, yalnızca bilinen bir çıktı sınırı olan modeller için muhakeme modeli ek kapasitesi ekler ve güvenli tamponlu değer bu sınırı aşacaksa istemci belirteç sınırını değiştirmez. İstemci sınırı zaten bilinen bir sınırın üzerindeyse OmniRoute, isteği üst sağlayıcıya göndermeden önce bu değeri söz konusu sınıra düşürür.

---

Sistem Durumu Panosu

Dashboard → Health üzerinden erişin. 6 karttan oluşan gerçek zamanlı sistem durumu genel görünümü:

Kart	Gösterdiği Bilgiler
Sistem Durumu	Çalışma süresi, sürüm, bellek kullanımı, veri dizini
Sağlayıcı Durumu	Genel sağlayıcı devre kesicisinin çalışma zamanı durumu
Hız Sınırları	Hesap başına etkin bağlantı bekleme süreleri ve kalan süre
Etkin Kilitlemeler	Etkin model kapsamlı kilitlemeler ve geçici hariç tutmalar
İmza Önbelleği	Yinelenenleri kaldırma önbelleği istatistikleri (etkin anahtarlar, isabet oranı)
Gecikme Telemetrisi	Sağlayıcı başına p50/p95/p99 gecikme toplulaştırması

Uzman İpucu: Sistem Durumu sayfası her 10 saniyede bir otomatik olarak yenilenir. Hangi sağlayıcıların sorun yaşadığını belirlemek için devre kesici kartını kullanın.

---

🤖 Otomatik Yönlendirme (Sıfır yapılandırma)

OmniRoute, bağlı tüm sağlayıcılar arasından her istek için en iyi modeli seçen puan odaklı bir otomatik yönlendiriciyle birlikte gelir — yönetilmesi gereken bir kombinasyon yoktur. İsteği auto/* öneklerinden biriyle göndermeniz yeterlidir; OmniRoute gecikme süresi, maliyet, başarı oranı, bağlam uyumu, modelin göreve uygunluğu, son hatalar, kota ve devre kesici durumuna göre adayları puanlayarak anında sanal bir kombinasyon oluşturur.

Önek	Optimizasyon hedefi
auto	Dengeli varsayılan (gecikme × maliyet × başarı oranı)
auto/coding	Kodlama görevleri: Claude, GPT-5, GLM, Kimi, Qwen Coder ve DeepSeek kodlama modellerini tercih eder
auto/cheap	En düşük $/token, daha yüksek gecikmeyi kabul eder
auto/fast	En düşük gecikme, maliyeti dikkate almaz
auto/offline	Yalnızca yerel sağlayıcılar (Ollama, vLLM, llama.cpp) — ağdan yalıtılmış kurulumlar için kullanışlıdır
auto/smart	Öncelik akıl yürütme kalitesindedir (Opus, GPT-5 xhigh, R1, GLM 5.1 reasoning)
auto/lkgp	"Bilinen Son İyi Sağlayıcı" — son başarılı sağlayıcıya sabitlenir, ardından kurallara geri döner

Örnek:

curl -X POST http://localhost:20128/v1/chat/completions \
  -H "Authorization: Bearer $OMNIROUTE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto/coding",
    "messages": [{ "role": "user", "content": "Refactor this Python function" }],
    "stream": true
  }'

Otomatik yönlendirici; puanlama ağırlıklarının nasıl ayarlanacağı, sağlayıcıların nasıl kara listeye alınacağı ve yönlendirme kararlarının Dashboard → Auto Combo bölümünde nasıl inceleneceği dâhil olmak üzere AUTO-COMBO.md dosyasında ayrıntılı olarak açıklanmaktadır.

---

🔌 MCP ve A2A Entegrasyonu

OmniRoute hem bir MCP sunucusudur (Model Context Protocol) hem de bir A2A sunucusudur (Agent-to-Agent JSON-RPC 2.0). MCP uyumlu herhangi bir IDE veya aracı ana makinesi, OmniRoute araçlarını doğrudan çağırabilir — ek bir sarmalayıcı gerekmez.

MCP aktarımları

• SSE: http://localhost:20128/api/mcp/sse
• Akışlı HTTP: http://localhost:20128/api/mcp/stream
• stdio: omniroute --mcp (stdio tercih eden IDE eklentileri için)

Claude Desktop'ı bağlama

macOS'ta ~/Library/Application Support/Claude/claude_desktop_config.json dosyasını veya Windows/Linux'taki eşdeğerini düzenleyin:

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

Cursor / Continue / VS Code MCP'yi bağlama

http://localhost:20128/api/mcp/sse SSE URL'sini ve Dashboard → API Keys bölümünde oluşturulan bir Bearer API anahtarını kullanın.

Kapsamlar

MCP şu anda 32 adlandırılmış kapsam tanımlar. Her Bearer anahtarı belirli kapsamlarla sınırlandırılabilir — kapsamların ve araçların kesin listesi için MCP-SERVER.md, JSON-RPC şeması içinse A2A-SERVER.md dosyasına bakın.

---

🧠 Beceri Sistemi

OmniRoute, ajanların ve A2A uç noktasının alana özgü rutinleri (ör. code-review, summarize, extract-facts, web-research) çalıştırabilmesi için genişletilebilir bir beceri çerçevesi (src/lib/skills/) sunar.

• Pazar Yeri Arayüzü — Panel → Beceriler bölümünden becerilere göz atın ve bunları yükleyin
• Anahtar başına kapsamlar — Hangi API anahtarlarının hangi becerileri çağırabileceğini kısıtlayın
• Özel beceriler — src/lib/a2a/skills/ dizinine bir TypeScript dosyası ekleyip kaydedin; beceri A2A üzerinden hemen çağrılabilir hâle gelir

Tam referans: SKILLS.md.

---

💾 Bellek Sistemi

OmniRoute, hibrit erişimle uzun süreli konuşma belleğini kalıcı olarak saklar:

• Geçmiş konuşma sıralarında anahtar kelime araması için SQLite FTS5
• Anlamsal hatırlama için Qdrant vektör deposu (isteğe bağlı)
• Otomatik olgu çıkarımı — varlıklar, tercihler ve kararlar her oturumdan sonra özetlenerek memory_facts tablosunda saklanır
• Bellekler API anahtarı ve oturum bazında kapsamlandırılır

Bellekleri Panel → Bellek bölümünden yönetin (arama, düzenleme, dışa aktarma, temizleme). HTTP arayüzü (/api/memory/*), ajanların olguları programatik olarak göndermesine ve sorgulamasına olanak tanır — bkz. MEMORY.md.

---

🔔 Webhook'lar

Gerçek zamanlı izleme ve otomasyon için OmniRoute olaylarına abone olun.

• Hedef URL ve HMAC imzalama gizli anahtarıyla Panel → Webhook'lar bölümünde bir webhook oluşturun
• Kullanılabilir olaylar: request.completed, request.failed, provider.unavailable, budget.exceeded, combo.switched, circuit_breaker.opened, circuit_breaker.closed
• Her yük, doğrulama için X-OmniRoute-Signature (HMAC-SHA256) içerir
• Yeniden denemeler: üstel geri çekilme ile 3 deneme, ardından teslim edilemeyen iletiler kuyruğu

Şemanın tamamı için bkz. WEBHOOKS.md.

---

☁️ Bulut Ajanları

OmniRoute, uzun süreli görevleri yerel yönlendirmenizi yönettiğiniz aynı panelden gönderebilmeniz için bulut kodlama ajanlarıyla (OpenAI Codex Cloud, Devin, Jules, Antigravity) entegre olur.

• Panel → Bulut Ajanları bölümünden veya POST /api/v1/agents/tasks aracılığıyla görevler oluşturun
• Her görev için durumu, günlükleri ve çıktıları takip edin
• Her sağlayıcı için kendi API anahtarınızı kullanın — kimlik bilgileri OmniRoute örneğinden asla ayrılmaz

Tam referans: CLOUD_AGENT.md.

---

🛠️ Programatik Yönetim

Her OmniRoute kaynağını (sağlayıcılar, kombinasyonlar, anahtarlar, ayarlar) manage kapsamına sahip bir Bearer anahtarı kullanarak HTTP üzerinden yönetebilirsiniz.

Anahtarı Panel → API Anahtarları → Yeni Anahtar → Kapsam: manage bölümünden oluşturun, ardından:

# Sağlayıcıları listele
curl http://localhost:20128/api/providers \
  -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY"

# Sağlayıcı bağlantısı ekle
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" }'

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

# API anahtarlarını listele/oluştur
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"] }'

Uç noktaların tam kataloğu ve istek/yanıt şemaları için API_REFERENCE.md dosyasına bakın.

---

💻 Dahili CLI

OmniRoute; kurulum, tanılama ve çalışma zamanı denetimi için dahili bir CLI (omniroute …) ile birlikte gelir. Bu, üçüncü taraf CLI'ları (Claude Code, Cursor, Codex, Cline, …) OmniRoute ile iletişim kurabilecek şekilde yapılandıran panodaki "CLI Araçları" sayfasından ayrıdır.

omniroute setup                    # Etkileşimli sihirbaz (parola, sağlayıcılar, kombinasyonlar)
omniroute setup --non-interactive  # CI kullanımına uygun
omniroute doctor                   # Sistem durumu tanılaması (veri dizini, DB, sağlayıcılar, portlar)
omniroute providers available      # Desteklenen sağlayıcıları listele
omniroute providers list           # Yapılandırılmış bağlantıları listele
omniroute providers test <id>      # Bir sağlayıcı bağlantısını canlı olarak test et
omniroute combos list              # Kombinasyonları listele
omniroute combos switch <name>     # Varsayılan kombinasyonu ayarla
omniroute models                   # Kullanılabilir modelleri listele (--json, --search)
omniroute keys add | list | remove # API anahtarlarını terminalden yönet
omniroute backup                   # Yapılandırmanın ve DB'nin anlık görüntüsünü al
omniroute restore [<timestamp>]    # Bir anlık görüntüden geri yükle
omniroute health                   # Ayrıntılı sistem durumu (devre kesiciler, önbellek, bellek)
omniroute quota                    # Sağlayıcı kota kullanımı
omniroute mcp status               # MCP sunucusu durumu
omniroute a2a status               # A2A sunucusu durumu
omniroute tunnel list|create|stop  # Cloudflare/Tailscale/ngrok tünelleri
omniroute reset-password           # Yönetici parolasını sıfırla
omniroute --mcp                    # MCP sunucusunu stdio üzerinden başlat
omniroute --port 3000              # Sunucuyu özel bir portta başlat

İpucu: Sağlıksız sağlayıcı bağlantıları için uyarı almak üzere omniroute doctor --json komutunu izleme aracınızla birlikte kullanın.

---

🖥️ Masaüstü Uygulaması (Electron)

OmniRoute; Windows, macOS ve Linux için yerel bir masaüstü uygulaması olarak sunulur.

Kurulum

# electron dizininden:
cd electron
npm install

# Geliştirme modu (çalışan Next.js geliştirme sunucusuna bağlanır):
npm run dev

# Üretim modu (bağımsız derlemeyi kullanır):
npm start

Yükleyicileri Derleme

cd electron
npm run build          # Geçerli platform
npm run build:win      # Windows (.exe NSIS)
npm run build:mac      # macOS (.dmg evrensel)
npm run build:linux    # Linux (.AppImage)

Çıktı → electron/dist-electron/

Temel Özellikler

Özellik	Açıklama
Sunucu Hazırlığı	Pencereyi göstermeden önce sunucuyu yoklar (boş ekran göstermez)
Sistem Tepsisi	Tepsiye küçültme, port değiştirme, tepsi menüsünden çıkış
Port Yönetimi	Sunucu portunu tepsiden değiştirme (sunucuyu otomatik başlatır)
İçerik Güvenliği İlkesi	Oturum üstbilgileri aracılığıyla kısıtlayıcı CSP
Tek Örnek	Aynı anda yalnızca bir uygulama örneği çalışabilir
Çevrimdışı Mod	Paketlenmiş Next.js sunucusu internet olmadan çalışır

Ortam Değişkenleri

Değişken	Varsayılan	Açıklama
OMNIROUTE_PORT	20128	Sunucu portu
OMNIROUTE_MEMORY_MB	512	Node.js yığın sınırı (64–16384 MB)

📖 Tam dokümantasyon: electron/README.md