# 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 masowo 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 kompatybilny 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 z Claude Code
→ Logowanie OAuth → Automatyczne odświeżanie tokenu
→ Śledzenie limitu 5-godzinnego + tygodniowego
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 limity dla każdego modelu!
Nie masz przeglądarki na hoście OmniRoute? Uruchom `claude setup-token` w dowolnym miejscu, gdzie jesteś zalogowany w Claude Code, i wklej roczny token do karty **Token konfiguracji**. Zobacz [Claude Code z tokenem konfiguracji](../providers/CLAUDE_CODE_SETUP_TOKEN.md).
Trasy zgodne z Claude i Claude Code zachowują maksymalny poziom nakładu na rozumowanie `max` dla
modeli Opus i Sonnet. Modele Haiku nie akceptują poziomu nakładu `max`, dlatego OmniRoute obniża to
żądanie do wysokiego budżetu na rozumowanie przed wysłaniem go do dostawcy nadrzędnego.
#### OpenAI Codex (Plus/Pro)
```bash
Panel → Dostawcy → Połącz z Codex
→ Logowanie OAuth (port 1455)
→ Resetowanie 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 z 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
```
**Kredyty AI (rozliczanie na podstawie tokenów).** Gdy GitHub zgłasza dla konta wartość `credits_used`,
karta Limitów dostawcy wyświetla wiersz **Kredyty AI** z liczbą kredytów
zużytych w bieżącym okresie rozliczeniowym, także w przypadku nielimitowanych planów organizacji.
**Lokalny limit kredytów AI.** Edytuj połączenie z GitHub i ustaw **Limit kredytów AI na
okres rozliczeniowy** (`providerSpecificData.githubCreditLimit`). Pusta wartość wyłącza limit; `0`
zawsze pomija połączenie. Gdy ostatni odczyt użycia jest równy limitowi lub go przekracza,
wybór konta pomija to połączenie, a routing przełącza się na inne połączenia — tak samo jak w
przypadku odcięcia przez zasady limitu. Sprawdzane jest użycie zebrane już podczas okresowego
odświeżania limitu — GitHub nigdy nie jest wywoływany na ścieżce żądania — a mechanizm działa
w trybie fail-open: brak odczytu lub nieaktualny odczyt (starszy niż 15 minut albo pochodzący z
okresu rozliczeniowego, który już się zresetował) nie blokuje połączenia. To lokalne zabezpieczenie,
**a nie gwarantowany limit wydatków**: opóźnienia w raportowaniu przez GitHub, interwał odświeżania,
żądania będące w toku oraz użycie poza OmniRoute mogą spowodować przekroczenie limitu. Aby
ustawić twardy limit, użyj własnych mechanizmów kontroli wydatków GitHub.
### 💰 Niedrodzy dostawcy
#### GLM-4.7 (reset dzienny, 0,6 USD/1 mln)
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× większy limit przy koszcie 1/7! Reset codziennie o 10:00.
#### MiniMax M2.1 (reset co 5 godzin, 0,20 USD/1 mln)
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 (1 mln tokenów)!
#### Kimi K2 (stała opłata 9 USD/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ła opłata 9 USD/miesiąc za 10 mln tokenów = efektywny koszt 0,90 USD/1 mln!
#### 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 zgodny z OpenAI.
### 🆓 DARMOWI dostawcy
Darmowi dostawcy niewymagający uwierzytelniania mają przełącznik obok opcji **Uwierzytelnianie niewymagane** na stronie dostawcy.
Wyłączenie go dezaktywuje dostawcę, usuwa go z widoków skonfigurowanych dostawców i widoku kompaktowego,
a także usuwa jego modele z `/v1/models`.
#### Qoder (9 DARMOWYCH modeli)
```bash
Panel → Połącz z Qoder → Logowanie OAuth → Dostęp zależy od bieżących limitów 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 (DARMOWY Claude)
```bash
Panel → Połącz z Kiro → AWS Builder ID lub Google/GitHub → około 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 npm (zalecana)
```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 automatycznie ładuje `.env` z `~/.omniroute/.env` lub `./.env`. `./.env` w katalogu roboczym może ustawić tylko krótką listę dozwolonych kluczy (porty, `REQUIRE_API_KEY`, ustawienia regionalne i kolory); umieść wszystko inne w `~/.omniroute/.env`. Zobacz [kontrakty na uruchomienie CLI](CLI-LAUNCH-CONTRACTS.md#working-directory-env).
### Tryb tacy
Uruchom OmniRoute w zasobniku systemowym:
```bash
omniroute serve --tray
```
Polecenie powraca, gdy serwer i taca będą gotowe.
Serwer działa bez terminala.
Tryb tacy obsługuje sesje macOS, Windows i graficzne Linux. Tryb tacy nie otwiera automatycznie pulpitu nawigacyjnego.
Użyj menu zasobnika, aby wykonać następujące czynności:
- Otwórz pulpit nawigacyjny.
- Otwórz `/dashboard/logs`.
- Zmień autostart.
- Przestań OmniRoute.
Nie łącz `--tray` z tymi opcjami:
- `--daemon`
- `--log`
- `--no-recovery`
Te tryby wymagają innej własności procesu.
Włącz uruchamianie przy następnym logowaniu komputera:
```bash
omniroute autostart enable
```
Autostart używa trybu zasobnika w sesjach macOS, Windows i graficznych Linux. Headless Linux korzysta z istniejącej usługi użytkownika systemowego.
Wyłącz uruchamianie przy logowaniu:
```bash
omniroute autostart disable
```
### Odinstalowywanie
Kiedy nie potrzebujesz już OmniRoute, udostępniamy dwa szybkie skrypty do czystego usunięcia:
| Rozkaz | Działanie |
| ------------------------ | -------------------------------------------------------------------------------------- |
| `npm run uninstall` | Usuwa aplikację systemową, ale** zachowuje Twoje DB i konfiguracje** w `~/.omniroute`. |
| `npm run uninstall:full` | Trwale usuwa aplikację AND** usuwa wszystkie konfiguracje, klucze i bazy danych** . |
> Uwaga: Aby uruchomić te polecenia, przejdź do folderu projektu OmniRoute (jeśli go sklonowałeś) i uruchom je. Alternatywnie, jeśli jest zainstalowany globalnie, możesz po prostu uruchomić `npm uninstall -g omniroute`.
### VPS Wdrożenie
```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
```
### Wdrożenie PM2 (mało pamięci)
W przypadku serwerów z ograniczonym RAM użyj opcji limitu pamięci:
```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
```
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
# 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
```
Informacje na temat trybu zintegrowanego z hostem i plików binarnych CLI można znaleźć w sekcji Docker w głównych dokumentach.
### Puste Linux (xbps-src)
Użytkownicy Void Linux mogą pakować i instalować OmniRoute natywnie, korzystając ze środowiska kompilacji krzyżowej `xbps-src`. Automatyzuje to samodzielną kompilację Node.js wraz z wymaganymi natywnymi powiązaniami `better-sqlite3`.
Wyświetl szablon 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
}
```
### Zmienne środowiskowe
| Zmienny | Domyślny | Opis |
| --------------------------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `JWT_SECRET` | _(wygenerowane automatycznie)_ | Sekret podpisywania JWT — generowany automatycznie przy pierwszym uruchomieniu i zachowywany w `server.env`; ustaw go jawnie, gdy katalog danych jest efemeryczny |
| `INITIAL_PASSWORD` | _(nieoprawny)_ | Hasło pierwszego logowania. Instalacje npm/source rozpoczynają się od `CHANGEME`: zamień go. Nieustawione: kreator dołączania |
| `DATA_DIR` | `~/.omniroute` | Katalog danych (db, użycie, logi) |
| `PORT` | domyślne ramy | Port serwisowy (w przykładach `20128` ) |
| `HOSTNAME` | domyślne ramy | Powiąż hosta (domyślnie Docker to `0.0.0.0`) |
| `NODE_ENV` | domyślne środowisko wykonawcze | Ustaw `production` do wdrożenia |
| `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128` | Publiczna baza URL pojawiła się na pulpicie nawigacyjnym i udostępniona serwerowi (zastępuje starsze `BASE_URL`) |
| `NEXT_PUBLIC_CLOUD_URL` | `https://omniroute.dev` | Baza punktu końcowego synchronizacji w chmurze URL (zastępuje starszą wersję `CLOUD_URL`) |
| `API_KEY_SECRET` | _(wygenerowane automatycznie)_ | Sekret HMAC dla wygenerowanych kluczy API — wygenerowany automatycznie przy pierwszym uruchomieniu i utrwalony w `server.env` |
| `REQUIRE_API_KEY` | `false` | Wymuś klucz Bearer API na `/v1/*` |
| `ALLOW_API_KEY_REVEAL` | `false` | Zezwalaj uwierzytelnionym użytkownikom pulpitu nawigacyjnego na ujawnianie na żądanie pełnych zapisanych wartości kluczy API |
| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Częstotliwość odświeżania po stronie serwera buforowanych danych dotyczących limitów dostawcy; Przyciski odświeżania UI nadal uruchamiają ręczną synchronizację |
| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Wyłącz automatyczne migawki SQLite przed writes/import/restore; ręczne kopie zapasowe nadal działają |
| `APP_LOG_TO_FILE` | `true` | Umożliwia zapisanie na dysku dziennika aplikacji i dziennika audytu |
| `AUTH_COOKIE_SECURE` | `false` | Wymuś plik cookie uwierzytelniania `Secure` (za odwrotnym proxy HTTPS ) |
| `CLOUDFLARED_BIN` | nieoprawny | Użyj istniejącego pliku binarnego `cloudflared` zamiast pobierania zarządzanego |
| `CLOUDFLARED_PROTOCOL` | `http2` | Transport dla zarządzanych szybkich tuneli (`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 monitów |
| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Maksymalna liczba wpisów w semantycznej pamięci podręcznej |
Aby zapoznać się z pełnym odwołaniem do zmiennych środowiskowych, zobacz [README](../README.md).
---
## 📊 Dostępne modele
Wyświetl wszystkie dostępne modele
> Poniższa lista została opracowana na podstawie `open-sse/config/providerRegistry.ts` dla v3.8.0. Katalogi chmurowe (Gemini, OpenRouter itd.) są synchronizowane dynamicznie — aby wyświetlić pełny aktualny katalog, otwórz **Dashboard → Providers → [provider] → Available Models** lub wywołaj `GET /api/models/catalog`.
>
> Jeśli wbudowana lista dostawcy uległa rozbieżności, użyj opcji **Import from /models** na tej stronie (lub włącz **Auto-Sync**), aby pobrać aktualny katalog ze źródła. Zostało to zweryfikowane w v3.8.50 dla LLM7.io (`gemini-3.1-flash-lite`) i UncloseAI (`solidrust/Hermes-3-Llama-3.1-8B-AWQ`); anonimowy dostęp Pollinations pozostawał ograniczony przez źródło podczas tej samej serii testów.
**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 wysiłku: `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/`)** — DARMOWY OAuth: użyj aktualnego katalogu wyświetlanego w sekcji **Dashboard → Providers → Kiro → Available Models**. Dostępność zależy od konta i planu.
**Qoder (`if/`)** — DARMOWY 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/`)** — 9 USD/mies. w rozliczeniu ryczałtowym lub płatność 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/`)** — ultraszybki: `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/`)** — natywny 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/`)** — hostowany w UE: `mistral/mistral-large-latest`, `mistral/mistral-medium-3-5`, `mistral/mistral-small-latest`, `mistral/codestral-latest`
**Perplexity (`pplx/`)** — ze wsparciem wyszukiwania: `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 wafla: `cerebras/zai-glm-4.7`, `cerebras/gpt-oss-120b`
**Cohere (`cohere/`)** — skoncentrowany 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/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/`)**: synchronizowany na bieżąco dla każdego klucza API z Google — brak statycznej listy. Połącz klucz w **Dashboard → Providers**, a następnie użyj **Available Models**, aby zaimportować aktualny 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 dalej), `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 `providerRegistry.ts` i może być automatycznie synchronizowany, 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ż właśnie tak oczekuje ich 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ść.
---
## 🧩 Zaawansowane funkcje
### Modele niestandardowe
Dodaj dowolny model ID do dowolnego dostawcy, nie czekając na aktualizację aplikacji:
```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"
```
Lub użyj Panelu:** Dostawcy → [Dostawca] → Modele niestandardowe** .
Uwagi:
- Dostawcy OpenRouter i OpenAI/Anthropic-compatible są zarządzani z poziomu** Dostępne modele** tylko. Ręczne dodawanie, importowanie i automatyczna synchronizacja wszystkich gruntów na tej samej liście dostępnych modeli, więc nie ma osobnej sekcji modeli niestandardowych dla tych dostawców.
- The** Modele niestandardowe** Sekcja jest przeznaczona dla dostawców, którzy nie udostępniają zarządzanych importów dostępnych modeli.
### Niestandardowi dostawcy kompatybilni z OpenAI
Dowolną bramę posługującą się OpenAI API (samodzielny serwer proxy, vLLM, agregator innej firmy) można dodać jako własny węzeł dostawcy:
1. **Dostawcy → Dodaj OpenAI Kompatybilny** .
2. **Nazwa** : etykieta wyświetlana węzła.
3. **Prefiks** : nazwa routingu. Klienci nazywają modele jako `/`, więc węzeł z przedrostkiem `mygw` obsługuje `mygw/gpt-4o-mini`. Wymagany; nie ma ograniczeń dotyczących znaków.
4. **API** : rodzina punktów końcowych obsługiwana przez bramę (zakończenia czatu, odpowiedzi, osadzenia, dźwięk, obrazy).
5. **Baza URL** : katalog główny API, aż 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 ustawiają je pod** Ustawienia zaawansowane** (ścieżka czatu, ścieżka modeli).
6. The** Klucz API (do czeku)** pole testuje jedynie połączenie. Po utworzeniu węzła otwórz go i użyj** Dodaj połączenie** do przechowywania klucza, którego będą używać żądania.
Węzeł otrzymuje wewnętrzny identyfikator w postaci `openai-compatible--`; nigdy nie musisz go wpisywać, prefiks jest nazwą publiczną.
#### Zarezerwowane przedrostki
Prefiks nie może być identyfikatorem ani aliasem wbudowanego dostawcy (na przykład `openai`, `cf`) ani identyfikatorem wycofanego dostawcy. Mechanizm rozpoznawania nazw modelu sprawdza wbudowane identyfikatory i aliasy przed węzłami niestandardowymi, więc węzeł używający jednego z tych przedrostków nigdy nie otrzyma ruchu: `/model` zamiast tego przejdzie do wbudowanego dostawcy lub zakończy się niepowodzeniem, jeśli dostawca ten zostanie wycofany. Tworzenie lub edytowanie węzła z takim przedrostkiem jest odrzucane w przypadku:
```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)
```
Wybierz odrębny przedrostek (`mygw`, `acme-proxy`). Jeśli żądania kierowane do węzła niestandardowego nie powiodą się z powodu błędu wskazującego nazwę wbudowanego dostawcy lub jego poświadczenia, sprawdź, czy prefiks węzła jest zarezerwowany: węzły zapisane przed istnieniem tej reguły są nadal przechowywane, ale ich prefiks kieruje do wbudowanego dostawcy. Edytuj węzeł i nadaj mu nowy przedrostek.
#### Opcje bramy dla każdego połączenia
Te klucze trafiają do `providerSpecificData` połączenia (na przykład poprzez `PUT /api/providers/{id}`):
- `toolNameMaxLength` (liczba całkowita, 1–1024) — dla połączeń zgodnych z formatem czatu OpenAI, których brama odrzuca długie nazwy narzędzi. Dłuższe nazwy są wysyłane jako krótkie aliasy i przywracane w odpowiedzi.
- `quotaEndpoint` — punkt końcowy quota/credits bramy, odczyt dotyczący paska przydziału pulpitu nawigacyjnego i routingu uwzględniającego przydziały. Działa zarówno na połączeniach kompatybilnych z OpenAI, jak i Anthropic; pełny kształt jest udokumentowany w `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" }
}
}
}
```
### Łączenie OmniRoute Peers
Kolejną bramkę OmniRoute można dodać jako** Niestandardowa kompatybilność z OpenAI** dostawca. Użyj bazy `/v1` partnera URL i dedykowanego klucza API o najniższych uprawnieniach wydanego przez tego partnera.
W przypadku łańcuchów wzajemnych lub z wieloma przeskokami włącz opcję ochrony przed pętlą na każdej bramce:
```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 wysłane do wyraźnie dozwolonego elementu równorzędnego URL otrzymują nagłówek `X-OmniRoute-Peer-Trace`. Brama odrzuca powtarzającą się instancję ID lub wyczerpany budżet przeskoku z HTTP `508 Loop Detected`; zwykli dostawcy wyższego szczebla nie otrzymują metadanych równorzędnych.
Łańcuch równorzędny nie jest replikacją bazy danych ani przełączaniem awaryjnym hosta. Każda brama utrzymuje niezależny stan SQLite, pamięci podręczne, liczniki szybkości i sesje. Używaj sprawdzonego odwrotnego proxy lub przełączania awaryjnego klienta, aby zapewnić dostępność active/passive lub active/active 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 dodawany automatycznie, jeśli go brakuje. Niedopasowane modele zwracają `400`.
### Konfiguracja serwera proxy sieci
```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"}}'
```
**Pierwszeństwo:** Specyficzne dla klucza → Specyficzne dla kombinacji → Specyficzne dla dostawcy → Globalne → Środowisko.
### Katalog modeli API
```bash
curl http://localhost:20128/api/models/catalog
```
Zwraca modele pogrupowane według dostawców z typami (`chat`, `embedding`, `image`).
### Synchronizacja w chmurze
- Synchronizuj dostawców, kombinacje i ustawienia na różnych urządzeniach
- Automatyczna synchronizacja w tle z limitem czasu + Fail-Fast
- Preferuj `NEXT_PUBLIC_BASE_URL`/`NEXT_PUBLIC_CLOUD_URL` po stronie serwera w produkcji
### Cloudflare Szybki tunel
- Dostępne w** Pulpit nawigacyjny → Punkty końcowe** dla Docker i innych wdrożeń hostowanych samodzielnie
- Tworzy tymczasowy plik `https://*.trycloudflare.com` URL, który przekazuje do bieżącego punktu końcowego `/v1` zgodnego z OpenAI
- Najpierw włącz instalowanie `cloudflared` tylko wtedy, gdy jest to potrzebne; później uruchamia ponownie, ponownie używa tego samego zarządzanego pliku binarnego
- Szybkie tunele nie są automatycznie przywracane po ponownym uruchomieniu OmniRoute lub kontenera; w razie potrzeby włącz je ponownie z poziomu pulpitu nawigacyjnego
- Tunele URLs są efemeryczne i zmieniają się za każdym razem, gdy stop/start tunel
- Zarządzane szybkie tunele domyślnie korzystają z transportu HTTP/2, aby uniknąć hałaśliwych ostrzeżeń o buforze QUIC UDP w ograniczonych kontenerach
- Ustaw `CLOUDFLARED_PROTOCOL=quic` lub `auto` jeśli chcesz zastąpić wybór zarządzanego transportu
- Ustaw `CLOUDFLARED_BIN` jeśli wolisz używać preinstalowanego 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 powoduje zatrzymania działającego tunelu.
### Inteligencja bramy LLM (faza 9)
- **Pamięć podręczna semantyczna** — Automatyczne buforowanie bez przesyłania strumieniowego, temperatura = 0 odpowiedzi (obejście z `X-OmniRoute-No-Cache: true`)
- **Poproś o Idempotencję** — Deduplikuje żądania w ciągu 5 sekund poprzez nagłówek `Idempotency-Key` lub `X-Request-Id`
- **Śledzenie postępu** — Włącz zdarzenia SSE `event: progress` poprzez nagłówek `X-OmniRoute-Progress: true`
---
### Plac zabaw dla tłumaczy
Dostęp przez** Pulpit nawigacyjny → Tłumacz** . Debuguj i wizualizuj, jak OmniRoute tłumaczy żądania API pomiędzy dostawcami.
| Tryb | Zamiar |
| ---------------------- | -------------------------------------------------------------------------------------------------- |
| **Plac gier i zabaw** | Wybierz formaty source/target, wklej żądanie i natychmiast zobacz przetłumaczony wynik |
| **Tester czatu** | Wysyłaj wiadomości na czacie na żywo przez serwer proxy i sprawdzaj pełny cykl request/response |
| **Stanowisko testowe** | Przeprowadzaj testy wsadowe w wielu kombinacjach formatów, aby zweryfikować poprawność tłumaczenia |
| **Monitor na żywo** | Oglądaj tłumaczenia w czasie rzeczywistym, gdy żądania przepływają przez serwer proxy |
**Przypadki użycia:**
- Debuguj, dlaczego konkretna kombinacja client/provider zawodzi
- Sprawdź, czy znaczniki myślenia, wywołania narzędzi i podpowiedzi systemowe są tłumaczone poprawnie
- Porównaj różnice w formatach między formatami OpenAI, Claude, Gemini i odpowiedzi API
---
### Strategie routingu
Skonfiguruj przez** Pulpit nawigacyjny → Ustawienia → Routing** . Pulpit nawigacyjny przedstawia sześć najczęściej używanych strategii; kombinacje i automatyczny router wewnętrznie obsługują szerszy zestaw.
**Strategie widoczne na pulpicie nawigacyjnym (routing na poziomie konta):**
| Strategia | Opis |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| **Najpierw wypełnij** | Używa kont w kolejności priorytetów — konto główne obsługuje wszystkie żądania, dopóki nie będą niedostępne |
| **Okrągły Robin** | Przełącza cyklicznie pomiędzy wszystkimi kontami z konfigurowalnym limitem stałym (domyślnie: 3 połączenia na konto) |
| **P2C (moc dwóch wyborów)** | Wybiera 2 losowe konta i ścieżki do zdrowszego — równoważy obciążenie świadomością zdrowia |
| **Losowy** | Losowo wybiera konto dla każdego żądania za pomocą tasowania Fishera-Yatesa |
| **Najrzadziej używany** | Trasuje do konta z najstarszym znacznikiem czasu `lastUsedAt`, równomiernie rozprowadzając ruch |
| **Optymalizacja kosztów** | Kieruje do konta o najniższej wartości priorytetu, optymalizując pod kątem dostawców o najniższych kosztach |
**Zaawansowane kombinacje i strategie automatyczne** (konfigurowalne przez kombinację lub poprzez prefiksy `auto/*` — zobacz [AUTO-COMBO.md](../routing/AUTO-COMBO.md) ):
- `priority` — ścisły porządek, nigdy okrężny
- `weighted` — proporcjonalny podział ruchu według wag poszczególnych modeli
- `fill-first` — opróżnij pierwszy model, aż osiągną limity
- `round-robin` / `strict-random` / `random`
- `p2c` (moc dwóch wyborów)
- `least-used` i `cost-optimized`
- `auto` — na podstawie wyników u wszystkich kandydatów
- `lkgp` (Ostatni znany dobry dostawca) — przypina ostatniego dobrego dostawcę, a następnie powraca do reguł
- `context-optimized` — wybiera model z największym oknem swobodnego kontekstu
- `context-relay` — łączy modele o długim kontekście dla kolejnych tur
#### Zewnętrzny nagłówek sesji trwałej
W przypadku koligacji sesji zewnętrznej (na przykład agenci Claude Code/Codex za odwrotnymi 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 w formie podkreślenia, włącz:
```nginx
underscores_in_headers on;
```
#### Aliasy modeli z symbolami wieloznacznymi
Utwórz wzorce symboli wieloznacznych, aby ponownie przypisać nazwy modeli:
```
Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-6
Pattern: gpt-* → Target: gh/gpt-5.3-codex
```
Symbole wieloznaczne obsługują `*` (dowolne znaki) i `?` (pojedynczy znak).
#### Łańcuchy rezerwowe
Zdefiniuj globalne łańcuchy awaryjne, które mają zastosowanie do wszystkich żądań:
```
Chain: 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
Oto przykładowe wzorce łączenia wielu dostawców i routingu między nimi w OmniRoute:
#### 1. Kombinacja agenta kodującego: zaawansowane rozumowanie z funkcją zastępczą Cost/Speed
Idealny dla agentów kodujących (OpenCode, Claude Code, Cursor, Cline). Początkowo kieruje się do modeli rozumowania granicznego, powracając do modeli szybkiego kodowania w przypadku wyczerpania przydziału lub błędów.
- **Panel** : Kombinacje → Nowe kombinacje → Nazwa: `agent-coding` → Strategia: `Priority`
- **Modele** :
1. `claude/claude-sonnet-4-6` (główny agent kodujący)
2. `openai/gpt-4o` (dodatkowa rezerwa o dużej pojemności)
3. `deepseek/deepseek-v4-flash` (wysoka wydajność i opłacalna rezerwa)
```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. Bezpłatna kombinacja automatycznego przełączania awaryjnego
Łączy wielu dostawców usług bezpłatnych i bezkluczykowych, aby zmaksymalizować czas pracy bez kosztów API.
- **Strategia** : `Least Used` lub `Round Robin` (rozdziela obciążenie pomiędzy przydziały)
- **Modele** :
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. Potok multimodalny / wizyjny i tekstowy
Łączenie wyspecjalizowanych modeli wizji z szybkim generowaniem tekstu na potrzeby przepływów pracy obejmujących zrozumienie obrazu i generowanie kodu.
- **Wzór** : Kombinacja `Priority`, w której na pierwszym miejscu znajdują się modele z funkcją widzenia, a na końcu model text/code o dużej przepustowości.
- **Modele** :
1. `gemini/gemini-2.5-pro` (silne zrozumienie image/multimodal )
2. `openai/gpt-4o` (Zrównoważone widzenie i użycie narzędzi)
3. `deepseek/deepseek-v4-flash` (generacja Text/code )
---
### Odporność i wyłączniki automatyczne
Skonfiguruj przez** Pulpit nawigacyjny → Ustawienia → Odporność** .
OmniRoute wdraża odporność na poziomie dostawcy za pomocą pięciu komponentów:
1. **Kolejka żądań i tempo** — Kształtowanie żądań na poziomie systemu:
- **Żądania na minutę (RPM)** — Maksymalna liczba żądań na minutę na konto
- **Min. czas między żądaniami** — Minimalna przerwa w milisekundach między żądaniami
- **Maksymalna liczba jednoczesnych żądań** — Maksymalna liczba jednoczesnych żądań na konto
2. **Czas odnowienia połączenia** — Konfiguracja typu per-auth dla pojedynczego połączenia po niepowodzeniach możliwych do powtórzenia:
- **Podstawowy czas odnowienia** — Domyślne okno odnowienia dla możliwych do ponowienia błędów przesyłania danych
- **Skorzystaj ze wskazówek dotyczących ponownej próby przesłania** — Honoruje autorytatywne wskazówki `Retry-After` lub resetowania, jeśli są dostępne
- **Maksymalne kroki wycofywania** — Maksymalny wykładniczy poziom zwrotu w przypadku powtarzających się awarii
3. **Wyłącznik automatyczny dostawcy** — Śledzi kompleksowe awarie dostawców, oznacza dostawcę zdegradowanego przy skonfigurowanym progu ostrzegawczym i otwiera wyłącznik po osiągnięciu skonfigurowanego progu awarii:
- **Próg degradacji** — Kolejne awarie dostawców przed wejściem `DEGRADED`
- **Próg niepowodzenia** — Kolejne awarie dostawców przed wejściem `OPEN`
- **Zresetuj limit czasu** — Okno czasowe, zanim dostawca zostanie ponownie przetestowany
- **CLOSED** (Zdrowy) — Żądania przebiegają normalnie
- **DEGRADED** — Żądania nadal płyną, podczas gdy śledzone są podwyższone awarie
- **OPEN** — Dostawca jest tymczasowo blokowany po powtarzających się awariach
- **HALF_OPEN** — Sprawdzanie, czy dostawca powrócił do zdrowia
Limity szybkości `429` obejmujące zasięg połączenia pozostają niezmienione** Czas odnowienia połączenia** i nie wliczają się do wyłącznika dostawcy.
Stan środowiska wykonawczego wyłącznika dostawcy jest wyświetlany jako włączony** Deska rozdzielcza → Health** tylko.
4. **Poczekaj na ochłodzenie** — Jeśli każde połączenie kandydujące już się schładza, OmniRoute może poczekać na najwcześniejszy czas odnowienia i automatycznie ponowić to samo żądanie klienta.
5. **Automatyczne wykrywanie limitu dawki** — Gdy dostawcy wyższego szczebla zwracają wyraźne okna oczekiwania, wskazówki te zastępują czas oczekiwania na połączenie lokalne, gdy ustawienie jest włączone.
**Wskazówka dla profesjonalistów:** Skorzystaj z** Zdrowie** strona do sprawdzania i resetowania wyłączników dostawcy usług na żywo po awarii. Strona Odporność zmienia jedynie konfigurację.
---
### Eksport/import bazy danych
Zarządzaj kopiami zapasowymi baz danych w** Pulpit nawigacyjny → 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 zapasowych, w tym: bazę danych, ustawienia, kombinacje, połączenia z dostawcami (bez poświadczeń), metadane klucza API |
| **Importuj bazę danych** | Prześlij plik `.sqlite`, aby zastąpić bieżącą bazę danych. Kopia zapasowa przed importem jest tworzona automatycznie, chyba że `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"
```
**Walidacja importu:** Zaimportowany plik jest sprawdzany pod kątem integralności (sprawdzanie SQLite pragma), wymaganych tabel (`provider_connections`, `provider_nodes`, `combos`, `api_keys`) i rozmiaru (maks. 100MB).
**Przypadki użycia:**
- Przeprowadź migrację OmniRoute pomiędzy maszynami
- Twórz zewnętrzne kopie zapasowe na potrzeby odzyskiwania po awarii
- Udostępniaj konfiguracje pomiędzy członkami zespołu (eksportuj całe archiwum udostępniania → )
---
### Panel ustawień
Strona ustawień jest zorganizowana w** 7 zakładek** dla łatwej nawigacji:
| Patka | Zawartość |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Ogólny** | Narzędzia pamięci systemowej, zachowanie domyślne, widoczność tunelu punktu końcowego |
| **Wygląd** | Sterowanie motywem (light/dark/system), widoczność paska bocznego, przełączniki panelu dla kart tunelu Cloudflare/Tailscale/ngrok |
| **AI** | Przemyślany budżet (przejściowy / automatyczny / niestandardowy / adaptacyjny — zobacz [THINKING_BUDGET.md](./THINKING_BUDGET.md) ), globalny monit systemowy, natychmiastowe statystyki pamięci podręcznej |
| **Bezpieczeństwo** | ustawienia Login/Password, kontrola dostępu IP, uwierzytelnianie API dla `/models`, blokowanie dostawców, ochrona przed natychmiastowym wstrzyknięciem |
| **Rozgromienie** | Globalna strategia routingu (Fill First / Round Robin / P2C / Random / Najrzadziej używane / Optymalizacja kosztowa), aliasy modeli z symbolami wieloznacznymi, łańcuchy rezerwowe, domyślne kombinacje |
| **Odporność** | Kolejka żądań, czas oczekiwania na połączenie, konfiguracja wyłącznika dostawcy i zachowanie oczekiwania na ochłodzenie |
| **Zaawansowany** | Globalna konfiguracja proxy (HTTP/SOCKS5), zastąpienia proxy dla poszczególnych dostawców |
Ogólne nie duplikuje już notatek rejestrowania i pamięci podręcznej w trybie tylko do odczytu. Ustawienia przechowywania i optymalizacji bazy danych są zachowywane poprzez `/api/settings/database`; ręczne czyszczenie pamięci podręcznej wykorzystuje `DELETE /api/cache`. Limity wierszy żądań i dzienników proxy są kontrolowane przez `CALL_LOGS_TABLE_MAX_ROWS` i `PROXY_LOGS_TABLE_MAX_ROWS`.
---
### Zarządzanie kosztami i budżetem
Dostęp przez** Pulpit nawigacyjny → Koszty** .
| Patka | Zamiar |
| ---------- | ------------------------------------------------------------------------------------------------------------ |
| **Budżet** | Ustaw limity wydatków na klucz API za pomocą budżetów daily/weekly/monthly i śledzenia w czasie rzeczywistym |
| **Wycena** | Przeglądaj i edytuj wpisy dotyczące cen modelu — koszt za 1 tys. tokenów input/output na dostawcę |
```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
```
**Śledzenie kosztów:** Każde żądanie rejestruje użycie tokena i oblicza koszt, korzystając z tabeli cen. Zobacz awarie w** Deska rozdzielcza → Użycie** według dostawcy, modelu i klucza API.
---
### Transkrypcja dźwięku
OmniRoute obsługuje transkrypcję audio za pośrednictwem punktu końcowego kompatybilnego z 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` jest natywną trasą Deepgram i wymaga klucza API Deepgram. Jeśli skonfigurowano tylko OpenRouter, użyj `openrouter/deepgram/nova-3`.
**Zamiana mowy na tekst (transkrypcja)** dostawcy:
- `openai/` (kompatybilny szeptem)
- `groq/` (Groq szept Turbo)
- `deepgram/` (rodzina Nova)
- `assemblyai/`
- `nvidia/` (papuga, kanarek)
- `huggingface/` (warianty szeptu)
- `qwen/`
**Zamiana tekstu na mowę (`POST /v1/audio/speech`)** dostawcy:
- `openai/` (tts-1, tts-1-hd)
- `hyperbolic/`
- `deepgram/` (Aura)
- `nvidia/` (Sroka TTS)
- `elevenlabs/`
- `huggingface/`
- `inworld/`
- `cartesia/`
- `playht/`
- `kie/`
- `aws-polly/`
- `xiaomi-mimo/`
- `coqui/`, `tortoise/`
- `qwen/`
Obsługiwane formaty audio do transkrypcji: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. Formaty wyjściowe TTS zależą od dostawcy (mp3, wav, opus, pcm, mulaw).
---
### Strategie równoważenia kombinacji
Skonfiguruj równoważenie poszczególnych kombinacji** Pulpit nawigacyjny → Combo → Create/Edit → Strategia** .
| Strategia | Opis |
| ------------------------- | --------------------------------------------------------------------------------- |
| **System okrężny** | Obraca modele sekwencyjnie |
| **Priorytet** | Zawsze wypróbowuje pierwszy model; cofa się tylko w przypadku błędu |
| **Losowy** | Wybiera losowy model z kombinacji dla każdego żądania |
| **Ważona** | Trasy proporcjonalnie na podstawie przypisanych wag do modelu |
| **Najrzadziej używany** | Trasy do modelu z najmniejszą liczbą ostatnich żądań (wykorzystuje metryki kombi) |
| **Optymalizacja kosztów** | Trasy do najtańszego dostępnego modelu (korzysta z tabeli cen) |
Można ustawić globalne domyślne kombinacje** Pulpit nawigacyjny → Ustawienia → Routing → Domyślne ustawienia kombinacji** . Limity czasu docelowego kombinacji domyślnie dziedziczą limit czasu bieżącego żądania. Używać** Docelowy limit czasu (sekundy)** w przypadku domyślnych kombinacji lub pojedynczej kombinacji tylko wtedy, gdy krótszy limit na cel powinien wywołać szybszy powrót.
Optymalizacje kombinacji z zerowym opóźnieniem są opcjonalne. Wyjechać** Optymalizacje z zerowym opóźnieniem** wyłączone, aby uniemożliwić tym funkcjom opóźnienia ściganie się z celami zastępczymi, pomijanie celów w oparciu o historię TTFT lub kompresowanie żądań zastępczych; włączenie tej opcji umożliwia skonfigurowanie zabezpieczeń, predykcyjnych pominięć TTFT i proaktywną kompresję awaryjną w celu zamiany wierności routing/request na mniejsze opóźnienia.
Wyłączyć** Bufor tokenów rozumowania** gdy dostawcy wyższego szczebla wymagają ścisłych limitów `max_tokens` / `maxOutputTokens`. Po włączeniu routing kombinowany dodaje zapas modelu rozumowania tylko dla modeli ze znanym limitem wyjściowym i pozostawia limit tokenów klienta niezmieniony, gdy wartość bezpiecznego buforowania przekroczy ten limit. Jeśli limit klienta jest już powyżej znanego limitu, OmniRoute ogranicza go do tego limitu przed wysłaniem żądania nadrzędnego.
---
### Panel zdrowia
Dostęp przez** Deska rozdzielcza → Health** . Przegląd stanu systemu w czasie rzeczywistym za pomocą 6 kart:
| Karta | Co pokazuje |
| ----------------------------- | --------------------------------------------------------------------------------- |
| **Stan systemu** | Czas pracy, wersja, wykorzystanie pamięci, katalog danych |
| **Zdrowie dostawcy** | Stan środowiska wykonawczego wyłącznika automatycznego dostawcy globalnego |
| **Limity stawek** | Aktywne czasy odnowienia połączenia na konto z pozostałym czasem |
| **Aktywne blokady** | Aktywne blokady w zakresie modelu i tymczasowe wykluczenia |
| **Pamięć podręczna podpisów** | Statystyki pamięci podręcznej deduplikacji (aktywne klucze, współczynnik trafień) |
| **Telemetria opóźnień** | Agregacja opóźnień p50/p95/p99 według dostawcy |
**Wskazówka dla profesjonalistów:** Strona Zdrowie odświeża się automatycznie co 10 sekund. Użyj karty wyłącznika, aby zidentyfikować dostawców, u których 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)