# User Guide (Українська)
🌐 **Languages:** 🇺🇸 [English](../../../../guides/USER_GUIDE.md) · 🇪🇹 [am](../../../am/docs/guides/USER_GUIDE.md) · 🇸🇦 [ar](../../../ar/docs/guides/USER_GUIDE.md) · 🇦🇿 [az](../../../az/docs/guides/USER_GUIDE.md) · 🇧🇬 [bg](../../../bg/docs/guides/USER_GUIDE.md) · 🇧🇩 [bn](../../../bn/docs/guides/USER_GUIDE.md) · 🇧🇦 [bs](../../../bs/docs/guides/USER_GUIDE.md) · 🇨🇿 [cs](../../../cs/docs/guides/USER_GUIDE.md) · 🇩🇰 [da](../../../da/docs/guides/USER_GUIDE.md) · 🇩🇪 [de](../../../de/docs/guides/USER_GUIDE.md) · 🇬🇷 [el](../../../el/docs/guides/USER_GUIDE.md) · 🇪🇸 [es](../../../es/docs/guides/USER_GUIDE.md) · 🇪🇪 [et](../../../et/docs/guides/USER_GUIDE.md) · 🇮🇷 [fa](../../../fa/docs/guides/USER_GUIDE.md) · 🇫🇮 [fi](../../../fi/docs/guides/USER_GUIDE.md) · 🇫🇷 [fr](../../../fr/docs/guides/USER_GUIDE.md) · 🇮🇪 [ga](../../../ga/docs/guides/USER_GUIDE.md) · 🇮🇳 [gu](../../../gu/docs/guides/USER_GUIDE.md) · 🇳🇬 [ha](../../../ha/docs/guides/USER_GUIDE.md) · 🇮🇱 [he](../../../he/docs/guides/USER_GUIDE.md) · 🇮🇳 [hi](../../../hi/docs/guides/USER_GUIDE.md) · 🇭🇷 [hr](../../../hr/docs/guides/USER_GUIDE.md) · 🇭🇺 [hu](../../../hu/docs/guides/USER_GUIDE.md) · 🇦🇲 [hy](../../../hy/docs/guides/USER_GUIDE.md) · 🇮🇩 [id](../../../id/docs/guides/USER_GUIDE.md) · 🇳🇬 [ig](../../../ig/docs/guides/USER_GUIDE.md) · 🇮🇹 [it](../../../it/docs/guides/USER_GUIDE.md) · 🇯🇵 [ja](../../../ja/docs/guides/USER_GUIDE.md) · 🇬🇪 [ka](../../../ka/docs/guides/USER_GUIDE.md) · 🇰🇭 [km](../../../km/docs/guides/USER_GUIDE.md) · 🇮🇳 [kn](../../../kn/docs/guides/USER_GUIDE.md) · 🇰🇷 [ko](../../../ko/docs/guides/USER_GUIDE.md) · 🇱🇹 [lt](../../../lt/docs/guides/USER_GUIDE.md) · 🇱🇻 [lv](../../../lv/docs/guides/USER_GUIDE.md) · 🇮🇳 [ml](../../../ml/docs/guides/USER_GUIDE.md) · 🇮🇳 [mr](../../../mr/docs/guides/USER_GUIDE.md) · 🇲🇾 [ms](../../../ms/docs/guides/USER_GUIDE.md) · 🇲🇹 [mt](../../../mt/docs/guides/USER_GUIDE.md) · 🇲🇲 [my](../../../my/docs/guides/USER_GUIDE.md) · 🇳🇵 [ne](../../../ne/docs/guides/USER_GUIDE.md) · 🇳🇱 [nl](../../../nl/docs/guides/USER_GUIDE.md) · 🇳🇴 [no](../../../no/docs/guides/USER_GUIDE.md) · 🇮🇳 [or](../../../or/docs/guides/USER_GUIDE.md) · 🇮🇳 [pa](../../../pa/docs/guides/USER_GUIDE.md) · 🇵🇭 [phi](../../../phi/docs/guides/USER_GUIDE.md) · 🇵🇱 [pl](../../../pl/docs/guides/USER_GUIDE.md) · 🇵🇹 [pt](../../../pt/docs/guides/USER_GUIDE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/guides/USER_GUIDE.md) · 🇷🇴 [ro](../../../ro/docs/guides/USER_GUIDE.md) · 🇷🇺 [ru](../../../ru/docs/guides/USER_GUIDE.md) · 🇱🇰 [si](../../../si/docs/guides/USER_GUIDE.md) · 🇸🇰 [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) · 🇵🇰 [ur](../../../ur/docs/guides/USER_GUIDE.md) · 🇺🇿 [uz](../../../uz/docs/guides/USER_GUIDE.md) · 🇻🇳 [vi](../../../vi/docs/guides/USER_GUIDE.md) · 🇳🇬 [yo](../../../yo/docs/guides/USER_GUIDE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/guides/USER_GUIDE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/guides/USER_GUIDE.md)
---
🌐 **Languages:** 🇺🇸 [English](../../../../guides/USER_GUIDE.md) · 🇪🇹 [am](../../../am/docs/guides/USER_GUIDE.md) · 🇸🇦 [ar](../../../ar/docs/guides/USER_GUIDE.md) · 🇦🇿 [az](../../../az/docs/guides/USER_GUIDE.md) · 🇧🇬 [bg](../../../bg/docs/guides/USER_GUIDE.md) · 🇧🇩 [bn](../../../bn/docs/guides/USER_GUIDE.md) · 🇧🇦 [bs](../../../bs/docs/guides/USER_GUIDE.md) · 🇨🇿 [cs](../../../cs/docs/guides/USER_GUIDE.md) · 🇩🇰 [da](../../../da/docs/guides/USER_GUIDE.md) · 🇩🇪 [de](../../../de/docs/guides/USER_GUIDE.md) · 🇬🇷 [el](../../../el/docs/guides/USER_GUIDE.md) · 🇪🇸 [es](../../../es/docs/guides/USER_GUIDE.md) · 🇪🇪 [et](../../../et/docs/guides/USER_GUIDE.md) · 🇮🇷 [fa](../../../fa/docs/guides/USER_GUIDE.md) · 🇫🇮 [fi](../../../fi/docs/guides/USER_GUIDE.md) · 🇫🇷 [fr](../../../fr/docs/guides/USER_GUIDE.md) · 🇮🇪 [ga](../../../ga/docs/guides/USER_GUIDE.md) · 🇮🇳 [gu](../../../gu/docs/guides/USER_GUIDE.md) · 🇳🇬 [ha](../../../ha/docs/guides/USER_GUIDE.md) · 🇮🇱 [he](../../../he/docs/guides/USER_GUIDE.md) · 🇮🇳 [hi](../../../hi/docs/guides/USER_GUIDE.md) · 🇭🇷 [hr](../../../hr/docs/guides/USER_GUIDE.md) · 🇭🇺 [hu](../../../hu/docs/guides/USER_GUIDE.md) · 🇦🇲 [hy](../../../hy/docs/guides/USER_GUIDE.md) · 🇮🇩 [id](../../../id/docs/guides/USER_GUIDE.md) · 🇳🇬 [ig](../../../ig/docs/guides/USER_GUIDE.md) · 🇮🇹 [it](../../../it/docs/guides/USER_GUIDE.md) · 🇯🇵 [ja](../../../ja/docs/guides/USER_GUIDE.md) · 🇬🇪 [ka](../../../ka/docs/guides/USER_GUIDE.md) · 🇰🇭 [km](../../../km/docs/guides/USER_GUIDE.md) · 🇮🇳 [kn](../../../kn/docs/guides/USER_GUIDE.md) · 🇰🇷 [ko](../../../ko/docs/guides/USER_GUIDE.md) · 🇱🇹 [lt](../../../lt/docs/guides/USER_GUIDE.md) · 🇱🇻 [lv](../../../lv/docs/guides/USER_GUIDE.md) · 🇮🇳 [ml](../../../ml/docs/guides/USER_GUIDE.md) · 🇮🇳 [mr](../../../mr/docs/guides/USER_GUIDE.md) · 🇲🇾 [ms](../../../ms/docs/guides/USER_GUIDE.md) · 🇲🇹 [mt](../../../mt/docs/guides/USER_GUIDE.md) · 🇲🇲 [my](../../../my/docs/guides/USER_GUIDE.md) · 🇳🇵 [ne](../../../ne/docs/guides/USER_GUIDE.md) · 🇳🇱 [nl](../../../nl/docs/guides/USER_GUIDE.md) · 🇳🇴 [no](../../../no/docs/guides/USER_GUIDE.md) · 🇮🇳 [or](../../../or/docs/guides/USER_GUIDE.md) · 🇮🇳 [pa](../../../pa/docs/guides/USER_GUIDE.md) · 🇵🇭 [phi](../../../phi/docs/guides/USER_GUIDE.md) · 🇵🇱 [pl](../../../pl/docs/guides/USER_GUIDE.md) · 🇵🇹 [pt](../../../pt/docs/guides/USER_GUIDE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/guides/USER_GUIDE.md) · 🇷🇴 [ro](../../../ro/docs/guides/USER_GUIDE.md) · 🇷🇺 [ru](../../../ru/docs/guides/USER_GUIDE.md) · 🇱🇰 [si](../../../si/docs/guides/USER_GUIDE.md) · 🇸🇰 [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) · 🇵🇰 [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)
Повний посібник із налаштування постачальників, створення комбінацій, інтеграції інструментів CLI та розгортання OmniRoute.
---
## Зміст
- [Огляд цін](#-pricing-at-a-glance)
- [Варіанти використання](#-use-cases)
- [Налаштування провайдера](#-provider-setup)
- [Інтеграція з CLI](#-cli-integration)
- [Розгортання](#-deployment)
- [Доступні моделі](#-available-models)
- [Розширені можливості](#-advanced-features)
- [Автоматична маршрутизація (без налаштування)](#-auto-routing-zero-config)
- [Інтеграція MCP та A2A](#-mcp--a2a-integration)
- [Система навичок](#-skills-system)
- [Система пам’яті](#-memory-system)
- [Вебхуки](#-webhooks)
- [Хмарні агенти](#-cloud-agents)
- [Програмне керування](#-programmatic-management)
- [Внутрішній CLI](#-internal-cli)
- [Настільний застосунок (Electron)](#-desktop-application-electron)
---
## 💰 Огляд цін
| Рівень | Провайдер | Вартість | Скидання квоти | Найкраще підходить для |
| ------------------ | ----------------- | ---------------------- | ----------------------------------- | --------------------------------- |
| **💳 ПІДПИСКА** | Claude Code (Pro) | $20/міс. | Кожні 5 год + щотижня | Тих, хто вже має підписку |
| | Codex (Plus/Pro) | $20-200/міс. | Кожні 5 год + щотижня | Користувачів OpenAI |
| | GitHub Copilot | $10-19/міс. | Щомісяця | Користувачів GitHub |
| **🔑 API-КЛЮЧ** | DeepSeek | Оплата за використання | Немає | Недорогих міркувань |
| | Groq | Оплата за використання | Немає | Надшвидкого інференсу |
| | xAI (Grok) | Оплата за використання | Немає | Міркувань Grok 4 |
| | Mistral | Оплата за використання | Немає | Моделей, розміщених у ЄС |
| | Perplexity | Оплата за використання | Немає | Роботи з доповненням пошуком |
| | Together AI | Оплата за використання | Немає | Моделей із відкритим кодом |
| | Fireworks AI | Оплата за використання | Немає | Швидкої генерації зображень FLUX |
| | Cerebras | Оплата за використання | Немає | Швидкості на рівні цілої пластини |
| | Cohere | Оплата за використання | Немає | RAG із Command R+ |
| | NVIDIA NIM | Оплата за використання | Немає | Корпоративних моделей |
| | Baidu Qianfan | Оплата за використання | Немає | Моделей ERNIE |
| **💰 ДЕШЕВО** | GLM-4.7 | $0.6/1M | Щодня о 10:00 | Бюджетного резервного варіанта |
| | MiniMax M2.1 | $0.2/1M | Ковзне вікно тривалістю 5 год | Найдешевшого варіанта |
| | Kimi K2 | Фіксовані $9/міс. | 10M токенів/міс. | Передбачуваної вартості |
| **🆓 БЕЗКОШТОВНО** | Qoder | $0 | Застосовуються обмеження провайдера | Перевірте актуальний каталог |
| | Kiro | $0 | ~50 кредитів/міс. | Безкоштовного Claude |
---
## 🎯 Варіанти використання
### Випадок 1: «Я маю підписку Claude Pro»
**Проблема:** квота згорає невикористаною, а під час інтенсивного програмування спрацьовують обмеження частоти запитів
```
Комбінація: "maximize-claude"
1. cc/claude-opus-4-7 (використовуйте підписку повністю)
2. glm/glm-4.7 (дешевий резервний варіант після вичерпання квоти)
3. if/qwen3.8-max-preview (безкоштовний аварійний резервний варіант)
Щомісячна вартість: $20 (підписка) + ~$5 (резерв) = загалом $25
замість $20 + розчарування через досягнення лімітів
```
### Випадок 2: «Я хочу нульову вартість»
**Проблема:** не можу дозволити собі підписки, але потрібен надійний ШІ для програмування
```
Комбінація: "zero-cost"
1. if/kimi-k2.7-code (зазначено безкоштовний доступ; можуть застосовуватися обмеження частоти запитів)
2. kr/qwen3-coder-next (безкоштовний резервний варіант Kiro)
Щомісячна вартість: $0
Якість: перевірте модель, обмеження, конфіденційність і SLA для свого робочого навантаження
```
### Випадок 3: «Мені потрібне програмування 24/7 без перерв»
**Проблема:** стислі терміни, не можу дозволити собі простої
```
Комбінація: "always-on"
1. cc/claude-opus-4-7 (найкраща якість)
2. cx/gpt-5.5 (друга підписка)
3. glm/glm-4.7 (дешево, скидання щодня)
4. minimax/MiniMax-M2.1 (найдешевше, скидання кожні 5 год)
5. if/deepseek-v4-flash (зазначено безкоштовний доступ; можуть застосовуватися обмеження частоти запитів)
Результат: 5 резервних рівнів підвищують стійкість; доступність зовнішніх сервісів не гарантується
Щомісячна вартість: $20-200 (підписки) + $10-20 (резерв)
```
### Випадок 4: «Я хочу БЕЗКОШТОВНИЙ ШІ в OpenClaw»
**Проблема:** потрібен ШІ-помічник у застосунках для обміну повідомленнями, цілком безкоштовно
```
Комбінація: "openclaw-free"
1. if/qwen3.8-max-preview (зазначено безкоштовний доступ; можуть застосовуватися обмеження частоти запитів)
2. if/deepseek-v4-flash (зазначено безкоштовний доступ; можуть застосовуватися обмеження частоти запитів)
3. if/kimi-k2.7-code (зазначено безкоштовний доступ; можуть застосовуватися обмеження частоти запитів)
Щомісячна вартість: $0
Доступ через: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
```
---
## 📖 Налаштування провайдерів
Щоб масово додати підключення за API-ключами з файлу CSV або JSON, скористайтеся пунктом **Панель керування → Провайдери → Імпортувати з файлу**. Стовпці є позиційними (`provider,name,apiKey,baseUrl,priority`); `provider` має вже існувати як керований провайдер або сумісний вузол. Див. [Імпорт провайдерів із файлу CSV або JSON](../providers/CSV-IMPORT.md).
### 🔐 Провайдери за підпискою
#### Claude Code (Pro/Max)
```bash
Панель керування → Провайдери → Підключити Claude Code
→ Вхід через OAuth → Автоматичне оновлення токена
→ Відстеження 5-годинної та тижневої квоти
Моделі:
cc/claude-opus-4-7
cc/claude-sonnet-4-6
cc/claude-haiku-4-5-20251001
```
**Порада:** Використовуйте Opus для складних завдань, а Sonnet — для швидкості. OmniRoute відстежує квоту для кожної моделі!
На хості OmniRoute немає браузера? Запустіть `claude setup-token` будь-де, де виконано вхід у Claude Code, і вставте токен із терміном дії один рік на вкладці **Токен налаштування**. Див. [Claude Code із токеном налаштування](../providers/CLAUDE_CODE_SETUP_TOKEN.md).
Маршрути Claude та сумісні з Claude Code зберігають рівень інтенсивності міркування `max` для моделей Opus і Sonnet. Моделі Haiku не підтримують рівень інтенсивності `max`, тому перед надсиланням запиту до зовнішнього сервісу OmniRoute знижує його до високого бюджету міркування.
#### OpenAI Codex (Plus/Pro)
```bash
Панель керування → Провайдери → Підключити Codex
→ Вхід через OAuth (порт 1455)
→ Скидання кожні 5 годин і щотижня
Моделі:
cx/gpt-5.5
cx/gpt-5.4
cx/gpt-5.3-codex
cx/gpt-5.3-codex-spark
```
#### GitHub Copilot
```bash
Панель керування → Провайдери → Підключити GitHub
→ OAuth через GitHub
→ Щомісячне скидання (1-го числа місяця)
Моделі:
gh/gpt-5.5
gh/gpt-5.4
gh/claude-sonnet-4.6
gh/claude-opus-4.7
gh/gemini-3.1-pro-preview
```
### 💰 Недорогі провайдери
#### GLM-4.7 (щоденне скидання, $0.6/1M)
1. Зареєструйтеся: [Zhipu AI](https://open.bigmodel.cn)
2. Отримайте API-ключ у Coding Plan
3. Панель керування → Додати API-ключ: Провайдер: `glm`, API-ключ: `your-key`
**Використання:** `glm/glm-4.7` — **Порада:** Coding Plan пропонує втричі більшу квоту за 1/7 вартості! Щоденне скидання о 10:00.
#### MiniMax M2.1 (скидання кожні 5 год, $0.20/1M)
1. Зареєструйтеся: [MiniMax](https://www.minimax.io)
2. Отримайте API-ключ → Панель керування → Додати API-ключ
**Використання:** `minimax/MiniMax-M2.1` — **Порада:** Найдешевший варіант для довгого контексту (1M токенів)!
#### Kimi K2 (фіксовані $9/місяць)
1. Оформте підписку: [Moonshot AI](https://platform.kimi.ai?aff=omniroute)
2. Отримайте API-ключ → Панель керування → Додати API-ключ
**Використання:** `kimi/kimi-k2.5` — **Порада:** Фіксовані $9/місяць за 10M токенів = фактична вартість $0.90/1M!
#### Baidu Qianfan / ERNIE
1. Зареєструйтеся: [Baidu AI Cloud Qianfan](https://cloud.baidu.com/product/wenxinworkshop)
2. Створіть API-ключ Qianfan → Панель керування → Додати API-ключ: Провайдер: `qianfan`
**Використання:** `qianfan/ernie-5.1`, `qianfan/ernie-x1.1` або інший ідентифікатор моделі Qianfan, сумісної з OpenAI.
### 🆓 БЕЗКОШТОВНІ провайдери
Безкоштовні провайдери без автентифікації мають перемикач поруч із параметром **Автентифікація не потрібна** на сторінці відповідного провайдера.
Його вимкнення деактивує цього провайдера, вилучає його з налаштованого та компактного подань списку провайдерів,
а також вилучає його моделі з `/v1/models`.
#### Qoder (9 БЕЗКОШТОВНИХ моделей)
```bash
Панель керування → Підключити Qoder → Вхід через 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
```
#### Kiro (Claude БЕЗКОШТОВНО)
```bash
Панель керування → Підключити Kiro → AWS Builder ID або Google/GitHub → ~50 кредитів/місяць
Моделі: kr/claude-sonnet-4.5, kr/claude-haiku-4.5
```
---
## 🎨 Комбінації
Ви можете змінювати порядок карток комбінацій безпосередньо в розділі **Панель керування → Комбінації**, перетягуючи маркер на кожній картці. Порядок зберігається в SQLite і відновлюється після перезавантаження.
### Приклад 1: Максимальне використання підписки → Дешева резервна модель
```
Панель керування → Комбінації → Створити нову
Назва: premium-coding
Моделі:
1. cc/claude-opus-4-7 (Основна модель за підпискою)
2. glm/glm-4.7 (Дешева резервна модель, $0.6/1M)
3. minimax/MiniMax-M2.7 (Найдешевший запасний варіант, $0.3/1M)
Використання в CLI: premium-coding
```
### Приклад 2: Лише безкоштовні моделі (Нульова вартість)
```
Назва: free-combo
Моделі:
1. if/kimi-k2.7-code (зазначено безкоштовний доступ; можуть застосовуватися обмеження провайдера)
2. kr/qwen3-coder-next (Безкоштовна резервна модель Kiro)
Вартість: наразі зазначено $0; умови та доступність можуть змінюватися
```
---
## 🔧 Інтеграція з CLI
### Cursor IDE
**Використання Cursor як клієнта OmniRoute** (спрямування чату Cursor через OmniRoute):
```
Налаштування → Моделі → Розширені:
Базова URL-адреса OpenAI API: http://localhost:20128/v1
Ключ OpenAI API: [з панелі керування OmniRoute]
Модель: cc/claude-opus-4-7
```
**Використання OmniRoute як провайдера Cursor** (OmniRoute звертається до Cursor як до зовнішнього сервісу): рекомендовано
**Панель керування → Провайдери → Cursor → Увійти через Cursor**. Для Docker див.
[`docs/providers/CURSOR-DOCKER.md`](../providers/CURSOR-DOCKER.md).
### Claude Code
Відредагуйте `~/.claude/settings.json`:
```json
{
"env": {
"ANTHROPIC_BASE_URL": "http://localhost:20128",
"ANTHROPIC_AUTH_TOKEN": "ваш-api-ключ-omniroute"
}
}
```
Тут використовуйте кореневу кінцеву точку, сумісну з Claude. Не додавайте `/v1` до `ANTHROPIC_BASE_URL`.
### Codex CLI
```bash
export OPENAI_BASE_URL="http://localhost:20128"
export OPENAI_API_KEY="ваш-api-ключ-omniroute"
codex "ваш запит"
```
### OpenClaw
Відредагуйте `~/.openclaw/openclaw.json`:
```json
{
"agents": {
"defaults": {
"model": { "primary": "omniroute/if/kimi-k2.7-code" }
}
},
"models": {
"providers": {
"omniroute": {
"baseUrl": "http://localhost:20128/v1",
"apiKey": "ваш-api-ключ-omniroute",
"api": "openai-completions",
"models": [{ "id": "if/kimi-k2.7-code", "name": "Kimi K2.7 Code" }]
}
}
}
}
```
**Або скористайтеся панеллю керування:** Інструменти CLI → OpenClaw → Автоматичне налаштування
### Cline / Continue / RooCode
```
Провайдер: Сумісний з OpenAI
Базова URL-адреса: http://localhost:20128/v1
Ключ API: [з панелі керування]
Модель: cc/claude-opus-4-7
```
---
## 🚀 Розгортання
### Глобальне встановлення через npm (Рекомендовано)
```bash
npm install -g omniroute
# Створіть каталог конфігурації
mkdir -p ~/.omniroute
# Створіть файл .env (див. .env.example)
cp .env.example ~/.omniroute/.env
# Запустіть сервер
omniroute
# Або з власним портом:
omniroute --port 3000
```
CLI автоматично завантажує `.env` з `~/.omniroute/.env` або `./.env`.
### Режим системного трея
Запустіть OmniRoute у системному треї:
```bash
omniroute serve --tray
```
Команда завершує роботу після того, як сервер і значок у треї будуть готові.
Сервер продовжує працювати без термінала.
Режим системного трея підтримує macOS, Windows і графічні сеанси Linux. У режимі системного трея панель керування не відкривається автоматично.
Використовуйте меню системного трея для таких дій:
- Відкрити панель керування.
- Відкрити `/dashboard/logs`.
- Змінити налаштування автоматичного запуску.
- Зупинити OmniRoute.
Не поєднуйте `--tray` із такими параметрами:
- `--daemon`
- `--log`
- `--no-recovery`
Ці режими потребують іншого керування процесами.
Увімкніть запуск під час наступного входу в систему:
```bash
omniroute autostart enable
```
Автоматичний запуск використовує режим системного трея в macOS, Windows і графічних сеансах Linux. Linux без графічного інтерфейсу використовує наявну користувацьку службу systemd.
Вимкніть запуск під час входу в систему:
```bash
omniroute autostart disable
```
### Видалення
Коли OmniRoute вам більше не потрібен, ми пропонуємо два швидкі сценарії для повного видалення:
| Команда | Дія |
| ------------------------ | --------------------------------------------------------------------------------------- |
| `npm run uninstall` | Видаляє системний застосунок, але **зберігає вашу БД і конфігурації** в `~/.omniroute`. |
| `npm run uninstall:full` | Видаляє застосунок І назавжди **стирає всі конфігурації, ключі та бази даних**. |
> Примітка: Щоб виконати ці команди, перейдіть до папки проєкту OmniRoute (якщо ви його клонували) і запустіть їх. Якщо застосунок установлено глобально, можна просто виконати `npm uninstall -g omniroute`.
### Розгортання на VPS
```bash
git clone https://github.com/diegosouzapw/OmniRoute.git
cd OmniRoute && npm install && npm run build
export JWT_SECRET="змініть-на-власний-безпечний-секрет"
export INITIAL_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="секрет-api-ключа-проксі-кінцевої-точки"
npm run start
# Або: pm2 start npm --name omniroute -- start
```
### Розгортання з PM2 (Мало пам’яті)
Для серверів з обмеженим обсягом оперативної пам’яті використовуйте параметр обмеження пам’яті:
```bash
# З обмеженням 512 МБ (за замовчуванням)
pm2 start npm --name omniroute -- start
# Або з власним обмеженням пам’яті
OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start
# Або за допомогою ecosystem.config.js
pm2 start ecosystem.config.js
```
Створіть `ecosystem.config.js`:
```javascript
module.exports = {
apps: [
{
name: "omniroute",
script: "npm",
args: "start",
env: {
NODE_ENV: "production",
OMNIROUTE_MEMORY_MB: "512",
JWT_SECRET: "ваш-секрет",
INITIAL_PASSWORD: "ваш-пароль",
},
node_args: "--max-old-space-size=512",
max_memory_restart: "300M",
},
],
};
```
### Docker
```bash
# Зберіть образ (за замовчуванням = runner-cli із попередньо встановленими codex/claude/droid)
docker build -t omniroute:cli .
# Портативний режим (рекомендовано)
docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli
```
Щодо інтегрованого з хостом режиму з бінарними файлами CLI див. розділ Docker в основній документації.
### Void Linux (xbps-src)
Користувачі Void Linux можуть пакувати та встановлювати OmniRoute нативно за допомогою фреймворку кроскомпіляції `xbps-src`. Це автоматизує створення автономної збірки Node.js разом із необхідними нативними прив’язками `better-sqlite3`.
Переглянути шаблон xbps-src
```bash
# Файл шаблону для '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() {
# Визначення цільової архітектури ЦП для 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) Установлення всіх залежностей без виконання скриптів
NODE_ENV=development npm ci --ignore-scripts
# 2) Створення автономної збірки Next.js
npm run build
# 3) Копіювання статичних ресурсів до автономної збірки
cp -r .next/static .next/standalone/.next/static
[ -d public ] && cp -r public .next/standalone/public || true
# 4) Компіляція нативної прив’язки 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) Розміщення скомпільованої прив’язки в автономній збірці
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) Видалення залежних від архітектури збірок sharp
rm -rf .next/standalone/node_modules/@img
# 7) Копіювання залежностей середовища виконання pino, пропущених статичним аналізом 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
# Запобігання видаленню порожніх каталогів маршрутизатора застосунку Next.js обробником після встановлення
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
}
```
### Змінні середовища
| Змінна | Значення за замовчуванням | Опис |
| --------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| `JWT_SECRET` | `omniroute-default-secret-change-me` | Секрет для підпису JWT (**змініть у продакшені**) |
| `INITIAL_PASSWORD` | `CHANGEME` | Пароль для першого входу |
| `DATA_DIR` | `~/.omniroute` | Каталог даних (база даних, використання, журнали) |
| `PORT` | значення за замовчуванням фреймворку | Порт сервісу (`20128` у прикладах) |
| `HOSTNAME` | значення за замовчуванням фреймворку | Хост прив’язки (у Docker за замовчуванням — `0.0.0.0`) |
| `NODE_ENV` | значення за замовчуванням середовища | Установіть `production` для розгортання |
| `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128` | Публічна базова URL-адреса, що відображається на панелі керування та доступна серверу (замінює застарілу `BASE_URL`) |
| `NEXT_PUBLIC_CLOUD_URL` | `https://omniroute.dev` | Базова URL-адреса кінцевої точки хмарної синхронізації (замінює застарілу `CLOUD_URL`) |
| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | Секрет HMAC для згенерованих ключів API |
| `REQUIRE_API_KEY` | `false` | Вимагати Bearer-ключ API для `/v1/*` |
| `ALLOW_API_KEY_REVEAL` | `false` | Дозволити автентифікованим користувачам панелі керування переглядати повні збережені значення ключів API за запитом |
| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Інтервал оновлення кешованих даних про ліміти постачальників на сервері; кнопки оновлення в інтерфейсі запускають ручну синхронізацію |
| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Вимкнути автоматичні знімки SQLite перед записом, імпортом або відновленням; резервне копіювання вручну й надалі працюватиме |
| `APP_LOG_TO_FILE` | `true` | Вмикає запис журналів застосунку та аудиту на диск |
| `AUTH_COOKIE_SECURE` | `false` | Примусово використовувати атрибут `Secure` для файлу cookie автентифікації (за зворотним проксі HTTPS) |
| `CLOUDFLARED_BIN` | не задано | Використовувати наявний бінарний файл `cloudflared` замість керованого завантаження |
| `CLOUDFLARED_PROTOCOL` | `http2` | Транспорт для керованих швидких тунелів (`http2`, `quic` або `auto`) |
| `OMNIROUTE_MEMORY_MB` | `512` | Обмеження купи Node.js у МБ |
| `PROMPT_CACHE_MAX_SIZE` | `50` | Максимальна кількість записів у кеші запитів |
| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Максимальна кількість записів у семантичному кеші |
Повний довідник змінних середовища дивіться у файлі [README](../README.md).
---
## 📊 Доступні моделі
Переглянути всі доступні моделі
> Наведений нижче список укладено на основі `open-sse/config/providerRegistry.ts` для v3.8.0. Хмарні каталоги (Gemini, OpenRouter тощо) синхронізуються динамічно — щоб переглянути повний актуальний каталог, відкрийте **Панель керування → Провайдери → [провайдер] → Доступні моделі** або виконайте запит `GET /api/models/catalog`.
>
> Якщо вбудований список провайдера застарів, скористайтеся функцією **Імпортувати з /models** на цій сторінці (або ввімкніть **Автосинхронізацію**), щоб отримати актуальний каталог із першоджерела. Це було перевірено у v3.8.50 для LLM7.io (`gemini-3.1-flash-lite`) та UncloseAI (`solidrust/Hermes-3-Llama-3.1-8B-AWQ`); під час того самого циклу тестування анонімний доступ до Pollinations залишався обмеженим на стороні першоджерела.
**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` (+ рівні інтенсивності: `gpt-5.5-xhigh`, `gpt-5.5-high`, `gpt-5.5-medium`, `gpt-5.5-low`), `cx/gpt-5.4`, `cx/gpt-5.4-mini`, `cx/gpt-5.3-codex`, `cx/gpt-5.3-codex-spark`
**GitHub Copilot (`gh/`)** — OAuth: `gh/gpt-5.5`, `gh/gpt-5.4`, `gh/gpt-5.4-mini`, `gh/gpt-5-mini`, `gh/gpt-5.3-codex`, `gh/claude-opus-4.7`, `gh/claude-opus-4.6`, `gh/claude-opus-4-5-20251101`, `gh/claude-sonnet-4.6`, `gh/claude-sonnet-4.5`, `gh/claude-haiku-4.5`, `gh/gemini-3.1-pro-preview`, `gh/gemini-3-flash-preview`, `gh/oswe-vscode-prime`
**Kiro (`kr/`)** — БЕЗКОШТОВНИЙ OAuth: використовуйте актуальний каталог, наведений у розділі **Панель керування → Провайдери → Kiro → Доступні моделі**. Доступність залежить від облікового запису та тарифного плану.
**Qoder (`if/`)** — БЕЗКОШТОВНИЙ OAuth: `if/qwen3.8-max-preview`, `if/qwen3.7-max`, `if/qwen3.7-plus`, `if/kimi-k3`, `if/kimi-k2.7-code`, `if/glm-5.2`, `if/deepseek-v4-pro`, `if/deepseek-v4-flash`, `if/minimax-m3`
**GLM (`glm/`, `glm-cn/`, `zai/`, `glmt/`)** — $0.2–0.6/1M: `glm/glm-5.1`, `glm/glm-5`, `glm/glm-5-turbo`, `glm/glm-4.7`, `glm/glm-4.7-flash`, `glm/glm-4.6`, `glm/glm-4.6v`, `glm/glm-4.5`, `glm/glm-4.5v`, `glm/glm-4.5-air`
**MiniMax (`minimax/`, `minimax-cn/`)** — $0.2/1M: `minimax/MiniMax-M2.7`, `minimax/MiniMax-M2.7-highspeed`, `minimax/MiniMax-M2.5`, `minimax/MiniMax-M2.5-highspeed`
**Kimi (`kimi/`, `kimi-coding/`, `kimi-coding-apikey/`)** — фіксована плата $9/міс. або оплата за використання: `kimi/kimi-k2.6`, `kimi/kimi-k2.5`
**DeepSeek (`ds/`)** — ключ API: `ds/deepseek-v4-pro`, `ds/deepseek-v4-flash`
**Groq (`groq/`)** — надшвидкий: `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/`)** — нативний 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/`)** — розміщення в ЄС: `mistral/mistral-large-latest`, `mistral/mistral-medium-3-5`, `mistral/mistral-small-latest`, `mistral/devstral-latest`, `mistral/codestral-latest`
**Perplexity (`pplx/`)** — із розширенням результатів пошуком: `pplx/sonar-deep-research`, `pplx/sonar-reasoning-pro`, `pplx/sonar-pro`, `pplx/sonar`
**Together AI (`together/`)** — відкритий код: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo-Free` (безкоштовно), `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/`)** — швидкий інференс: `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/`)** — масштаб цілої пластини: `cerebras/zai-glm-4.7`, `cerebras/gpt-oss-120b`
**Cohere (`cohere/`)** — орієнтований на 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/`)** — корпоративний: `nvidia/z-ai/glm-5.1`, `nvidia/minimaxai/minimax-m2.7`, `nvidia/google/gemma-4-31b-it`, `nvidia/mistralai/mistral-small-4-119b-2603`, `nvidia/mistralai/mistral-large-3-675b-instruct-2512`, `nvidia/qwen/qwen3.5-397b-a17b`, `nvidia/deepseek-ai/deepseek-v4-pro`, `nvidia/openai/gpt-oss-120b`, `nvidia/nvidia/nemotron-3-super-120b-a12b`
**Baidu Qianfan (`qianfan/`)** — ERNIE: `qianfan/ernie-5.1`, `qianfan/ernie-5.0-thinking-latest`, `qianfan/ernie-x1.1`
**Ollama Cloud (`ollama-cloud/`)**: `ollama-cloud/deepseek-v4-pro`, `ollama-cloud/deepseek-v4-flash`, `ollama-cloud/kimi-k2.6`, `ollama-cloud/glm-5.1`, `ollama-cloud/minimax-m2.7`, `ollama-cloud/gemma4:31b`, `ollama-cloud/qwen3.5:397b`
**Gemini (Google Cloud `gemini/`)**: синхронізується безпосередньо з Google для кожного ключа API — статичного списку немає. Підключіть ключ у розділі **Панель керування → Провайдери**, а потім скористайтеся функцією **Доступні моделі**, щоб імпортувати поточний каталог (наприклад, `gemini/gemini-3-pro`, `gemini/gemini-3-flash`).
**Інші сумісні провайдери** (вибрані): `cohere`, `databricks`, `snowflake`, `together`, `vertex`, `alibaba`, `alibaba-cn`, `bedrock` (через `aws-bedrock`), `azure-ai`, `openrouter` (наскрізний каталог), `siliconflow`, `hyperbolic`, `huggingface`, `featherless-ai`, `cloudflare-ai`, `scaleway`, `deepinfra`, `vercel-ai-gateway`, `bazaarlink`, `friendliai`, `nous-research`, `reka`, `volcengine`, `ai21`, `gigachat`. Кожен із них підтримує власний список моделей у `providerRegistry.ts` і може автоматично синхронізуватися, якщо провайдер надає кінцеву точку `/models`.
**Примітка щодо ідентифікаторів моделей:** OmniRoute використовує нативні ідентифікатори провайдерів (`claude-opus-4-8`, `gpt-5.5`, `glm-5.1`, `MiniMax-M2.7`, `kimi-k2.5`, `grok-4.20-0309-reasoning`). Деякі ідентифікатори містять версії з крапками, оскільки саме такого формату очікує зовнішній API. Якщо моделі немає у наведеному вище списку, виконайте `omniroute models --search ` або надішліть запит `GET /api/models/catalog`, щоб підтвердити її доступність.
---
## 🧩 Розширені можливості
### Власні моделі
Додавайте будь-який ID моделі до будь-якого провайдера, не чекаючи оновлення застосунку:
```bash
# Через 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"}'
# Список: curl http://localhost:20128/api/provider-models?provider=openai
# Видалення: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-5.2"
```
Або скористайтеся панеллю керування: **Провайдери → [Провайдер] → Власні моделі**.
Примітки:
- Провайдерами, сумісними з OpenRouter і OpenAI/Anthropic, можна керувати лише через розділ **Доступні моделі**. Ручне додавання, імпорт і автоматична синхронізація додають моделі до одного списку доступних моделей, тому для цих провайдерів немає окремого розділу «Власні моделі».
- Розділ **Власні моделі** призначений для провайдерів, які не підтримують керований імпорт доступних моделей.
### Власні OpenAI-сумісні провайдери
Будь-який шлюз, що підтримує API OpenAI (самостійно розміщений проксі, vLLM або сторонній агрегатор),
можна додати як окремий вузол провайдера:
1. **Провайдери → Додати OpenAI-сумісний**.
2. **Назва**: відображувана мітка вузла.
3. **Префікс**: назва для маршрутизації. Клієнти викликають моделі у форматі `/`, тому вузол із
префіксом `mygw` обслуговує `mygw/gpt-4o-mini`. Обов’язковий; обмежень щодо символів немає.
4. **Тип API**: сімейство кінцевих точок, яке обслуговує шлюз (Chat Completions, Responses,
Embeddings, аудіо, зображення).
5. **Базова URL-адреса**: корінь API включно з `/v1` (наприклад,
`https://gateway.example.com/v1`), а не повний шлях `/chat/completions`. Шлюзи з
нестандартними шляхами налаштовують їх у розділі **Розширені налаштування** (шлях чату, шлях моделей).
6. Поле **Ключ API (для перевірки)** лише перевіряє з’єднання. Після створення вузла
відкрийте його та скористайтеся функцією **Додати з’єднання**, щоб зберегти ключ, який використовуватимуть запити.
Вузол отримує внутрішній ідентифікатор у форматі `openai-compatible--`; вам ніколи
не потрібно вводити його вручну, оскільки публічною назвою є префікс.
#### Зарезервовані префікси
Префікс не може бути ідентифікатором або псевдонімом вбудованого провайдера (наприклад, `openai`, `cf`), а також
ідентифікатором вилученого провайдера. Засіб визначення моделей перевіряє ідентифікатори та псевдоніми вбудованих провайдерів перед
власними вузлами, тому вузол з одним із таких префіксів ніколи не отримуватиме трафік:
`/model` натомість спрямовуватиметься до вбудованого провайдера або завершуватиметься відмовою, якщо цього провайдера
було вилучено. Створення або редагування вузла з таким префіксом відхиляється з повідомленням:
```text
prefix: "" є зарезервованим префіксом провайдера — виберіть інший префікс (зарезервовані ідентифікатори/псевдоніми не можна використовувати для власних вузлів, оскільки запити на зразок /model спрямовуються до вбудованого провайдера або завершуються відмовою, якщо його вилучено)
```
Виберіть унікальний префікс (`mygw`, `acme-proxy`). Якщо запити до власного вузла завершуються
помилкою, у якій згадується вбудований провайдер або його облікові дані, перевірте, чи не є префікс вузла
зарезервованим: вузли, збережені до появи цього правила, усе ще зберігаються, але їхній префікс спрямовує запити до
вбудованого провайдера. Відредагуйте вузол і надайте йому новий префікс.
### Побудова ланцюжків вузлів OmniRoute
Інший шлюз OmniRoute можна додати як **власного OpenAI-сумісного** провайдера. Використовуйте
базову URL-адресу `/v1` партнерського вузла та окремий API-ключ із мінімально необхідними привілеями, виданий цим вузлом.
Для взаємних або багатоланкових ланцюжків увімкніть добровільний захист від циклів на кожному шлюзі:
```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
```
Заголовок `X-OmniRoute-Peer-Trace` отримують лише запити, надіслані на URL-адресу партнерського вузла,
яку явно внесено до списку дозволених. Шлюз відхиляє повторний ідентифікатор екземпляра або вичерпаний ліміт
переходів із HTTP `508 Loop Detected`; звичайні провайдери верхнього рівня не отримують метаданих партнерських вузлів.
Побудова ланцюжків партнерських вузлів не є реплікацією бази даних або відмовостійкістю хоста. Кожен шлюз зберігає незалежний
стан SQLite, кеші, лічильники частоти та сеанси. Для забезпечення доступності в режимі «активний/пасивний» або «активний/активний» використовуйте
зворотний проксі з перевіркою стану або перемикання на резервний ресурс на стороні клієнта й ніколи не монтуйте одну базу даних SQLite
до кількох запущених екземплярів OmniRoute.
### Виділені маршрути провайдерів
Спрямовуйте запити безпосередньо до конкретного провайдера з перевіркою моделі:
```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
```
Префікс провайдера додається автоматично, якщо він відсутній. Запити з невідповідними моделями повертають `400`.
### Налаштування мережевого проксі
```bash
# Установлення глобального проксі
curl -X PUT http://localhost:20128/api/settings/proxy \
-d '{"global": {"type":"http","host":"proxy.example.com","port":"8080"}}'
# Проксі для окремого провайдера
curl -X PUT http://localhost:20128/api/settings/proxy \
-d '{"providers": {"openai": {"type":"socks5","host":"proxy.example.com","port":"1080"}}}'
# Перевірка проксі
curl -X POST http://localhost:20128/api/settings/proxy/test \
-d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}'
```
**Пріоритет:** Для конкретного ключа → Для конкретної комбінації → Для конкретного провайдера → Глобальний → Середовище.
### API каталогу моделей
```bash
curl http://localhost:20128/api/models/catalog
```
Повертає моделі, згруповані за провайдерами, із типами (`chat`, `embedding`, `image`).
### Хмарна синхронізація
- Синхронізація провайдерів, комбінацій і налаштувань між пристроями
- Автоматична фонова синхронізація з тайм-аутом і швидким завершенням у разі помилки
- У робочому середовищі надавайте перевагу серверним `NEXT_PUBLIC_BASE_URL`/`NEXT_PUBLIC_CLOUD_URL`
### Швидкий тунель Cloudflare
- Доступно в **Dashboard → Endpoints** для Docker та інших самостійно розгорнутих інсталяцій
- Створює тимчасову URL-адресу `https://*.trycloudflare.com`, яка переспрямовує запити до вашої поточної OpenAI-сумісної кінцевої точки `/v1`
- Під час першого ввімкнення `cloudflared` установлюється лише за потреби; подальші перезапуски повторно використовують той самий керований бінарний файл
- Quick Tunnels не відновлюються автоматично після перезапуску OmniRoute або контейнера; за потреби повторно ввімкніть їх на інформаційній панелі
- URL-адреси тунелів є тимчасовими та змінюються щоразу, коли ви зупиняєте або запускаєте тунель
- Керовані Quick Tunnels за замовчуванням використовують транспорт HTTP/2, щоб уникнути надокучливих попереджень QUIC про буфер UDP у контейнерах з обмеженими ресурсами
- Установіть `CLOUDFLARED_PROTOCOL=quic` або `auto`, якщо хочете перевизначити вибір керованого транспорту
- Установіть `CLOUDFLARED_BIN`, якщо віддаєте перевагу попередньо встановленому бінарному файлу `cloudflared` замість керованого завантаження
- Панелі Cloudflare Quick Tunnel, Tailscale Funnel і ngrok Tunnel можна показувати або приховувати в **Settings → Appearance**. Приховування панелі не зупиняє активний тунель.
### Інтелектуальні можливості шлюзу LLM (етап 9)
- **Семантичний кеш** — автоматично кешує непотокові відповіді з temperature=0 (обхід за допомогою `X-OmniRoute-No-Cache: true`)
- **Ідемпотентність запитів** — усуває дублікати запитів у межах 5 с за допомогою заголовка `Idempotency-Key` або `X-Request-Id`
- **Відстеження прогресу** — опціональні події SSE `event: progress` за допомогою заголовка `X-OmniRoute-Progress: true`
---
### Інтерактивне середовище перекладача
Доступ через **Dashboard → Translator**. Налагоджуйте та візуалізуйте, як OmniRoute перетворює запити API між постачальниками.
| Режим | Призначення |
| ------------------------------- | -------------------------------------------------------------------------------------------------------- |
| **Інтерактивне середовище** | Виберіть вихідний і цільовий формати, вставте запит і миттєво перегляньте перетворений результат |
| **Тестер чату** | Надсилайте повідомлення чату в реальному часі через проксі та перевіряйте повний цикл запиту й відповіді |
| **Стенд тестування** | Запускайте пакетні тести для кількох комбінацій форматів, щоб перевірити правильність перетворення |
| **Моніторинг у реальному часі** | Спостерігайте за перетвореннями в реальному часі під час проходження запитів через проксі |
**Варіанти використання:**
- Налагодження причин збою певної комбінації клієнта й постачальника
- Перевірка правильності перетворення тегів міркування, викликів інструментів і системних запитів
- Порівняння відмінностей форматів OpenAI, Claude, Gemini та Responses API
---
### Стратегії маршрутизації
Налаштовуються через **Dashboard → Settings → Routing**. Інформаційна панель надає шість найуживаніших стратегій; комбінації та автоматичний маршрутизатор внутрішньо підтримують ширший набір.
**Стратегії, доступні на інформаційній панелі (маршрутизація на рівні облікового запису):**
| Стратегія | Опис |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| **Заповнення першого** | Використовує облікові записи за пріоритетом — основний обліковий запис обробляє всі запити, доки не стане недоступним |
| **Циклічний перебір** | Почергово перебирає всі облікові записи з налаштовуваним лімітом закріплення (за замовчуванням: 3 виклики на обліковий запис) |
| **P2C (вибір із двох варіантів)** | Вибирає 2 випадкові облікові записи та спрямовує запит до справнішого — балансує навантаження з урахуванням стану |
| **Випадковий вибір** | Випадково вибирає обліковий запис для кожного запиту за допомогою перемішування Фішера — Єйтса |
| **Найменш використовуваний** | Спрямовує запит до облікового запису з найдавнішою часовою позначкою `lastUsedAt`, рівномірно розподіляючи трафік |
| **Оптимізація вартості** | Спрямовує запит до облікового запису з найнижчим значенням пріоритету, оптимізуючи вибір на користь найдешевших постачальників |
**Розширені стратегії комбінацій та автоматичної маршрутизації** (налаштовуються для кожної комбінації окремо або через префікси `auto/*` — див. [AUTO-COMBO.md](../routing/AUTO-COMBO.md)):
- `priority` — строгий порядок без циклічного перебору
- `weighted` — пропорційний розподіл трафіку відповідно до ваг кожної моделі
- `fill-first` — використовує першу модель до досягнення лімітів
- `round-robin` / `strict-random` / `random`
- `p2c` (вибір із двох варіантів)
- `least-used` і `cost-optimized`
- `auto` — вибір серед усіх кандидатів на основі оцінки
- `lkgp` (останній відомий справний постачальник) — закріплює останнього успішного постачальника, а потім переходить до резервних правил
- `context-optimized` — вибирає модель із найбільшим вільним контекстним вікном
- `context-relay` — об’єднує в ланцюжок моделі з великим контекстом для наступних ходів
#### Зовнішній заголовок закріпленого сеансу
Для зовнішньої спорідненості сеансів (наприклад, для агентів Claude Code/Codex за зворотними проксі) надішліть:
```http
X-Session-Id: your-session-key
```
OmniRoute також приймає `x_session_id` і повертає фактичний ключ сеансу в `X-OmniRoute-Session-Id`.
Якщо ви використовуєте Nginx і надсилаєте заголовки з символами підкреслення, увімкніть:
```nginx
underscores_in_headers on;
```
#### Псевдоніми моделей із символами підстановки
Створюйте шаблони із символами підстановки для перепризначення назв моделей:
```
Шаблон: claude-sonnet-* → Ціль: cc/claude-sonnet-4-6
Шаблон: gpt-* → Ціль: gh/gpt-5.3-codex
```
Символи підстановки підтримують `*` (будь-які символи) та `?` (один символ).
#### Ланцюжки резервного перемикання
Визначайте глобальні ланцюжки резервного перемикання, які застосовуються до всіх запитів:
```
Ланцюжок: production-fallback
1. cc/claude-opus-4-7
2. gh/gpt-5.3-codex
3. glm/glm-4.7
```
---
### Поширені комбінації постачальників і схеми маршрутизації
Нижче наведено приклади схем для поєднання кількох постачальників і маршрутизації між ними в OmniRoute:
#### 1. Комбінація для агента програмування: високорівневе міркування з резервним варіантом за вартістю/швидкістю
Ідеально підходить для агентів програмування (OpenCode, Claude Code, Cursor, Cline). Спочатку спрямовує запити до передових моделей міркування, а після вичерпання квоти або виникнення помилок перемикається на швидкі моделі програмування.
- **Dashboard**: Combos → New Combo → Name: `agent-coding` → Strategy: `Priority`
- **Моделі**:
1. `claude/claude-sonnet-4-6` (Основний агент програмування)
2. `openai/gpt-4o` (Другорядний резервний варіант із високою пропускною здатністю)
3. `deepseek/deepseek-v4-flash` (Високоефективний та економний резервний варіант)
```bash
# Приклад через 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. Комбінація автоматичного перемикання для безкоштовних рівнів
Об’єднує в ланцюжок кількох провайдерів із безкоштовними рівнями та без ключів, щоб максимізувати час безвідмовної роботи без витрат на API.
- **Стратегія**: `Least Used` або `Round Robin` (розподіляє навантаження між квотами)
- **Моделі**:
1. `groq/llama-3.3-70b-versatile`
2. `gemini/gemini-2.5-flash`
3. `cerebras/gpt-oss-120b`
```bash
# Приклад через 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. Мультимодальний конвеєр / конвеєр для зображень і тексту
Поєднання спеціалізованих моделей комп’ютерного зору зі швидкісною генерацією тексту для робочих процесів, що передбачають розуміння зображень і генерацію коду.
- **Шаблон**: комбінація `Priority`, у якій спочатку перелічено моделі з підтримкою зображень, а наприкінці — високопродуктивну модель для тексту/коду.
- **Моделі**:
1. `gemini/gemini-2.5-pro` (Високий рівень розуміння зображень і мультимодальних даних)
2. `openai/gpt-4o` (Збалансована робота із зображеннями та використання інструментів)
3. `deepseek/deepseek-v4-flash` (Генерація тексту/коду)
---
### Відмовостійкість і автоматичні вимикачі
Налаштовуються через **Панель керування → Налаштування → Відмовостійкість**.
OmniRoute реалізує відмовостійкість на рівні провайдерів за допомогою п’яти компонентів:
1. **Черга запитів і регулювання темпу** — керування потоком запитів на системному рівні:
- **Запитів за хвилину (RPM)** — максимальна кількість запитів за хвилину для одного облікового запису
- **Мінімальний час між запитами** — мінімальний інтервал у мілісекундах між запитами
- **Максимум одночасних запитів** — максимальна кількість одночасних запитів для одного облікового запису
2. **Пауза з’єднання** — конфігурація для кожного типу автентифікації окремого з’єднання після помилок, що допускають повторну спробу:
- **Базова пауза** — стандартний період паузи для помилок висхідного провайдера, що допускають повторну спробу
- **Використовувати підказки висхідного провайдера щодо повторної спроби** — враховує авторитетні підказки `Retry-After` або скидання, якщо вони надані
- **Максимум кроків відтермінування** — максимальний рівень експоненційного відтермінування для повторюваних помилок
3. **Автоматичний вимикач провайдера** — відстежує наскрізні помилки провайдера, позначає провайдера як такого, що працює з погіршенням, після досягнення налаштованого порога попередження та розмикає вимикач після досягнення налаштованого порога помилок:
- **Поріг погіршення** — кількість послідовних помилок провайдера перед переходом у стан `DEGRADED`
- **Поріг помилок** — кількість послідовних помилок провайдера перед переходом у стан `OPEN`
- **Час очікування до скидання** — проміжок часу перед повторною перевіркою провайдера
- **CLOSED** (Справний) — запити обробляються у звичайному режимі
- **DEGRADED** — запити й надалі обробляються, поки відстежується підвищена кількість помилок
- **OPEN** — провайдер тимчасово заблокований після повторюваних помилок
- **HALF_OPEN** — перевіряється, чи відновився провайдер
Обмеження частоти `429`, пов’язані зі з’єднанням, залишаються в межах **Паузи з’єднання** та не враховуються автоматичним вимикачем провайдера.
Стан автоматичного вимикача провайдера під час виконання відображається лише на сторінці **Панель керування → Стан системи**.
4. **Очікування завершення паузи** — якщо всі доступні з’єднання вже перебувають на паузі, OmniRoute може дочекатися завершення найближчої паузи й автоматично повторити той самий клієнтський запит.
5. **Автоматичне визначення обмежень частоти** — коли висхідні провайдери повертають явні періоди очікування, ці підказки перевизначають локальну паузу з’єднання, якщо відповідне налаштування ввімкнено.
**Професійна порада:** використовуйте сторінку **Стан системи**, щоб перевіряти та скидати активні автоматичні вимикачі провайдерів після збою. Сторінка «Відмовостійкість» змінює лише конфігурацію.
---
### Експорт / імпорт бази даних
Керуйте резервними копіями бази даних у розділі **Панель керування → Налаштування → Система та сховище**.
| Дія | Опис |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Експортувати базу даних** | Завантажує поточну базу даних SQLite як файл `.sqlite` |
| **Експортувати все (.tar.gz)** | Завантажує повний архів резервної копії, що містить базу даних, налаштування, комбінації, з’єднання з провайдерами (без облікових даних) і метадані ключів API |
| **Імпортувати базу даних** | Завантажує файл `.sqlite`, щоб замінити поточну базу даних. Перед імпортом автоматично створюється резервна копія, якщо не встановлено `DISABLE_SQLITE_AUTO_BACKUP=true` |
```bash
# API: Експорт бази даних
curl -o backup.sqlite http://localhost:20128/api/db-backups/export
# API: Експорт усього (повний архів)
curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll
# API: Імпорт бази даних
curl -X POST http://localhost:20128/api/db-backups/import \
-F "file=@backup.sqlite"
```
**Перевірка імпорту:** імпортований файл перевіряється на цілісність (перевірка за допомогою pragma SQLite), наявність обов’язкових таблиць (`provider_connections`, `provider_nodes`, `combos`, `api_keys`) і розмір (максимум 100 МБ).
**Варіанти використання:**
- Перенесення OmniRoute між комп’ютерами
- Створення зовнішніх резервних копій для аварійного відновлення
- Обмін конфігураціями між членами команди (експортувати все → поділитися архівом)
---
### Панель налаштувань
Для зручної навігації сторінку налаштувань розділено на **7 вкладок**:
| Вкладка | Вміст |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Загальні** | Системні інструменти сховища, поведінка за замовчуванням, видимість тунелів кінцевих точок |
| **Вигляд** | Керування темою (світла/темна/системна), видимість бічної панелі, перемикачі панелей для карток тунелів Cloudflare/Tailscale/ngrok |
| **ШІ** | Бюджет міркувань (передавання без змін / автоматичне видалення / власний / адаптивний — див. [THINKING_BUDGET.md](./THINKING_BUDGET.md)), глобальна системна підказка, статистика кешу підказок |
| **Безпека** | Налаштування входу/пароля, контроль доступу за IP-адресами, автентифікація API для `/models`, блокування постачальників, захист від ін'єкцій у підказки |
| **Маршрутизація** | Глобальна стратегія маршрутизації (заповнення першого / циклічна / P2C / випадкова / найменш використовуваний / оптимізована за вартістю), псевдоніми моделей із символами узагальнення, ланцюжки резервування, стандартні параметри комбінацій |
| **Стійкість** | Черга запитів, період очікування підключення, конфігурація запобіжника постачальника та поведінка очікування завершення періоду відновлення |
| **Розширені** | Глобальна конфігурація проксі (HTTP/SOCKS5), перевизначення проксі для окремих постачальників |
У розділі «Загальні» більше не дублюються доступні лише для читання примітки щодо журналювання та кешу. Налаштування зберігання й
оптимізації бази даних зберігаються через `/api/settings/database`; ручне очищення кешу виконується за допомогою
`DELETE /api/cache`. Обмеження кількості рядків у журналах запитів і проксі контролюються змінними
`CALL_LOGS_TABLE_MAX_ROWS` та `PROXY_LOGS_TABLE_MAX_ROWS`.
---
### Керування витратами та бюджетом
Доступ через **Панель керування → Витрати**.
| Вкладка | Призначення |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------- |
| **Бюджет** | Установлення лімітів витрат для кожного ключа API з щоденними/щотижневими/щомісячними бюджетами та відстеженням у реальному часі |
| **Ціни** | Перегляд і редагування записів про ціни моделей — вартість за 1 тис. вхідних/вихідних токенів для кожного постачальника |
```bash
# API: Установлення бюджету
curl -X POST http://localhost:20128/api/usage/budget \
-H "Content-Type: application/json" \
-d '{"keyId": "key-123", "limit": 50.00, "period": "monthly"}'
# API: Отримання поточного стану бюджету
curl http://localhost:20128/api/usage/budget
```
**Відстеження витрат:** Для кожного запиту реєструється використання токенів і розраховується вартість за таблицею цін. Переглядайте деталізацію за постачальником, моделлю та ключем API у розділі **Панель керування → Використання**.
---
### Транскрибування аудіо
OmniRoute підтримує транскрибування аудіо через сумісну з OpenAI кінцеву точку:
```bash
POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data
# Приклад із 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` — це власний маршрут Deepgram, для якого потрібен ключ API Deepgram.
Якщо налаштовано лише OpenRouter, використовуйте `openrouter/deepgram/nova-3`.
Постачальники **перетворення мовлення на текст (транскрибування)**:
- `openai/` (сумісні з whisper)
- `groq/` (Groq Whisper Turbo)
- `deepgram/` (сімейство Nova)
- `assemblyai/`
- `nvidia/` (Parakeet, Canary)
- `huggingface/` (варіанти whisper)
- `qwen/`
Постачальники **перетворення тексту на мовлення (`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/`
Підтримувані формати аудіо для транскрибування: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. Формати виведення TTS залежать від постачальника (mp3, wav, opus, pcm, mulaw).
---
### Стратегії балансування комбінацій
Налаштуйте балансування для кожної комбінації в розділі **Панель керування → Комбінації → Створити/Редагувати → Стратегія**.
| Стратегія | Опис |
| ---------------------------- | ---------------------------------------------------------------------------------------------------- |
| **Циклічна** | Послідовно перебирає моделі |
| **Пріоритетна** | Завжди спочатку використовує першу модель; переходить до резервної лише в разі помилки |
| **Випадкова** | Вибирає випадкову модель із комбінації для кожного запиту |
| **Зважена** | Розподіляє маршрути пропорційно до вагових коефіцієнтів, призначених кожній моделі |
| **Найменш використовувана** | Спрямовує запит до моделі з найменшою кількістю нещодавніх запитів (використовує метрики комбінації) |
| **Оптимізована за вартістю** | Спрямовує запит до найдешевшої доступної моделі (використовує таблицю цін) |
Глобальні стандартні параметри комбінацій можна встановити в розділі **Панель керування → Налаштування → Маршрутизація → Стандартні параметри комбінацій**.
За замовчуванням тайм-аути цільових моделей комбінації успадковують поточний тайм-аут запиту. Використовуйте **Тайм-аут цільової моделі
(секунди)** у стандартних параметрах комбінацій або для окремої комбінації лише тоді, коли коротше обмеження для кожної цільової моделі має
швидше активувати резервний варіант.
Оптимізації комбінацій із нульовою затримкою вмикаються явно. Залиште параметр **Оптимізації з нульовою затримкою** вимкненим, щоб
ці функції скорочення затримки не запускали цільові резервні моделі паралельно, не пропускали цільові моделі на основі історії TTFT
і не стискали резервні запити; увімкнення цього параметра дозволяє налаштоване хеджування, прогнозоване пропускання за TTFT
і проактивне стиснення резервних запитів, обмінюючи точність маршрутизації/запиту на меншу затримку в довгому хвості.
Вимкніть **буфер токенів міркування**, якщо провайдери вищого рівня вимагають суворого дотримання обмежень `max_tokens` / `maxOutputTokens`. Коли його ввімкнено, комбінована маршрутизація додає резерв для моделей міркування лише для моделей із відомим обмеженням виведення та залишає клієнтський ліміт токенів без змін, якщо безпечне значення з урахуванням буфера перевищувало б це обмеження. Якщо клієнтський ліміт уже перевищує відоме обмеження, OmniRoute зменшує його до цього обмеження перед надсиланням запиту провайдеру вищого рівня.
---
### Панель стану системи
Доступ через **Панель керування → Стан системи**. Огляд стану системи в реальному часі з 6 картками:
| Картка | Що вона показує |
| ----------------------- | -------------------------------------------------------------------------------------- |
| **Стан системи** | Час безперервної роботи, версія, використання пам’яті, каталог даних |
| **Стан провайдерів** | Глобальний стан автоматичного вимикача провайдерів під час виконання |
| **Обмеження швидкості** | Активні періоди очікування з’єднань для кожного облікового запису та час, що залишився |
| **Активні блокування** | Активні блокування для окремих моделей і тимчасові виключення |
| **Кеш сигнатур** | Статистика кешу дедуплікації (активні ключі, частка влучень) |
| **Телеметрія затримки** | Агреговані показники затримки p50/p95/p99 для кожного провайдера |
**Порада:** Сторінка стану системи автоматично оновлюється кожні 10 секунд. Використовуйте картку автоматичного вимикача, щоб визначити, у яких провайдерів виникають проблеми.
---
## 🤖 Автоматична маршрутизація (без налаштування)
OmniRoute постачається з **автоматичним маршрутизатором на основі оцінювання**, який вибирає найкращу модель для кожного запиту серед усіх підключених провайдерів — не потрібно підтримувати жодних комбінацій. Просто надішліть запит з одним із префіксів `auto/*`, і OmniRoute динамічно сформує віртуальну комбінацію, оцінюючи кандидатів за затримкою, вартістю, частотою успішних запитів, відповідністю контексту, придатністю моделі до завдання, нещодавніми збоями, квотою та станом автоматичного вимикача.
| Префікс | Що оптимізує |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `auto` | Збалансований варіант за замовчуванням (затримка × вартість × частота успішних запитів) |
| `auto/coding` | Завдання програмування: надає перевагу Claude, GPT-5, GLM, Kimi, Qwen Coder, моделям DeepSeek для програмування |
| `auto/cheap` | Найнижча вартість за токен, допускає вищу затримку |
| `auto/fast` | Найнижча затримка, ігнорує вартість |
| `auto/offline` | Лише локальні провайдери (Ollama, vLLM, llama.cpp) — корисно для ізольованих середовищ |
| `auto/smart` | Пріоритет якості міркувань (Opus, GPT-5 xhigh, R1, GLM 5.1 reasoning) |
| `auto/lkgp` | «Останній відомий справний провайдер» — закріплює останнього успішного провайдера, а потім переходить до правил резервування |
Приклад:
```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": "Рефакторизуй цю функцію Python" }],
"stream": true
}'
```
Повний опис автоматичного маршрутизатора наведено в [AUTO-COMBO.md](../routing/AUTO-COMBO.md), зокрема як налаштовувати ваги оцінювання, додавати провайдерів до чорного списку та переглядати рішення щодо маршрутизації в розділі **Панель керування → Автоматична комбінація**.
---
## 🔌 Інтеграція MCP та A2A
OmniRoute одночасно є **сервером MCP** (Model Context Protocol) і **сервером A2A** (Agent-to-Agent JSON-RPC 2.0). Будь-яке IDE або середовище запуску агентів, сумісне з MCP, може безпосередньо викликати інструменти OmniRoute — додаткова обгортка не потрібна.
### Транспорти MCP
- **SSE**: `http://localhost:20128/api/mcp/sse`
- **Потоковий HTTP**: `http://localhost:20128/api/mcp/stream`
- **stdio**: `omniroute --mcp` (для плагінів IDE, які віддають перевагу stdio)
### Підключення Claude Desktop
Відредагуйте `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) або відповідний файл у Windows/Linux:
```json
{
"mcpServers": {
"omniroute": {
"command": "omniroute",
"args": ["--mcp"]
}
}
}
```
### Підключення Cursor / Continue / VS Code MCP
Використовуйте SSE URL `http://localhost:20128/api/mcp/sse` і Bearer API-ключ, створений у розділі **Панель керування → API-ключі**.
### Області доступу
Наразі MCP визначає 32 іменовані області доступу. Кожен Bearer-ключ можна обмежити певними областями доступу — актуальний перелік областей та інструментів наведено в [MCP-SERVER.md](../frameworks/MCP-SERVER.md), а схему JSON-RPC — у [A2A-SERVER.md](../frameworks/A2A-SERVER.md).
---
## 🧠 Система навичок
OmniRoute надає розширюваний **фреймворк навичок** (`src/lib/skills/`), завдяки якому агенти та кінцева точка A2A можуть виконувати спеціалізовані для певної предметної області процедури (наприклад, `code-review`, `summarize`, `extract-facts`, `web-research`).
- **Інтерфейс маркетплейсу** — Переглядайте та встановлюйте навички через **Панель керування → Навички**
- **Області доступу для окремих ключів** — Обмежуйте, які ключі API можуть викликати певні навички
- **Власні навички** — Додайте файл TypeScript до `src/lib/a2a/skills/`, зареєструйте його, і він одразу стане доступним для виклику через A2A
Повна довідка: [SKILLS.md](../frameworks/SKILLS.md).
---
## 💾 Система пам’яті
OmniRoute зберігає **довготривалу пам’ять розмов** із гібридним пошуком:
- **SQLite FTS5** для пошуку за ключовими словами в попередніх репліках
- **Векторне сховище Qdrant** (необов’язкове) для семантичного пошуку
- **Автоматичне вилучення фактів** — сутності, уподобання та рішення узагальнюються після кожного сеансу й зберігаються в таблиці `memory_facts`
- Спогади ізольовані за ключем API та сеансом
Керуйте спогадами в розділі **Панель керування → Пам’ять** (пошук, редагування, експорт, очищення). HTTP-інтерфейс (`/api/memory/*`) дає агентам змогу програмно додавати та запитувати факти — див. [MEMORY.md](../frameworks/MEMORY.md).
---
## 🔔 Вебхуки
Підписуйтеся на події OmniRoute для моніторингу й автоматизації в реальному часі.
- Створіть вебхук у розділі **Панель керування → Вебхуки**, указавши цільову URL-адресу та секрет для підпису HMAC
- Доступні події: `request.completed`, `request.failed`, `provider.unavailable`, `budget.exceeded`, `combo.switched`, `circuit_breaker.opened`, `circuit_breaker.closed`
- Кожне корисне навантаження містить `X-OmniRoute-Signature` (HMAC-SHA256) для перевірки
- Повторні спроби: 3 спроби з експоненційною затримкою, після чого повідомлення надсилається до черги недоставлених повідомлень
Повна схема наведена в [WEBHOOKS.md](../frameworks/WEBHOOKS.md).
---
## ☁️ Хмарні агенти
OmniRoute інтегрується з хмарними агентами для програмування (**OpenAI Codex Cloud**, **Devin**, **Jules**, **Antigravity**), щоб ви могли надсилати довготривалі завдання з тієї самої панелі керування, яка використовується для локальної маршрутизації.
- Створюйте завдання в розділі **Панель керування → Хмарні агенти** або через `POST /api/v1/agents/tasks`
- Відстежуйте статус, журнали та артефакти кожного завдання
- Використовуйте власний ключ API для кожного постачальника — облікові дані ніколи не залишають екземпляр OmniRoute
Повна довідка: [CLOUD_AGENT.md](../frameworks/CLOUD_AGENT.md).
---
## 🛠️ Програмне керування
Ви можете керувати всіма ресурсами OmniRoute (постачальниками, комбінаціями, ключами, налаштуваннями) через HTTP за допомогою **ключа Bearer з областю доступу `manage`**.
Згенеруйте ключ у розділі **Панель керування → Ключі API → Новий ключ → Область доступу: manage**, а потім:
```bash
# Вивести список постачальників
curl http://localhost:20128/api/providers \
-H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY"
# Додати підключення до постачальника
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" }'
# Створити комбінацію
curl -X POST http://localhost:20128/api/combos \
-H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY" \
-H "Content-Type: application/json" \
-d '{ "name": "premium", "strategy": "priority", "models": [{ "model": "cc/claude-opus-4-7" }, { "model": "glm/glm-5.1" }] }'
# Вивести список ключів API / створити ключ 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"] }'
```
Повний каталог кінцевих точок і схеми запитів/відповідей див. у [API_REFERENCE.md](../reference/API_REFERENCE.md).
---
## 💻 Внутрішній CLI
OmniRoute постачається з внутрішнім CLI (`omniroute …`) для налаштування, діагностики та керування під час виконання. Він **відрізняється від сторінки «Інструменти CLI» на панелі керування**, де налаштовуються сторонні CLI (Claude Code, Cursor, Codex, Cline, …), щоб вони могли взаємодіяти з OmniRoute.
```bash
omniroute setup # Інтерактивний майстер (пароль, провайдери, комбінації)
omniroute setup --non-interactive # Підходить для CI
omniroute doctor # Діагностика стану (каталог даних, БД, провайдери, порти)
omniroute providers available # Показати підтримуваних провайдерів
omniroute providers list # Показати налаштовані підключення
omniroute providers test # Перевірити підключення до провайдера в реальному часі
omniroute combos list # Показати комбінації
omniroute combos switch # Установити стандартну комбінацію
omniroute models # Показати доступні моделі (--json, --search)
omniroute keys add | list | remove # Керувати ключами API з термінала
omniroute backup # Створити знімок конфігурації та БД
omniroute restore [] # Відновити зі знімка
omniroute health # Докладний стан (запобіжники, кеш, пам’ять)
omniroute quota # Використання квоти провайдера
omniroute mcp status # Стан сервера MCP
omniroute a2a status # Стан сервера A2A
omniroute tunnel list|create|stop # Тунелі Cloudflare/Tailscale/ngrok
omniroute reset-password # Скинути пароль адміністратора
omniroute --mcp # Запустити сервер MCP через stdio
omniroute --port 3000 # Запустити сервер на власному порту
```
Порада: поєднайте `omniroute doctor --json` зі своїм інструментом моніторингу, щоб отримувати сповіщення про несправні підключення до провайдерів.
---
## 🖥️ Настільний застосунок (Electron)
OmniRoute доступний як нативний настільний застосунок для Windows, macOS і Linux.
### Встановлення
```bash
# З каталогу electron:
cd electron
npm install
# Режим розробки (підключення до запущеного сервера розробки Next.js):
npm run dev
# Робочий режим (використовує автономну збірку):
npm start
```
### Створення інсталяторів
```bash
cd electron
npm run build # Поточна платформа
npm run build:win # Windows (.exe NSIS)
npm run build:mac # macOS (.dmg universal)
npm run build:linux # Linux (.AppImage)
```
Результат → `electron/dist-electron/`
### Основні можливості
| Можливість | Опис |
| --------------------------- | ---------------------------------------------------------------- |
| **Готовність сервера** | Опитує сервер перед показом вікна (без порожнього екрана) |
| **Системний трей** | Згортання в трей, зміна порту та вихід із меню трея |
| **Керування портом** | Зміна порту сервера з трея (сервер перезапускається автоматично) |
| **Політика безпеки вмісту** | Обмежувальна CSP через заголовки сеансу |
| **Один екземпляр** | Одночасно може працювати лише один екземпляр застосунку |
| **Автономний режим** | Вбудований сервер Next.js працює без інтернету |
### Змінні середовища
| Змінна | Стандартне значення | Опис |
| --------------------- | ------------------- | ------------------------------------ |
| `OMNIROUTE_PORT` | `20128` | Порт сервера |
| `OMNIROUTE_MEMORY_MB` | `512` | Обмеження купи Node.js (64–16384 МБ) |
📖 Повна документація: [`electron/README.md`](../../electron/README.md)