# User Guide (Čeština)
🌐 **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) · 🇩🇰 [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) · 🇸🇰 [sk](../../../sk/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) · 🇩🇰 [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) · 🇸🇰 [sk](../../../sk/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ůvodce konfigurací poskytovatelů, vytvářením kombinací, integrací nástrojů CLI a nasazením OmniRoute.
---
## Obsah
- [Přehled cen](#-pricing-at-a-glance)
- [Případy použití](#-use-cases)
- [Nastavení poskytovatele](#-provider-setup)
- [Integrace CLI](#-cli-integration)
- [Nasazení](#-deployment)
- [Dostupné modely](#-available-models)
- [Pokročilé funkce](#-advanced-features)
- [Automatické směrování (bez konfigurace)](#-auto-routing-zero-config)
- [Integrace MCP a A2A](#-mcp--a2a-integration)
- [Systém dovedností](#-skills-system)
- [Paměťový systém](#-memory-system)
- [Webhooky](#-webhooks)
- [Cloudoví agenti](#-cloud-agents)
- [Programová správa](#-programmatic-management)
- [Interní CLI](#-internal-cli)
- [Desktopová aplikace (Electron)](#-desktop-application-electron)
---
## 💰 Přehled cen
| Úroveň | Poskytovatel | Cena | Obnovení kvóty | Nejvhodnější pro |
| ----------------- | ----------------- | ----------------- | -------------------------- | --------------------------- |
| **💳 PŘEDPLATNÉ** | Claude Code (Pro) | $20/měsíc | 5 h + týdně | Stávající předplatitele |
| | Codex (Plus/Pro) | $20–200/měsíc | 5 h + týdně | Uživatele OpenAI |
| | GitHub Copilot | $10–19/měsíc | Měsíčně | Uživatele GitHubu |
| **🔑 API KLÍČ** | DeepSeek | Platba za využití | Žádné | Levné uvažování |
| | Groq | Platba za využití | Žádné | Ultrarychlou inferenci |
| | xAI (Grok) | Platba za využití | Žádné | Uvažování Grok 4 |
| | Mistral | Platba za využití | Žádné | Modely hostované v EU |
| | Perplexity | Platba za využití | Žádné | Rozšíření o vyhledávání |
| | Together AI | Platba za využití | Žádné | Open-source modely |
| | Fireworks AI | Platba za využití | Žádné | Rychlé obrázky FLUX |
| | Cerebras | Platba za využití | Žádné | Rychlost na úrovni waferu |
| | Cohere | Platba za využití | Žádné | Command R+ RAG |
| | NVIDIA NIM | Platba za využití | Žádné | Podnikové modely |
| | Baidu Qianfan | Platba za využití | Žádné | Modely ERNIE |
| **💰 LEVNÉ** | GLM-4.7 | $0.6/1M | Denně v 10:00 | Levnou zálohu |
| | MiniMax M2.1 | $0.2/1M | Průběžně po 5 hodinách | Nejlevnější možnost |
| | Kimi K2 | Paušál $9/měsíc | 10M tokenů/měsíc | Předvídatelné náklady |
| **🆓 ZDARMA** | Qoder | $0 | Platí limity poskytovatele | Ověření aktuálního katalogu |
| | Kiro | $0 | ~50 kreditů/měsíc | Claude zdarma |
---
## 🎯 Případy použití
### Případ 1: „Mám předplatné Claude Pro“
**Problém:** Kvóta vyprší nevyužitá, při intenzivním programování narážím na limity požadavků
```
Kombinace: "maximize-claude"
1. cc/claude-opus-4-7 (plné využití předplatného)
2. glm/glm-4.7 (levná záloha po vyčerpání kvóty)
3. if/qwen3.8-max-preview (bezplatná nouzová alternativa)
Měsíční náklady: $20 (předplatné) + ~$5 (záloha) = celkem $25
oproti $20 + narážení na limity = frustrace
```
### Případ 2: „Chci nulové náklady“
**Problém:** Nemohu si dovolit předplatné a potřebuji spolehlivou AI pro programování
```
Kombinace: "zero-cost"
1. if/kimi-k2.7-code (uvedený bezplatný přístup; mohou platit limity požadavků)
2. kr/qwen3-coder-next (bezplatná alternativa Kiro)
Měsíční náklady: $0
Kvalita: ověřte model, limity, ochranu soukromí a SLA pro své pracovní zatížení
```
### Případ 3: „Potřebuji programovat 24/7 bez přerušení“
**Problém:** Mám termíny a nemohu si dovolit výpadky
```
Kombinace: "always-on"
1. cc/claude-opus-4-7 (nejlepší kvalita)
2. cx/gpt-5.5 (druhé předplatné)
3. glm/glm-4.7 (levné, obnovuje se denně)
4. minimax/MiniMax-M2.1 (nejlevnější, obnovení po 5 h)
5. if/deepseek-v4-flash (uvedený bezplatný přístup; mohou platit limity požadavků)
Výsledek: 5 záložních vrstev zvyšuje odolnost; dostupnost externích služeb není zaručena
Měsíční náklady: $20–200 (předplatná) + $10–20 (záloha)
```
### Případ 4: „Chci v OpenClaw AI ZDARMA“
**Problém:** Potřebuji AI asistenta v komunikačních aplikacích, zcela zdarma
```
Kombinace: "openclaw-free"
1. if/qwen3.8-max-preview (uvedený bezplatný přístup; mohou platit limity požadavků)
2. if/deepseek-v4-flash (uvedený bezplatný přístup; mohou platit limity požadavků)
3. if/kimi-k2.7-code (uvedený bezplatný přístup; mohou platit limity požadavků)
Měsíční náklady: $0
Přístup přes: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
```
---
## 📖 Nastavení poskytovatelů
Pro hromadné přidání připojení s klíčem API ze souboru CSV nebo JSON použijte **Přehled → Poskytovatelé → Importovat ze souboru**. Sloupce jsou poziční (`provider,name,apiKey,baseUrl,priority`); `provider` již musí existovat jako spravovaný poskytovatel nebo kompatibilní uzel. Viz [Import poskytovatelů ze souboru CSV nebo JSON](../providers/CSV-IMPORT.md).
### 🔐 Poskytovatelé předplatného
#### Claude Code (Pro/Max)
```bash
Přehled → Poskytovatelé → Připojit Claude Code
→ Přihlášení přes OAuth → Automatické obnovení tokenu
→ Sledování 5hodinového + týdenního limitu
Modely:
cc/claude-opus-4-7
cc/claude-sonnet-4-6
cc/claude-haiku-4-5-20251001
```
**Tip:** Pro složité úlohy používejte Opus, pro rychlost Sonnet. OmniRoute sleduje limit pro každý model!
Nemáte na hostiteli OmniRoute prohlížeč? Spusťte `claude setup-token` kdekoli, kde jste přihlášeni ke Claude Code, a vložte jednoletý token na kartu **Nastavovací token**. Viz [Claude Code s nastavovacím tokenem](../providers/CLAUDE_CODE_SETUP_TOKEN.md).
Trasy kompatibilní s Claude a Claude Code zachovávají úroveň přemýšlení `max` pro
modely Opus a Sonnet. Modely Haiku úroveň úsilí `max` nepřijímají, takže OmniRoute tento
požadavek před odesláním upstreamu sníží na vysoký rozpočet přemýšlení.
#### OpenAI Codex (Plus/Pro)
```bash
Přehled → Poskytovatelé → Připojit Codex
→ Přihlášení přes OAuth (port 1455)
→ 5hodinový + týdenní reset
Modely:
cx/gpt-5.5
cx/gpt-5.4
cx/gpt-5.3-codex
cx/gpt-5.3-codex-spark
```
#### GitHub Copilot
```bash
Přehled → Poskytovatelé → Připojit GitHub
→ OAuth přes GitHub
→ Měsíční reset (1. den v měsíci)
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
```
**AI kredity (účtování podle tokenů).** Když GitHub pro účet vrátí `credits_used`,
karta Limitů poskytovatele zobrazí řádek **AI kredity** se spotřebovanými kredity
v aktuálním fakturačním období, a to i u neomezených organizačních plánů.
**Místní limit AI kreditů.** Upravte připojení GitHub a nastavte **Limit AI kreditů na
fakturační období** (`providerSpecificData.githubCreditLimit`). Prázdná hodnota tuto
funkci deaktivuje; `0` připojení vždy přeskočí. Když je poslední odečet využití na
úrovni limitu nebo nad ní, výběr účtu toto připojení přeskočí a směrování přejde na
vaše ostatní připojení, stejně jako při dosažení limitu podle zásad kvóty. Kontrola
čte využití, které již shromažďuje pravidelné obnovení kvóty — na cestě požadavku nikdy
nevolá GitHub — a při chybě se připojení neblokuje: chybějící nebo zastaralý odečet
(starší než 15 minut nebo z fakturačního období, které již bylo resetováno) připojení
neblokuje. Jde o místní ochranu, **nikoli o zaručený strop výdajů**: zpoždění
vykazování GitHubu, interval obnovování, probíhající požadavky a využití mimo
OmniRoute mohou limit překročit. Pro pevný strop používejte vlastní limity výdajů
v GitHubu.
### 💰 Levní poskytovatelé
#### GLM-4.7 (denní reset, $0.6/1M)
1. Zaregistrujte se: [Zhipu AI](https://open.bigmodel.cn)
2. Získejte klíč API z Coding Plan
3. Přehled → Přidat klíč API: Poskytovatel: `glm`, Klíč API: `your-key`
**Použití:** `glm/glm-4.7` — **Tip:** Coding Plan nabízí trojnásobnou kvótu za sedminovou cenu! Reset každý den v 10:00.
#### MiniMax M2.1 (5hodinový reset, $0.20/1M)
1. Zaregistrujte se: [MiniMax](https://www.minimax.io)
2. Získejte klíč API → Přehled → Přidat klíč API
**Použití:** `minimax/MiniMax-M2.1` — **Tip:** Nejlevnější možnost pro dlouhý kontext (1M tokenů)!
#### Kimi K2 ($9/měsíc paušálně)
1. Předplaťte si službu: [Moonshot AI](https://platform.kimi.ai?aff=omniroute)
2. Získejte klíč API → Přehled → Přidat klíč API
**Použití:** `kimi/kimi-k2.5` — **Tip:** Pevná cena $9/měsíc za 10M tokenů = efektivní cena $0.90/1M!
#### Baidu Qianfan / ERNIE
1. Zaregistrujte se: [Baidu AI Cloud Qianfan](https://cloud.baidu.com/product/wenxinworkshop)
2. Vytvořte klíč API Qianfan → Přehled → Přidat klíč API: Poskytovatel: `qianfan`
**Použití:** `qianfan/ernie-5.1`, `qianfan/ernie-x1.1` nebo jiný identifikátor modelu kompatibilního s OpenAI API v Qianfanu.
### 🆓 BEZPLATNÍ poskytovatelé
Bezplatní poskytovatelé bez ověřování mají na své stránce přepínač vedle možnosti **Není vyžadováno ověření**.
Jeho vypnutím poskytovatele deaktivujete, odeberete ho ze zobrazení nakonfigurovaných poskytovatelů / kompaktního zobrazení
a odeberete jeho modely z `/v1/models`.
#### Qoder (9 BEZPLATNÝCH modelů)
```bash
Přehled → Připojit Qoder → Přihlášení přes OAuth → Přístup podléhá aktuálním limitům poskytovatele
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 (BEZPLATNÝ Claude)
```bash
Přehled → Připojit Kiro → AWS Builder ID nebo Google/GitHub → přibližně 50 kreditů/měsíc
Modely: kr/claude-sonnet-4.5, kr/claude-haiku-4.5
```
---
## 🎨 Kombinace
Karty kombinací můžete přeskupit přímo v části **Řídicí panel → Kombinace** přetažením úchytu na každé kartě. Pořadí se ukládá do SQLite a po opětovném načtení se obnoví.
### Příklad 1: Maximální využití předplatného → Levná záloha
```
Řídicí panel → Kombinace → Vytvořit novou
Název: premium-coding
Modely:
1. cc/claude-opus-4-7 (Primární model z předplatného)
2. glm/glm-4.7 (Levná záloha, $0.6/1M)
3. minimax/MiniMax-M2.7 (Nejlevnější záložní varianta, $0.3/1M)
Použití v CLI: premium-coding
```
### Příklad 2: Pouze bezplatné modely (nulové náklady)
```
Název: free-combo
Modely:
1. if/kimi-k2.7-code (uváděn s bezplatným přístupem; mohou platit omezení poskytovatele)
2. kr/qwen3-coder-next (bezplatná záložní varianta Kiro)
Cena: aktuálně uváděna jako $0; podmínky a dostupnost se mohou změnit
```
---
## 🔧 Integrace s CLI
### Cursor IDE
**Použití Cursoru jako klienta OmniRoute** (směrování chatu Cursoru přes OmniRoute):
```
Nastavení → Modely → Pokročilé:
Základní URL OpenAI API: http://localhost:20128/v1
Klíč OpenAI API: [z řídicího panelu OmniRoute]
Model: cc/claude-opus-4-7
```
**Použití OmniRoute jako poskytovatele Cursoru** (OmniRoute volá Cursor jako nadřazenou službu): upřednostněte
**Řídicí panel → Poskytovatelé → Cursor → Přihlásit se pomocí Cursoru**. Pro Docker viz
[`docs/providers/CURSOR-DOCKER.md`](../providers/CURSOR-DOCKER.md).
### Claude Code
Upravte `~/.claude/settings.json`:
```json
{
"env": {
"ANTHROPIC_BASE_URL": "http://localhost:20128",
"ANTHROPIC_AUTH_TOKEN": "your-omniroute-api-key"
}
}
```
Zde použijte kořenový koncový bod kompatibilní s Claude. K `ANTHROPIC_BASE_URL` nepřidávejte `/v1`.
### Codex CLI
```bash
export OPENAI_BASE_URL="http://localhost:20128"
export OPENAI_API_KEY="your-omniroute-api-key"
codex "your prompt"
```
### OpenClaw
Upravte `~/.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" }]
}
}
}
}
```
**Nebo použijte řídicí panel:** Nástroje CLI → OpenClaw → Automatická konfigurace
### Cline / Continue / RooCode
```
Poskytovatel: Kompatibilní s OpenAI
Základní URL: http://localhost:20128/v1
Klíč API: [z řídicího panelu]
Model: cc/claude-opus-4-7
```
---
## Nasazení 🚀
### Globální instalace npm (doporučeno)
```bash
npm install -g omniroute
# Create config directory
mkdir -p ~/.omniroute
# Create .env file (see .env.example)
cp .env.example ~/.omniroute/.env
# Start server
omniroute
# Or with custom port:
omniroute --port 3000
```
CLI automaticky načte `.env` z `~/.omniroute/.env` nebo `./.env`. `./.env` v pracovním adresáři může nastavit pouze krátký seznam povolených klíčů (porty, `REQUIRE_API_KEY`, národní prostředí a nastavení barev); vše ostatní vložte do `~/.omniroute/.env`. Viz [smlouvy na uvedení CLI](CLI-LAUNCH-CONTRACTS.md#working-directory-env).
### Režim zásobníku
Spusťte OmniRoute v systémové liště:
```bash
omniroute serve --tray
```
Příkaz se vrátí poté, co jsou server a zásobník připraveny.
Server pokračuje bez terminálu.
Režim zásobníku podporuje relace macOS, Windows a grafické Linux. Režim zásobníku neotevře palubní desku automaticky.
Použijte nabídku zásobníku pro tyto akce:
- Otevřete palubní desku.
- Otevřete `/dashboard/logs`.
- Změňte automatické spouštění.
- Stop OmniRoute.
Nekombinujte `--tray` s těmito možnostmi:
- `--daemon`
- `--log`
- `--no-recovery`
Tyto režimy vyžadují různé vlastnictví procesu.
Povolit spuštění při příštím přihlášení počítače:
```bash
omniroute autostart enable
```
Automatické spuštění používá režim zásobníku u relací macOS, Windows a grafického Linux. Headless Linux využívá stávající uživatelskou službu systemd.
Zakázat spouštění při přihlášení:
```bash
omniroute autostart disable
```
### Odinstalování
Když již nepotřebujete OmniRoute, nabízíme dva rychlé skripty pro čisté odstranění:
| Příkaz | Akce |
| ------------------------ | ------------------------------------------------------------------------------------- |
| `npm run uninstall` | Odebere systémovou aplikaci, ale** uchovává vaše DB a konfigurace** v `~/.omniroute`. |
| `npm run uninstall:full` | Trvale odstraní aplikaci AND** vymaže všechny konfigurace, klíče a databáze** . |
> Poznámka: Chcete-li tyto příkazy spustit, přejděte do složky projektu OmniRoute (pokud jste ji naklonovali) a spusťte je. Případně, pokud je globálně nainstalován, můžete jednoduše spustit `npm uninstall -g omniroute`.
### Nasazení 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
# Or: pm2 start npm --name omniroute -- start
```
### Nasazení PM2 (málo paměti)
Pro servery s omezeným RAM použijte možnost limit paměti:
```bash
# With 512MB limit (default)
pm2 start npm --name omniroute -- start
# Or with custom memory limit
OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start
# Or using ecosystem.config.js
pm2 start ecosystem.config.js
```
Vytvořit `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
# Build image (default = runner-cli with codex/claude/droid preinstalled)
docker build -t omniroute:cli .
# Portable mode (recommended)
docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli
```
Informace o režimu integrovaném do hostitele s binárními soubory CLI naleznete v části Docker v hlavních dokumentech.
### Void Linux (xbps-src)
Uživatelé Void Linux mohou zabalit a nainstalovat OmniRoute nativně pomocí rámce křížové kompilace `xbps-src`. To automatizuje samostatné sestavení Node.js spolu s požadovanými nativními vazbami `better-sqlite3`.
Zobrazit šablonu xbps-src
```bash
# Template file for '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() {
# Determine target CPU arch for 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) Install all deps – skip scripts
NODE_ENV=development npm ci --ignore-scripts
# 2) Build the Next.js standalone bundle
npm run build
# 3) Copy static assets into standalone
cp -r .next/static .next/standalone/.next/static
[ -d public ] && cp -r public .next/standalone/public || true
# 4) Compile better-sqlite3 native binding
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) Place the compiled binding into the standalone bundle
local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
mkdir -p "$_bs3_release"
cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
# 6) Remove arch-specific sharp bundles
rm -rf .next/standalone/node_modules/@img
# 7) Copy pino runtime deps omitted by Next.js static analysis:
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
# Prevent removal of empty Next.js app router dirs by the post-install hook
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
}
```
### Proměnné prostředí
| Variabilní | Výchozí | Popis |
| --------------------------------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `JWT_SECRET` | _(automaticky vygenerováno)_ | tajné podepisování JWT — automaticky vygenerováno při prvním spuštění a přetrvává do `server.env`; nastavte jej explicitně, když je datový adresář pomíjivý |
| `INITIAL_PASSWORD` | _(nenastaveno)_ | První přihlašovací heslo. instalace npm/source začínají na `CHANGEME`: nahraďte jej. Nenastaveno: průvodce pro přihlášení |
| `DATA_DIR` | `~/.omniroute` | Datový adresář (db, využití, protokoly) |
| `PORT` | výchozí nastavení rámce | Servisní port (v příkladech `20128` ) |
| `HOSTNAME` | výchozí nastavení rámce | Svázat hostitele (Docker výchozí `0.0.0.0`) |
| `NODE_ENV` | výchozí runtime | Nastavte `production` pro nasazení |
| `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128` | Veřejná základna URL se objevila na řídicím panelu a byla vystavena serveru (nahrazuje starší `BASE_URL`) |
| `NEXT_PUBLIC_CLOUD_URL` | `https://omniroute.dev` | Cloud synchronizace koncového bodu základní URL (nahrazuje starší `CLOUD_URL`) |
| `API_KEY_SECRET` | _(automaticky vygenerováno)_ | HMAC secret pro vygenerované klíče API — se automaticky vygenerovalo při prvním spuštění a zůstalo zachováno do `server.env` |
| `REQUIRE_API_KEY` | `false` | Vynutit Bearer API klíč na `/v1/*` |
| `ALLOW_API_KEY_REVEAL` | `false` | Umožněte ověřeným uživatelům řídicích panelů na vyžádání odhalit úplné uložené hodnoty klíče API |
| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Obnovovací kadence na straně serveru pro data o limitech poskytovatelů uložená v mezipaměti; Tlačítka UI refresh stále spouštějí manuální synchronizaci |
| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Zakázat automatické snímky SQLite před writes/import/restore; ruční zálohování stále funguje |
| `APP_LOG_TO_FILE` | `true` | Umožňuje výstup protokolu aplikace a auditu na disk |
| `AUTH_COOKIE_SECURE` | `false` | Vynutit `Secure` auth cookie (za HTTPS reverzní proxy) |
| `CLOUDFLARED_BIN` | odstaveno | Místo řízeného stahování použijte existující binární soubor `cloudflared` |
| `CLOUDFLARED_PROTOCOL` | `http2` | Přeprava pro spravované rychlé tunely (`http2`, `quic` nebo `auto`) |
| `OMNIROUTE_MEMORY_MB` | `512` | limit haldy Node.js v MB |
| `PROMPT_CACHE_MAX_SIZE` | `50` | Maximální počet položek mezipaměti |
| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Maximální počet položek sémantické mezipaměti |
Úplný odkaz na proměnné prostředí naleznete v souboru [README](../README.md).
---
## 📊 Dostupné modely
Zobrazit všechny dostupné modely
> Níže uvedený seznam je sestaven ze souboru `open-sse/config/providerRegistry.ts` pro v3.8.0. Cloudové katalogy (Gemini, OpenRouter atd.) se synchronizují dynamicky — úplný aktuální katalog otevřete v **Dashboard → Providers → [provider] → Available Models** nebo zavolejte `GET /api/models/catalog`.
>
> Pokud se vestavěný seznam poskytovatele změnil, použijte na této stránce možnost **Import from /models** (nebo povolte **Auto-Sync**) a načtěte aktuální katalog upstreamu. Toto bylo ověřeno ve v3.8.50 pro LLM7.io (`gemini-3.1-flash-lite`) a UncloseAI (`solidrust/Hermes-3-Llama-3.1-8B-AWQ`); anonymní přístup Pollinations zůstal během stejného testovacího průchodu omezený ze strany upstreamu.
**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` (+ úrovně úsilí: `gpt-5.5-xhigh`, `gpt-5.5-high`, `gpt-5.5-medium`, `gpt-5.5-low`), `cx/gpt-5.4`, `cx/gpt-5.4-mini`, `cx/gpt-5.3-codex`, `cx/gpt-5.3-codex-spark`
**GitHub Copilot (`gh/`)** — OAuth: `gh/gpt-5.5`, `gh/gpt-5.4`, `gh/gpt-5.4-mini`, `gh/gpt-5-mini`, `gh/gpt-5.3-codex`, `gh/claude-opus-4.7`, `gh/claude-opus-4.6`, `gh/claude-opus-4-5-20251101`, `gh/claude-sonnet-4.6`, `gh/claude-sonnet-4.5`, `gh/claude-haiku-4.5`, `gh/gemini-3.1-pro-preview`, `gh/gemini-3-flash-preview`, `gh/oswe-vscode-prime`
**Kiro (`kr/`)** — OAuth ZDARMA: použijte aktuální katalog zobrazený v **Dashboard → Providers → Kiro → Available Models**. Dostupnost závisí na účtu a tarifu.
**Qoder (`if/`)** — OAuth ZDARMA: `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 USD/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 USD/1M: `minimax/MiniMax-M2.7`, `minimax/MiniMax-M2.7-highspeed`, `minimax/MiniMax-M2.5`, `minimax/MiniMax-M2.5-highspeed`
**Kimi (`kimi/`, `kimi-coding/`, `kimi-coding-apikey/`)** — 9 USD/měsíc paušálně nebo podle využití: `kimi/kimi-k2.6`, `kimi/kimi-k2.5`
**DeepSeek (`ds/`)** — klíč API: `ds/deepseek-v4-pro`, `ds/deepseek-v4-flash`
**Groq (`groq/`)** — ultra rychlé: `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/`)** — nativní 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 EU: `mistral/mistral-large-latest`, `mistral/mistral-medium-3-5`, `mistral/mistral-small-latest`, `mistral/codestral-latest`
**Perplexity (`pplx/`)** — rozšířené vyhledáváním: `pplx/sonar-deep-research`, `pplx/sonar-reasoning-pro`, `pplx/sonar-pro`, `pplx/sonar`
**Together AI (`together/`)** — open source: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo-Free` (zdarma), `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/`)** — rychlá inference: `fireworks/accounts/fireworks/models/kimi-k2p6`, `fireworks/accounts/fireworks/models/minimax-m2p7`, `fireworks/accounts/fireworks/models/qwen3p6-plus`, `fireworks/accounts/fireworks/models/glm-5p1`, `fireworks/accounts/fireworks/models/deepseek-v4-pro`
**Cerebras (`cerebras/`)** — v měřítku waferu: `cerebras/zai-glm-4.7`, `cerebras/gpt-oss-120b`
**Cohere (`cohere/`)** — zaměřené 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/`)** — pro podnikové použití: `nvidia/google/gemma-4-31b-it`, `nvidia/nvidia/nemotron-3.5-super-vl-120b-a12b`, `nvidia/nvidia/nemotron-3-ultra-550b-a55b`, `nvidia/nvidia/nemotron-3.5-lightning-30b-a3b`
**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 se aktuálně podle klíče API ze služby Google — žádný statický seznam. Připojte klíč v **Dashboard → Providers** a pomocí **Available Models** importujte aktuální katalog (např. `gemini/gemini-3-pro`, `gemini/gemini-3-flash`).
**Další kompatibilní poskytovatelé** (vybraní): `cohere`, `databricks`, `snowflake`, `together`, `vertex`, `alibaba`, `alibaba-cn`, `bedrock` (prostřednictvím `aws-bedrock`), `azure-ai`, `openrouter` (katalog passthrough), `siliconflow`, `hyperbolic`, `huggingface`, `featherless-ai`, `cloudflare-ai`, `scaleway`, `deepinfra`, `vercel-ai-gateway`, `bazaarlink`, `friendliai`, `nous-research`, `reka`, `volcengine`, `ai21`, `gigachat`. Každý z nich udržuje vlastní seznam modelů v `providerRegistry.ts` a lze jej automaticky synchronizovat, pokud poskytovatel zpřístupňuje koncový bod `/models`.
**Poznámka k ID modelů:** OmniRoute používá nativní ID poskytovatelů (`claude-opus-4-8`, `gpt-5.5`, `glm-5.1`, `MiniMax-M2.7`, `kimi-k2.5`, `grok-4.20-0309-reasoning`). Některá ID obsahují verze s tečkami, protože právě tak je očekává upstreamové API. Pokud model není uveden výše, spusťte `omniroute models --search ` nebo zavolejte `GET /api/models/catalog` a ověřte jeho dostupnost.
---
## Pokročilé funkce 🧩
### Vlastní modely
Přidejte jakýkoli model ID k libovolnému poskytovateli bez čekání na aktualizaci aplikace:
```bash
# Via 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"}'
# List: curl http://localhost:20128/api/provider-models?provider=openai
# Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-5.2"
```
Nebo použijte Dashboard:** Poskytovatelé → [Poskytovatel] → Vlastní modely** .
Poznámky:
- Poskytovatelé OpenRouter a OpenAI/Anthropic-compatible jsou spravováni z** Dostupné modely** pouze. Ručně přidávejte, importujte a automaticky synchronizujte všechny pozemky ve stejném seznamu dostupných modelů, takže pro tyto poskytovatele neexistuje žádná samostatná sekce Vlastní modely.
- The** Vlastní modely** je určena pro poskytovatele, kteří nevystavují importy spravovaných dostupných modelů.
### Vlastní poskytovatelé kompatibilní s OpenAI
Jakoukoli bránu, která mluví OpenAI API (samostatně hostovaný proxy, vLLM, agregátor třetí strany), lze přidat jako svůj vlastní uzel poskytovatele:
1. **Poskytovatelé → Přidat OpenAI kompatibilní** .
2. **Jméno** : zobrazovaný štítek pro uzel.
3. **Předpona** : název směrování. Klienti nazývají modely jako `/`, takže uzel s předponou `mygw` slouží `mygw/gpt-4o-mini`. Požadovaný; neexistuje žádné omezení charakteru.
4. **Typ API** : rodina koncových bodů, které brána obsluhuje (dokončení chatu, odpovědi, vkládání, zvuk, obrázky).
5. **Základna URL** : kořen API až do `/v1` včetně (například `https://gateway.example.com/v1`), nikoli úplná cesta `/chat/completions`. Brány s nestandardními cestami je nastavte pod** Pokročilá nastavení** (cesta chatu, cesta modelů).
6. The**API klíč (pro kontrolu)** pole pouze testuje připojení. Po vytvoření uzlu jej otevřete a použijte** Přidat připojení** k uložení klíče, který budou požadavky používat.
Uzel získá interní id ve tvaru `openai-compatible--`; nemusíte jej nikdy psát, předpona je veřejný název.
#### Vyhrazené předpony
Předpona nemůže být id nebo alias vestavěného poskytovatele (například `openai`, `cf`), ani id vyřazeného poskytovatele. Překladač modelu kontroluje vestavěná ID a aliasy před vlastními uzly, takže uzel používající jednu z těchto předpon by nikdy neobdržel provoz: `/model` by místo toho přešel k vestavěnému poskytovateli nebo by selhal, pokud by byl poskytovatel vyřazen. Vytvoření nebo úprava uzlu s takovou předponou je odmítnuta s:
```text
prefix: "" is a reserved provider prefix — choose a different prefix (reserved ids/aliases cannot be used for custom nodes because requests like /model route to a built-in provider or fail closed when retired)
```
Vyberte odlišnou předponu (`mygw`, `acme-proxy`). Pokud požadavky na vlastní uzel selžou s chybou, která uvádí vestavěného poskytovatele nebo jeho pověření, zkontrolujte, zda je předpona uzlu vyhrazena: uzly uložené před existencí tohoto pravidla jsou stále uloženy, ale jejich předpona je směrována k vestavěnému poskytovateli. Upravte uzel a dejte mu novou předponu.
#### Možnosti brány podle připojení
Tyto klíče jdou do `providerSpecificData` připojení (například přes `PUT /api/providers/{id}`):
- `toolNameMaxLength` (celé číslo, 1–1024) — pro připojení kompatibilní s formátem chatu OpenAI, jejichž brána odmítá dlouhé názvy nástrojů. Delší názvy jsou odesílány jako krátké aliasy a obnoveny v odpovědi.
- `quotaEndpoint` — koncový bod quota/credits brány, čtení pro pás kvót řídicího panelu a směrování s ohledem na kvóty. Funguje na připojení kompatibilních s OpenAI i Anthropic; plný tvar je doložen v `open-sse/services/usage/openaiCompatible.ts`.
```json
{
"toolNameMaxLength": 64,
"quotaEndpoint": {
"url": "https://gateway.example.com/key/info",
"auth": "bearer",
"quotas": {
"budget": { "used": "$.info.spend", "total": "$.info.max_budget", "currency": "USD" }
}
}
}
```
### Řetězení OmniRoute Peers
Další bránu OmniRoute lze přidat jako a** Vlastní kompatibilní s OpenAI** poskytovatel. Použijte základ `/v1` URL partnera a vyhrazený klíč API s nejnižším oprávněním vydaný tímto partnerem.
U recipročních nebo víceskokových řetězců povolte volitelnou ochranu smyčky na každé bráně:
```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
```
Záhlaví `X-OmniRoute-Peer-Trace` obdrží pouze požadavky odeslané přímo na seznamu povolených peer URL. Brána odmítá opakovanou instanci ID nebo vyčerpaný skokový rozpočet pomocí HTTP `508 Loop Detected`; běžní upstream poskytovatelé neobdrží žádná peer metadata.
Zřetězení rovnocenných partnerů není replikace databáze nebo převzetí služeb při selhání hostitele. Každá brána udržuje nezávislý stav SQLite, mezipaměti, čítače rychlosti a relace. Pro dostupnost active/passive nebo active/active použijte reverzní proxy nebo klient s kontrolou stavu při selhání a nikdy nepřipojujte jednu databázi SQLite do více spuštěných instancí OmniRoute.
### Vyhrazené trasy poskytovatelů
Směrujte požadavky přímo ke konkrétnímu poskytovateli s ověření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
```
Pokud chybí předpona poskytovatele, je automaticky přidána. Neshodné modely vrátí `400`.
### Konfigurace síťového proxy
```bash
# Set global proxy
curl -X PUT http://localhost:20128/api/settings/proxy \
-d '{"global": {"type":"http","host":"proxy.example.com","port":"8080"}}'
# Per-provider proxy
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"}}'
```
**Přednost:** Specifické pro klíč → Combo specifické → Specifické pro poskytovatele → Global → Environment.
### Katalog modelů API
```bash
curl http://localhost:20128/api/models/catalog
```
Vrátí modely seskupené podle poskytovatele s typy (`chat`, `embedding`, `image`).
### Cloudová synchronizace
- Synchronizujte poskytovatele, kombinace a nastavení napříč zařízeními
- Automatická synchronizace na pozadí s časovým limitem + -fast
- Ve výrobě preferujte `NEXT_PUBLIC_BASE_URL`/`NEXT_PUBLIC_CLOUD_URL` na straně serveru
### Cloudflare Rychlý tunel
- Dostupné v** Dashboard → Endpoints** pro Docker a další samostatně hostovaná nasazení
- Vytvoří dočasný `https://*.trycloudflare.com` URL, který bude přesměrován na váš aktuální koncový bod `/v1` kompatibilní s OpenAI
- Nejprve povolte instalaci `cloudflared` pouze v případě potřeby; pozdější restartování znovu použije stejný spravovaný binární soubor
- Rychlé tunely se po restartu OmniRoute nebo kontejneru automaticky neobnoví; v případě potřeby je znovu povolte z palubní desky
- Tunelové URLs jsou pomíjivé a mění se pokaždé, když stop/start tunelem
- Spravované rychlé tunely jsou výchozí pro přenos HTTP/2, aby se zabránilo hlučným varováním vyrovnávací paměti QUIC UDP v omezených kontejnerech
- Pokud chcete volbu spravovaného přenosu přepsat, nastavte `CLOUDFLARED_PROTOCOL=quic` nebo `auto`
- Nastavte `CLOUDFLARED_BIN` pokud dáváte přednost použití předinstalovaného binárního souboru `cloudflared` namísto spravovaného stahování
- Panely Cloudflare Quick Tunnel, Tailscale Funnel a ngrok Tunnel lze zobrazit nebo skrýt v** Nastavení → Vzhled** . Skrytí panelu nezastaví běžící tunel.
### LLM Gateway Intelligence (Fáze 9)
- **Sémantická mezipaměť** — Automatické ukládání do mezipaměti bez streamování, odezvy teploty = 0 (obejít pomocí `X-OmniRoute-No-Cache: true`)
- **Žádost o idempotenci** — Deduplikuje požadavky do 5 s prostřednictvím hlavičky `Idempotency-Key` nebo `X-Request-Id`
- **Sledování pokroku** — Přihlaste se k událostem SSE `event: progress` prostřednictvím záhlaví `X-OmniRoute-Progress: true`
---
### Překladatelské hřiště
Přístup přes** Překladač palubní desky →** . Laďte a vizualizujte, jak OmniRoute překládá požadavky API mezi poskytovateli.
| Režim | Účel |
| --------------------- | ------------------------------------------------------------------------------------------ |
| **Dětské hřiště** | Vyberte formáty source/target, vložte požadavek a okamžitě si prohlédněte přeložený výstup |
| **Tester chatu** | Odesílejte zprávy živého chatu přes proxy a prohlédněte si celý cyklus request/response |
| **Testovací stolice** | Spusťte dávkové testy ve více kombinacích formátů, abyste ověřili správnost překladu |
| **Živý monitor** | Sledujte překlady v reálném čase, jak požadavky proudí přes proxy |
**Případy použití:**
- Odlaďte, proč konkrétní kombinace client/provider selže
- Ověřte, že se značky myšlení, volání nástrojů a systémové výzvy překládají správně
- Porovnejte rozdíly ve formátu mezi formáty OpenAI, Claude, Gemini a Responses API
---
### Strategie směrování
Konfigurovat přes** Ovládací panel → Nastavení → Směrování** . Na palubní desce je zobrazeno šest nejpoužívanějších strategií; komba a auto-router interně podporují širší sadu.
**Strategie viditelné na panelu (směrování na úrovni účtu):**
| Strategie | Popis |
| ---------------------------- | ------------------------------------------------------------------------------------------------ |
| **Nejprve vyplnit** | Používá účty v pořadí priority – primární účet zpracovává všechny požadavky, dokud není dostupný |
| **Round Robin** | Prochází všechny účty s nastavitelným limitem (výchozí: 3 volání na účet) |
| **P2C (síla dvou možností)** | Vybere 2 náhodné účty a cesty ke zdravějšímu — vyrovnává zátěž s vědomím zdraví |
| **Náhodný** | Náhodně vybere účet pro každý požadavek pomocí Fisher-Yates shuffle |
| **Nejméně používané** | Směruje na účet s nejstarším časovým razítkem `lastUsedAt`, distribuuje provoz rovnoměrně |
| **Optimalizace nákladů** | Směruje na účet s nejnižší prioritou, optimalizuje se pro poskytovatele s nejnižšími náklady |
**Pokročilé kombinované a automatické strategie** (lze konfigurovat pomocí kombinace nebo pomocí předpon `auto/*` – viz [AUTO-COMBO.md](../routing/AUTO-COMBO.md) ):
- `priority` — přísný řád, nikdy kulaté
- `weighted` — proporcionální provoz rozdělený podle vah jednotlivých modelů
- `fill-first` — vypusťte první model, dokud nenarazí na limity
- `round-robin` / `strict-random` / `random`
- `p2c` (síla dvou možností)
- `least-used` a `cost-optimized`
- `auto` — řízené skóre u všech kandidátů
- `lkgp` (Last Known Good Provider) — připne k poslednímu úspěšnému poskytovateli a poté se vrátí k pravidlům
- `context-optimized` — vybere model s největším volným kontextovým oknem
- `context-relay` — řetězí modely s dlouhým kontextem pro následné obraty
#### Externí Sticky Session Header
Pro externí afinitu relace (například agenti Claude Code/Codex za reverzními proxy) odešlete:
```http
X-Session-Id: your-session-key
```
OmniRoute také přijímá `x_session_id` a vrací efektivní klíč relace v `X-OmniRoute-Session-Id`.
Pokud používáte Nginx a odesíláte záhlaví formuláře podtržení, povolte:
```nginx
underscores_in_headers on;
```
#### Zástupné aliasy modelu
Vytvořte vzory zástupných znaků pro přemapování názvů modelů:
```
Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-6
Pattern: gpt-* → Target: gh/gpt-5.3-codex
```
Zástupné znaky podporují `*` (libovolné znaky) a `?` (jeden znak).
#### Záložní řetězy
Definujte globální záložní řetězce, které platí pro všechny požadavky:
```
Chain: production-fallback
1. cc/claude-opus-4-7
2. gh/gpt-5.3-codex
3. glm/glm-4.7
```
---
### Společné kombinace poskytovatelů a vzory směrování
Zde jsou příklady vzorů pro kombinování více poskytovatelů a směrování mezi nimi v OmniRoute:
#### 1. Coding Agent Combo: High-End Reasoning se Cost/Speed Fallback
Ideální pro kódovací agenty (OpenCode, Claude Code, Cursor, Cline). Směruje zpočátku k modelům hraničního uvažování, při vyčerpání kvót nebo chybách se vrací k modelům rychlého kódování.
- **Dashboard** : Combos → Nové Combo → Název: `agent-coding` → Strategie: `Priority`
- **Modelky** :
1. `claude/claude-sonnet-4-6` (primární kódovací agent)
2. `openai/gpt-4o` (sekundární vysokokapacitní záložní)
3. `deepseek/deepseek-v4-flash` (Vysoce efektivní, nákladově efektivní záložní)
```bash
# Example via 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. Free-Tier Auto Failover Combo
Řetězce více bezplatných a bezklíčových poskytovatelů pro maximalizaci doby provozuschopnosti bez nákladů API.
- **Strategie** : `Least Used` nebo `Round Robin` (distribuuje zatížení napříč kvótami)
- **Modelky** :
1. `groq/llama-3.3-70b-versatile`
2. `gemini/gemini-2.5-flash`
3. `cerebras/gpt-oss-120b`
```bash
# Example via 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ální / Vision & Text Pipeline
Spárování specializovaných modelů vidění s vysokorychlostním generováním textu pro pracovní postupy zahrnující porozumění obrazu a generování kódu.
- **Vzor** : Kombinace `Priority`, která nejprve uvádí modely schopné vidění a jako poslední model text/code s vysokou propustností.
- **Modelky** :
1. `gemini/gemini-2.5-pro` (silné porozumění image/multimodal )
2. `openai/gpt-4o` (vyvážené vidění a používání nástrojů)
3. `deepseek/deepseek-v4-flash` (generace Text/code )
---
### Odolnost a jističe
Konfigurovat přes** Ovládací panel → Nastavení → Odolnost** .
OmniRoute implementuje odolnost na úrovni poskytovatele s pěti komponentami:
1. **Fronta požadavků a rychlost zobrazování** — Tvarování požadavku na úrovni systému:
- **Požadavky za minutu (RPM)** — Maximální počet požadavků za minutu na účet
- **Minimální doba mezi požadavky** — Minimální mezera v milisekundách mezi požadavky
- **Maximální počet souběžných požadavků** — Maximální počet souběžných požadavků na účet
2. **Ochlazování připojení** — Konfigurace typu per-auth pro jedno připojení po opakovaných selháních:
- **Base Cooldown** — Výchozí ochlazovací okno pro opakovatelné selhání upstreamu
- **Použijte Upstream Retry Hints** — Ctí autoritativní `Retry-After` nebo resetovací rady, pokud jsou poskytovány
- **Maximální kroky při ústupu** — Maximální exponenciální úroveň ústupu pro opakované selhání
3. **Jistič poskytovatele** — Sleduje selhání end-to-end poskytovatele, označí poskytovatele za degradovaného na nakonfigurované prahové hodnotě varování a otevře jistič, když je dosaženo nakonfigurované prahové hodnoty selhání:
- **Prah degradace** — Po sobě jdoucí selhání poskytovatele před zadáním `DEGRADED`
- **Práh selhání** — Po sobě jdoucí selhání poskytovatele před zadáním `OPEN`
- **Resetovat časový limit** — Časové okno, než bude poskytovatel znovu testován
- **CLOSED** (Zdravé) — Požadavky probíhají normálně
- **DEGRADED** — Požadavky stále proudí, zatímco jsou sledována zvýšená selhání
- **OPEN** — Poskytovatel je dočasně zablokován po opakovaných poruchách
- **HALF_OPEN** — Testování, zda se poskytovatel zotavil
Limity rychlosti `429` v rozsahu připojení zůstávají v platnosti** Ochlazování připojení** a nezapočítávají se do poskytovatele jističe.
Stav běhu modulu poskytovatele je zobrazen na** Dashboard → Health** pouze.
4. **Počkejte na Cooldown** — Pokud se každé kandidátské připojení již ochlazuje, OmniRoute může počkat na nejbližší ochlazení a automaticky opakovat stejný požadavek klienta.
5. **Automatická detekce rychlostního limitu** — Když poskytovatelé upstream vrátí explicitní čekací okna, tyto rady přepíší ochlazení místního připojení, když je toto nastavení povoleno.
**Tip pro profesionály:** Použijte** Zdraví** stránku pro kontrolu a resetování živých jističů poskytovatele po výpadku. Stránka Odolnost mění pouze konfiguraci.
---
### Export / Import databáze
Spravujte zálohy databáze v** Ovládací panel → Nastavení → Systém a úložiště** .
| Akce | Popis |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Export databáze** | Stáhne aktuální databázi SQLite jako soubor `.sqlite` |
| **Exportovat vše (.tar.gz)** | Stáhne úplný záložní archiv včetně: databáze, nastavení, kombinací, připojení poskytovatele (bez přihlašovacích údajů), metadat klíče API |
| **Importovat databázi** | Nahrajte soubor `.sqlite`, který nahradí aktuální databázi. Automaticky se vytvoří záloha před importem, pokud není `DISABLE_SQLITE_AUTO_BACKUP=true` |
```bash
# API: Export database
curl -o backup.sqlite http://localhost:20128/api/db-backups/export
# API: Export all (full archive)
curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll
# API: Import database
curl -X POST http://localhost:20128/api/db-backups/import \
-F "file=@backup.sqlite"
```
**Ověření importu:** Importovaný soubor je ověřen na integritu (kontrola SQLite pragma), požadované tabulky (`provider_connections`, `provider_nodes`, `combos`, `api_keys`) a velikost (max 100 MB).
**Případy použití:**
- Migrujte OmniRoute mezi počítači
- Vytvářejte externí zálohy pro obnovu po havárii
- Sdílejte konfigurace mezi členy týmu (exportujte veškerý sdílený archiv → )
---
### Ovládací panel nastavení
Stránka nastavení je uspořádána do** 7 karet** pro snadnou navigaci:
| Tab | Obsah |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Generál** | Nástroje systémového úložiště, výchozí chování, viditelnost tunelu koncového bodu |
| **Vzhled** | Ovládání motivu (light/dark/system), viditelnost postranního panelu, přepínání panelů pro karty tunelu Cloudflare/Tailscale/ngrok |
| **AI** | Thinking budget (passthrough / auto-strip / custom / adaptive — viz [THINKING_BUDGET.md](./THINKING_BUDGET.md) ), globální systémová výzva, promptní statistiky mezipaměti |
| **Zabezpečení** | Login/Password nastavení, IP Access Control, API auth for `/models`, Provider Blocking, prompt-injection guard |
| **Směrování** | Globální strategie směrování (Fill First / Round Robin / P2C / Random / Least Used / Cost Optimized), zástupné aliasy modelu, záložní řetězce, výchozí kombinace |
| **Odolnost** | Fronta požadavků, ochlazení připojení, konfigurace přerušovače poskytovatele a chování při čekání na ochlazení |
| **Moderní** | Globální konfigurace proxy (HTTP/SOCKS5), přepsání proxy podle poskytovatele |
Obecné již neduplikuje protokolování pouze pro čtení a poznámky mezipaměti. Nastavení uchovávání databáze a optimalizace jsou zachována prostřednictvím `/api/settings/database`; ruční vymazání mezipaměti používá `DELETE /api/cache`. Omezení řádků protokolu požadavků a proxy jsou řízena `CALL_LOGS_TABLE_MAX_ROWS` a `PROXY_LOGS_TABLE_MAX_ROWS`.
---
### Správa nákladů a rozpočtu
Přístup přes** Dashboard → Náklady** .
| Tab | Účel |
| ------------ | ---------------------------------------------------------------------------------------------- |
| **Rozpočet** | Nastavte limity výdajů na klíč API s rozpočty daily/weekly/monthly a sledováním v reálném čase |
| **Ceny** | Zobrazení a úprava položek cen modelu – cena za 1 000 tokenů input/output na poskytovatele |
```bash
# API: Set a budget
curl -X POST http://localhost:20128/api/usage/budget \
-H "Content-Type: application/json" \
-d '{"keyId": "key-123", "limit": 50.00, "period": "monthly"}'
# API: Get current budget status
curl http://localhost:20128/api/usage/budget
```
**Sledování nákladů:** Každý požadavek zaznamenává využití tokenu a vypočítává náklady pomocí cenové tabulky. Zobrazit rozdělení v** Dashboard → Použití** podle poskytovatele, modelu a klíče API.
---
### Přepis zvuku
OmniRoute podporuje přepis zvuku prostřednictvím koncového bodu kompatibilního s OpenAI:
```bash
POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data
# Example with 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 nativní trasa Deepgramu a potřebuje klíč Deepgram API. Pokud je nakonfigurováno pouze OpenRouter, použijte `openrouter/deepgram/nova-3`.
**Převod řeči na text (přepis)** poskytovatelé:
- `openai/` (kompatibilní s šepotem)
- `groq/` (Groq Whisper Turbo)
- `deepgram/` (rodina Nova)
- `assemblyai/`
- `nvidia/` (Parakeet, Kanárské ostrovy)
- `huggingface/` (šeptat varianty)
- `qwen/`
**Převod textu na řeč (`POST /v1/audio/speech`)** poskytovatelé:
- `openai/` (tts-1, tts-1-hd)
- `hyperbolic/`
- `deepgram/` (aura)
- `nvidia/` (straka TTS)
- `elevenlabs/`
- `huggingface/`
- `inworld/`
- `cartesia/`
- `playht/`
- `kie/`
- `aws-polly/`
- `xiaomi-mimo/`
- `coqui/`, `tortoise/`
- `qwen/`
Podporované zvukové formáty pro přepis: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. Výstupní formáty TTS závisí na poskytovateli (mp3, wav, opus, pcm, mulaw).
---
### Kombinované vyvažovací strategie
Nakonfigurujte vyvažování podle kombinace v** Dashboard → Combos → Create/Edit → Strategy** .
| Strategie | Popis |
| ---------------------------- | ------------------------------------------------------------------------------------- |
| **Round-Robin** | Postupně otáčí modely |
| **Přednost** | Vždy zkouší první model; vrací se pouze na chybu |
| **Náhodný** | Vybere náhodný model z kombinace pro každý požadavek |
| **Vážené** | Trasy proporcionálně na základě přiřazených vah na model |
| **Nejméně používané** | Směruje k modelu s nejmenším počtem nedávných požadavků (používá kombinované metriky) |
| **Nákladově optimalizované** | Trasy k nejlevnějšímu dostupnému modelu (používá cenovou tabulku) |
Lze nastavit globální výchozí hodnoty komba** Dashboard → Settings → Routing → Combo Defaults** . Časové limity kombinovaného cíle ve výchozím nastavení dědí aktuální časový limit požadavku. Použití** Cílový časový limit (v sekundách)** na výchozí hodnoty komba nebo jednotlivá komba pouze v případě, že by kratší limit na cíl měl spustit rychlejší návrat.
Kombinovaná optimalizace s nulovou latencí je volitelná. Dovolená** Optimalizace s nulovou latencí** deaktivováno, aby se zabránilo těmto funkcím latence v závodění se záložními cíli, přeskakování cílů na základě historie TTFT nebo komprese záložních požadavků; umožňuje nakonfigurované hedging, prediktivní přeskakování TTFT a proaktivní záložní kompresi pro výměnu věrnosti routing/request za nižší latenci ocasu.
Zakázat** Vyrovnávací paměť důvodového tokenu** když upstream poskytovatelé vyžadují přísné limity `max_tokens` / `maxOutputTokens`. Je-li povoleno, kombinované směrování pouze přidává prostor pro model uvažování pro modely se známým limitem výstupu a ponechává limit klientského tokenu beze změny, pokud by bezpečná hodnota ve vyrovnávací paměti tento limit překročila. Pokud je klientský limit již nad známým limitem, OmniRoute ho před odesláním upstream požadavku upevní na tento limit.
---
### Zdraví Dashboard
Přístup přes** Dashboard → Health** . Přehled stavu systému v reálném čase se 6 kartami:
| Karta | Co to ukazuje |
| ------------------------ | ------------------------------------------------------------------- |
| **Stav systému** | Uptime, verze, využití paměti, datový adresář |
| **Zdraví poskytovatele** | Stav běhu jističe globálního poskytovatele |
| **Omezení sazby** | Aktivní ochlazení připojení na účet se zbývajícím časem |
| **Aktivní uzamčení** | Aktivní uzamčení a dočasné vyloučení v rozsahu modelu |
| **Mezipaměť podpisů** | Statistiky deduplikační mezipaměti (aktivní klíče, četnost návštěv) |
| **Latenční telemetrie** | agregace latence p50/p95/p99 na poskytovatele |
**Tip pro profesionály:** Stránka Zdraví se automaticky obnovuje každých 10 sekund. Pomocí karty jističe zjistěte, u kterých poskytovatelů dochází k problémům.
---
## 🤖 Automatické směrování (bez konfigurace)
OmniRoute obsahuje **automatický směrovač řízený skóre**, který pro každý požadavek vybere nejlepší model napříč všemi připojenými poskytovateli — není třeba udržovat žádnou kombinaci. Stačí požadavek odeslat s jednou z předpon `auto/*` a OmniRoute za běhu sestaví virtuální kombinaci, přičemž kandidáty ohodnotí podle latence, nákladů, úspěšnosti, vhodnosti kontextu, vhodnosti modelu pro danou úlohu, nedávných selhání, kvóty a stavu jističe.
| Předpona | Optimalizuje pro |
| -------------- | ----------------------------------------------------------------------------------------------------------------- |
| `auto` | Vyvážené výchozí nastavení (latence × náklady × úspěšnost) |
| `auto/coding` | Programovací úlohy: upřednostňuje Claude, GPT-5, GLM, Kimi, Qwen Coder a modely DeepSeek pro programování |
| `auto/cheap` | Nejnižší cena za token, akceptuje vyšší latenci |
| `auto/fast` | Nejnižší latence, ignoruje náklady |
| `auto/offline` | Pouze lokální poskytovatelé (Ollama, vLLM, llama.cpp) — užitečné pro izolovaná prostředí |
| `auto/smart` | Prioritou je kvalita uvažování (Opus, GPT-5 xhigh, R1, GLM 5.1 reasoning) |
| `auto/lkgp` | „Poslední známý funkční poskytovatel“ — připne posledního úspěšného poskytovatele a poté použije záložní pravidla |
Pří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ý směrovač je podrobně popsán v dokumentu [AUTO-COMBO.md](../routing/AUTO-COMBO.md) — včetně postupu, jak upravit váhy hodnocení, zařadit poskytovatele na černou listinu a zkontrolovat rozhodnutí o směrování v části **Řídicí panel → Automatická kombinace**.
---
## 🔌 Integrace MCP a A2A
OmniRoute je současně **server MCP** (Model Context Protocol) a **server A2A** (Agent-to-Agent JSON-RPC 2.0). Libovolné IDE kompatibilní s MCP nebo hostitel agentů může nástroje OmniRoute volat přímo — není vyžadována žádná další obálka.
### Přenosy MCP
- **SSE**: `http://localhost:20128/api/mcp/sse`
- **Streamovatelné HTTP**: `http://localhost:20128/api/mcp/stream`
- **stdio**: `omniroute --mcp` (pro pluginy IDE, které upřednostňují stdio)
### Připojení aplikace Claude Desktop
Upravte soubor `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) nebo jeho ekvivalent ve Windows/Linuxu:
```json
{
"mcpServers": {
"omniroute": {
"command": "omniroute",
"args": ["--mcp"]
}
}
}
```
### Připojení Cursoru / Continue / MCP ve VS Code
Použijte adresu URL SSE `http://localhost:20128/api/mcp/sse` a klíč API typu Bearer vygenerovaný v části **Řídicí panel → Klíče API**.
### Rozsahy oprávnění
MCP aktuálně definuje 32 pojmenovaných rozsahů oprávnění. Každý klíč typu Bearer lze omezit na konkrétní rozsahy — autoritativní seznam rozsahů a nástrojů naleznete v dokumentu [MCP-SERVER.md](../frameworks/MCP-SERVER.md) a schéma JSON-RPC v dokumentu [A2A-SERVER.md](../frameworks/A2A-SERVER.md).
---
## 🧠 Systém dovedností
OmniRoute poskytuje rozšiřitelný **framework dovedností** (`src/lib/skills/`), díky němuž mohou agenti a koncový bod A2A spouštět rutiny specifické pro konkrétní doménu (např. `code-review`, `summarize`, `extract-facts`, `web-research`).
- **Uživatelské rozhraní tržiště** — Procházejte a instalujte dovednosti v části **Dashboard → Skills**
- **Rozsahy pro jednotlivé klíče** — Omezte, které API klíče mohou vyvolávat jednotlivé dovednosti
- **Vlastní dovednosti** — Vložte soubor TypeScript do `src/lib/a2a/skills/`, zaregistrujte jej a okamžitě jej bude možné vyvolat přes A2A
Úplná dokumentace: [SKILLS.md](../frameworks/SKILLS.md).
---
## 💾 Systém paměti
OmniRoute uchovává **dlouhodobou konverzační paměť** s hybridním vyhledáváním:
- **SQLite FTS5** pro vyhledávání podle klíčových slov v předchozích interakcích
- **Vektorové úložiště Qdrant** (volitelné) pro sémantické vybavování
- **Automatická extrakce faktů** — entity, preference a rozhodnutí jsou po každé relaci shrnuty a uloženy do tabulky `memory_facts`
- Paměti jsou odděleny podle API klíče a relace
Paměti můžete spravovat v části **Dashboard → Memory** (vyhledávání, úpravy, export, vymazání). Rozhraní HTTP (`/api/memory/*`) umožňuje agentům programově odesílat fakta a dotazovat se na ně — viz [MEMORY.md](../frameworks/MEMORY.md).
---
## 🔔 Webhooky
Přihlaste se k odběru událostí OmniRoute pro monitorování a automatizaci v reálném čase.
- Vytvořte webhook v části **Dashboard → Webhooks** se cílovou URL adresou a tajným klíčem pro podepisování HMAC
- Dostupné události: `request.completed`, `request.failed`, `provider.unavailable`, `budget.exceeded`, `combo.switched`, `circuit_breaker.opened`, `circuit_breaker.closed`
- Každá datová část obsahuje pro účely ověření hlavičku `X-OmniRoute-Signature` (HMAC-SHA256)
- Opakované pokusy: 3 pokusy s exponenciálním prodlužováním prodlevy, poté přesun do fronty nedoručených zpráv
Úplné schéma najdete v [WEBHOOKS.md](../frameworks/WEBHOOKS.md).
---
## ☁️ Cloudoví agenti
OmniRoute se integruje s cloudovými agenty pro programování (**OpenAI Codex Cloud**, **Devin**, **Jules**, **Antigravity**), takže můžete zadávat dlouhotrvající úlohy ze stejného ovládacího panelu, který spravuje vaše místní směrování.
- Vytvářejte úlohy v části **Dashboard → Cloud Agents** nebo prostřednictvím `POST /api/v1/agents/tasks`
- Sledujte stav, protokoly a artefakty jednotlivých úloh
- Použijte vlastní API klíč pro každého poskytovatele — přihlašovací údaje nikdy neopustí instanci OmniRoute
Úplná dokumentace: [CLOUD_AGENT.md](../frameworks/CLOUD_AGENT.md).
---
## 🛠️ Programová správa
Každý prostředek OmniRoute (poskytovatele, kombinace, klíče, nastavení) můžete spravovat přes HTTP pomocí **klíče Bearer s rozsahem `manage`**.
Vygenerujte klíč v části **Dashboard → API Keys → New Key → Scope: manage** a poté:
```bash
# Vypsat poskytovatele
curl http://localhost:20128/api/providers \
-H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY"
# Přidat připojení k poskytovateli
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" }'
# Vytvořit kombinaci
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" }] }'
# Vypsat/vytvořit API klíče
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"] }'
```
Úplný katalog koncových bodů a schémata požadavků a odpovědí najdete v [API_REFERENCE.md](../reference/API_REFERENCE.md).
---
## 💻 Interní CLI
OmniRoute obsahuje interní CLI (`omniroute …`) pro nastavení, diagnostiku a řízení za běhu. Je **oddělené od stránky „Nástroje CLI“ v ovládacím panelu**, která konfiguruje CLI nástroje třetích stran (Claude Code, Cursor, Codex, Cline, …), aby mohly komunikovat s OmniRoute.
```bash
omniroute setup # Interaktivní průvodce (heslo, poskytovatelé, kombinace)
omniroute setup --non-interactive # Vhodné pro CI
omniroute doctor # Diagnostika stavu (datový adresář, DB, poskytovatelé, porty)
omniroute providers available # Výpis podporovaných poskytovatelů
omniroute providers list # Výpis nakonfigurovaných připojení
omniroute providers test # Živý test připojení k poskytovateli
omniroute combos list # Výpis kombinací
omniroute combos switch # Nastavení výchozí kombinace
omniroute models # Výpis dostupných modelů (--json, --search)
omniroute keys add | list | remove # Správa API klíčů z terminálu
omniroute backup # Snímek konfigurace a DB
omniroute restore [] # Obnovení ze snímku
omniroute health # Podrobný stav (jističe, mezipaměť, paměť)
omniroute quota # Využití kvót poskytovatelů
omniroute mcp status # Stav serveru MCP
omniroute a2a status # Stav serveru A2A
omniroute tunnel list|create|stop # Tunely Cloudflare/Tailscale/ngrok
omniroute reset-password # Resetování hesla správce
omniroute --mcp # Spuštění serveru MCP přes stdio
omniroute --port 3000 # Spuštění serveru na vlastním portu
```
Tip: propojte `omniroute doctor --json` se svým monitorovacím nástrojem, abyste dostávali upozornění na nefunkční připojení k poskytovatelům.
---
## 🖥️ Desktopová aplikace (Electron)
OmniRoute je k dispozici jako nativní desktopová aplikace pro Windows, macOS a Linux.
### Instalace
```bash
# Z adresáře electron:
cd electron
npm install
# Vývojový režim (připojení k běžícímu vývojovému serveru Next.js):
npm run dev
# Produkční režim (používá samostatné sestavení):
npm start
```
### Sestavení instalačních balíčků
```bash
cd electron
npm run build # Aktuální platforma
npm run build:win # Windows (.exe NSIS)
npm run build:mac # macOS (.dmg universal)
npm run build:linux # Linux (.AppImage)
```
Výstup → `electron/dist-electron/`
### Klíčové funkce
| Funkce | Popis |
| ----------------------------- | ------------------------------------------------------------------------- |
| **Připravenost serveru** | Kontroluje server před zobrazením okna (žádná prázdná obrazovka) |
| **Systémová lišta** | Minimalizace do systémové lišty, změna portu a ukončení z nabídky lišty |
| **Správa portu** | Změna portu serveru ze systémové lišty (server se automaticky restartuje) |
| **Zásady zabezpečení obsahu** | Restriktivní CSP prostřednictvím hlaviček relace |
| **Jediná instance** | V jednu chvíli může běžet pouze jedna instance aplikace |
| **Offline režim** | Přibalený server Next.js funguje bez připojení k internetu |
### Proměnné prostředí
| Proměnná | Výchozí hodnota | Popis |
| --------------------- | --------------- | --------------------------------- |
| `OMNIROUTE_PORT` | `20128` | Port serveru |
| `OMNIROUTE_MEMORY_MB` | `512` | Limit haldy Node.js (64–16384 MB) |
📖 Úplná dokumentace: [`electron/README.md`](../../electron/README.md)