# User Guide (Polski)
🌐 **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) · 🇵🇹 [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)
---
🌐 **Języki:** 🇺🇸 [English](./USER_GUIDE.md) | 🇪🇹 [አማርኛ](../i18n/am/docs/guides/USER_GUIDE.md) | 🇸🇦 [العربية](../i18n/ar/docs/guides/USER_GUIDE.md) | 🇦🇿 [Azərbaycan dili](../i18n/az/docs/guides/USER_GUIDE.md) | 🇧🇬 [Български](../i18n/bg/docs/guides/USER_GUIDE.md) | 🇧🇩 [বাংলা](../i18n/bn/docs/guides/USER_GUIDE.md) | 🇧🇦 [Bosanski](../i18n/bs/docs/guides/USER_GUIDE.md) | 🇨🇿 [Čeština](../i18n/cs/docs/guides/USER_GUIDE.md) | 🇩🇰 [Dansk](../i18n/da/docs/guides/USER_GUIDE.md) | 🇩🇪 [Deutsch](../i18n/de/docs/guides/USER_GUIDE.md) | 🇬🇷 [Ελληνικά](../i18n/el/docs/guides/USER_GUIDE.md) | 🇪🇸 [Español](../i18n/es/docs/guides/USER_GUIDE.md) | 🇪🇪 [Eesti](../i18n/et/docs/guides/USER_GUIDE.md) | 🇮🇷 [فارسی](../i18n/fa/docs/guides/USER_GUIDE.md) | 🇫🇮 [Suomi](../i18n/fi/docs/guides/USER_GUIDE.md) | 🇫🇷 [Français](../i18n/fr/docs/guides/USER_GUIDE.md) | 🇮🇪 [Gaeilge](../i18n/ga/docs/guides/USER_GUIDE.md) | 🇮🇳 [ગુજરાતી](../i18n/gu/docs/guides/USER_GUIDE.md) | 🇳🇬 [Hausa](../i18n/ha/docs/guides/USER_GUIDE.md) | 🇮🇱 [עברית](../i18n/he/docs/guides/USER_GUIDE.md) | 🇮🇳 [हिन्दी](../i18n/hi/docs/guides/USER_GUIDE.md) | 🇭🇷 [Hrvatski](../i18n/hr/docs/guides/USER_GUIDE.md) | 🇭🇺 [Magyar](../i18n/hu/docs/guides/USER_GUIDE.md) | 🇦🇲 [Հայերեն](../i18n/hy/docs/guides/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](../i18n/id/docs/guides/USER_GUIDE.md) | 🇳🇬 [Igbo](../i18n/ig/docs/guides/USER_GUIDE.md) | 🇮🇹 [Italiano](../i18n/it/docs/guides/USER_GUIDE.md) | 🇯🇵 [日本語](../i18n/ja/docs/guides/USER_GUIDE.md) | 🇬🇪 [ქართული](../i18n/ka/docs/guides/USER_GUIDE.md) | 🇰🇭 [ខ្មែរ](../i18n/km/docs/guides/USER_GUIDE.md) | 🇮🇳 [ಕನ್ನಡ](../i18n/kn/docs/guides/USER_GUIDE.md) | 🇰🇷 [한국어](../i18n/ko/docs/guides/USER_GUIDE.md) | 🇱🇹 [Lietuvių](../i18n/lt/docs/guides/USER_GUIDE.md) | 🇱🇻 [Latviešu](../i18n/lv/docs/guides/USER_GUIDE.md) | 🇮🇳 [മലയാളം](../i18n/ml/docs/guides/USER_GUIDE.md) | 🇮🇳 [मराठी](../i18n/mr/docs/guides/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](../i18n/ms/docs/guides/USER_GUIDE.md) | 🇲🇹 [Malti](../i18n/mt/docs/guides/USER_GUIDE.md) | 🇲🇲 [မြန်မာ](../i18n/my/docs/guides/USER_GUIDE.md) | 🇳🇵 [नेपाली](../i18n/ne/docs/guides/USER_GUIDE.md) | 🇳🇱 [Nederlands](../i18n/nl/docs/guides/USER_GUIDE.md) | 🇳🇴 [Norsk](../i18n/no/docs/guides/USER_GUIDE.md) | 🇮🇳 [ଓଡ଼ିଆ](../i18n/or/docs/guides/USER_GUIDE.md) | 🇮🇳 [ਪੰਜਾਬੀ](../i18n/pa/docs/guides/USER_GUIDE.md) | 🇵🇭 [Filipino](../i18n/phi/docs/guides/USER_GUIDE.md) | 🇵🇱 [Polski](../i18n/pl/docs/guides/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](../i18n/pt/docs/guides/USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](../i18n/pt-BR/docs/guides/USER_GUIDE.md) | 🇷🇴 [Română](../i18n/ro/docs/guides/USER_GUIDE.md) | 🇷🇺 [Русский](../i18n/ru/docs/guides/USER_GUIDE.md) | 🇱🇰 [සිංහල](../i18n/si/docs/guides/USER_GUIDE.md) | 🇸🇰 [Slovenčina](../i18n/sk/docs/guides/USER_GUIDE.md) | 🇸🇮 [Slovenščina](../i18n/sl/docs/guides/USER_GUIDE.md) | 🇷🇸 [Српски](../i18n/sr/docs/guides/USER_GUIDE.md) | 🇸🇪 [Svenska](../i18n/sv/docs/guides/USER_GUIDE.md) | 🇰🇪 [Kiswahili](../i18n/sw/docs/guides/USER_GUIDE.md) | 🇮🇳 [தமிழ்](../i18n/ta/docs/guides/USER_GUIDE.md) | 🇮🇳 [తెలుగు](../i18n/te/docs/guides/USER_GUIDE.md) | 🇹🇭 [ไทย](../i18n/th/docs/guides/USER_GUIDE.md) | 🇹🇷 [Türkçe](../i18n/tr/docs/guides/USER_GUIDE.md) | 🇺🇦 [Українська](../i18n/uk-UA/docs/guides/USER_GUIDE.md) | 🇵🇰 [اردو](../i18n/ur/docs/guides/USER_GUIDE.md) | 🇺🇿 [Oʻzbekcha](../i18n/uz/docs/guides/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](../i18n/vi/docs/guides/USER_GUIDE.md) | 🇳🇬 [Yorùbá](../i18n/yo/docs/guides/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](../i18n/zh-CN/docs/guides/USER_GUIDE.md) | 🇹🇼 [中文 (繁體)](../i18n/zh-TW/docs/guides/USER_GUIDE.md)
Kompletny przewodnik dotyczący konfigurowania dostawców, tworzenia kombinacji, integrowania narzędzi CLI i wdrażania OmniRoute.
---
## Spis treści
- [Cennik w skrócie](#-pricing-at-a-glance)
- [Przypadki użycia](#-use-cases)
- [Konfiguracja dostawców](#-provider-setup)
- [Integracja z CLI](#-cli-integration)
- [Wdrażanie](#-deployment)
- [Dostępne modele](#-available-models)
- [Funkcje zaawansowane](#-advanced-features)
- [Automatyczne kierowanie (bez konfiguracji)](#-auto-routing-zero-config)
- [Integracja MCP i A2A](#-mcp--a2a-integration)
- [System umiejętności](#-skills-system)
- [System pamięci](#-memory-system)
- [Webhooki](#-webhooks)
- [Agenci w chmurze](#-cloud-agents)
- [Zarządzanie programistyczne](#-programmatic-management)
- [Wewnętrzny interfejs CLI](#-internal-cli)
- [Aplikacja desktopowa (Electron)](#-desktop-application-electron)
---
## 💰 Cennik w skrócie
| Plan | Dostawca | Koszt | Odnawianie limitu | Najlepsze zastosowanie |
| ------------------ | ----------------- | ---------------- | -------------------------- | -------------------------------- |
| **💳 SUBSKRYPCJA** | Claude Code (Pro) | $20/mies. | Co 5 godz. + co tydzień | Osoby mające już subskrypcję |
| | Codex (Plus/Pro) | $20-200/mies. | Co 5 godz. + co tydzień | Użytkownicy OpenAI |
| | GitHub Copilot | $10-19/mies. | Co miesiąc | Użytkownicy GitHub |
| **🔑 KLUCZ API** | DeepSeek | Opłata za użycie | Brak | Tanie wnioskowanie |
| | Groq | Opłata za użycie | Brak | Ultraszybkie wnioskowanie |
| | xAI (Grok) | Opłata za użycie | Brak | Wnioskowanie Grok 4 |
| | Mistral | Opłata za użycie | Brak | Modele hostowane w UE |
| | Perplexity | Opłata za użycie | Brak | Wyszukiwanie wspomagane przez AI |
| | Together AI | Opłata za użycie | Brak | Modele open source |
| | Fireworks AI | Opłata za użycie | Brak | Szybkie generowanie obrazów FLUX |
| | Cerebras | Opłata za użycie | Brak | Szybkość w skali całego wafla |
| | Cohere | Opłata za użycie | Brak | RAG z Command R+ |
| | NVIDIA NIM | Opłata za użycie | Brak | Modele dla przedsiębiorstw |
| | Baidu Qianfan | Opłata za użycie | Brak | Modele ERNIE |
| **💰 TANIE** | GLM-4.7 | $0.6/1M | Codziennie o 10:00 | Budżetowa opcja zapasowa |
| | MiniMax M2.1 | $0.2/1M | Ruchome okno 5-godzinne | Najtańsza opcja |
| | Kimi K2 | Stałe $9/mies. | 10M tokenów/mies. | Przewidywalny koszt |
| **🆓 BEZPŁATNE** | Qoder | $0 | Obowiązują limity dostawcy | Sprawdź aktualny katalog |
| | Kiro | $0 | ~50 kredytów/mies. | Bezpłatny Claude |
---
## 🎯 Przypadki użycia
### Przypadek 1: „Mam subskrypcję Claude Pro”
**Problem:** Limit przepada niewykorzystany, a podczas intensywnego programowania występują ograniczenia częstotliwości żądań
```
Zestaw: "maximize-claude"
1. cc/claude-opus-4-7 (pełne wykorzystanie subskrypcji)
2. glm/glm-4.7 (tania opcja zapasowa po wyczerpaniu limitu)
3. if/qwen3.8-max-preview (bezpłatna awaryjna opcja rezerwowa)
Koszt miesięczny: $20 (subskrypcja) + ~$5 (opcja zapasowa) = łącznie $25
zamiast $20 + ciągłe osiąganie limitów = frustracja
```
### Przypadek 2: „Nie chcę ponosić żadnych kosztów”
**Problem:** Nie stać mnie na subskrypcje, potrzebuję niezawodnego AI do programowania
```
Zestaw: "zero-cost"
1. if/kimi-k2.7-code (wymieniony jako dostępny bezpłatnie; mogą obowiązywać ograniczenia częstotliwości żądań)
2. kr/qwen3-coder-next (bezpłatna opcja zapasowa Kiro)
Koszt miesięczny: $0
Jakość: zweryfikuj model, limity, prywatność oraz SLA pod kątem swojego zastosowania
```
### Przypadek 3: „Potrzebuję programowania 24/7, bez przerw”
**Problem:** Terminy, nie mogę sobie pozwolić na przestoje
```
Zestaw: "always-on"
1. cc/claude-opus-4-7 (najlepsza jakość)
2. cx/gpt-5.5 (druga subskrypcja)
3. glm/glm-4.7 (tani, limit odnawiany codziennie)
4. minimax/MiniMax-M2.1 (najtańszy, limit odnawiany co 5 godz.)
5. if/deepseek-v4-flash (wymieniony jako dostępny bezpłatnie; mogą obowiązywać ograniczenia częstotliwości żądań)
Rezultat: 5 warstw opcji zapasowych zwiększa odporność; dostępność usług zewnętrznych nie jest gwarantowana
Koszt miesięczny: $20-200 (subskrypcje) + $10-20 (opcje zapasowe)
```
### Przypadek 4: „Chcę BEZPŁATNEGO AI w OpenClaw”
**Problem:** Potrzebuję całkowicie bezpłatnego asystenta AI w komunikatorach
```
Zestaw: "openclaw-free"
1. if/qwen3.8-max-preview (wymieniony jako dostępny bezpłatnie; mogą obowiązywać ograniczenia częstotliwości żądań)
2. if/deepseek-v4-flash (wymieniony jako dostępny bezpłatnie; mogą obowiązywać ograniczenia częstotliwości żądań)
3. if/kimi-k2.7-code (wymieniony jako dostępny bezpłatnie; mogą obowiązywać ograniczenia częstotliwości żądań)
Koszt miesięczny: $0
Dostęp przez: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
```
---
## 📖 Konfiguracja dostawców
Aby zbiorczo dodać połączenia z kluczami API z pliku CSV lub JSON, użyj opcji **Panel → Dostawcy → Importuj z pliku**. Kolumny są pozycyjne (`provider,name,apiKey,baseUrl,priority`); `provider` musi już istnieć jako zarządzany dostawca lub zgodny węzeł. Zobacz [Importowanie dostawców z pliku CSV lub JSON](../providers/CSV-IMPORT.md).
### 🔐 Dostawcy subskrypcyjni
#### Claude Code (Pro/Max)
```bash
Panel → Dostawcy → Połącz Claude Code
→ Logowanie OAuth → Automatyczne odświeżanie tokenu
→ Śledzenie limitów 5-godzinnych i tygodniowych
Modele:
cc/claude-opus-4-7
cc/claude-sonnet-4-6
cc/claude-haiku-4-5-20251001
```
**Wskazówka:** Używaj Opus do złożonych zadań, a Sonnet, gdy liczy się szybkość. OmniRoute śledzi limit osobno dla każdego modelu!
Brak przeglądarki na hoście OmniRoute? Uruchom `claude setup-token` w dowolnym miejscu, w którym użytkownik jest zalogowany do Claude Code, i wklej roczny token na karcie **Token konfiguracji**. Zobacz [Claude Code z tokenem konfiguracji](../providers/CLAUDE_CODE_SETUP_TOKEN.md).
Trasy zgodne z Claude i Claude Code zachowują poziom intensywności rozumowania `max` dla modeli Opus i Sonnet. Modele Haiku nie obsługują poziomu intensywności `max`, dlatego przed wysłaniem żądania do dostawcy nadrzędnego OmniRoute obniża je do wysokiego budżetu rozumowania.
#### OpenAI Codex (Plus/Pro)
```bash
Panel → Dostawcy → Połącz Codex
→ Logowanie OAuth (port 1455)
→ Reset co 5 godzin + reset tygodniowy
Modele:
cx/gpt-5.5
cx/gpt-5.4
cx/gpt-5.3-codex
cx/gpt-5.3-codex-spark
```
#### GitHub Copilot
```bash
Panel → Dostawcy → Połącz GitHub
→ OAuth przez GitHub
→ Reset miesięczny (1. dzień miesiąca)
Modele:
gh/gpt-5.5
gh/gpt-5.4
gh/claude-sonnet-4.6
gh/claude-opus-4.7
gh/gemini-3.1-pro-preview
```
### 💰 Tani dostawcy
#### GLM-4.7 (reset codzienny, $0.6/1M)
1. Zarejestruj się: [Zhipu AI](https://open.bigmodel.cn)
2. Uzyskaj klucz API z Coding Plan
3. Panel → Dodaj klucz API: Dostawca: `glm`, Klucz API: `your-key`
**Użycie:** `glm/glm-4.7` — **Wskazówka:** Coding Plan oferuje 3-krotnie większy limit za 1/7 ceny! Reset codziennie o 10:00.
#### MiniMax M2.1 (reset co 5 godz., $0.20/1M)
1. Zarejestruj się: [MiniMax](https://www.minimax.io)
2. Uzyskaj klucz API → Panel → Dodaj klucz API
**Użycie:** `minimax/MiniMax-M2.1` — **Wskazówka:** Najtańsza opcja dla długiego kontekstu (1M tokenów)!
#### Kimi K2 (stała opłata $9/miesiąc)
1. Wykup subskrypcję: [Moonshot AI](https://platform.kimi.ai?aff=omniroute)
2. Uzyskaj klucz API → Panel → Dodaj klucz API
**Użycie:** `kimi/kimi-k2.5` — **Wskazówka:** Stałe $9/miesiąc za 10M tokenów oznacza efektywny koszt $0.90/1M!
#### Baidu Qianfan / ERNIE
1. Zarejestruj się: [Baidu AI Cloud Qianfan](https://cloud.baidu.com/product/wenxinworkshop)
2. Utwórz klucz API Qianfan → Panel → Dodaj klucz API: Dostawca: `qianfan`
**Użycie:** `qianfan/ernie-5.1`, `qianfan/ernie-x1.1` lub inny identyfikator modelu Qianfan zgodnego z OpenAI.
### 🆓 DARMOWI dostawcy
Dostawcy niewymagający uwierzytelniania mają przełącznik obok opcji **Uwierzytelnianie nie jest wymagane** na swojej stronie.
Wyłączenie go dezaktywuje danego dostawcę, usuwa go ze skonfigurowanych i kompaktowych widoków dostawców oraz
usuwa jego modele z `/v1/models`.
#### Qoder (9 DARMOWYCH modeli)
```bash
Panel → Połącz Qoder → Logowanie OAuth → Dostęp podlega aktualnym limitom dostawcy
Modele: 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 ZA DARMO)
```bash
Panel → Połącz Kiro → AWS Builder ID lub Google/GitHub → ~50 kredytów/miesiąc
Modele: kr/claude-sonnet-4.5, kr/claude-haiku-4.5
```
---
## 🎨 Kombinacje
Możesz zmieniać kolejność kart kombinacji bezpośrednio w sekcji **Panel → Kombinacje**, przeciągając uchwyt na każdej karcie. Kolejność jest zapisywana w SQLite i przywracana po ponownym wczytaniu.
### Przykład 1: Maksymalne wykorzystanie subskrypcji → Tania alternatywa
```
Panel → Kombinacje → Utwórz nową
Nazwa: premium-coding
Modele:
1. cc/claude-opus-4-7 (Główny model w ramach subskrypcji)
2. glm/glm-4.7 (Tania alternatywa, $0.6/1M)
3. minimax/MiniMax-M2.7 (Najtańszy model rezerwowy, $0.3/1M)
Użycie w CLI: premium-coding
```
### Przykład 2: Tylko bezpłatne modele (zerowy koszt)
```
Nazwa: free-combo
Modele:
1. if/kimi-k2.7-code (oznaczony jako dostępny bezpłatnie; mogą obowiązywać limity dostawcy)
2. kr/qwen3-coder-next (bezpłatny model rezerwowy Kiro)
Koszt: obecnie oznaczony jako $0; warunki i dostępność mogą ulec zmianie
```
---
## 🔧 Integracja z CLI
### Cursor IDE
**Używanie Cursor jako klienta OmniRoute** (przekierowanie czatu Cursor przez OmniRoute):
```
Ustawienia → Modele → Zaawansowane:
Bazowy adres URL API OpenAI: http://localhost:20128/v1
Klucz API OpenAI: [z panelu OmniRoute]
Model: cc/claude-opus-4-7
```
**Używanie OmniRoute z Cursor jako dostawcą** (OmniRoute wywołuje usługę nadrzędną Cursor): preferowana metoda to
**Panel → Dostawcy → Cursor → Zaloguj przez Cursor**. W środowisku Docker zobacz
[`docs/providers/CURSOR-DOCKER.md`](../providers/CURSOR-DOCKER.md).
### Claude Code
Edytuj `~/.claude/settings.json`:
```json
{
"env": {
"ANTHROPIC_BASE_URL": "http://localhost:20128",
"ANTHROPIC_AUTH_TOKEN": "your-omniroute-api-key"
}
}
```
Użyj tutaj głównego punktu końcowego zgodnego z Claude. Nie dodawaj `/v1` do `ANTHROPIC_BASE_URL`.
### Codex CLI
```bash
export OPENAI_BASE_URL="http://localhost:20128"
export OPENAI_API_KEY="your-omniroute-api-key"
codex "your prompt"
```
### OpenClaw
Edytuj `~/.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" }]
}
}
}
}
```
**Lub użyj panelu:** Narzędzia CLI → OpenClaw → Automatyczna konfiguracja
### Cline / Continue / RooCode
```
Dostawca: Zgodny z OpenAI
Bazowy adres URL: http://localhost:20128/v1
Klucz API: [z panelu]
Model: cc/claude-opus-4-7
```
---
## 🚀 Wdrożenie
### Globalna instalacja przez npm (zalecana)
```bash
npm install -g omniroute
# Utwórz katalog konfiguracji
mkdir -p ~/.omniroute
# Utwórz plik .env (zobacz .env.example)
cp .env.example ~/.omniroute/.env
# Uruchom serwer
omniroute
# Lub z niestandardowym portem:
omniroute --port 3000
```
CLI automatycznie wczytuje plik `.env` z `~/.omniroute/.env` lub `./.env`.
### Tryb zasobnika systemowego
Uruchom OmniRoute w zasobniku systemowym:
```bash
omniroute serve --tray
```
Polecenie kończy działanie, gdy serwer i ikona zasobnika są gotowe.
Serwer działa dalej bez otwartego terminala.
Tryb zasobnika jest obsługiwany w systemach macOS, Windows oraz w graficznych sesjach systemu Linux. Tryb zasobnika nie otwiera panelu automatycznie.
Menu zasobnika umożliwia wykonywanie następujących działań:
- Otwarcie panelu.
- Otwarcie `/dashboard/logs`.
- Zmiana ustawienia automatycznego uruchamiania.
- Zatrzymanie OmniRoute.
Nie łącz `--tray` z następującymi opcjami:
- `--daemon`
- `--log`
- `--no-recovery`
Te tryby wymagają innego sposobu zarządzania procesem.
Włącz uruchamianie przy następnym logowaniu do systemu:
```bash
omniroute autostart enable
```
Automatyczne uruchamianie korzysta z trybu zasobnika w systemach macOS, Windows oraz w graficznych sesjach systemu Linux. Linux bez środowiska graficznego korzysta z istniejącej usługi użytkownika systemd.
Wyłącz uruchamianie przy logowaniu:
```bash
omniroute autostart disable
```
### Odinstalowywanie
Gdy OmniRoute nie będzie już potrzebny, udostępniamy dwa szybkie skrypty umożliwiające jego całkowite usunięcie:
| Polecenie | Działanie |
| ------------------------ | ----------------------------------------------------------------------------------------- |
| `npm run uninstall` | Usuwa aplikację systemową, ale **zachowuje bazę danych i konfiguracje** w `~/.omniroute`. |
| `npm run uninstall:full` | Usuwa aplikację ORAZ trwale **kasuje wszystkie konfiguracje, klucze i bazy danych**. |
> Uwaga: aby uruchomić te polecenia, przejdź do folderu projektu OmniRoute (jeśli został sklonowany), a następnie je wykonaj. Jeśli pakiet został zainstalowany globalnie, możesz zamiast tego po prostu uruchomić `npm uninstall -g omniroute`.
### Wdrożenie 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
# Lub: pm2 start npm --name omniroute -- start
```
### Wdrożenie z PM2 (małe zużycie pamięci)
W przypadku serwerów z ograniczoną ilością pamięci RAM użyj opcji limitu pamięci:
```bash
# Z limitem 512 MB (domyślnie)
pm2 start npm --name omniroute -- start
# Lub z niestandardowym limitem pamięci
OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start
# Lub przy użyciu ecosystem.config.js
pm2 start ecosystem.config.js
```
Utwórz `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
# Zbuduj obraz (domyślnie = runner-cli z preinstalowanymi codex/claude/droid)
docker build -t omniroute:cli .
# Tryb przenośny (zalecany)
docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli
```
Informacje o trybie zintegrowanym z hostem i plikami binarnymi CLI znajdziesz w sekcji Docker w głównej dokumentacji.
### Void Linux (xbps-src)
Użytkownicy Void Linux mogą natywnie pakować i instalować OmniRoute przy użyciu frameworka kompilacji skrośnej `xbps-src`. Automatyzuje on tworzenie samodzielnej wersji Node.js wraz z wymaganymi natywnymi powiązaniami `better-sqlite3`.
Wyświetl szablon xbps-src
```bash
# Plik szablonu dla pakietu „omniroute”
pkgname=omniroute
version=3.8.0
revision=1
hostmakedepends="nodejs python3 make"
depends="openssl"
short_desc="Uniwersalna brama AI z inteligentnym routingiem dla wielu dostawców LLM"
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() {
# Określ docelową architekturę procesora dla 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) Zainstaluj wszystkie zależności – pomiń skrypty
NODE_ENV=development npm ci --ignore-scripts
# 2) Zbuduj samodzielny pakiet Next.js
npm run build
# 3) Skopiuj zasoby statyczne do samodzielnego pakietu
cp -r .next/static .next/standalone/.next/static
[ -d public ] && cp -r public .next/standalone/public || true
# 4) Skompiluj natywne powiązanie 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) Umieść skompilowane powiązanie w samodzielnym pakiecie
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) Usuń pakiety sharp przeznaczone dla konkretnych architektur
rm -rf .next/standalone/node_modules/@img
# 7) Skopiuj zależności środowiska uruchomieniowego pino pominięte przez analizę statyczną 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
# Zapobiegaj usuwaniu pustych katalogów routera aplikacji Next.js przez skrypt wykonywany po instalacji
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
}
```
### Zmienne środowiskowe
| Zmienna | Wartość domyślna | Opis |
| --------------------------------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `JWT_SECRET` | `omniroute-default-secret-change-me` | Sekret do podpisywania tokenów JWT (**zmień w środowisku produkcyjnym**) |
| `INITIAL_PASSWORD` | `CHANGEME` | Hasło pierwszego logowania |
| `DATA_DIR` | `~/.omniroute` | Katalog danych (baza danych, użycie, dzienniki) |
| `PORT` | domyślna wartość frameworka | Port usługi (`20128` w przykładach) |
| `HOSTNAME` | domyślna wartość frameworka | Adres hosta do nasłuchiwania (Docker domyślnie używa `0.0.0.0`) |
| `NODE_ENV` | domyślna wartość środowiska uruchomieniowego | Ustaw `production` na potrzeby wdrożenia |
| `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128` | Publiczny bazowy adres URL udostępniany panelowi i serwerowi (zastępuje starszą zmienną `BASE_URL`) |
| `NEXT_PUBLIC_CLOUD_URL` | `https://omniroute.dev` | Bazowy adres URL punktu końcowego synchronizacji z chmurą (zastępuje starszą zmienną `CLOUD_URL`) |
| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | Sekret HMAC dla generowanych kluczy API |
| `REQUIRE_API_KEY` | `false` | Wymagaj klucza API Bearer dla `/v1/*` |
| `ALLOW_API_KEY_REVEAL` | `false` | Zezwalaj uwierzytelnionym użytkownikom panelu na wyświetlanie pełnych wartości przechowywanych kluczy API na żądanie |
| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Częstotliwość odświeżania po stronie serwera danych limitów dostawców zapisanych w pamięci podręcznej; przyciski odświeżania w interfejsie nadal uruchamiają ręczną synchronizację |
| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Wyłącz automatyczne migawki SQLite przed zapisem, importem lub przywracaniem; ręczne kopie zapasowe nadal działają |
| `APP_LOG_TO_FILE` | `true` | Włącza zapisywanie dzienników aplikacji i audytu na dysku |
| `AUTH_COOKIE_SECURE` | `false` | Wymuszaj atrybut `Secure` dla pliku cookie uwierzytelniania (za odwrotnym proxy HTTPS) |
| `CLOUDFLARED_BIN` | nieustawiona | Użyj istniejącego pliku binarnego `cloudflared` zamiast pobierania zarządzanej wersji |
| `CLOUDFLARED_PROTOCOL` | `http2` | Protokół transportowy dla zarządzanych tuneli Quick Tunnels (`http2`, `quic` lub `auto`) |
| `OMNIROUTE_MEMORY_MB` | `512` | Limit sterty Node.js w MB |
| `PROMPT_CACHE_MAX_SIZE` | `50` | Maksymalna liczba wpisów w pamięci podręcznej promptów |
| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Maksymalna liczba wpisów w semantycznej pamięci podręcznej |
Pełną dokumentację zmiennych środowiskowych można znaleźć w pliku [README](../README.md).
---
## 📊 Dostępne modele
Wyświetl wszystkie dostępne modele
> Poniższa lista została opracowana na podstawie pliku `open-sse/config/providerRegistry.ts` dla wersji v3.8.0. Katalogi chmurowe (Gemini, OpenRouter itp.) są synchronizowane dynamicznie — aby wyświetlić pełny katalog na żywo, otwórz **Panel → Dostawcy → [dostawca] → Dostępne modele** lub wywołaj `GET /api/models/catalog`.
>
> Jeśli wbudowana lista dostawcy przestała odpowiadać bieżącemu katalogowi, użyj opcji **Importuj z /models** na tej stronie (lub włącz **Automatyczną synchronizację**), aby pobrać aktualny katalog ze źródła nadrzędnego. Zostało to zweryfikowane w wersji v3.8.50 dla LLM7.io (`gemini-3.1-flash-lite`) oraz UncloseAI (`solidrust/Hermes-3-Llama-3.1-8B-AWQ`); podczas tych samych testów anonimowy dostęp do Pollinations nadal podlegał ograniczeniom źródła nadrzędnego.
**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` (+ poziomy intensywności: `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/`)** — BEZPŁATNY OAuth: użyj aktualnego katalogu wyświetlanego w sekcji **Panel → Dostawcy → Kiro → Dostępne modele**. Dostępność zależy od konta i planu.
**Qoder (`if/`)** — BEZPŁATNY 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 USD/1 mln: `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/1 mln: `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/`)** — stała opłata 9 USD/mies. lub opłata za użycie: `kimi/kimi-k2.6`, `kimi/kimi-k2.5`
**DeepSeek (`ds/`)** — klucz API: `ds/deepseek-v4-pro`, `ds/deepseek-v4-flash`
**Groq (`groq/`)** — wyjątkowo szybkie działanie: `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/`)** — natywne modele 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/`)** — hostowane w UE: `mistral/mistral-large-latest`, `mistral/mistral-medium-3-5`, `mistral/mistral-small-latest`, `mistral/devstral-latest`, `mistral/codestral-latest`
**Perplexity (`pplx/`)** — wspomagane wyszukiwaniem: `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` (bezpłatny), `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/`)** — szybkie wnioskowanie: `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/`)** — w skali całego wafla: `cerebras/zai-glm-4.7`, `cerebras/gpt-oss-120b`
**Cohere (`cohere/`)** — ukierunkowane 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/`)** — dla przedsiębiorstw: `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/`)**: synchronizowane na żywo z Google osobno dla każdego klucza API — brak statycznej listy. Połącz klucz w sekcji **Panel → Dostawcy**, a następnie użyj opcji **Dostępne modele**, aby zaimportować bieżący katalog (np. `gemini/gemini-3-pro`, `gemini/gemini-3-flash`).
**Inni zgodni dostawcy** (wybrani): `cohere`, `databricks`, `snowflake`, `together`, `vertex`, `alibaba`, `alibaba-cn`, `bedrock` (przez `aws-bedrock`), `azure-ai`, `openrouter` (katalog przekazywany bezpośrednio), `siliconflow`, `hyperbolic`, `huggingface`, `featherless-ai`, `cloudflare-ai`, `scaleway`, `deepinfra`, `vercel-ai-gateway`, `bazaarlink`, `friendliai`, `nous-research`, `reka`, `volcengine`, `ai21`, `gigachat`. Każdy z nich utrzymuje własną listę modeli w pliku `providerRegistry.ts` i może być synchronizowany automatycznie, jeśli dostawca udostępnia punkt końcowy `/models`.
**Uwaga dotycząca identyfikatorów modeli:** OmniRoute używa natywnych identyfikatorów dostawców (`claude-opus-4-8`, `gpt-5.5`, `glm-5.1`, `MiniMax-M2.7`, `kimi-k2.5`, `grok-4.20-0309-reasoning`). Niektóre identyfikatory zawierają wersje z kropkami, ponieważ tego oczekuje nadrzędne API. Jeśli model nie znajduje się na powyższej liście, uruchom `omniroute models --search ` lub wywołaj `GET /api/models/catalog`, aby potwierdzić jego dostępność.
---
## 🧩 Funkcje zaawansowane
### Modele niestandardowe
Dodaj dowolny identyfikator modelu do dowolnego dostawcy bez oczekiwania na aktualizację aplikacji:
```bash
# Za pośrednictwem API
curl -X POST http://localhost:20128/api/provider-models \
-H "Content-Type: application/json" \
-d '{"provider": "openai", "modelId": "gpt-5.2", "modelName": "GPT-5.2"}'
# Lista: curl http://localhost:20128/api/provider-models?provider=openai
# Usuwanie: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-5.2"
```
Możesz też użyć panelu: **Dostawcy → [Dostawca] → Modele niestandardowe**.
Uwagi:
- Dostawcami zgodnymi z OpenRouter oraz OpenAI/Anthropic zarządza się wyłącznie z poziomu **Dostępnych modeli**. Ręczne dodawanie, importowanie i automatyczna synchronizacja trafiają na tę samą listę dostępnych modeli, dlatego dla tych dostawców nie ma osobnej sekcji Modele niestandardowe.
- Sekcja **Modele niestandardowe** jest przeznaczona dla dostawców, którzy nie udostępniają zarządzanych importów dostępnych modeli.
### Niestandardowi dostawcy zgodni z OpenAI
Każdą bramę obsługującą API OpenAI (samodzielnie hostowane proxy, vLLM lub agregator zewnętrzny)
można dodać jako osobny węzeł dostawcy:
1. **Dostawcy → Dodaj dostawcę zgodnego z OpenAI**.
2. **Nazwa**: etykieta wyświetlana dla węzła.
3. **Prefiks**: nazwa używana do routingu. Klienci wywołują modele jako `/`, więc węzeł z
prefiksem `mygw` udostępnia `mygw/gpt-4o-mini`. Pole wymagane; nie ma ograniczeń dotyczących znaków.
4. **Typ API**: rodzina punktów końcowych obsługiwana przez bramę (Chat Completions, Responses,
Embeddings, audio, obrazy).
5. **Bazowy URL**: główny adres API, do `/v1` włącznie (na przykład
`https://gateway.example.com/v1`), a nie pełna ścieżka `/chat/completions`. Bramy z
niestandardowymi ścieżkami konfigurują je w sekcji **Ustawienia zaawansowane** (ścieżka czatu, ścieżka modeli).
6. Pole **Klucz API (do sprawdzenia)** służy tylko do testowania połączenia. Po utworzeniu węzła
otwórz go i użyj opcji **Dodaj połączenie**, aby zapisać klucz używany przez żądania.
Węzeł otrzymuje wewnętrzny identyfikator w formacie `openai-compatible--`; nigdy nie
musisz go wpisywać, ponieważ nazwą publiczną jest prefiks.
#### Zarezerwowane prefiksy
Prefiks nie może być identyfikatorem ani aliasem wbudowanego dostawcy (na przykład `openai`, `cf`) ani
identyfikatorem wycofanego dostawcy. Mechanizm rozpoznawania modeli sprawdza identyfikatory i aliasy wbudowanych dostawców przed
węzłami niestandardowymi, dlatego węzeł używający jednego z tych prefiksów nigdy nie otrzymałby ruchu:
`/model` zostałby skierowany do wbudowanego dostawcy albo odrzucony, jeśli ten dostawca
został wycofany. Próba utworzenia lub edycji węzła z takim prefiksem jest odrzucana z komunikatem:
```text
prefix: "" jest zarezerwowanym prefiksem dostawcy — wybierz inny prefiks (zarezerwowanych identyfikatorów/aliasów nie można używać dla węzłów niestandardowych, ponieważ żądania takie jak /model są kierowane do wbudowanego dostawcy lub odrzucane, gdy dostawca został wycofany)
```
Wybierz unikalny prefiks (`mygw`, `acme-proxy`). Jeśli żądania do niestandardowego węzła kończą się
błędem wskazującym wbudowanego dostawcę lub jego dane uwierzytelniające, sprawdź, czy prefiks węzła jest
zarezerwowany: węzły zapisane przed wprowadzeniem tej reguły są nadal przechowywane, ale ich prefiksy kierują ruch do
wbudowanego dostawcy. Edytuj węzeł i przypisz mu nowy prefiks.
### Łączenie równorzędnych instancji OmniRoute
Inną bramę OmniRoute można dodać jako **niestandardowego dostawcę zgodnego z OpenAI**. Użyj
bazowego adresu URL `/v1` równorzędnej instancji oraz dedykowanego klucza API o minimalnych uprawnieniach, wydanego przez tę instancję.
W przypadku łańcuchów wzajemnych lub wieloetapowych włącz opcjonalne zabezpieczenie przed pętlami na każdej bramie:
```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
```
Tylko żądania wysyłane do jawnie dozwolonego adresu URL równorzędnej instancji otrzymują nagłówek
`X-OmniRoute-Peer-Trace`. Brama odrzuca powtórzony identyfikator instancji lub wyczerpany limit przeskoków
z kodem HTTP `508 Loop Detected`; zwykli dostawcy nadrzędni nie otrzymują żadnych metadanych równorzędnych instancji.
Łączenie równorzędnych instancji nie jest replikacją bazy danych ani przełączaniem awaryjnym hosta. Każda brama zachowuje niezależny
stan SQLite, pamięci podręczne, liczniki limitów i sesje. W celu zapewnienia dostępności active/passive lub active/active użyj
odwrotnego proxy z kontrolą kondycji albo mechanizmu przełączania awaryjnego po stronie klienta i nigdy nie montuj jednej bazy danych SQLite
w wielu działających instancjach OmniRoute.
### Dedykowane trasy dostawców
Kieruj żądania bezpośrednio do konkretnego dostawcy z walidacją 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
```
Prefiks dostawcy jest automatycznie dodawany, jeśli go brakuje. Niedopasowane modele zwracają `400`.
### Konfiguracja proxy sieciowego
```bash
# Ustaw globalne proxy
curl -X PUT http://localhost:20128/api/settings/proxy \
-d '{"global": {"type":"http","host":"proxy.example.com","port":"8080"}}'
# Proxy dla poszczególnych dostawców
curl -X PUT http://localhost:20128/api/settings/proxy \
-d '{"providers": {"openai": {"type":"socks5","host":"proxy.example.com","port":"1080"}}}'
# Przetestuj proxy
curl -X POST http://localhost:20128/api/settings/proxy/test \
-d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}'
```
**Kolejność pierwszeństwa:** Dla konkretnego klucza → Dla konkretnej kombinacji → Dla konkretnego dostawcy → Globalne → Środowisko.
### API katalogu modeli
```bash
curl http://localhost:20128/api/models/catalog
```
Zwraca modele pogrupowane według dostawcy wraz z typami (`chat`, `embedding`, `image`).
### Synchronizacja z chmurą
- Synchronizowanie dostawców, kombinacji i ustawień między urządzeniami
- Automatyczna synchronizacja w tle z limitem czasu i szybkim przerywaniem w przypadku błędu
- W środowisku produkcyjnym preferuj zmienne po stronie serwera `NEXT_PUBLIC_BASE_URL`/`NEXT_PUBLIC_CLOUD_URL`
### Szybki tunel Cloudflare
- Dostępne w **Panel → Punkty końcowe** dla wdrożeń Docker i innych wdrożeń samodzielnie hostowanych
- Tworzy tymczasowy adres URL `https://*.trycloudflare.com`, który przekierowuje do bieżącego punktu końcowego `/v1` zgodnego z OpenAI
- Przy pierwszym włączeniu instaluje `cloudflared` tylko w razie potrzeby; kolejne uruchomienia ponownie wykorzystują ten sam zarządzany plik binarny
- Szybkie tunele nie są automatycznie przywracane po ponownym uruchomieniu OmniRoute lub kontenera; w razie potrzeby włącz je ponownie w panelu
- Adresy URL tuneli są tymczasowe i zmieniają się za każdym razem, gdy zatrzymujesz lub uruchamiasz tunel
- Zarządzane szybkie tunele domyślnie używają transportu HTTP/2, aby uniknąć uciążliwych ostrzeżeń dotyczących bufora UDP QUIC w kontenerach z ograniczonymi zasobami
- Ustaw `CLOUDFLARED_PROTOCOL=quic` lub `auto`, jeśli chcesz zastąpić zarządzany wybór transportu
- Ustaw `CLOUDFLARED_BIN`, jeśli wolisz używać wstępnie zainstalowanego pliku binarnego `cloudflared` zamiast zarządzanego pobierania
- Panele Cloudflare Quick Tunnel, Tailscale Funnel i ngrok Tunnel można wyświetlać lub ukrywać w **Ustawienia → Wygląd**. Ukrycie panelu nie zatrzymuje działającego tunelu.
### Inteligentna brama LLM (faza 9)
- **Pamięć podręczna semantyczna** — Automatycznie zapisuje w pamięci podręcznej odpowiedzi bez strumieniowania z temperature=0 (można ją pominąć za pomocą `X-OmniRoute-No-Cache: true`)
- **Idempotencja żądań** — Usuwa duplikaty żądań w przedziale 5 s za pomocą nagłówka `Idempotency-Key` lub `X-Request-Id`
- **Śledzenie postępu** — Opcjonalne zdarzenia SSE `event: progress` włączane za pomocą nagłówka `X-OmniRoute-Progress: true`
---
### Plac zabaw translatora
Dostęp przez **Panel → Translator**. Debuguj i wizualizuj sposób, w jaki OmniRoute tłumaczy żądania API między dostawcami.
| Tryb | Przeznaczenie |
| ---------------------- | ----------------------------------------------------------------------------------------------- |
| **Plac zabaw** | Wybierz format źródłowy i docelowy, wklej żądanie i natychmiast zobacz przetłumaczony wynik |
| **Tester czatu** | Wysyłaj wiadomości czatu na żywo przez serwer proxy i analizuj pełny cykl żądania i odpowiedzi |
| **Stanowisko testowe** | Uruchamiaj testy wsadowe dla wielu kombinacji formatów, aby zweryfikować poprawność tłumaczenia |
| **Monitor na żywo** | Obserwuj tłumaczenia w czasie rzeczywistym podczas przepływu żądań przez serwer proxy |
**Przypadki użycia:**
- Debugowanie przyczyn niepowodzenia określonej kombinacji klienta i dostawcy
- Sprawdzanie, czy znaczniki rozumowania, wywołania narzędzi i prompty systemowe są poprawnie tłumaczone
- Porównywanie różnic w formatach OpenAI, Claude, Gemini i Responses API
---
### Strategie routingu
Konfiguracja przez **Panel → Ustawienia → Routing**. Panel udostępnia sześć najczęściej używanych strategii; kombinacje i automatyczny router obsługują wewnętrznie szerszy zestaw.
**Strategie widoczne w panelu (routing na poziomie konta):**
| Strategia | Opis |
| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| **Wypełniaj najpierw** | Używa kont według kolejności priorytetów — konto główne obsługuje wszystkie żądania, dopóki nie stanie się niedostępne |
| **Round Robin** | Cyklicznie przełącza się między wszystkimi kontami z konfigurowalnym limitem trwałego przypisania (domyślnie: 3 wywołania na konto) |
| **P2C (wybór z dwóch możliwości)** | Wybiera 2 losowe konta i kieruje ruch do zdrowszego z nich — równoważy obciążenie z uwzględnieniem kondycji |
| **Losowo** | Losowo wybiera konto dla każdego żądania za pomocą tasowania Fishera-Yatesa |
| **Najrzadziej używane** | Kieruje ruch do konta z najstarszym znacznikiem czasu `lastUsedAt`, równomiernie rozdzielając ruch |
| **Optymalizacja kosztów** | Kieruje ruch do konta z najniższą wartością priorytetu, optymalizując wybór pod kątem najtańszych dostawców |
**Zaawansowane strategie kombinacji i automatyczne** (konfigurowane dla poszczególnych kombinacji lub za pomocą prefiksów `auto/*` — zobacz [AUTO-COMBO.md](../routing/AUTO-COMBO.md)):
- `priority` — ścisła kolejność, bez przełączania round-robin
- `weighted` — proporcjonalny podział ruchu według wag poszczególnych modeli
- `fill-first` — wykorzystuje pierwszy model aż do osiągnięcia limitów
- `round-robin` / `strict-random` / `random`
- `p2c` (wybór z dwóch możliwości)
- `least-used` i `cost-optimized`
- `auto` — wybór spośród wszystkich kandydatów na podstawie punktacji
- `lkgp` (ostatni znany sprawny dostawca) — przypina do ostatniego dostawcy, który pomyślnie obsłużył żądanie, a następnie stosuje reguły rezerwowe
- `context-optimized` — wybiera model z największym wolnym oknem kontekstu
- `context-relay` — łączy modele z długim kontekstem dla kolejnych tur
#### Zewnętrzny nagłówek trwałej sesji
Aby zapewnić zewnętrzne przypisanie do sesji (na przykład dla agentów Claude Code/Codex działających za odwrotnymi serwerami proxy), wyślij:
```http
X-Session-Id: your-session-key
```
OmniRoute akceptuje również `x_session_id` i zwraca efektywny klucz sesji w `X-OmniRoute-Session-Id`.
Jeśli używasz Nginx i wysyłasz nagłówki z podkreśleniami, włącz:
```nginx
underscores_in_headers on;
```
#### Aliasy modeli z symbolami wieloznacznymi
Twórz wzorce z symbolami wieloznacznymi, aby zmieniać mapowanie nazw modeli:
```
Wzorzec: claude-sonnet-* → Cel: cc/claude-sonnet-4-6
Wzorzec: gpt-* → Cel: gh/gpt-5.3-codex
```
Symbole wieloznaczne obsługują `*` (dowolne znaki) i `?` (pojedynczy znak).
#### Łańcuchy awaryjne
Definiuj globalne łańcuchy awaryjne mające zastosowanie do wszystkich żądań:
```
Łańcuch: production-fallback
1. cc/claude-opus-4-7
2. gh/gpt-5.3-codex
3. glm/glm-4.7
```
---
### Typowe kombinacje dostawców i wzorce routingu
Poniżej przedstawiono przykładowe wzorce łączenia wielu dostawców i kierowania ruchu między nimi w OmniRoute:
#### 1. Kombinacja dla agenta programistycznego: zaawansowane rozumowanie z awaryjnym wyborem według kosztu i szybkości
Idealna dla agentów programistycznych (OpenCode, Claude Code, Cursor, Cline). Początkowo kieruje ruch do czołowych modeli rozumowania, a po wyczerpaniu limitu lub wystąpieniu błędów przełącza się na szybkie modele programistyczne.
- **Panel**: Kombinacje → Nowa kombinacja → Nazwa: `agent-coding` → Strategia: `Priority`
- **Modele**:
1. `claude/claude-sonnet-4-6` (Główny agent programistyczny)
2. `openai/gpt-4o` (Dodatkowy model awaryjny o dużej wydajności)
3. `deepseek/deepseek-v4-flash` (Wysoce wydajny i opłacalny model awaryjny)
```bash
# Przykład za pośrednictwem 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. Kombinacja automatycznego przełączania awaryjnego w warstwie bezpłatnej
Łączy wielu dostawców z warstwy bezpłatnej oraz niewymagających klucza, aby zmaksymalizować dostępność bez ponoszenia kosztów API.
- **Strategia**: `Least Used` lub `Round Robin` (rozkłada obciążenie między limity)
- **Modele**:
1. `groq/llama-3.3-70b-versatile`
2. `gemini/gemini-2.5-flash`
3. `cerebras/gpt-oss-120b`
```bash
# Przykład za pośrednictwem 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. Potok multimodalny / obrazu i tekstu
Łączenie wyspecjalizowanych modeli wizyjnych z szybkim generowaniem tekstu na potrzeby przepływów pracy obejmujących rozumienie obrazów i generowanie kodu.
- **Wzorzec**: Kombinacja `Priority`, w której najpierw wymienione są modele obsługujące obraz, a na końcu model tekstowy/kodowy o wysokiej przepustowości.
- **Modele**:
1. `gemini/gemini-2.5-pro` (Zaawansowane rozumienie obrazów i treści multimodalnych)
2. `openai/gpt-4o` (Zrównoważona obsługa obrazu i użycia narzędzi)
3. `deepseek/deepseek-v4-flash` (Generowanie tekstu/kodu)
---
### Odporność i wyłączniki automatyczne
Skonfiguruj w **Panel sterowania → Ustawienia → Odporność**.
OmniRoute zapewnia odporność na poziomie dostawcy za pomocą pięciu komponentów:
1. **Kolejka żądań i regulacja tempa** — Kształtowanie ruchu żądań na poziomie systemu:
- **Żądania na minutę (RPM)** — Maksymalna liczba żądań na minutę dla każdego konta
- **Minimalny czas między żądaniami** — Minimalny odstęp między żądaniami w milisekundach
- **Maksymalna liczba równoczesnych żądań** — Maksymalna liczba jednoczesnych żądań dla każdego konta
2. **Okres wstrzymania połączenia** — Konfiguracja dla poszczególnych typów uwierzytelniania dla pojedynczego połączenia po błędach umożliwiających ponowienie:
- **Bazowy okres wstrzymania** — Domyślny czas wstrzymania po błędach usług nadrzędnych umożliwiających ponowienie
- **Używaj wskazówek ponowienia od usługi nadrzędnej** — Uwzględnia wiążące wskazówki `Retry-After` lub dotyczące resetowania, jeśli zostały podane
- **Maksymalna liczba kroków wycofania** — Maksymalny poziom wycofania wykładniczego dla powtarzających się błędów
3. **Wyłącznik automatyczny dostawcy** — Śledzi kompleksowe awarie dostawcy, oznacza dostawcę jako zdegradowanego po osiągnięciu skonfigurowanego progu ostrzegawczego i otwiera wyłącznik po osiągnięciu skonfigurowanego progu awarii:
- **Próg degradacji** — Liczba kolejnych awarii dostawcy przed przejściem do stanu `DEGRADED`
- **Próg awarii** — Liczba kolejnych awarii dostawcy przed przejściem do stanu `OPEN`
- **Limit czasu resetowania** — Czas do ponownego przetestowania dostawcy
- **CLOSED** (Sprawny) — Żądania są przetwarzane normalnie
- **DEGRADED** — Żądania nadal są przetwarzane, a zwiększona liczba awarii jest monitorowana
- **OPEN** — Dostawca jest tymczasowo blokowany po powtarzających się awariach
- **HALF_OPEN** — Sprawdzanie, czy dostawca odzyskał sprawność
Limity szybkości `429` dotyczące konkretnego połączenia pozostają obsługiwane przez **Okres wstrzymania połączenia** i nie są uwzględniane przez wyłącznik dostawcy.
Stan wyłącznika dostawcy w czasie wykonywania jest wyświetlany wyłącznie w **Panel sterowania → Kondycja**.
4. **Oczekiwanie na zakończenie okresu wstrzymania** — Jeśli wszystkie połączenia kandydujące są już wstrzymane, OmniRoute może poczekać na zakończenie najwcześniejszego okresu wstrzymania i automatycznie ponowić to samo żądanie klienta.
5. **Automatyczne wykrywanie limitu szybkości** — Gdy dostawcy nadrzędni zwracają jawne okresy oczekiwania, wskazówki te zastępują lokalny okres wstrzymania połączenia, jeśli to ustawienie jest włączone.
**Wskazówka:** Strona **Kondycja** umożliwia sprawdzanie i resetowanie aktywnych wyłączników dostawców po awarii. Strona Odporność służy wyłącznie do zmiany konfiguracji.
---
### Eksportowanie/importowanie bazy danych
Zarządzaj kopiami zapasowymi bazy danych w **Panel sterowania → Ustawienia → System i pamięć masowa**.
| Działanie | Opis |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Eksportuj bazę danych** | Pobiera bieżącą bazę danych SQLite jako plik `.sqlite` |
| **Eksportuj wszystko (.tar.gz)** | Pobiera pełne archiwum kopii zapasowej obejmujące: bazę danych, ustawienia, kombinacje, połączenia z dostawcami (bez danych uwierzytelniających), metadane kluczy API |
| **Importuj bazę danych** | Przesyła plik `.sqlite`, aby zastąpić bieżącą bazę danych. Kopia zapasowa sprzed importu jest tworzona automatycznie, chyba że ustawiono `DISABLE_SQLITE_AUTO_BACKUP=true` |
```bash
# API: Eksportuj bazę danych
curl -o backup.sqlite http://localhost:20128/api/db-backups/export
# API: Eksportuj wszystko (pełne archiwum)
curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll
# API: Importuj bazę danych
curl -X POST http://localhost:20128/api/db-backups/import \
-F "file=@backup.sqlite"
```
**Walidacja importu:** Importowany plik jest sprawdzany pod kątem integralności (kontrola pragma SQLite), wymaganych tabel (`provider_connections`, `provider_nodes`, `combos`, `api_keys`) oraz rozmiaru (maks. 100 MB).
**Przypadki użycia:**
- Migrowanie OmniRoute między komputerami
- Tworzenie zewnętrznych kopii zapasowych na potrzeby odzyskiwania po awarii
- Udostępnianie konfiguracji członkom zespołu (eksportuj wszystko → udostępnij archiwum)
---
### Panel ustawień
Strona ustawień jest podzielona na **7 kart**, co ułatwia nawigację:
| Karta | Zawartość |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Ogólne** | Narzędzia pamięci systemowej, domyślne zachowanie, widoczność tuneli Endpoint |
| **Wygląd** | Ustawienia motywu (jasny/ciemny/systemowy), widoczność paska bocznego, przełączniki paneli kart tuneli Cloudflare/Tailscale/ngrok |
| **AI** | Budżet myślenia (przekazywanie / automatyczne usuwanie / niestandardowy / adaptacyjny — zobacz [THINKING_BUDGET.md](./THINKING_BUDGET.md)), globalny prompt systemowy, statystyki pamięci podręcznej promptów |
| **Bezpieczeństwo** | Ustawienia logowania/hasła, kontrola dostępu IP, uwierzytelnianie API dla `/models`, blokowanie dostawców, ochrona przed wstrzykiwaniem promptów |
| **Routing** | Globalna strategia routingu (wypełnianie po kolei / Round Robin / P2C / losowa / najmniej używane / optymalizacja kosztów), aliasy modeli z symbolami wieloznacznymi, łańcuchy rezerwowe, domyślne ustawienia kombinacji |
| **Odporność** | Kolejka żądań, okres karencji połączeń, konfiguracja wyłącznika dostawcy oraz oczekiwanie na zakończenie okresu karencji |
| **Zaawansowane** | Globalna konfiguracja serwera proxy (HTTP/SOCKS5), nadpisania ustawień proxy dla poszczególnych dostawców |
Karta Ogólne nie powiela już informacji tylko do odczytu dotyczących logowania i pamięci podręcznej. Ustawienia przechowywania oraz
optymalizacji bazy danych są utrwalane za pośrednictwem `/api/settings/database`; ręczne czyszczenie pamięci podręcznej używa
`DELETE /api/cache`. Limity wierszy dzienników żądań i serwera proxy są kontrolowane przez
`CALL_LOGS_TABLE_MAX_ROWS` oraz `PROXY_LOGS_TABLE_MAX_ROWS`.
---
### Zarządzanie kosztami i budżetem
Dostęp przez **Panel → Koszty**.
| Karta | Przeznaczenie |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| **Budżet** | Ustawianie limitów wydatków dla poszczególnych kluczy API z budżetami dziennymi/tygodniowymi/miesięcznymi i śledzeniem w czasie rzeczywistym |
| **Cennik** | Wyświetlanie i edytowanie wpisów cenowych modeli — koszt za 1 tys. tokenów wejściowych/wyjściowych dla każdego dostawcy |
```bash
# API: Ustaw budżet
curl -X POST http://localhost:20128/api/usage/budget \
-H "Content-Type: application/json" \
-d '{"keyId": "key-123", "limit": 50.00, "period": "monthly"}'
# API: Pobierz bieżący stan budżetu
curl http://localhost:20128/api/usage/budget
```
**Śledzenie kosztów:** Każde żądanie rejestruje użycie tokenów i oblicza koszt na podstawie tabeli cen. Zestawienia według dostawcy, modelu i klucza API można wyświetlić w sekcji **Panel → Użycie**.
---
### Transkrypcja dźwięku
OmniRoute obsługuje transkrypcję dźwięku za pośrednictwem punktu końcowego zgodnego z OpenAI:
```bash
POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data
# Przykład z użyciem 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` jest natywną trasą Deepgram i wymaga klucza API Deepgram.
Jeśli skonfigurowano wyłącznie OpenRouter, użyj `openrouter/deepgram/nova-3`.
Dostawcy funkcji **zamiany mowy na tekst (transkrypcji)**:
- `openai/` (zgodność z Whisper)
- `groq/` (Groq Whisper Turbo)
- `deepgram/` (rodzina Nova)
- `assemblyai/`
- `nvidia/` (Parakeet, Canary)
- `huggingface/` (warianty Whisper)
- `qwen/`
Dostawcy funkcji **zamiany tekstu na mowę (`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/`
Obsługiwane formaty audio dla transkrypcji: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. Formaty wyjściowe TTS zależą od dostawcy (mp3, wav, opus, pcm, mulaw).
---
### Strategie równoważenia kombinacji
Równoważenie dla poszczególnych kombinacji można skonfigurować w sekcji **Panel → Kombinacje → Utwórz/Edytuj → Strategia**.
| Strategia | Opis |
| ------------------------- | ------------------------------------------------------------------------------------------------- |
| **Round-Robin** | Przełącza się kolejno między modelami |
| **Priorytetowa** | Zawsze najpierw próbuje użyć pierwszego modelu; przechodzi na model rezerwowy tylko w razie błędu |
| **Losowa** | Dla każdego żądania wybiera losowy model z kombinacji |
| **Ważona** | Kieruje żądania proporcjonalnie na podstawie wag przypisanych poszczególnym modelom |
| **Najmniej używane** | Kieruje żądanie do modelu z najmniejszą liczbą ostatnich żądań (korzysta z metryk kombinacji) |
| **Optymalizacja kosztów** | Kieruje żądanie do najtańszego dostępnego modelu (korzysta z tabeli cen) |
Globalne ustawienia domyślne kombinacji można określić w sekcji **Panel → Ustawienia → Routing → Domyślne ustawienia kombinacji**.
Limity czasu dla celów kombinacji domyślnie dziedziczą bieżący limit czasu żądania. Opcji **Limit czasu celu
(w sekundach)** w domyślnych ustawieniach kombinacji lub w pojedynczej kombinacji należy używać tylko wtedy, gdy krótszy limit dla danego celu powinien
szybciej uruchamiać mechanizm rezerwowy.
Optymalizacje kombinacji o zerowym opóźnieniu są opcjonalne. Pozostaw opcję **Optymalizacje o zerowym opóźnieniu** wyłączoną, aby
zapobiec sytuacjom, w których te funkcje opóźnień ścigają się z celami rezerwowymi, pomijają cele na podstawie historii TTFT
lub kompresują żądania rezerwowe; włączenie tej opcji pozwala skonfigurowanemu hedgingowi, predykcyjnemu pomijaniu na podstawie TTFT
i proaktywnej kompresji mechanizmu rezerwowego obniżyć opóźnienia w ogonie rozkładu kosztem wierności routingu/żądań.
Wyłącz **Bufor tokenów rozumowania**, gdy dostawcy nadrzędni wymagają ścisłych limitów
`max_tokens` / `maxOutputTokens`. Po włączeniu routing łączony dodaje dodatkowy zapas na rozumowanie tylko
dla modeli ze znanym limitem wyjściowym i pozostawia limit tokenów klienta bez zmian, gdy bezpieczna wartość
z uwzględnieniem bufora przekroczyłaby ten limit. Jeśli limit klienta już przekracza znany limit,
OmniRoute zmniejsza go do tej wartości przed wysłaniem żądania do dostawcy nadrzędnego.
---
### Panel kondycji
Dostęp przez **Panel → Kondycja**. Przegląd kondycji systemu w czasie rzeczywistym obejmujący 6 kart:
| Karta | Co przedstawia |
| ----------------------------- | --------------------------------------------------------------------------------- |
| **Stan systemu** | Czas działania, wersja, użycie pamięci, katalog danych |
| **Kondycja dostawców** | Globalny stan działania mechanizmu circuit breaker dostawców |
| **Limity szybkości** | Aktywne okresy karencji połączeń dla poszczególnych kont wraz z pozostałym czasem |
| **Aktywne blokady** | Aktywne blokady dotyczące modeli i tymczasowe wykluczenia |
| **Pamięć podręczna sygnatur** | Statystyki pamięci podręcznej deduplikacji (aktywne klucze, współczynnik trafień) |
| **Telemetria opóźnień** | Zagregowane opóźnienia p50/p95/p99 dla poszczególnych dostawców |
**Wskazówka:** Strona Kondycja odświeża się automatycznie co 10 sekund. Użyj karty mechanizmu circuit breaker, aby ustalić, u których dostawców występują problemy.
---
## 🤖 Automatyczne trasowanie (bez konfiguracji)
OmniRoute jest wyposażony w **automatyczny router oparty na punktacji**, który wybiera najlepszy model dla każdego żądania spośród wszystkich połączonych dostawców — bez konieczności utrzymywania kombinacji. Wystarczy wysłać żądanie z jednym z prefiksów `auto/*`, a OmniRoute na bieżąco utworzy wirtualną kombinację, oceniając kandydatów pod kątem opóźnienia, kosztu, współczynnika powodzenia, dopasowania do kontekstu, przydatności modelu do zadania, ostatnich awarii, limitów oraz stanu mechanizmu circuit breaker.
| Prefiks | Kryterium optymalizacji |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `auto` | Zrównoważone ustawienie domyślne (opóźnienie × koszt × współczynnik powodzenia) |
| `auto/coding` | Zadania programistyczne: preferuje Claude, GPT-5, GLM, Kimi, Qwen Coder i modele DeepSeek do kodowania |
| `auto/cheap` | Najniższy koszt $/token, dopuszcza większe opóźnienie |
| `auto/fast` | Najniższe opóźnienie, ignoruje koszt |
| `auto/offline` | Tylko lokalni dostawcy (Ollama, vLLM, llama.cpp) — przydatne w środowiskach odizolowanych od sieci |
| `auto/smart` | Najpierw jakość rozumowania (Opus, GPT-5 xhigh, R1, rozumowanie GLM 5.1) |
| `auto/lkgp` | „Ostatni znany dobry dostawca” — przypina ostatniego dostawcę, którego wywołanie zakończyło się powodzeniem, a następnie korzysta z reguł awaryjnych |
Przykład:
```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
}'
```
Pełny opis automatycznego routera znajduje się w pliku [AUTO-COMBO.md](../routing/AUTO-COMBO.md) — obejmuje on dostrajanie wag punktacji, dodawanie dostawców do czarnej listy oraz analizowanie decyzji dotyczących trasowania w sekcji **Panel → Auto Combo**.
---
## 🔌 Integracja z MCP i A2A
OmniRoute jest zarówno **serwerem MCP** (Model Context Protocol), jak i **serwerem A2A** (Agent-to-Agent JSON-RPC 2.0). Każde środowisko IDE lub host agenta zgodny z MCP może bezpośrednio wywoływać narzędzia OmniRoute — bez konieczności stosowania dodatkowej warstwy pośredniej.
### Transporty MCP
- **SSE**: `http://localhost:20128/api/mcp/sse`
- **Strumieniowy HTTP**: `http://localhost:20128/api/mcp/stream`
- **stdio**: `omniroute --mcp` (dla wtyczek IDE preferujących stdio)
### Łączenie z Claude Desktop
Edytuj plik `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) lub jego odpowiednik w systemie Windows/Linux:
```json
{
"mcpServers": {
"omniroute": {
"command": "omniroute",
"args": ["--mcp"]
}
}
}
```
### Łączenie z Cursor / Continue / VS Code MCP
Użyj adresu URL SSE `http://localhost:20128/api/mcp/sse` oraz klucza API typu Bearer wygenerowanego w sekcji **Panel → Klucze API**.
### Zakresy
MCP definiuje obecnie 32 nazwane zakresy. Każdy klucz Bearer można ograniczyć do określonych zakresów — pełną listę zakresów i narzędzi zawiera plik [MCP-SERVER.md](../frameworks/MCP-SERVER.md), a schemat JSON-RPC znajduje się w pliku [A2A-SERVER.md](../frameworks/A2A-SERVER.md).
---
## 🧠 System umiejętności
OmniRoute udostępnia rozszerzalny **framework umiejętności** (`src/lib/skills/`), dzięki któremu agenci i punkt końcowy A2A mogą uruchamiać procedury specyficzne dla danej dziedziny (np. `code-review`, `summarize`, `extract-facts`, `web-research`).
- **Interfejs marketplace’u** — przeglądaj i instaluj umiejętności w sekcji **Panel → Umiejętności**
- **Zakresy dla poszczególnych kluczy** — ograniczaj, które klucze API mogą wywoływać określone umiejętności
- **Niestandardowe umiejętności** — umieść plik TypeScript w `src/lib/a2a/skills/`, zarejestruj go, a natychmiast będzie można go wywoływać przez A2A
Pełna dokumentacja: [SKILLS.md](../frameworks/SKILLS.md).
---
## 💾 System pamięci
OmniRoute przechowuje **długoterminową pamięć konwersacji**, korzystając z hybrydowego wyszukiwania:
- **SQLite FTS5** do wyszukiwania słów kluczowych w poprzednich turach rozmowy
- **Magazyn wektorowy Qdrant** (opcjonalnie) do wyszukiwania semantycznego
- **Automatyczne wyodrębnianie faktów** — encje, preferencje i decyzje są podsumowywane po każdej sesji i zapisywane w tabeli `memory_facts`
- Pamięć jest izolowana dla każdego klucza API i każdej sesji
Zarządzaj pamięcią w sekcji **Panel → Pamięć** (wyszukiwanie, edycja, eksport, czyszczenie). Interfejs HTTP (`/api/memory/*`) umożliwia agentom programowe przesyłanie i wyszukiwanie faktów — zobacz [MEMORY.md](../frameworks/MEMORY.md).
---
## 🔔 Webhooki
Subskrybuj zdarzenia OmniRoute na potrzeby monitorowania i automatyzacji w czasie rzeczywistym.
- Utwórz webhook w sekcji **Panel → Webhooki**, podając docelowy URL i sekret podpisu HMAC
- Dostępne zdarzenia: `request.completed`, `request.failed`, `provider.unavailable`, `budget.exceeded`, `combo.switched`, `circuit_breaker.opened`, `circuit_breaker.closed`
- Każdy ładunek zawiera `X-OmniRoute-Signature` (HMAC-SHA256) do weryfikacji
- Ponowienia: 3 próby z wykładniczym wydłużaniem opóźnienia, a następnie kolejka komunikatów niedostarczonych
Pełny schemat znajduje się w [WEBHOOKS.md](../frameworks/WEBHOOKS.md).
---
## ☁️ Agenci chmurowi
OmniRoute integruje się z chmurowymi agentami programistycznymi (**OpenAI Codex Cloud**, **Devin**, **Jules**, **Antigravity**), dzięki czemu możesz zlecać długotrwałe zadania z tego samego panelu, który obsługuje lokalne trasowanie.
- Twórz zadania w sekcji **Panel → Agenci chmurowi** lub za pomocą `POST /api/v1/agents/tasks`
- Śledź stan, logi i artefakty poszczególnych zadań
- Używaj własnego klucza API dla każdego dostawcy — dane uwierzytelniające nigdy nie opuszczają instancji OmniRoute
Pełna dokumentacja: [CLOUD_AGENT.md](../frameworks/CLOUD_AGENT.md).
---
## 🛠️ Zarządzanie programowe
Każdym zasobem OmniRoute (dostawcami, kombinacjami, kluczami, ustawieniami) możesz zarządzać przez HTTP za pomocą **klucza Bearer z zakresem `manage`**.
Wygeneruj klucz w sekcji **Panel → Klucze API → Nowy klucz → Zakres: manage**, a następnie:
```bash
# Wyświetl dostawców
curl http://localhost:20128/api/providers \
-H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY"
# Dodaj połączenie z dostawcą
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" }'
# Utwórz kombinację
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" }] }'
# Wyświetl/utwórz klucze API
curl http://localhost:20128/api/keys -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY"
curl -X POST http://localhost:20128/api/keys -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY" \
-d '{ "name": "ci-bot", "scopes": ["chat"] }'
```
Pełny katalog punktów końcowych oraz schematy żądań i odpowiedzi znajdziesz w [API_REFERENCE.md](../reference/API_REFERENCE.md).
---
## 💻 Wewnętrzny interfejs CLI
OmniRoute zawiera wewnętrzny interfejs CLI (`omniroute …`) służący do konfiguracji, diagnostyki i sterowania środowiskiem uruchomieniowym. Jest on **niezależny od strony „Narzędzia CLI” w panelu**, która konfiguruje narzędzia CLI innych firm (Claude Code, Cursor, Codex, Cline, …), aby mogły komunikować się z OmniRoute.
```bash
omniroute setup # Interaktywny kreator (hasło, dostawcy, kombinacje)
omniroute setup --non-interactive # Przyjazny dla środowisk CI
omniroute doctor # Diagnostyka stanu (katalog danych, baza danych, dostawcy, porty)
omniroute providers available # Wyświetla obsługiwanych dostawców
omniroute providers list # Wyświetla skonfigurowane połączenia
omniroute providers test # Testuje na żywo połączenie z dostawcą
omniroute combos list # Wyświetla kombinacje
omniroute combos switch # Ustawia domyślną kombinację
omniroute models # Wyświetla dostępne modele (--json, --search)
omniroute keys add | list | remove # Zarządza kluczami API z poziomu terminala
omniroute backup # Tworzy migawkę konfiguracji i bazy danych
omniroute restore [] # Przywraca dane z migawki
omniroute health # Szczegółowy stan (bezpieczniki, pamięć podręczna, pamięć)
omniroute quota # Wykorzystanie limitów dostawców
omniroute mcp status # Stan serwera MCP
omniroute a2a status # Stan serwera A2A
omniroute tunnel list|create|stop # Tunele Cloudflare/Tailscale/ngrok
omniroute reset-password # Resetuje hasło administratora
omniroute --mcp # Uruchamia serwer MCP przez stdio
omniroute --port 3000 # Uruchamia serwer na niestandardowym porcie
```
Wskazówka: połącz `omniroute doctor --json` z narzędziem monitorującym, aby otrzymywać alerty o niesprawnych połączeniach z dostawcami.
---
## 🖥️ Aplikacja komputerowa (Electron)
OmniRoute jest dostępny jako natywna aplikacja komputerowa dla systemów Windows, macOS i Linux.
### Instalacja
```bash
# Z katalogu electron:
cd electron
npm install
# Tryb deweloperski (łączy się z uruchomionym serwerem deweloperskim Next.js):
npm run dev
# Tryb produkcyjny (korzysta z samodzielnej kompilacji):
npm start
```
### Tworzenie instalatorów
```bash
cd electron
npm run build # Bieżąca platforma
npm run build:win # Windows (.exe NSIS)
npm run build:mac # macOS (.dmg uniwersalny)
npm run build:linux # Linux (.AppImage)
```
Dane wyjściowe → `electron/dist-electron/`
### Najważniejsze funkcje
| Funkcja | Opis |
| ---------------------------------- | -------------------------------------------------------------- |
| **Gotowość serwera** | Sprawdza serwer przed wyświetleniem okna (bez pustego ekranu) |
| **Zasobnik systemowy** | Minimalizacja do zasobnika, zmiana portu i zamykanie z menu |
| **Zarządzanie portem** | Zmiana portu serwera z zasobnika (automatycznie go restartuje) |
| **Polityka bezpieczeństwa treści** | Restrykcyjna polityka CSP za pośrednictwem nagłówków sesji |
| **Pojedyncza instancja** | Jednocześnie może działać tylko jedna instancja aplikacji |
| **Tryb offline** | Dołączony serwer Next.js działa bez dostępu do internetu |
### Zmienne środowiskowe
| Zmienna | Wartość domyślna | Opis |
| --------------------- | ---------------- | ---------------------------------- |
| `OMNIROUTE_PORT` | `20128` | Port serwera |
| `OMNIROUTE_MEMORY_MB` | `512` | Limit sterty Node.js (64–16384 MB) |
📖 Pełna dokumentacja: [`electron/README.md`](../../electron/README.md)