# User Guide (Slovenčina)
🌐 **Languages:** 🇺🇸 [English](../../../../guides/USER_GUIDE.md) · 🇪🇹 [am](../../../am/docs/guides/USER_GUIDE.md) · 🇸🇦 [ar](../../../ar/docs/guides/USER_GUIDE.md) · 🇦🇿 [az](../../../az/docs/guides/USER_GUIDE.md) · 🇧🇬 [bg](../../../bg/docs/guides/USER_GUIDE.md) · 🇧🇩 [bn](../../../bn/docs/guides/USER_GUIDE.md) · 🇧🇦 [bs](../../../bs/docs/guides/USER_GUIDE.md) · 🇨🇿 [cs](../../../cs/docs/guides/USER_GUIDE.md) · 🇩🇰 [da](../../../da/docs/guides/USER_GUIDE.md) · 🇩🇪 [de](../../../de/docs/guides/USER_GUIDE.md) · 🇬🇷 [el](../../../el/docs/guides/USER_GUIDE.md) · 🇪🇸 [es](../../../es/docs/guides/USER_GUIDE.md) · 🇪🇪 [et](../../../et/docs/guides/USER_GUIDE.md) · 🇮🇷 [fa](../../../fa/docs/guides/USER_GUIDE.md) · 🇫🇮 [fi](../../../fi/docs/guides/USER_GUIDE.md) · 🇫🇷 [fr](../../../fr/docs/guides/USER_GUIDE.md) · 🇮🇪 [ga](../../../ga/docs/guides/USER_GUIDE.md) · 🇮🇳 [gu](../../../gu/docs/guides/USER_GUIDE.md) · 🇳🇬 [ha](../../../ha/docs/guides/USER_GUIDE.md) · 🇮🇱 [he](../../../he/docs/guides/USER_GUIDE.md) · 🇮🇳 [hi](../../../hi/docs/guides/USER_GUIDE.md) · 🇭🇷 [hr](../../../hr/docs/guides/USER_GUIDE.md) · 🇭🇺 [hu](../../../hu/docs/guides/USER_GUIDE.md) · 🇦🇲 [hy](../../../hy/docs/guides/USER_GUIDE.md) · 🇮🇩 [id](../../../id/docs/guides/USER_GUIDE.md) · 🇳🇬 [ig](../../../ig/docs/guides/USER_GUIDE.md) · 🇮🇹 [it](../../../it/docs/guides/USER_GUIDE.md) · 🇯🇵 [ja](../../../ja/docs/guides/USER_GUIDE.md) · 🇬🇪 [ka](../../../ka/docs/guides/USER_GUIDE.md) · 🇰🇭 [km](../../../km/docs/guides/USER_GUIDE.md) · 🇮🇳 [kn](../../../kn/docs/guides/USER_GUIDE.md) · 🇰🇷 [ko](../../../ko/docs/guides/USER_GUIDE.md) · 🇱🇹 [lt](../../../lt/docs/guides/USER_GUIDE.md) · 🇱🇻 [lv](../../../lv/docs/guides/USER_GUIDE.md) · 🇮🇳 [ml](../../../ml/docs/guides/USER_GUIDE.md) · 🇮🇳 [mr](../../../mr/docs/guides/USER_GUIDE.md) · 🇲🇾 [ms](../../../ms/docs/guides/USER_GUIDE.md) · 🇲🇹 [mt](../../../mt/docs/guides/USER_GUIDE.md) · 🇲🇲 [my](../../../my/docs/guides/USER_GUIDE.md) · 🇳🇵 [ne](../../../ne/docs/guides/USER_GUIDE.md) · 🇳🇱 [nl](../../../nl/docs/guides/USER_GUIDE.md) · 🇳🇴 [no](../../../no/docs/guides/USER_GUIDE.md) · 🇮🇳 [or](../../../or/docs/guides/USER_GUIDE.md) · 🇮🇳 [pa](../../../pa/docs/guides/USER_GUIDE.md) · 🇵🇭 [phi](../../../phi/docs/guides/USER_GUIDE.md) · 🇵🇱 [pl](../../../pl/docs/guides/USER_GUIDE.md) · 🇵🇹 [pt](../../../pt/docs/guides/USER_GUIDE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/guides/USER_GUIDE.md) · 🇷🇴 [ro](../../../ro/docs/guides/USER_GUIDE.md) · 🇷🇺 [ru](../../../ru/docs/guides/USER_GUIDE.md) · 🇱🇰 [si](../../../si/docs/guides/USER_GUIDE.md) · 🇸🇮 [sl](../../../sl/docs/guides/USER_GUIDE.md) · 🇷🇸 [sr](../../../sr/docs/guides/USER_GUIDE.md) · 🇸🇪 [sv](../../../sv/docs/guides/USER_GUIDE.md) · 🇰🇪 [sw](../../../sw/docs/guides/USER_GUIDE.md) · 🇮🇳 [ta](../../../ta/docs/guides/USER_GUIDE.md) · 🇮🇳 [te](../../../te/docs/guides/USER_GUIDE.md) · 🇹🇭 [th](../../../th/docs/guides/USER_GUIDE.md) · 🇹🇷 [tr](../../../tr/docs/guides/USER_GUIDE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/guides/USER_GUIDE.md) · 🇵🇰 [ur](../../../ur/docs/guides/USER_GUIDE.md) · 🇺🇿 [uz](../../../uz/docs/guides/USER_GUIDE.md) · 🇻🇳 [vi](../../../vi/docs/guides/USER_GUIDE.md) · 🇳🇬 [yo](../../../yo/docs/guides/USER_GUIDE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/guides/USER_GUIDE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/guides/USER_GUIDE.md)
---
🌐 **Languages:** 🇺🇸 [English](../../../../guides/USER_GUIDE.md) · 🇪🇹 [am](../../../am/docs/guides/USER_GUIDE.md) · 🇸🇦 [ar](../../../ar/docs/guides/USER_GUIDE.md) · 🇦🇿 [az](../../../az/docs/guides/USER_GUIDE.md) · 🇧🇬 [bg](../../../bg/docs/guides/USER_GUIDE.md) · 🇧🇩 [bn](../../../bn/docs/guides/USER_GUIDE.md) · 🇧🇦 [bs](../../../bs/docs/guides/USER_GUIDE.md) · 🇨🇿 [cs](../../../cs/docs/guides/USER_GUIDE.md) · 🇩🇰 [da](../../../da/docs/guides/USER_GUIDE.md) · 🇩🇪 [de](../../../de/docs/guides/USER_GUIDE.md) · 🇬🇷 [el](../../../el/docs/guides/USER_GUIDE.md) · 🇪🇸 [es](../../../es/docs/guides/USER_GUIDE.md) · 🇪🇪 [et](../../../et/docs/guides/USER_GUIDE.md) · 🇮🇷 [fa](../../../fa/docs/guides/USER_GUIDE.md) · 🇫🇮 [fi](../../../fi/docs/guides/USER_GUIDE.md) · 🇫🇷 [fr](../../../fr/docs/guides/USER_GUIDE.md) · 🇮🇪 [ga](../../../ga/docs/guides/USER_GUIDE.md) · 🇮🇳 [gu](../../../gu/docs/guides/USER_GUIDE.md) · 🇳🇬 [ha](../../../ha/docs/guides/USER_GUIDE.md) · 🇮🇱 [he](../../../he/docs/guides/USER_GUIDE.md) · 🇮🇳 [hi](../../../hi/docs/guides/USER_GUIDE.md) · 🇭🇷 [hr](../../../hr/docs/guides/USER_GUIDE.md) · 🇭🇺 [hu](../../../hu/docs/guides/USER_GUIDE.md) · 🇦🇲 [hy](../../../hy/docs/guides/USER_GUIDE.md) · 🇮🇩 [id](../../../id/docs/guides/USER_GUIDE.md) · 🇳🇬 [ig](../../../ig/docs/guides/USER_GUIDE.md) · 🇮🇹 [it](../../../it/docs/guides/USER_GUIDE.md) · 🇯🇵 [ja](../../../ja/docs/guides/USER_GUIDE.md) · 🇬🇪 [ka](../../../ka/docs/guides/USER_GUIDE.md) · 🇰🇭 [km](../../../km/docs/guides/USER_GUIDE.md) · 🇮🇳 [kn](../../../kn/docs/guides/USER_GUIDE.md) · 🇰🇷 [ko](../../../ko/docs/guides/USER_GUIDE.md) · 🇱🇹 [lt](../../../lt/docs/guides/USER_GUIDE.md) · 🇱🇻 [lv](../../../lv/docs/guides/USER_GUIDE.md) · 🇮🇳 [ml](../../../ml/docs/guides/USER_GUIDE.md) · 🇮🇳 [mr](../../../mr/docs/guides/USER_GUIDE.md) · 🇲🇾 [ms](../../../ms/docs/guides/USER_GUIDE.md) · 🇲🇹 [mt](../../../mt/docs/guides/USER_GUIDE.md) · 🇲🇲 [my](../../../my/docs/guides/USER_GUIDE.md) · 🇳🇵 [ne](../../../ne/docs/guides/USER_GUIDE.md) · 🇳🇱 [nl](../../../nl/docs/guides/USER_GUIDE.md) · 🇳🇴 [no](../../../no/docs/guides/USER_GUIDE.md) · 🇮🇳 [or](../../../or/docs/guides/USER_GUIDE.md) · 🇮🇳 [pa](../../../pa/docs/guides/USER_GUIDE.md) · 🇵🇭 [phi](../../../phi/docs/guides/USER_GUIDE.md) · 🇵🇱 [pl](../../../pl/docs/guides/USER_GUIDE.md) · 🇵🇹 [pt](../../../pt/docs/guides/USER_GUIDE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/guides/USER_GUIDE.md) · 🇷🇴 [ro](../../../ro/docs/guides/USER_GUIDE.md) · 🇷🇺 [ru](../../../ru/docs/guides/USER_GUIDE.md) · 🇱🇰 [si](../../../si/docs/guides/USER_GUIDE.md) · 🇸🇮 [sl](../../../sl/docs/guides/USER_GUIDE.md) · 🇷🇸 [sr](../../../sr/docs/guides/USER_GUIDE.md) · 🇸🇪 [sv](../../../sv/docs/guides/USER_GUIDE.md) · 🇰🇪 [sw](../../../sw/docs/guides/USER_GUIDE.md) · 🇮🇳 [ta](../../../ta/docs/guides/USER_GUIDE.md) · 🇮🇳 [te](../../../te/docs/guides/USER_GUIDE.md) · 🇹🇭 [th](../../../th/docs/guides/USER_GUIDE.md) · 🇹🇷 [tr](../../../tr/docs/guides/USER_GUIDE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/guides/USER_GUIDE.md) · 🇵🇰 [ur](../../../ur/docs/guides/USER_GUIDE.md) · 🇺🇿 [uz](../../../uz/docs/guides/USER_GUIDE.md) · 🇻🇳 [vi](../../../vi/docs/guides/USER_GUIDE.md) · 🇳🇬 [yo](../../../yo/docs/guides/USER_GUIDE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/guides/USER_GUIDE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/guides/USER_GUIDE.md)
Kompletná príručka ku konfigurácii poskytovateľov, vytváraniu kombinácií, integrácii nástrojov CLI a nasadeniu OmniRoute.
---
## Obsah
- [Prehľad cien](#-pricing-at-a-glance)
- [Prípady použitia](#-use-cases)
- [Nastavenie poskytovateľa](#-provider-setup)
- [Integrácia CLI](#-cli-integration)
- [Nasadenie](#-deployment)
- [Dostupné modely](#-available-models)
- [Pokročilé funkcie](#-advanced-features)
- [Automatické smerovanie (bez konfigurácie)](#-auto-routing-zero-config)
- [Integrácia MCP a A2A](#-mcp--a2a-integration)
- [Systém zručností](#-skills-system)
- [Pamäťový systém](#-memory-system)
- [Webhooky](#-webhooks)
- [Cloudoví agenti](#-cloud-agents)
- [Programová správa](#-programmatic-management)
- [Interné CLI](#-internal-cli)
- [Desktopová aplikácia (Electron)](#-desktop-application-electron)
---
## 💰 Prehľad cien
| Úroveň | Poskytovateľ | Cena | Obnovenie kvóty | Najvhodnejšie pre |
| ----------------- | ----------------- | --------------------- | --------------------------- | ---------------------------------- |
| **💳 PREDPLATNÉ** | Claude Code (Pro) | $20/mes. | 5 hod. + týždenne | Používatelia s predplatným |
| | Codex (Plus/Pro) | $20-200/mes. | 5 hod. + týždenne | Používatelia OpenAI |
| | GitHub Copilot | $10-19/mes. | Mesačne | Používatelia GitHubu |
| **🔑 API KĽÚČ** | DeepSeek | Platba podľa využitia | Žiadne | Lacné uvažovanie |
| | Groq | Platba podľa využitia | Žiadne | Mimoriadne rýchle odvodzovanie |
| | xAI (Grok) | Platba podľa využitia | Žiadne | Uvažovanie s Grok 4 |
| | Mistral | Platba podľa využitia | Žiadne | Modely hostované v EÚ |
| | Perplexity | Platba podľa využitia | Žiadne | Rozšírenie o vyhľadávanie |
| | Together AI | Platba podľa využitia | Žiadne | Modely s otvoreným zdrojovým kódom |
| | Fireworks AI | Platba podľa využitia | Žiadne | Rýchle obrázky FLUX |
| | Cerebras | Platba podľa využitia | Žiadne | Rýchlosť na úrovni celého waferu |
| | Cohere | Platba podľa využitia | Žiadne | Command R+ RAG |
| | NVIDIA NIM | Platba podľa využitia | Žiadne | Podnikové modely |
| | Baidu Qianfan | Platba podľa využitia | Žiadne | Modely ERNIE |
| **💰 LACNÉ** | GLM-4.7 | $0.6/1M | Denne o 10:00 | Lacná záloha |
| | MiniMax M2.1 | $0.2/1M | Priebežne každých 5 hodín | Najlacnejšia možnosť |
| | Kimi K2 | Paušálne $9/mes. | 10M tokenov/mes. | Predvídateľné náklady |
| **🆓 ZADARMO** | Qoder | $0 | Platia limity poskytovateľa | Overte aktuálny katalóg |
| | Kiro | $0 | ~50 kreditov/mes. | Claude zadarmo |
---
## 🎯 Prípady použitia
### Prípad 1: „Mám predplatné Claude Pro“
**Problém:** Kvóta vyprší nevyužitá, pri intenzívnom programovaní sa uplatňujú obmedzenia rýchlosti
```
Kombinácia: "maximize-claude"
1. cc/claude-opus-4-7 (plné využitie predplatného)
2. glm/glm-4.7 (lacná záloha po vyčerpaní kvóty)
3. if/qwen3.8-max-preview (bezplatná núdzová záložná možnosť)
Mesačné náklady: $20 (predplatné) + ~$5 (záloha) = spolu $25
oproti $20 + dosiahnutie limitov = frustrácia
```
### Prípad 2: „Nechcem platiť nič“
**Problém:** Nemôžem si dovoliť predplatné a potrebujem spoľahlivú AI na programovanie
```
Kombinácia: "zero-cost"
1. if/kimi-k2.7-code (uvádzaný bezplatný prístup; môžu platiť obmedzenia rýchlosti)
2. kr/qwen3-coder-next (bezplatná záloha Kiro)
Mesačné náklady: $0
Kvalita: overte model, limity, ochranu súkromia a SLA pre vaše pracovné zaťaženie
```
### Prípad 3: „Potrebujem programovať nepretržite, bez prerušení“
**Problém:** Termíny, nemôžem si dovoliť výpadky
```
Kombinácia: "always-on"
1. cc/claude-opus-4-7 (najlepšia kvalita)
2. cx/gpt-5.5 (druhé predplatné)
3. glm/glm-4.7 (lacné, obnovuje sa denne)
4. minimax/MiniMax-M2.1 (najlacnejšie, obnovenie po 5 hod.)
5. if/deepseek-v4-flash (uvádzaný bezplatný prístup; môžu platiť obmedzenia rýchlosti)
Výsledok: 5 záložných vrstiev zvyšuje odolnosť; dostupnosť služieb vyššej úrovne nie je zaručená
Mesačné náklady: $20-200 (predplatné) + $10-20 (záloha)
```
### Prípad 4: „Chcem BEZPLATNÚ AI v OpenClaw“
**Problém:** Potrebujem asistenta AI v komunikačných aplikáciách úplne zadarmo
```
Kombinácia: "openclaw-free"
1. if/qwen3.8-max-preview (uvádzaný bezplatný prístup; môžu platiť obmedzenia rýchlosti)
2. if/deepseek-v4-flash (uvádzaný bezplatný prístup; môžu platiť obmedzenia rýchlosti)
3. if/kimi-k2.7-code (uvádzaný bezplatný prístup; môžu platiť obmedzenia rýchlosti)
Mesačné náklady: $0
Prístup cez: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
```
---
## 📖 Nastavenie poskytovateľov
Ak chcete hromadne pridať pripojenia s API kľúčmi zo súboru CSV alebo JSON, použite **Dashboard → Providers → Import from file**. Stĺpce sú pozičné (`provider,name,apiKey,baseUrl,priority`); `provider` už musí existovať ako spravovaný poskytovateľ alebo kompatibilný uzol. Pozrite si [Import poskytovateľov zo súboru CSV alebo JSON](../providers/CSV-IMPORT.md).
### 🔐 Poskytovatelia s predplatným
#### Claude Code (Pro/Max)
```bash
Dashboard → Providers → Connect Claude Code
→ Prihlásenie cez OAuth → Automatické obnovenie tokenu
→ Sledovanie 5-hodinovej a týždennej kvóty
Modely:
cc/claude-opus-4-7
cc/claude-sonnet-4-6
cc/claude-haiku-4-5-20251001
```
**Profesionálny tip:** Opus používajte na komplexné úlohy a Sonnet na rýchlosť. OmniRoute sleduje kvótu pre každý model!
Na hostiteľovi OmniRoute nie je prehliadač? Spustite `claude setup-token` kdekoľvek, kde ste prihlásení do Claude Code, a vložte jednoročný token na kartu **Setup Token**. Pozrite si [Claude Code s nastavovacím tokenom](../providers/CLAUDE_CODE_SETUP_TOKEN.md).
Trasy kompatibilné s Claude a Claude Code zachovávajú úroveň úsilia pri uvažovaní `max` pre modely Opus a Sonnet. Modely Haiku nepodporujú úroveň úsilia `max`, preto OmniRoute pred odoslaním požiadavky nadradenému poskytovateľovi zmení túto požiadavku na vysoký rozpočet na uvažovanie.
#### OpenAI Codex (Plus/Pro)
```bash
Dashboard → Providers → Connect Codex
→ Prihlásenie cez OAuth (port 1455)
→ Obnovenie po 5 hodinách a po týždni
Modely:
cx/gpt-5.5
cx/gpt-5.4
cx/gpt-5.3-codex
cx/gpt-5.3-codex-spark
```
#### GitHub Copilot
```bash
Dashboard → Providers → Connect GitHub
→ OAuth cez GitHub
→ Mesačné obnovenie (1. deň v mesiaci)
Modely:
gh/gpt-5.5
gh/gpt-5.4
gh/claude-sonnet-4.6
gh/claude-opus-4.7
gh/gemini-3.1-pro-preview
```
### 💰 Lacní poskytovatelia
#### GLM-4.7 (denné obnovenie, $0.6/1M)
1. Zaregistrujte sa: [Zhipu AI](https://open.bigmodel.cn)
2. Získajte API kľúč z plánu Coding Plan
3. Dashboard → Add API Key: Poskytovateľ: `glm`, API kľúč: `your-key`
**Použitie:** `glm/glm-4.7` — **Profesionálny tip:** Coding Plan ponúka 3-násobnú kvótu za 1/7 ceny! Obnovuje sa denne o 10:00.
#### MiniMax M2.1 (obnovenie po 5 h, $0.20/1M)
1. Zaregistrujte sa: [MiniMax](https://www.minimax.io)
2. Získajte API kľúč → Dashboard → Add API Key
**Použitie:** `minimax/MiniMax-M2.1` — **Profesionálny tip:** Najlacnejšia možnosť pre dlhý kontext (1M tokenov)!
#### Kimi K2 (pevne $9/mesiac)
1. Predplaťte si službu: [Moonshot AI](https://platform.kimi.ai?aff=omniroute)
2. Získajte API kľúč → Dashboard → Add API Key
**Použitie:** `kimi/kimi-k2.5` — **Profesionálny tip:** Pevných $9/mesiac za 10M tokenov = efektívna cena $0.90/1M!
#### Baidu Qianfan / ERNIE
1. Zaregistrujte sa: [Baidu AI Cloud Qianfan](https://cloud.baidu.com/product/wenxinworkshop)
2. Vytvorte API kľúč Qianfan → Dashboard → Add API Key: Poskytovateľ: `qianfan`
**Použitie:** `qianfan/ernie-5.1`, `qianfan/ernie-x1.1` alebo iné ID modelu Qianfan kompatibilného s OpenAI.
### 🆓 BEZPLATNÍ poskytovatelia
Bezplatní poskytovatelia bez overenia majú na svojej stránke prepínač vedľa položky **No authentication required**.
Jeho vypnutím daného poskytovateľa deaktivujete, odstránite ho z nakonfigurovaného/kompaktného zobrazenia poskytovateľov
a jeho modely odstránite z `/v1/models`.
#### Qoder (9 BEZPLATNÝCH modelov)
```bash
Dashboard → Connect Qoder → Prihlásenie cez OAuth → Prístup podlieha aktuálnym limitom poskytovateľa
Modely: 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 BEZPLATNE)
```bash
Dashboard → Connect Kiro → AWS Builder ID alebo Google/GitHub → ~50 kreditov/mesiac
Modely: kr/claude-sonnet-4.5, kr/claude-haiku-4.5
```
---
## 🎨 Kombinácie
Karty kombinácií môžete meniť priamo v časti **Ovládací panel → Kombinácie** potiahnutím rukoväti na každej karte. Poradie sa uloží v SQLite a po opätovnom načítaní sa obnoví.
### Príklad 1: Maximalizácia predplatného → Lacná záloha
```
Ovládací panel → Kombinácie → Vytvoriť novú
Názov: premium-coding
Modely:
1. cc/claude-opus-4-7 (Primárny model z predplatného)
2. glm/glm-4.7 (Lacná záloha, $0.6/1M)
3. minimax/MiniMax-M2.7 (Najlacnejšia núdzová možnosť, $0.3/1M)
Použitie v CLI: premium-coding
```
### Príklad 2: Iba bezplatné modely (nulové náklady)
```
Názov: free-combo
Modely:
1. if/kimi-k2.7-code (uvedený bezplatný prístup; môžu platiť obmedzenia poskytovateľa)
2. kr/qwen3-coder-next (bezplatná záloha Kiro)
Náklady: momentálne uvedené ako $0; podmienky a dostupnosť sa môžu zmeniť
```
---
## 🔧 Integrácia s CLI
### Cursor IDE
**Použitie Cursor ako klienta OmniRoute** (smerovanie chatu Cursor cez OmniRoute):
```
Nastavenia → Modely → Rozšírené:
Základná URL API OpenAI: http://localhost:20128/v1
Kľúč API OpenAI: [z ovládacieho panela OmniRoute]
Model: cc/claude-opus-4-7
```
**Použitie OmniRoute s poskytovateľom Cursor** (OmniRoute volá nadradenú službu Cursor): uprednostnite
**Ovládací panel → Poskytovatelia → Cursor → Prihlásiť sa pomocou Cursor**. V prostredí Docker si pozrite
[`docs/providers/CURSOR-DOCKER.md`](../providers/CURSOR-DOCKER.md).
### Claude Code
Upravte súbor `~/.claude/settings.json`:
```json
{
"env": {
"ANTHROPIC_BASE_URL": "http://localhost:20128",
"ANTHROPIC_AUTH_TOKEN": "your-omniroute-api-key"
}
}
```
Tu použite koreňový koncový bod kompatibilný s Claude. K `ANTHROPIC_BASE_URL` nepridávajte `/v1`.
### Codex CLI
```bash
export OPENAI_BASE_URL="http://localhost:20128"
export OPENAI_API_KEY="your-omniroute-api-key"
codex "your prompt"
```
### OpenClaw
Upravte súbor `~/.openclaw/openclaw.json`:
```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" }]
}
}
}
}
```
**Alebo použite ovládací panel:** Nástroje CLI → OpenClaw → Automatická konfigurácia
### Cline / Continue / RooCode
```
Poskytovateľ: Kompatibilný s OpenAI
Základná URL: http://localhost:20128/v1
Kľúč API: [z ovládacieho panela]
Model: cc/claude-opus-4-7
```
---
## 🚀 Nasadenie
### Globálna inštalácia cez npm (odporúčané)
```bash
npm install -g omniroute
# Vytvorenie konfiguračného adresára
mkdir -p ~/.omniroute
# Vytvorenie súboru .env (pozrite si .env.example)
cp .env.example ~/.omniroute/.env
# Spustenie servera
omniroute
# Alebo s vlastným portom:
omniroute --port 3000
```
CLI automaticky načíta súbor `.env` z `~/.omniroute/.env` alebo `./.env`.
### Režim systémovej lišty
Spustite OmniRoute v systémovej lište:
```bash
omniroute serve --tray
```
Príkaz sa ukončí po pripravení servera a systémovej lišty.
Server naďalej beží bez terminálu.
Režim systémovej lišty podporuje macOS, Windows a grafické relácie Linuxu. V režime systémovej lišty sa ovládací panel neotvorí automaticky.
Ponuku systémovej lišty použite na tieto akcie:
- Otvorenie ovládacieho panela.
- Otvorenie `/dashboard/logs`.
- Zmenu automatického spúšťania.
- Zastavenie OmniRoute.
Nekombinujte `--tray` s týmito možnosťami:
- `--daemon`
- `--log`
- `--no-recovery`
Tieto režimy vyžadujú odlišné vlastníctvo procesu.
Povoľte spustenie pri nasledujúcom prihlásení do počítača:
```bash
omniroute autostart enable
```
Automatické spúšťanie používa režim systémovej lišty v systémoch macOS, Windows a grafických reláciách Linuxu. Linux bez grafického rozhrania používa existujúcu používateľskú službu systemd.
Zakážte spúšťanie pri prihlásení:
```bash
omniroute autostart disable
```
### Odinštalovanie
Keď už OmniRoute nepotrebujete, poskytujeme dva rýchle skripty na jeho úplné odstránenie:
| Príkaz | Akcia |
| ------------------------ | -------------------------------------------------------------------------------------------- |
| `npm run uninstall` | Odstráni systémovú aplikáciu, ale **ponechá vašu databázu a konfigurácie** v `~/.omniroute`. |
| `npm run uninstall:full` | Odstráni aplikáciu A zároveň natrvalo **vymaže všetky konfigurácie, kľúče a databázy**. |
> Poznámka: Ak chcete spustiť tieto príkazy, prejdite do priečinka projektu OmniRoute (ak ste ho klonovali) a spustite ich. Ak ste aplikáciu nainštalovali globálne, môžete jednoducho spustiť `npm uninstall -g omniroute`.
### Nasadenie na VPS
```bash
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
# Alebo: pm2 start npm --name omniroute -- start
```
### Nasadenie pomocou PM2 (nízka spotreba pamäte)
Pre servery s obmedzenou pamäťou RAM použite možnosť obmedzenia pamäte:
```bash
# S limitom 512 MB (predvolené)
pm2 start npm --name omniroute -- start
# Alebo s vlastným limitom pamäte
OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start
# Alebo pomocou ecosystem.config.js
pm2 start ecosystem.config.js
```
Vytvorte súbor `ecosystem.config.js`:
```javascript
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
```bash
# Zostavenie obrazu (predvolené = runner-cli s predinštalovanými codex/claude/droid)
docker build -t omniroute:cli .
# Prenosný režim (odporúčané)
docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli
```
Informácie o režime integrovanom s hostiteľom a binárnymi súbormi CLI nájdete v časti Docker v hlavnej dokumentácii.
### Void Linux (xbps-src)
Používatelia Void Linuxu môžu OmniRoute zostaviť do balíka a natívne nainštalovať pomocou frameworku `xbps-src` na krížovú kompiláciu. Tento proces automatizuje samostatné zostavenie Node.js spolu s požadovanými natívnymi väzbami `better-sqlite3`.
Zobraziť šablónu xbps-src
```bash
# Súbor šablóny pre „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 "
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() {
# Určenie cieľovej architektúry CPU pre 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) Inštalácia všetkých závislostí – preskočenie skriptov
NODE_ENV=development npm ci --ignore-scripts
# 2) Zostavenie samostatného balíka Next.js
npm run build
# 3) Skopírovanie statických prostriedkov do samostatného balíka
cp -r .next/static .next/standalone/.next/static
[ -d public ] && cp -r public .next/standalone/public || true
# 4) Kompilácia natívnej väzby 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) Umiestnenie skompilovanej väzby do samostatného balíka
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) Odstránenie balíkov sharp špecifických pre jednotlivé architektúry
rm -rf .next/standalone/node_modules/@img
# 7) Skopírovanie runtime závislostí pino vynechaných statickou analýzou 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
# Zabránenie odstráneniu prázdnych adresárov smerovača aplikácie Next.js hookom po inštalácii
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
}
```
### Premenné prostredia
| Premenná | Predvolená hodnota | Popis |
| --------------------------------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `JWT_SECRET` | `omniroute-default-secret-change-me` | Tajný kľúč na podpisovanie JWT (**v produkcii ho zmeňte**) |
| `INITIAL_PASSWORD` | `CHANGEME` | Heslo na prvé prihlásenie |
| `DATA_DIR` | `~/.omniroute` | Dátový adresár (databáza, využitie, protokoly) |
| `PORT` | predvolená hodnota frameworku | Port služby (v príkladoch `20128`) |
| `HOSTNAME` | predvolená hodnota frameworku | Hostiteľ pre väzbu (Docker predvolene používa `0.0.0.0`) |
| `NODE_ENV` | predvolená hodnota behového prostredia | Pri nasadení nastavte na `production` |
| `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128` | Verejná základná URL sprístupnená ovládaciemu panelu a serveru (nahrádza staršiu premennú `BASE_URL`) |
| `NEXT_PUBLIC_CLOUD_URL` | `https://omniroute.dev` | Základná URL koncového bodu cloudovej synchronizácie (nahrádza staršiu premennú `CLOUD_URL`) |
| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | Tajný kľúč HMAC pre generované kľúče API |
| `REQUIRE_API_KEY` | `false` | Vyžadovať kľúč API typu Bearer na `/v1/*` |
| `ALLOW_API_KEY_REVEAL` | `false` | Umožniť overeným používateľom ovládacieho panela na požiadanie zobraziť úplné hodnoty uložených kľúčov API |
| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Interval obnovovania údajov o limitoch poskytovateľov uložených vo vyrovnávacej pamäti na strane servera; tlačidlá obnovenia v používateľskom rozhraní naďalej spúšťajú manuálnu synchronizáciu |
| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Zakázať automatické snímky SQLite pred zápisom/importom/obnovením; manuálne zálohy budú naďalej fungovať |
| `APP_LOG_TO_FILE` | `true` | Povolí zapisovanie protokolov aplikácie a auditu na disk |
| `AUTH_COOKIE_SECURE` | `false` | Vynútiť atribút `Secure` pre autentifikačný súbor cookie (za reverzným proxy serverom HTTPS) |
| `CLOUDFLARED_BIN` | nenastavené | Použiť existujúci binárny súbor `cloudflared` namiesto spravovaného sťahovania |
| `CLOUDFLARED_PROTOCOL` | `http2` | Prenosový protokol pre spravované rýchle tunely (`http2`, `quic` alebo `auto`) |
| `OMNIROUTE_MEMORY_MB` | `512` | Limit haldy Node.js v MB |
| `PROMPT_CACHE_MAX_SIZE` | `50` | Maximálny počet položiek vo vyrovnávacej pamäti promptov |
| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Maximálny počet položiek v sémantickej vyrovnávacej pamäti |
Úplný prehľad premenných prostredia nájdete v súbore [README](../README.md).
---
## 📊 Dostupné modely
Zobraziť všetky dostupné modely
> Zoznam nižšie je zostavený zo súboru `open-sse/config/providerRegistry.ts` pre v3.8.0. Cloudové katalógy (Gemini, OpenRouter atď.) sa synchronizujú dynamicky — úplný aktuálny katalóg otvoríte cez **Dashboard → Providers → [provider] → Available Models** alebo volaním `GET /api/models/catalog`.
>
> Ak vstavaný zoznam poskytovateľa prestal byť aktuálny, použite na danej stránke možnosť **Import from /models** (alebo povoľte **Auto-Sync**) a načítajte aktuálny katalóg z nadradeného zdroja. Toto bolo overené vo v3.8.50 pre LLM7.io (`gemini-3.1-flash-lite`) a UncloseAI (`solidrust/Hermes-3-Llama-3.1-8B-AWQ`); anonymný prístup k Pollinations zostal počas rovnakého testovania obmedzený na strane nadradeného zdroja.
**Claude Code (`cc/`)** — OAuth Pro/Max: `cc/claude-opus-4-8`, `cc/claude-opus-4-7`, `cc/claude-opus-4-6`, `cc/claude-opus-4-5-20251101`, `cc/claude-sonnet-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
**Codex (`cx/`)** — OAuth Plus/Pro: `cx/gpt-5.5` (+ úrovne úsilia: `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/`)** — BEZPLATNÝ OAuth: použite aktuálny katalóg zobrazený v časti **Dashboard → Providers → Kiro → Available Models**. Dostupnosť závisí od účtu a plánu.
**Qoder (`if/`)** — BEZPLATNÝ 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/`)** — paušál $9/mesiac alebo platba podľa používania: `kimi/kimi-k2.6`, `kimi/kimi-k2.5`
**DeepSeek (`ds/`)** — kľúč API: `ds/deepseek-v4-pro`, `ds/deepseek-v4-flash`
**Groq (`groq/`)** — ultrarýchly: `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/`)** — natívny 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/`)** — hostovaný v EÚ: `mistral/mistral-large-latest`, `mistral/mistral-medium-3-5`, `mistral/mistral-small-latest`, `mistral/devstral-latest`, `mistral/codestral-latest`
**Perplexity (`pplx/`)** — rozšírený o vyhľadávanie: `pplx/sonar-deep-research`, `pplx/sonar-reasoning-pro`, `pplx/sonar-pro`, `pplx/sonar`
**Together AI (`together/`)** — otvorený zdrojový kód: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo-Free` (bezplatný), `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/`)** — rýchla inferencia: `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/`)** — na úrovni waferov: `cerebras/zai-glm-4.7`, `cerebras/gpt-oss-120b`
**Cohere (`cohere/`)** — zameraný na 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/`)** — podnikové riešenie: `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/`)**: Synchronizuje sa priebežne z Google podľa kľúča API — bez statického zoznamu. Pripojte kľúč v časti **Dashboard → Providers** a potom pomocou možnosti **Available Models** importujte aktuálny katalóg (napr. `gemini/gemini-3-pro`, `gemini/gemini-3-flash`).
**Ďalší kompatibilní poskytovatelia** (výber): `cohere`, `databricks`, `snowflake`, `together`, `vertex`, `alibaba`, `alibaba-cn`, `bedrock` (cez `aws-bedrock`), `azure-ai`, `openrouter` (priechodný katalóg), `siliconflow`, `hyperbolic`, `huggingface`, `featherless-ai`, `cloudflare-ai`, `scaleway`, `deepinfra`, `vercel-ai-gateway`, `bazaarlink`, `friendliai`, `nous-research`, `reka`, `volcengine`, `ai21`, `gigachat`. Každý udržiava vlastný zoznam modelov v súbore `providerRegistry.ts` a možno ho automaticky synchronizovať, keď poskytovateľ sprístupňuje koncový bod `/models`.
**Poznámka k ID modelov:** OmniRoute používa natívne ID poskytovateľov (`claude-opus-4-8`, `gpt-5.5`, `glm-5.1`, `MiniMax-M2.7`, `kimi-k2.5`, `grok-4.20-0309-reasoning`). Niektoré ID obsahujú verzie s bodkami, pretože ich v tejto podobe očakáva nadradené API. Ak model nie je uvedený vyššie, spustite `omniroute models --search ` alebo zavolajte `GET /api/models/catalog`, aby ste overili jeho dostupnosť.
---
## 🧩 Pokročilé funkcie
### Vlastné modely
Pridajte ľubovoľné ID modelu k ľubovoľnému poskytovateľovi bez čakania na aktualizáciu aplikácie:
```bash
# Prostredníctvom 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"}'
# Zoznam: curl http://localhost:20128/api/provider-models?provider=openai
# Odstránenie: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-5.2"
```
Alebo použite ovládací panel: **Poskytovatelia → [Poskytovateľ] → Vlastné modely**.
Poznámky:
- Poskytovatelia kompatibilní s OpenRouter a OpenAI/Anthropic sa spravujú iba v časti **Dostupné modely**. Manuálne pridanie, import aj automatická synchronizácia sa ukladajú do rovnakého zoznamu dostupných modelov, takže pre týchto poskytovateľov neexistuje samostatná časť Vlastné modely.
- Časť **Vlastné modely** je určená pre poskytovateľov, ktorí neposkytujú spravované importy dostupných modelov.
### Vlastní poskytovatelia kompatibilní s OpenAI
Každú bránu, ktorá používa API OpenAI (proxy hostované vo vlastnej réžii, vLLM alebo agregátor tretej strany),
možno pridať ako samostatný uzol poskytovateľa:
1. **Poskytovatelia → Pridať poskytovateľa kompatibilného s OpenAI**.
2. **Názov**: zobrazovaný názov uzla.
3. **Predpona**: názov používaný na smerovanie. Klienti volajú modely ako `/`, takže uzol s
predponou `mygw` obsluhuje `mygw/gpt-4o-mini`. Povinné; neplatia žiadne obmedzenia znakov.
4. **Typ API**: skupina koncových bodov, ktoré brána obsluhuje (Chat Completions, Responses,
Embeddings, zvuk, obrázky).
5. **Základná URL**: koreň API až po `/v1` vrátane (napríklad
`https://gateway.example.com/v1`), nie úplná cesta `/chat/completions`. Brány s
neštandardnými cestami ich nastavia v časti **Rozšírené nastavenia** (cesta chatu, cesta modelov).
6. Pole **Kľúč API (na kontrolu)** iba testuje pripojenie. Po vytvorení uzla
ho otvorte a pomocou možnosti **Pridať pripojenie** uložte kľúč, ktorý sa bude používať pri požiadavkách.
Uzol dostane interné ID v tvare `openai-compatible--`; nikdy ho
nemusíte zadávať, pretože verejným názvom je predpona.
#### Vyhradené predpony
Predpona nemôže byť ID ani alias vstavaného poskytovateľa (napríklad `openai`, `cf`) ani
ID vyradeného poskytovateľa. Prekladač modelov kontroluje vstavané ID a aliasy pred
vlastnými uzlami, takže uzol používajúci jednu z týchto predpôn by nikdy neprijímal požiadavky:
`/model` by namiesto toho smerovalo k vstavanému poskytovateľovi alebo by sa bezpečne zamietlo, ak bol tento poskytovateľ
vyradený. Vytvorenie alebo úprava uzla s takouto predponou sa zamietne s hlásením:
```text
prefix: "" je vyhradená predpona poskytovateľa — vyberte inú predponu (vyhradené ID/aliasy nemožno použiť pre vlastné uzly, pretože požiadavky ako /model smerujú k vstavanému poskytovateľovi alebo sa po jeho vyradení bezpečne zamietnu)
```
Vyberte odlišnú predponu (`mygw`, `acme-proxy`). Ak požiadavky na vlastný uzol zlyhávajú s
chybou, ktorá uvádza vstavaného poskytovateľa alebo jeho prihlasovacie údaje, skontrolujte, či predpona uzla nie je
vyhradená: uzly uložené pred zavedením tohto pravidla sú stále uložené, ale ich predpona smeruje k
vstavanému poskytovateľovi. Upravte uzol a prideľte mu novú predponu.
### Reťazenie partnerských uzlov OmniRoute
Ďalšiu bránu OmniRoute možno pridať ako **vlastného poskytovateľa kompatibilného s OpenAI**. Použite
základnú URL partnera `/v1` a vyhradený kľúč API s minimálnymi oprávneniami, ktorý vydal daný partner.
Pri obojsmerných alebo viacskokových reťazcoch povoľte na každej bráne voliteľnú ochranu pred slučkami:
```bash
# gateway-a
OMNIROUTE_INSTANCE_ID=gateway-a
OMNIROUTE_PEER_URLS=http://gateway-b:20128/v1
OMNIROUTE_PEER_MAX_HOPS=4
```
```bash
# gateway-b
OMNIROUTE_INSTANCE_ID=gateway-b
OMNIROUTE_PEER_URLS=http://gateway-a:20128/v1
OMNIROUTE_PEER_MAX_HOPS=4
```
Hlavičku `X-OmniRoute-Peer-Trace` dostanú iba požiadavky odoslané na partnerskú URL, ktorá je explicitne uvedená v zozname povolených adries.
Brána odmietne opakované ID inštancie alebo vyčerpaný limit skokov s HTTP `508 Loop Detected`;
bežní nadradení poskytovatelia nedostávajú žiadne metadáta partnera.
Reťazenie partnerských uzlov nie je replikácia databázy ani prepnutie pri zlyhaní hostiteľa. Každá brána si udržiava nezávislý
stav SQLite, vyrovnávacie pamäte, počítadlá limitov a relácie. Na aktívnu/pasívnu alebo aktívnu/aktívnu dostupnosť použite reverzné proxy
s kontrolou stavu alebo prepnutie pri zlyhaní na strane klienta a nikdy nepripájajte jednu databázu SQLite
k viacerým spusteným inštanciám OmniRoute.
### Vyhradené trasy poskytovateľov
Smerujte požiadavky priamo ku konkrétnemu poskytovateľovi s overením modelu:
```bash
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
```
Ak predpona poskytovateľa chýba, pridá sa automaticky. Nezhodujúce sa modely vrátia `400`.
### Konfigurácia sieťového proxy
```bash
# Nastavenie globálneho proxy
curl -X PUT http://localhost:20128/api/settings/proxy \
-d '{"global": {"type":"http","host":"proxy.example.com","port":"8080"}}'
# Proxy pre konkrétneho poskytovateľa
curl -X PUT http://localhost:20128/api/settings/proxy \
-d '{"providers": {"openai": {"type":"socks5","host":"proxy.example.com","port":"1080"}}}'
# Test proxy
curl -X POST http://localhost:20128/api/settings/proxy/test \
-d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}'
```
**Priorita:** Špecifické pre kľúč → špecifické pre kombináciu → špecifické pre poskytovateľa → globálne → prostredie.
### API katalógu modelov
```bash
curl http://localhost:20128/api/models/catalog
```
Vracia modely zoskupené podľa poskytovateľa s typmi (`chat`, `embedding`, `image`).
### Cloudová synchronizácia
- Synchronizácia poskytovateľov, kombinácií a nastavení medzi zariadeniami
- Automatická synchronizácia na pozadí s časovým limitom a okamžitým ukončením pri chybe
- V produkčnom prostredí uprednostnite serverové `NEXT_PUBLIC_BASE_URL`/`NEXT_PUBLIC_CLOUD_URL`
### Rýchly tunel Cloudflare
- Dostupné v časti **Ovládací panel → Koncové body** pre Docker a ďalšie samostatne hostované nasadenia
- Vytvorí dočasnú URL adresu `https://*.trycloudflare.com`, ktorá presmerúva na váš aktuálny koncový bod `/v1` kompatibilný s OpenAI
- Pri prvom povolení sa `cloudflared` nainštaluje iba v prípade potreby; pri neskorších reštartoch sa znova použije rovnaký spravovaný binárny súbor
- Rýchle tunely sa po reštarte OmniRoute alebo kontajnera automaticky neobnovia; v prípade potreby ich znova povoľte z ovládacieho panela
- URL adresy tunelov sú dočasné a zmenia sa pri každom zastavení/spustení tunela
- Spravované rýchle tunely predvolene používajú prenos HTTP/2, aby sa v kontajneroch s obmedzenými prostriedkami predišlo zahlcovaniu upozorneniami na vyrovnávaciu pamäť UDP protokolu QUIC
- Ak chcete prepísať výber spravovaného prenosu, nastavte `CLOUDFLARED_PROTOCOL=quic` alebo `auto`
- Ak namiesto spravovaného stiahnutia uprednostňujete použitie predinštalovaného binárneho súboru `cloudflared`, nastavte `CLOUDFLARED_BIN`
- Panely Cloudflare Quick Tunnel, Tailscale Funnel a ngrok Tunnel možno zobraziť alebo skryť v časti **Nastavenia → Vzhľad**. Skrytie panela nezastaví spustený tunel.
### Inteligencia brány LLM (fáza 9)
- **Sémantická vyrovnávacia pamäť** — Automaticky ukladá do vyrovnávacej pamäte odpovede bez streamovania s hodnotou temperature=0 (obídenie pomocou `X-OmniRoute-No-Cache: true`)
- **Idempotentnosť požiadaviek** — Deduplikuje požiadavky v rámci 5 sekúnd pomocou hlavičky `Idempotency-Key` alebo `X-Request-Id`
- **Sledovanie priebehu** — Voliteľné udalosti SSE `event: progress` prostredníctvom hlavičky `X-OmniRoute-Progress: true`
---
### Testovacie prostredie prekladača
Prístup cez **Ovládací panel → Prekladač**. Ladí a vizualizuje spôsob, akým OmniRoute prekladá požiadavky API medzi poskytovateľmi.
| Režim | Účel |
| ------------------------- | ------------------------------------------------------------------------------------------ |
| **Testovacie prostredie** | Vyberte zdrojové/cieľové formáty, vložte požiadavku a okamžite si pozrite preložený výstup |
| **Tester chatu** | Odosielajte živé četové správy cez proxy a kontrolujte celý cyklus požiadavky/odpovede |
| **Testovacia zostava** | Spúšťajte dávkové testy s viacerými kombináciami formátov na overenie správnosti prekladu |
| **Živé monitorovanie** | Sledujte preklady v reálnom čase počas prechodu požiadaviek cez proxy |
**Prípady použitia:**
- Ladenie príčiny zlyhania konkrétnej kombinácie klienta a poskytovateľa
- Overenie, že sa značky premýšľania, volania nástrojov a systémové výzvy prekladajú správne
- Porovnanie rozdielov medzi formátmi OpenAI, Claude, Gemini a Responses API
---
### Stratégie smerovania
Konfigurujte cez **Ovládací panel → Nastavenia → Smerovanie**. Ovládací panel poskytuje šesť najpoužívanejších stratégií; kombinácie a automatický smerovač interne podporujú širšiu množinu.
**Stratégie viditeľné v ovládacom paneli (smerovanie na úrovni účtu):**
| Stratégia | Popis |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| **Najskôr zaplniť** | Používa účty podľa poradia priority — primárny účet spracováva všetky požiadavky, kým nie je nedostupný |
| **Cyklické prideľovanie** | Cyklicky prechádza všetkými účtami s konfigurovateľným limitom zachovania väzby (predvolene: 3 volania na účet) |
| **P2C (sila dvoch možností)** | Vyberie 2 náhodné účty a požiadavku nasmeruje na účet v lepšom stave — vyvažuje zaťaženie so zohľadnením stavu |
| **Náhodne** | Náhodne vyberie účet pre každú požiadavku pomocou Fisherovho-Yatesovho premiešania |
| **Najmenej používaný** | Smeruje na účet s najstaršou časovou značkou `lastUsedAt`, čím rovnomerne rozdeľuje prevádzku |
| **Optimalizované podľa nákladov** | Smeruje na účet s najnižšou hodnotou priority, čím optimalizuje výber poskytovateľov s najnižšími nákladmi |
**Pokročilé kombinované a automatické stratégie** (konfigurovateľné pre jednotlivé kombinácie alebo pomocou predpôn `auto/*` — pozrite si [AUTO-COMBO.md](../routing/AUTO-COMBO.md)):
- `priority` — prísne poradie, nikdy nepoužíva cyklické prideľovanie
- `weighted` — pomerné rozdelenie prevádzky podľa váh jednotlivých modelov
- `fill-first` — využíva prvý model, kým sa nedosiahnu limity
- `round-robin` / `strict-random` / `random`
- `p2c` (sila dvoch možností)
- `least-used` a `cost-optimized`
- `auto` — výber zo všetkých kandidátov na základe skóre
- `lkgp` (posledný známy funkčný poskytovateľ) — zachováva posledného úspešného poskytovateľa a následne prechádza na záložné pravidlá
- `context-optimized` — vyberie model s najväčším voľným kontextovým oknom
- `context-relay` — reťazí modely s dlhým kontextom pre nadväzujúce kolá
#### Externá hlavička zachovania relácie
Na externé zachovanie afinity relácie (napríklad pre agentov Claude Code/Codex za reverznými proxy servermi) odošlite:
```http
X-Session-Id: váš-kľúč-relácie
```
OmniRoute akceptuje aj `x_session_id` a vracia platný kľúč relácie v hlavičke `X-OmniRoute-Session-Id`.
Ak používate Nginx a odosielate hlavičky s podčiarkovníkmi, povoľte:
```nginx
underscores_in_headers on;
```
#### Zástupné aliasy modelov
Vytvorte vzory so zástupnými znakmi na premapovanie názvov modelov:
```
Vzor: claude-sonnet-* → Cieľ: cc/claude-sonnet-4-6
Vzor: gpt-* → Cieľ: gh/gpt-5.3-codex
```
Zástupné znaky podporujú `*` (ľubovoľné znaky) a `?` (jeden znak).
#### Reťazce záložných možností
Definujte globálne reťazce záložných možností, ktoré sa uplatňujú na všetky požiadavky:
```
Reťazec: production-fallback
1. cc/claude-opus-4-7
2. gh/gpt-5.3-codex
3. glm/glm-4.7
```
---
### Bežné kombinácie poskytovateľov a vzory smerovania
Nasledujú príklady vzorov na kombinovanie viacerých poskytovateľov a smerovanie medzi nimi v OmniRoute:
#### 1. Kombinácia pre programovacieho agenta: pokročilé uvažovanie so záložnou možnosťou optimalizovanou podľa nákladov/rýchlosti
Ideálne pre programovacích agentov (OpenCode, Claude Code, Cursor, Cline). Požiadavky sa najskôr smerujú na špičkové modely uvažovania a pri vyčerpaní kvóty alebo výskyte chýb sa prechádza na rýchle programovacie modely.
- **Ovládací panel**: Kombinácie → Nová kombinácia → Názov: `agent-coding` → Stratégia: `Priority`
- **Modely**:
1. `claude/claude-sonnet-4-6` (Primárny programovací agent)
2. `openai/gpt-4o` (Sekundárna záložná možnosť s vysokou kapacitou)
3. `deepseek/deepseek-v4-flash` (Vysoko efektívna a nákladovo výhodná záložná možnosť)
```bash
# Príklad cez API
curl -X POST http://localhost:20128/api/combos \
-H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "agent-coding",
"strategy": "priority",
"models": [
{ "model": "claude/claude-sonnet-4-6" },
{ "model": "openai/gpt-4o" },
{ "model": "deepseek/deepseek-v4-flash" }
]
}'
```
#### 2. Kombinácia s automatickým prepnutím medzi bezplatnými úrovňami
Reťazí viacerých poskytovateľov s bezplatnou úrovňou a bez potreby kľúča, aby maximalizovala dostupnosť bez nákladov na API.
- **Stratégia**: `Least Used` alebo `Round Robin` (rozdeľuje záťaž medzi kvóty)
- **Modely**:
1. `groq/llama-3.3-70b-versatile`
2. `gemini/gemini-2.5-flash`
3. `cerebras/gpt-oss-120b`
```bash
# Príklad cez CLI
omniroute combo create free-stack \
--models "groq/llama-3.3-70b-versatile,gemini/gemini-2.5-flash,cerebras/gpt-oss-120b" \
--strategy round-robin
```
#### 3. Multimodálny kanál / kanál pre obraz a text
Kombinácia špecializovaných modelov pre obraz s vysokorýchlostným generovaním textu pre pracovné postupy zahŕňajúce porozumenie obrázkom a generovanie kódu.
- **Vzor**: Kombinácia `Priority`, ktorá uvádza najskôr modely podporujúce obraz a ako posledný model s vysokou priepustnosťou pre text/kód.
- **Modely**:
1. `gemini/gemini-2.5-pro` (Silné porozumenie obrázkom a multimodálnemu obsahu)
2. `openai/gpt-4o` (Vyvážená práca s obrazom a používanie nástrojov)
3. `deepseek/deepseek-v4-flash` (Generovanie textu/kódu)
---
### Odolnosť a ističe
Nakonfigurujte ich cez **Ovládací panel → Nastavenia → Odolnosť**.
OmniRoute implementuje odolnosť na úrovni poskytovateľa pomocou piatich komponentov:
1. **Front požiadaviek a riadenie tempa** — Riadenie požiadaviek na úrovni systému:
- **Počet požiadaviek za minútu (RPM)** — Maximálny počet požiadaviek za minútu na jeden účet
- **Minimálny čas medzi požiadavkami** — Minimálny odstup medzi požiadavkami v milisekundách
- **Maximálny počet súbežných požiadaviek** — Maximálny počet súčasných požiadaviek na jeden účet
2. **Čas na zotavenie pripojenia** — Konfigurácia podľa typu overenia pre jedno pripojenie po zlyhaniach, ktoré možno zopakovať:
- **Základný čas na zotavenie** — Predvolené časové okno na zotavenie po zlyhaniach nadradenej služby, ktoré možno zopakovať
- **Použiť pokyny nadradenej služby na opakovanie** — Rešpektuje autoritatívnu hlavičku `Retry-After` alebo pokyny na obnovenie, ak sú poskytnuté
- **Maximálny počet krokov predlžovania intervalu** — Maximálna úroveň exponenciálneho predlžovania intervalu pri opakovaných zlyhaniach
3. **Istič poskytovateľa** — Sleduje komplexné zlyhania poskytovateľa, označí poskytovateľa za degradovaného pri nakonfigurovanej varovnej prahovej hodnote a otvorí istič po dosiahnutí nakonfigurovanej prahovej hodnoty zlyhaní:
- **Prahová hodnota degradácie** — Počet po sebe nasledujúcich zlyhaní poskytovateľa pred prechodom do stavu `DEGRADED`
- **Prahová hodnota zlyhaní** — Počet po sebe nasledujúcich zlyhaní poskytovateľa pred prechodom do stavu `OPEN`
- **Časový limit obnovenia** — Časové okno pred opätovným otestovaním poskytovateľa
- **CLOSED** (V poriadku) — Požiadavky sa spracúvajú normálne
- **DEGRADED** — Požiadavky sa naďalej spracúvajú, pričom sa sleduje zvýšený počet zlyhaní
- **OPEN** — Poskytovateľ je po opakovaných zlyhaniach dočasne zablokovaný
- **HALF_OPEN** — Testuje sa, či sa poskytovateľ zotavil
Obmedzenia rýchlosti `429` viazané na pripojenie zostávajú v režime **Čas na zotavenie pripojenia** a nezapočítavajú sa do ističa poskytovateľa.
Aktuálny stav ističa poskytovateľa sa zobrazuje iba v časti **Ovládací panel → Stav**.
4. **Čakať na zotavenie** — Ak sú už všetky kandidátske pripojenia v režime zotavenia, OmniRoute môže počkať na najskoršie zotavenie a automaticky zopakovať rovnakú požiadavku klienta.
5. **Automatická detekcia obmedzenia rýchlosti** — Keď nadradení poskytovatelia vrátia explicitné časové okná čakania, tieto pokyny prepíšu lokálny čas na zotavenie pripojenia, ak je toto nastavenie povolené.
**Profesionálny tip:** Na kontrolu a obnovenie aktívnych ističov poskytovateľov po výpadku použite stránku **Stav**. Stránka Odolnosť mení iba konfiguráciu.
---
### Export/import databázy
Spravujte zálohy databázy v časti **Ovládací panel → Nastavenia → Systém a úložisko**.
| Akcia | Opis |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Exportovať databázu** | Stiahne aktuálnu databázu SQLite ako súbor `.sqlite` |
| **Exportovať všetko (.tar.gz)** | Stiahne úplný archív zálohy vrátane databázy, nastavení, kombinácií, pripojení poskytovateľov (bez prihlasovacích údajov) a metadát kľúčov API |
| **Importovať databázu** | Nahrá súbor `.sqlite`, ktorý nahradí aktuálnu databázu. Pred importom sa automaticky vytvorí záloha, pokiaľ nie je nastavené `DISABLE_SQLITE_AUTO_BACKUP=true` |
```bash
# API: Export databázy
curl -o backup.sqlite http://localhost:20128/api/db-backups/export
# API: Export všetkého (úplný archív)
curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll
# API: Import databázy
curl -X POST http://localhost:20128/api/db-backups/import \
-F "file=@backup.sqlite"
```
**Overenie importu:** Importovaný súbor sa overí z hľadiska integrity (kontrola pomocou pragma SQLite), požadovaných tabuliek (`provider_connections`, `provider_nodes`, `combos`, `api_keys`) a veľkosti (max. 100 MB).
**Prípady použitia:**
- Migrácia OmniRoute medzi počítačmi
- Vytváranie externých záloh na obnovu po havárii
- Zdieľanie konfigurácií medzi členmi tímu (exportovať všetko → zdieľať archív)
---
### Ovládací panel nastavení
Stránka nastavení je kvôli jednoduchej navigácii usporiadaná do **7 kariet**:
| Karta | Obsah |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Všeobecné** | Nástroje systémového úložiska, predvolené správanie, viditeľnosť tunela Endpoint |
| **Vzhľad** | Ovládanie motívu (svetlý/tmavý/systémový), viditeľnosť bočného panela, prepínače panelov pre karty tunelov Cloudflare/Tailscale/ngrok |
| **AI** | Rozpočet na premýšľanie (odovzdanie bez zmeny / automatické odstránenie / vlastný / adaptívny — pozrite si [THINKING_BUDGET.md](./THINKING_BUDGET.md)), globálna systémová výzva, štatistiky vyrovnávacej pamäte výziev |
| **Zabezpečenie** | Nastavenia prihlásenia/hesla, riadenie prístupu podľa IP, autentifikácia API pre `/models`, blokovanie poskytovateľov, ochrana pred vložením škodlivých inštrukcií do výzvy |
| **Smerovanie** | Globálna stratégia smerovania (postupné napĺňanie / cyklické prideľovanie / P2C / náhodné / najmenej používané / optimalizované podľa nákladov), aliasy modelov so zástupnými znakmi, reťazce záložných možností, predvolené nastavenia kombinácií |
| **Odolnosť** | Front požiadaviek, interval obnovenia pripojenia, konfigurácia ističa poskytovateľa a správanie pri čakaní na skončenie intervalu obnovenia |
| **Pokročilé** | Globálna konfigurácia proxy (HTTP/SOCKS5), individuálne nastavenia proxy pre jednotlivých poskytovateľov |
Karta Všeobecné už neduplikuje informačné poznámky o protokolovaní a vyrovnávacej pamäti iba na čítanie. Nastavenia uchovávania a
optimalizácie databázy sa ukladajú prostredníctvom `/api/settings/database`; manuálne vymazanie vyrovnávacej pamäte používa
`DELETE /api/cache`. Limity počtu riadkov tabuliek protokolov požiadaviek a proxy sú riadené premennými
`CALL_LOGS_TABLE_MAX_ROWS` a `PROXY_LOGS_TABLE_MAX_ROWS`.
---
### Správa nákladov a rozpočtu
Prístup cez **Ovládací panel → Náklady**.
| Karta | Účel |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| **Rozpočet** | Nastavenie limitov výdavkov pre jednotlivé kľúče API pomocou denných/týždenných/mesačných rozpočtov a sledovania v reálnom čase |
| **Ceny** | Zobrazenie a úprava záznamov cien modelov — náklady na 1 000 vstupných/výstupných tokenov podľa poskytovateľa |
```bash
# API: Nastavenie rozpočtu
curl -X POST http://localhost:20128/api/usage/budget \
-H "Content-Type: application/json" \
-d '{"keyId": "key-123", "limit": 50.00, "period": "monthly"}'
# API: Získanie aktuálneho stavu rozpočtu
curl http://localhost:20128/api/usage/budget
```
**Sledovanie nákladov:** Každá požiadavka zaznamenáva využitie tokenov a vypočítava náklady pomocou tabuľky cien. Rozdelenie podľa poskytovateľa, modelu a kľúča API si môžete pozrieť v časti **Ovládací panel → Využitie**.
---
### Prepis zvuku
OmniRoute podporuje prepis zvuku prostredníctvom koncového bodu kompatibilného s OpenAI:
```bash
POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data
# Príklad s použitím 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` je natívna trasa Deepgram a vyžaduje kľúč API služby Deepgram.
Ak je nakonfigurovaný iba OpenRouter, použite `openrouter/deepgram/nova-3`.
Poskytovatelia funkcie **prevodu reči na text (prepisu)**:
- `openai/` (kompatibilné s Whisper)
- `groq/` (Groq Whisper Turbo)
- `deepgram/` (rodina Nova)
- `assemblyai/`
- `nvidia/` (Parakeet, Canary)
- `huggingface/` (varianty Whisper)
- `qwen/`
Poskytovatelia funkcie **prevodu textu na reč (`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/`
Podporované zvukové formáty pre prepis: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. Výstupné formáty TTS závisia od poskytovateľa (mp3, wav, opus, pcm, mulaw).
---
### Stratégie vyvažovania kombinácií
Vyvažovanie jednotlivých kombinácií nakonfigurujte v časti **Ovládací panel → Kombinácie → Vytvoriť/Upraviť → Stratégia**.
| Stratégia | Opis |
| --------------------------------- | -------------------------------------------------------------------------------------- |
| **Cyklické prideľovanie** | Postupne strieda jednotlivé modely |
| **Priorita** | Vždy najskôr skúsi prvý model; na záložný model prejde iba pri chybe |
| **Náhodné** | Pre každú požiadavku vyberie náhodný model z kombinácie |
| **Vážené** | Smeruje proporcionálne na základe váh priradených jednotlivým modelom |
| **Najmenej používané** | Smeruje na model s najmenším počtom nedávnych požiadaviek (používa metriky kombinácie) |
| **Optimalizované podľa nákladov** | Smeruje na najlacnejší dostupný model (používa tabuľku cien) |
Globálne predvolené nastavenia kombinácií možno nastaviť v časti **Ovládací panel → Nastavenia → Smerovanie → Predvolené nastavenia kombinácií**.
Časové limity cieľov kombinácie predvolene dedia aktuálny časový limit požiadavky. Možnosť **Časový limit cieľa
(sekundy)** v predvolených nastaveniach kombinácií alebo v samostatnej kombinácii použite iba vtedy, keď má kratší limit pre jednotlivé ciele
aktivovať rýchlejší prechod na záložnú možnosť.
Optimalizácie kombinácií s nulovou latenciou sú voliteľné. Možnosť **Optimalizácie s nulovou latenciou** nechajte vypnutú, aby
tieto funkcie latencie nesúťažili so záložnými cieľmi, nepreskakovali ciele na základe histórie TTFT
ani nekomprimovali záložné požiadavky; jej zapnutie umožňuje nakonfigurované súbežné odosielanie, prediktívne preskakovanie podľa TTFT
a proaktívnu kompresiu záložných požiadaviek, ktoré vymieňajú vernosť smerovania/požiadaviek za nižšiu
koncovú latenciu.
Vypnite **vyrovnávaciu pamäť tokenov uvažovania**, keď upstream poskytovatelia vyžadujú prísne limity
`max_tokens` / `maxOutputTokens`. Keď je táto možnosť povolená, kombinované smerovanie pridáva rezervu pre modely uvažovania
iba pri modeloch so známym limitom výstupu a ponecháva klientsky limit tokenov nezmenený, ak by
bezpečná hodnota s rezervou tento limit prekročila. Ak je klientsky limit už vyšší než známy limit,
OmniRoute ho pred odoslaním upstream požiadavky zníži na tento limit.
---
### Panel stavu
Prístup cez **Panel → Stav**. Prehľad stavu systému v reálnom čase so 6 kartami:
| Karta | Čo zobrazuje |
| ------------------------------- | ------------------------------------------------------------------------------ |
| **Stav systému** | Doba prevádzky, verzia, využitie pamäte, dátový adresár |
| **Stav poskytovateľov** | Globálny prevádzkový stav ističa poskytovateľov |
| **Limity požiadaviek** | Aktívne prestávky medzi pripojeniami pre jednotlivé účty so zostávajúcim časom |
| **Aktívne blokovania** | Aktívne blokovania viazané na model a dočasné vylúčenia |
| **Vyrovnávacia pamäť podpisov** | Štatistiky vyrovnávacej pamäte deduplikácie (aktívne kľúče, miera zásahov) |
| **Telemetria latencie** | Agregácia latencie p50/p95/p99 pre jednotlivých poskytovateľov |
**Praktický tip:** Stránka Stav sa automaticky obnovuje každých 10 sekúnd. Pomocou karty ističa môžete zistiť, ktorí poskytovatelia majú problémy.
---
## 🤖 Automatické smerovanie (bez konfigurácie)
OmniRoute obsahuje **automatický smerovač riadený skóre**, ktorý pre každú požiadavku vyberie najlepší model spomedzi všetkých pripojených poskytovateľov — bez potreby udržiavať kombinácie. Stačí odoslať požiadavku s jednou z predpôn `auto/*` a OmniRoute priebežne zostaví virtuálnu kombináciu, pričom kandidátov hodnotí podľa latencie, nákladov, úspešnosti, vhodnosti kontextu, vhodnosti modelu pre danú úlohu, nedávnych zlyhaní, kvóty a stavu ističa.
| Predpona | Optimalizuje pre |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `auto` | Vyvážené predvolené nastavenie (latencia × náklady × úspešnosť) |
| `auto/coding` | Programátorské úlohy: uprednostňuje Claude, GPT-5, GLM, Kimi, Qwen Coder a modely DeepSeek pre programovanie |
| `auto/cheap` | Najnižšia cena za token, akceptuje vyššiu latenciu |
| `auto/fast` | Najnižšia latencia, ignoruje náklady |
| `auto/offline` | Iba lokálni poskytovatelia (Ollama, vLLM, llama.cpp) — užitočné pre izolované prostredia |
| `auto/smart` | Na prvom mieste je kvalita uvažovania (Opus, GPT-5 xhigh, R1, uvažovanie GLM 5.1) |
| `auto/lkgp` | „Posledný známy funkčný poskytovateľ“ — pripne posledného úspešného poskytovateľa a následne použije pravidlá záložného prepnutia |
Príklad:
```bash
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
}'
```
Automatický smerovač je podrobne opísaný v dokumente [AUTO-COMBO.md](../routing/AUTO-COMBO.md) — vrátane postupu úpravy váh hodnotenia, pridávania poskytovateľov na čiernu listinu a kontroly rozhodnutí smerovania v časti **Ovládací panel → Automatická kombinácia**.
---
## 🔌 Integrácia MCP a A2A
OmniRoute je zároveň **server MCP** (Model Context Protocol) aj **server A2A** (Agent-to-Agent JSON-RPC 2.0). Ľubovoľné IDE alebo hostiteľ agenta kompatibilný s MCP môže priamo volať nástroje OmniRoute — nie je potrebná žiadna ďalšia obálka.
### Transporty MCP
- **SSE**: `http://localhost:20128/api/mcp/sse`
- **Streamovateľné HTTP**: `http://localhost:20128/api/mcp/stream`
- **stdio**: `omniroute --mcp` (pre zásuvné moduly IDE, ktoré uprednostňujú stdio)
### Pripojenie Claude Desktop
Upravte súbor `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) alebo jeho ekvivalent v systéme Windows/Linux:
```json
{
"mcpServers": {
"omniroute": {
"command": "omniroute",
"args": ["--mcp"]
}
}
}
```
### Pripojenie Cursor / Continue / VS Code MCP
Použite adresu URL SSE `http://localhost:20128/api/mcp/sse` a kľúč Bearer API vygenerovaný v časti **Ovládací panel → Kľúče API**.
### Rozsahy
MCP v súčasnosti definuje 32 pomenovaných rozsahov. Každý kľúč Bearer možno obmedziť na konkrétne rozsahy — autoritatívny zoznam rozsahov a nástrojov nájdete v dokumente [MCP-SERVER.md](../frameworks/MCP-SERVER.md) a schému JSON-RPC v dokumente [A2A-SERVER.md](../frameworks/A2A-SERVER.md).
---
## 🧠 Systém zručností
OmniRoute poskytuje rozšíriteľný **framework zručností** (`src/lib/skills/`), vďaka ktorému môžu agenti a koncový bod A2A spúšťať rutiny špecifické pre danú doménu (napr. `code-review`, `summarize`, `extract-facts`, `web-research`).
- **Používateľské rozhranie Marketplace** — Prehľadávajte a inštalujte zručnosti cez **Dashboard → Skills**
- **Rozsahy pre jednotlivé kľúče** — Obmedzte, ktoré API kľúče môžu spúšťať konkrétne zručnosti
- **Vlastné zručnosti** — Vložte súbor TypeScript do `src/lib/a2a/skills/`, zaregistrujte ho a okamžite ho bude možné spúšťať cez A2A
Kompletná dokumentácia: [SKILLS.md](../frameworks/SKILLS.md).
---
## 💾 Systém pamäte
OmniRoute uchováva **dlhodobú konverzačnú pamäť** s hybridným vyhľadávaním:
- **SQLite FTS5** na vyhľadávanie podľa kľúčových slov v predchádzajúcich interakciách
- **Vektorové úložisko Qdrant** (voliteľné) na sémantické vyhľadávanie
- **Automatická extrakcia faktov** — entity, preferencie a rozhodnutia sa po každej relácii zosumarizujú a uložia do tabuľky `memory_facts`
- Pamäte sú oddelené podľa API kľúča a relácie
Pamäte môžete spravovať cez **Dashboard → Memory** (vyhľadávanie, úpravy, export, vymazanie). Rozhranie HTTP (`/api/memory/*`) umožňuje agentom programovo odosielať fakty a vyhľadávať ich — pozrite si [MEMORY.md](../frameworks/MEMORY.md).
---
## 🔔 Webhooky
Prihláste sa na odber udalostí OmniRoute na monitorovanie a automatizáciu v reálnom čase.
- Vytvorte webhook cez **Dashboard → Webhooks** s cieľovou adresou URL a podpisovacím tajomstvom HMAC
- Dostupné udalosti: `request.completed`, `request.failed`, `provider.unavailable`, `budget.exceeded`, `combo.switched`, `circuit_breaker.opened`, `circuit_breaker.closed`
- Každá dátová časť obsahuje hlavičku `X-OmniRoute-Signature` (HMAC-SHA256) na overenie
- Opakované pokusy: 3 pokusy s exponenciálnym predlžovaním intervalov, potom presun do frontu neúspešných správ
Kompletná schéma je uvedená v [WEBHOOKS.md](../frameworks/WEBHOOKS.md).
---
## ☁️ Cloudoví agenti
OmniRoute sa integruje s cloudovými programovacími agentmi (**OpenAI Codex Cloud**, **Devin**, **Jules**, **Antigravity**), takže môžete odosielať dlhotrvajúce úlohy z rovnakého ovládacieho panela, ktorý spravuje vaše lokálne smerovanie.
- Vytvárajte úlohy cez **Dashboard → Cloud Agents** alebo pomocou `POST /api/v1/agents/tasks`
- Sledujte stav, protokoly a artefakty jednotlivých úloh
- Použite vlastný API kľúč pre každého poskytovateľa — prihlasovacie údaje nikdy neopustia inštanciu OmniRoute
Kompletná dokumentácia: [CLOUD_AGENT.md](../frameworks/CLOUD_AGENT.md).
---
## 🛠️ Programová správa
Každý prostriedok OmniRoute (poskytovateľov, kombinácie, kľúče, nastavenia) môžete spravovať cez HTTP pomocou **kľúča Bearer s rozsahom `manage`**.
Vygenerujte kľúč cez **Dashboard → API Keys → New Key → Scope: manage** a potom:
```bash
# Zobrazenie zoznamu poskytovateľov
curl http://localhost:20128/api/providers \
-H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY"
# Pridanie pripojenia k poskytovateľovi
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" }'
# Vytvorenie kombinácie
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" }] }'
# Zobrazenie zoznamu/vytvorenie API kľúčov
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"] }'
```
Kompletný katalóg koncových bodov a schémy požiadaviek/odpovedí nájdete v [API_REFERENCE.md](../reference/API_REFERENCE.md).
---
## 💻 Interné CLI
OmniRoute obsahuje interné CLI (`omniroute …`) na nastavenie, diagnostiku a riadenie za behu. Je **oddelené od stránky „Nástroje CLI“ v ovládacom paneli**, ktorá konfiguruje CLI nástroje tretích strán (Claude Code, Cursor, Codex, Cline, …), aby mohli komunikovať s OmniRoute.
```bash
omniroute setup # Interaktívny sprievodca (heslo, poskytovatelia, kombinácie)
omniroute setup --non-interactive # Vhodné pre CI
omniroute doctor # Diagnostika stavu (dátový adresár, DB, poskytovatelia, porty)
omniroute providers available # Zoznam podporovaných poskytovateľov
omniroute providers list # Zoznam nakonfigurovaných pripojení
omniroute providers test # Test pripojenia k poskytovateľovi v reálnom čase
omniroute combos list # Zoznam kombinácií
omniroute combos switch # Nastavenie predvolenej kombinácie
omniroute models # Zoznam dostupných modelov (--json, --search)
omniroute keys add | list | remove # Správa kľúčov API z terminálu
omniroute backup # Snímka konfigurácie + DB
omniroute restore [] # Obnovenie zo snímky
omniroute health # Podrobný stav (ističe, vyrovnávacia pamäť, pamäť)
omniroute quota # Využitie kvót poskytovateľov
omniroute mcp status # Stav servera MCP
omniroute a2a status # Stav servera A2A
omniroute tunnel list|create|stop # Tunely Cloudflare/Tailscale/ngrok
omniroute reset-password # Obnovenie hesla správcu
omniroute --mcp # Spustenie servera MCP cez stdio
omniroute --port 3000 # Spustenie servera na vlastnom porte
```
Tip: prepojte `omniroute doctor --json` so svojím monitorovacím nástrojom, aby vás upozornil na nefunkčné pripojenia k poskytovateľom.
---
## 🖥️ Desktopová aplikácia (Electron)
OmniRoute je k dispozícii ako natívna desktopová aplikácia pre Windows, macOS a Linux.
### Inštalácia
```bash
# Z adresára electron:
cd electron
npm install
# Vývojový režim (pripojenie k spustenému vývojovému serveru Next.js):
npm run dev
# Produkčný režim (používa samostatné zostavenie):
npm start
```
### Zostavenie inštalátorov
```bash
cd electron
npm run build # Aktuálna platforma
npm run build:win # Windows (.exe NSIS)
npm run build:mac # macOS (.dmg univerzálny)
npm run build:linux # Linux (.AppImage)
```
Výstup → `electron/dist-electron/`
### Kľúčové funkcie
| Funkcia | Opis |
| ------------------------------ | ----------------------------------------------------------------- |
| **Pripravenosť servera** | Pred zobrazením okna kontroluje server (žiadna prázdna obrazovka) |
| **Systémová lišta** | Minimalizácia do lišty, zmena portu, ukončenie z ponuky lišty |
| **Správa portu** | Zmena portu servera z lišty (automaticky reštartuje server) |
| **Zásady zabezpečenia obsahu** | Reštriktívne CSP prostredníctvom hlavičiek relácie |
| **Jedna inštancia** | Naraz môže byť spustená iba jedna inštancia aplikácie |
| **Režim offline** | Pribalený server Next.js funguje bez internetu |
### Premenné prostredia
| Premenná | Predvolená hodnota | Opis |
| --------------------- | ------------------ | --------------------------------- |
| `OMNIROUTE_PORT` | `20128` | Port servera |
| `OMNIROUTE_MEMORY_MB` | `512` | Limit haldy Node.js (64–16384 MB) |
📖 Úplná dokumentácia: [`electron/README.md`](../../electron/README.md)