# 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
```
**Кредити ШІ (оплата на основі токенів).** Коли GitHub повідомляє
`credits_used` для облікового запису, картка лімітів провайдера показує рядок
**Кредити ШІ** із кількістю кредитів, використаних у поточному розрахунковому періоді, зокрема для необмежених планів організацій.
**Локальний ліміт кредитів ШІ.** Відредагуйте підключення GitHub і встановіть параметр **Ліміт кредитів ШІ на розрахунковий період** (`providerSpecificData.githubCreditLimit`). Порожнє значення вимикає ліміт; `0` завжди пропускає це підключення. Коли останнє показання використання дорівнює ліміту або перевищує його, вибір облікового запису пропускає це підключення, а маршрутизація переходить до інших підключень — так само, як у разі досягнення обмеження політики квот. Перевірка використовує дані про використання, які вже збираються під час періодичного оновлення квот — вона ніколи не звертається до GitHub під час обробки запиту — і працює за принципом відкритого доступу: відсутнє або застаріле показання (старше за 15 хвилин або отримане в розрахунковому періоді, який уже завершився) не блокує підключення. Це локальний запобіжний механізм, **а не гарантована межа витрат**: затримки у звітах GitHub, інтервал оновлення, запити в процесі виконання та використання поза OmniRoute можуть призвести до перевищення ліміту. Для жорсткого обмеження використовуйте власні засоби контролю витрат GitHub.
### 💰 Недорогі провайдери
#### 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 пропонує квоту в 3 рази більшу за 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
# 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 автоматично завантажує `.env` із `~/.omniroute/.env` або `./.env`. `./.env` у робочому каталозі може встановлювати лише короткий список дозволених ключів (порти, `REQUIRE_API_KEY`, параметри локалі та кольору); помістіть все інше в `~/.omniroute/.env`. Див. [контракти на запуск CLI](CLI-LAUNCH-CONTRACTS.md#working-directory-env).
### Режим лотка
Запустіть OmniRoute в системному треї:
```bash
omniroute serve --tray
```
Команда повертається після того, як сервер і трей будуть готові.
Сервер продовжує роботу без терміналу.
Режим трея підтримує сеанси macOS, Windows і графічні Linux. Режим трея не відкриває інформаційну панель автоматично.
Використовуйте меню трея для таких дій:
- Відкрийте інформаційну панель.
- Відкрийте `/dashboard/logs`.
- Змінити автозапуск.
- Зупинити OmniRoute.
Не поєднуйте `--tray` з цими параметрами:
- `--daemon`
- `--log`
- `--no-recovery`
Ці режими вимагають різного володіння процесом.
Увімкнути запуск під час наступного входу в систему:
```bash
omniroute autostart enable
```
Автозапуск використовує режим трея в сеансах macOS, Windows і графічного Linux. Headless Linux використовує наявну службу користувача systemd.
Вимкнути запуск під час входу:
```bash
omniroute autostart disable
```
### Видалення
Якщо вам більше не потрібен OmniRoute, ми пропонуємо два швидких сценарії для чистого видалення:
| Команда | Дія |
| ------------------------ | ----------------------------------------------------------------------------------- |
| `npm run uninstall` | Видаляє системну програму але** зберігає ваш DB та конфігурації** в `~/.omniroute`. |
| `npm run uninstall:full` | Назавжди видаляє програму AND** стирає всі конфігурації, ключі та бази даних** . |
> Примітка. Щоб запустити ці команди, перейдіть до папки проекту 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="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
```
### Розгортання PM2 (мало пам’яті)
Для серверів з обмеженим RAM використовуйте опцію обмеження пам’яті:
```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
```
Створіть `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
```
Для інтегрованого режиму з двійковими файлами CLI див. розділ Docker в основних документах.
### Void Linux (xbps-src)
Користувачі Void Linux можуть пакувати та інсталювати OmniRoute нативно за допомогою фреймворку крос-компіляції `xbps-src`. Це автоматизує окрему збірку Node.js разом із необхідними власними зв’язками `better-sqlite3`.
Переглянути шаблон 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
}
```
### Змінні середовища
| змінна | За замовчуванням | опис |
| --------------------------------------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `JWT_SECRET` | _(створено автоматично)_ | секрет підпису JWT — автоматично генерується під час першого запуску та зберігається в `server.env`; встановіть його явно, якщо каталог даних є ефемерним |
| `INITIAL_PASSWORD` | _(не встановлено)_ | Перший пароль для входу. Встановлення npm/source починаються з `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` | _(створено автоматично)_ | секрет HMAC для згенерованих ключів API — автоматично генерується під час першого запуску та зберігається в `server.env` |
| `REQUIRE_API_KEY` | `false` | Примусове застосування ключа API на `/v1/*` |
| `ALLOW_API_KEY_REVEAL` | `false` | Дозвольте автентифікованим користувачам інформаційної панелі відкривати повні збережені значення ключів API на вимогу |
| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Частота оновлення на стороні сервера для кешованих даних про обмеження постачальника; Кнопки оновлення UI все ще запускають ручну синхронізацію |
| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Вимкнути автоматичні знімки SQLite перед writes/import/restore; ручне резервне копіювання все ще працює |
| `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 в MB |
| `PROMPT_CACHE_MAX_SIZE` | `50` | Максимальна кількість записів у кеші підказок |
| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Максимальна кількість записів семантичного кешу |
Повну довідку про змінні середовища див. у [README](../README.md).
---
## 📊 Доступні моделі
Переглянути всі доступні моделі
> Наведений нижче список укладено на основі `open-sse/config/providerRegistry.ts` для v3.8.0. Хмарні каталоги (Gemini, OpenRouter тощо) синхронізуються динамічно — щоб переглянути повний актуальний каталог, відкрийте **Панель керування → Постачальники → [provider] → Доступні моделі** або виконайте запит `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` (+ рівні effort: `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/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/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/`)**: синхронізується в реальному часі за ключем API від Google — статичного списку немає. Підключіть ключ у **Панель керування → Постачальники**, а потім скористайтеся пунктом **Доступні моделі**, щоб імпортувати актуальний каталог (наприклад, `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
# 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"
```
Або використовуйте інформаційну панель:** Постачальники → [Постачальник] → Спеціальні моделі** .
Примітки:
- З провайдерів OpenRouter та OpenAI/Anthropic-compatible можна керувати** Доступні моделі** тільки. Додавання, імпорт і автоматична синхронізація вручну все потрапляє в той самий список доступних моделей, тому для цих постачальників немає окремого розділу «Користувацькі моделі».
- The** Спеціальні моделі** розділ призначений для постачальників, які не надають імпорту керованої доступної моделі.
### Спеціальні постачальники, сумісні з OpenAI
Будь-який шлюз, який використовує OpenAI API (власний проксі-сервер, vLLM, сторонній агрегатор), можна додати як власний вузол провайдера:
1. **Постачальники → Додати OpenAI Compatible** .
2. **Ім'я** : відображувана мітка для вузла.
3. **Префікс** : назва маршруту. Клієнти називають моделі як `/`, тому вузол із префіксом `mygw` обслуговує `mygw/gpt-4o-mini`. обов'язковий; немає обмежень на символи.
4. **Тип API** : сімейство кінцевих точок, яке обслуговує шлюз (завершення чату, відповіді, вбудовування, аудіо, зображення).
5. **База URL** : корінь API, до `/v1` включно (наприклад `https://gateway.example.com/v1`), а не повний шлях `/chat/completions`. Шлюзи з нестандартними шляхами встановлюють їх під** Розширені налаштування** (шлях чату, шлях моделей).
6. The** ключ API (для перевірки)** поле лише перевіряє з’єднання. Після створення вузла відкрийте його та використовуйте** Додати підключення** для зберігання ключа, який використовуватимуть запити.
Вузол отримує внутрішній ідентифікатор у формі `openai-compatible--`; вам ніколи не потрібно вводити його, префікс є публічною назвою.
#### Зарезервовані префікси
Префікс не може бути ідентифікатором чи псевдонімом вбудованого постачальника (наприклад `openai`, `cf`), ані ідентифікатором вилученого постачальника. Резолвер моделі перевіряє вбудовані ідентифікатори та псевдоніми перед користувацькими вузлами, тому вузол, який використовує один із цих префіксів, ніколи не отримуватиме трафік: замість цього `/model` спрямовуватиметься до вбудованого постачальника або не закриватиметься, якщо цей постачальник припинить роботу. Створення або редагування вузла з таким префіксом відхиляється з:
```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)
```
Виберіть чіткий префікс (`mygw`, `acme-proxy`). Якщо запити до настроюваного вузла завершуються помилкою з іменем вбудованого постачальника або його обліковими даними, перевірте, чи зарезервовано префікс вузла: вузли, збережені до того, як існувало це правило, усе ще зберігаються, але їхні префікси спрямовуються до вбудованого постачальника. Відредагуйте вузол і дайте йому новий префікс.
#### Параметри шлюзу для кожного з’єднання
Ці ключі входять до `providerSpecificData` підключення (наприклад, через `PUT /api/providers/{id}`):
- `toolNameMaxLength` (ціле число, 1–1024) — для з’єднань, сумісних із форматом чату OpenAI шлюз яких відхиляє довгі назви інструментів. Довші імена надсилаються як короткі псевдоніми та відновлюються у відповіді.
- `quotaEndpoint` — кінцева точка quota/credits шлюзу, читання для смуги квот на інформаційній панелі та маршрутизації з урахуванням квот. Працює як на підключеннях, сумісних з OpenAI, так і на Anthropic; повна форма задокументована в `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" }
}
}
}
```
### З’єднання однорангових вузлів OmniRoute
Ще один шлюз OmniRoute можна додати як a** Спеціальний OpenAI-сумісний** провайдер. Використовуйте базовий `/v1` URL однорангового вузла та виділений ключ 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 з явно дозволеного списку. Шлюз відхиляє повторний екземпляр ID або вичерпаний бюджет переходу за допомогою HTTP `508 Loop Detected`; звичайні провайдери висхідного потоку не отримують однорангових метаданих.
Одноранговий ланцюжок не є реплікацією бази даних або відновленням хоста після відмови. Кожен шлюз зберігає незалежний стан SQLite, кеші, лічильники швидкості та сеанси. Використовуйте перевірений зворотний проксі-сервер або клієнтське перемикання після відмови для доступності active/passive або active/active і ніколи не монтуйте одну базу даних 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
# 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"}}'
```
**пріоритет:** Специфічний ключ → Комбінований → Специфічний постачальник → Глобальне середовище →.
### Каталог моделей API
```bash
curl http://localhost:20128/api/models/catalog
```
Повертає моделі, згруповані за постачальниками з типами (`chat`, `embedding`, `image`).
### Хмарна синхронізація
- Синхронізація постачальників, комбінацій і налаштувань на всіх пристроях
- Автоматична фонова синхронізація з тайм-аутом + fail-fast
- Віддавайте перевагу серверним `NEXT_PUBLIC_BASE_URL`/`NEXT_PUBLIC_CLOUD_URL` у виробництві
### Швидкий тунель Cloudflare
- Доступний в** Панель інструментів → Endpoints** для Docker та інших самостійних розгортань
- Створює тимчасовий `https://*.trycloudflare.com` URL, який пересилає вашу поточну кінцеву точку `/v1`, сумісну з OpenAI
- First enable встановлює `cloudflared` лише за потреби; пізніші перезапуски повторно використовують той самий керований двійковий файл
- Швидкі тунелі не відновлюються автоматично після перезапуску OmniRoute або контейнера; за потреби повторно ввімкніть їх на інформаційній панелі
- Тунель URLs є ефемерним і змінюється кожного разу, коли ви stop/start тунель
- Керовані швидкі тунелі за замовчуванням використовують транспорт HTTP/2, щоб уникнути шумових попереджень буфера QUIC UDP у обмежених контейнерах
- Установіть `CLOUDFLARED_PROTOCOL=quic` або `auto` якщо ви бажаєте замінити вибір керованого транспорту
- Встановіть `CLOUDFLARED_BIN` якщо ви віддаєте перевагу використанню попередньо встановленого двійкового файлу `cloudflared` замість керованого завантаження
- Панелі Cloudflare Quick Tunnel, Tailscale Funnel і ngrok Tunnel можна показувати або приховувати в** Налаштування → Зовнішній вигляд** . Приховування панелі не зупиняє запущений тунель.
### LLM Gateway Intelligence (Phase 9)
- **Семантичний кеш** — Автоматично кешує непотокові відповіді, температура = 0 (обійти за допомогою `X-OmniRoute-No-Cache: true`)
- **Ідемпотентність запиту** — Дедуплікує запити протягом 5 секунд через заголовок `Idempotency-Key` або `X-Request-Id`
- **Відстеження прогресу** — Підключення подій SSE `event: progress` через заголовок `X-OmniRoute-Progress: true`
---
### Майданчик для перекладачів
Доступ через** Інформаційна панель → Translator** . Налагодження та візуалізація того, як OmniRoute перекладає запити API між постачальниками.
| Режим | призначення |
| ------------------------ | ---------------------------------------------------------------------------------------------- |
| **Дитячий майданчик** | Виберіть формати source/target, вставте запит і миттєво перегляньте перекладений результат |
| **Тестер чату** | Надсилайте повідомлення чату через проксі та перевіряйте повний цикл request/response |
| **Випробувальний стенд** | Виконайте пакетні тести для кількох комбінацій форматів, щоб перевірити правильність перекладу |
| **Живий монітор** | Переглядайте переклади в реальному часі, коли запити надходять через проксі |
**Випадки використання:**
- Налагодити причину невдачі певної комбінації client/provider
- Переконайтеся, що теги мислення, виклики інструментів і системні підказки перекладаються правильно
- Порівняйте відмінності форматів між форматами OpenAI, Claude, Gemini і відповідей API
---
### Стратегії маршрутизації
Налаштувати через** Інформаційна панель → Параметри → Маршрутизація** . Інформаційна панель показує шість найбільш використовуваних стратегій; комбо та автоматичний маршрутизатор внутрішньо підтримує більший набір.
**Стратегії, видимі на інформаційній панелі (маршрутизація на рівні облікового запису):**
| Стратегія | опис |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| **Заповніть спочатку** | Використовує облікові записи в пріоритетному порядку — основний обліковий запис обробляє всі запити, доки вони не стануть недоступними |
| **Кругова система** | Переглядає всі облікові записи з настроюваним лімітом (за замовчуванням: 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;
```
#### Псевдоніми моделей шаблонів підстановки
Створіть шаблони символів підстановки, щоб змінити назви моделей:
```
Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-6
Pattern: gpt-* → Target: gh/gpt-5.3-codex
```
Символи підстановки підтримують `*` (будь-які символи) і `?` (один символ).
#### Резервні ланцюги
Визначте глобальні резервні ланцюжки, які застосовуються до всіх запитів:
```
Chain: production-fallback
1. cc/claude-opus-4-7
2. gh/gpt-5.3-codex
3. glm/glm-4.7
```
---
### Поширені комбінації провайдерів і шаблони маршрутизації
Ось приклади шаблонів для об’єднання кількох провайдерів і маршрутизації між ними в OmniRoute:
#### 1. Комбінація агента кодування: високоефективне міркування з резервним варіантом Cost/Speed
Ідеально підходить для агентів кодування (OpenCode, Claude Code, Cursor, Cline). Спочатку маршрути до граничних моделей міркування, повертаючись до моделей швидкого кодування у разі вичерпання квоти або помилок.
- **Приладова панель** : Комбо → Нове комбо → Назва: `agent-coding` → Стратегія: `Priority`
- **Моделі** :
1. `claude/claude-sonnet-4-6` (основний агент кодування)
2. `openai/gpt-4o` (вторинний резервний високопродуктивний)
3. `deepseek/deepseek-v4-flash` (високоефективний, економічно ефективний запасний варіант)
```bash
# Example via API
curl -X POST http://localhost:20128/api/combos \
-H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "agent-coding",
"strategy": "priority",
"models": [
{ "model": "claude/claude-sonnet-4-6" },
{ "model": "openai/gpt-4o" },
{ "model": "deepseek/deepseek-v4-flash" }
]
}'
```
#### 2. Free-Tier Auto Failover Combo
Об’єднує кілька безкоштовних і безключових постачальників, щоб максимально збільшити час безвідмовної роботи без витрат API.
- **Стратегія** : `Least Used` або `Round Robin` (розподіляє навантаження за квотами)
- **Моделі** :
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. Мультимодальний / Конвеєр бачення та тексту
Поєднання спеціалізованих моделей бачення з високошвидкісною генерацією тексту для робочих процесів, пов’язаних із розумінням зображення та генерацією коду.
- **Візерунок** : комбінація `Priority`, у якій спочатку перераховуються моделі, здатні бачити, і остання модель text/code з високою пропускною здатністю.
- **Моделі** :
1. `gemini/gemini-2.5-pro` (Сильне розуміння image/multimodal )
2. `openai/gpt-4o` (Збалансоване бачення та використання інструментів)
3. `deepseek/deepseek-v4-flash` (генерація Text/code )
---
### Стійкість і автоматичні вимикачі
Налаштувати через** Інформаційна панель → Налаштування → Стійкість** .
OmniRoute реалізує стійкість на рівні постачальника з п’ятьма компонентами:
1. **Черга запитів і швидкість** — Формування запиту на системному рівні:
- **Запитів за хвилину (RPM)** — Максимальна кількість запитів за хвилину на обліковий запис
- **Мінімальний час між запитами** — Мінімальний інтервал у мілісекундах між запитами
- **Максимальна кількість одночасних запитів** — Максимальна кількість одночасних запитів на обліковий запис
2. **Перезарядка підключення** — Конфігурація типу авторизації для одного підключення після повторних помилок:
- **Базовий час відновлення** — Вікно відновлення за замовчуванням для повторних помилок висхідного потоку
- **Використовуйте підказки щодо повторної спроби** — Враховує авторитетні підказки `Retry-After` або скидання, якщо є
- **Максимальний крок відступу** — Максимальний експоненціальний рівень відстрочки для повторних відмов
3. **Автоматичний вимикач постачальника** — Відстежує наскрізні збої провайдера, позначає провайдера, що погіршився на налаштованому пороговому значенні попередження, і відкриває вимикач, коли налаштований поріг збою досягнуто:
- **Поріг деградації** — Послідовні збої провайдера перед входом `DEGRADED`
- **Поріг відмови** — Послідовні збої провайдера перед входом `OPEN`
- **Скинути час очікування** — Часове вікно до повторного тестування постачальника
- **CLOSED** (Справний) — Запити надходять нормально
- **DEGRADED** — Запити все ще надходять, поки відстежуються підвищені збої
- **OPEN** — Провайдер тимчасово заблоковано після повторних збоїв
- **HALF_OPEN** — Перевірка, якщо провайдер відновився
Обмеження швидкості `429` залежно від підключення залишаються** Перезарядка підключення** і не зараховуються до вимикача провайдера.
Стан часу виконання програми вимикача постачальника показано на** Інформаційна панель → Health** тільки.
4. **Дочекайтеся перезарядки** — Якщо кожне з’єднання-кандидат уже охолоджується, OmniRoute може дочекатися самого раннього відновлення та автоматично повторити той самий запит клієнта.
5. **Автоматичне визначення обмеження швидкості** — Коли вихідні постачальники повертають явні вікна очікування, ці підказки перекривають час відновлення локального з’єднання, коли параметр увімкнено.
**Порада професіонала:** Використовуйте** Здоров'я** сторінка для перевірки та скидання вимикачів активного постачальника після збою. Сторінка стійкості змінює лише конфігурацію.
---
### Експорт/імпорт бази даних
Керуйте резервними копіями бази даних у** Інформаційна панель → Налаштування → Система та сховище** .
| Дія | опис |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Експорт бази даних** | Завантажує поточну базу даних SQLite як файл `.sqlite` |
| **Експортувати все (.tar.gz)** | Завантажує повний резервний архів, включаючи: базу даних, налаштування, комбінації, з’єднання провайдера (без облікових даних), метадані ключа API |
| **Імпорт бази даних** | Завантажте файл `.sqlite`, щоб замінити поточну базу даних. Резервна копія перед імпортом створюється автоматично, якщо не `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"
```
**Перевірка імпорту:** Імпортований файл перевіряється на цілісність (SQLite pragma check), необхідні таблиці (`provider_connections`, `provider_nodes`, `combos`, `api_keys`) і розмір (макс. 100 МБ).
**Випадки використання:**
- Перенесення OmniRoute між машинами
- Створіть зовнішні резервні копії для аварійного відновлення
- Поділитися конфігураціями між членами команди (експортувати весь архів обміну → )
---
### Інформаційна панель налаштувань
Сторінка налаштувань організована в** 7 вкладок** для зручної навігації:
| вкладка | Зміст |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Загальний** | Інструменти системного зберігання, поведінка за замовчуванням, видимість тунелю кінцевої точки |
| **Зовнішній вигляд** | Елементи керування темою (light/dark/system), видимість бічної панелі, перемикачі панелей для карток тунелю Cloudflare/Tailscale/ngrok |
| **AI** | Бюджет мислення (прохідний / автоматичне видалення / спеціальний / адаптивний — див. [THINKING_BUDGET.md](./THINKING_BUDGET.md) ), глобальна системна підказка, підказка про кеш-статистику |
| **Безпека** | Налаштування Login/Password, контроль доступу IP, автентифікація API для `/models`, блокування постачальника, захист підказок |
| **Маршрутизація** | Глобальна стратегія маршрутизації (Fill First / Round Robin / P2C / Random / Least Used / Cost Optimized), псевдоніми моделей зі знаком підстановки, резервні ланцюжки, комбіновані параметри за замовчуванням |
| **Стійкість** | Черга запитів, час відновлення з’єднання, конфігурація вимикача постачальника та поведінка очікування відновлення |
| **Просунутий** | Глобальна конфігурація проксі (HTTP/SOCKS5), заміна проксі для кожного постачальника |
Загальне більше не дублює журналювання лише для читання та кешування нотаток. Параметри зберігання та оптимізації бази даних зберігаються через `/api/settings/database`; ручне очищення кешу використовує `DELETE /api/cache`. Обмеження рядків журналу запитів і проксі-серверів контролюються `CALL_LOGS_TABLE_MAX_ROWS` і `PROXY_LOGS_TABLE_MAX_ROWS`.
---
### Управління витратами та бюджетом
Доступ через** Інформаційна панель → Витрати** .
| вкладка | призначення |
| ----------------- | -------------------------------------------------------------------------------------------------------------- |
| **Бюджет** | Встановіть ліміти витрат на ключ API за допомогою бюджетів daily/weekly/monthly і відстеження в реальному часі |
| **Ціноутворення** | Перегляд і редагування записів моделі ціноутворення — вартість 1 тис. токенів input/output на постачальника |
```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
```
**Відстеження витрат:** Кожен запит реєструє використання токенів і розраховує вартість за допомогою таблиці цін. Переглянути розбивки в** Інформаційна панель використання →** за постачальником, моделлю та ключем API.
---
### Транскрипція аудіо
OmniRoute підтримує транскрипцію аудіо через кінцеву точку, сумісну з 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` є рідним маршрутом Deepgram і потребує ключа Deepgram API. Якщо налаштовано лише OpenRouter, використовуйте `openrouter/deepgram/nova-3`.
**Перетворення мови в текст (транскрипція)** провайдери:
- `openai/` (сумісний з Whisper)
- `groq/` (Groq Whisper Turbo)
- `deepgram/` (сімейство Nova)
- `assemblyai/`
- `nvidia/` (папуга, канарка)
- `huggingface/` (варіанти пошепки)
- `qwen/`
**Синтез мовлення (`POST /v1/audio/speech`)** провайдери:
- `openai/` (tts-1, tts-1-hd)
- `hyperbolic/`
- `deepgram/` (аура)
- `nvidia/` (Сорока 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).
---
### Комбіновані стратегії балансування
Налаштуйте балансування для комбо** Dashboard → Combos → Create/Edit → Стратегія** .
| Стратегія | опис |
| ----------------------------- | ---------------------------------------------------------------------------------------------- |
| **Кругова система** | Послідовно обертається моделями |
| **Пріоритет** | Завжди пробує першу модель; повертається лише в разі помилки |
| **Випадковий** | Вибирає випадкову модель із комбо для кожного запиту |
| **Зважений** | Маршрути пропорційно на основі призначених ваг для кожної моделі |
| **Найменш використовуваний** | Маршрути до моделі з найменшою кількістю останніх запитів (використовує комбіновані показники) |
| **Оптимізовано за витратами** | Маршрути до найдешевшої доступної моделі (використовується таблиця цін) |
Можна встановити глобальні стандартні параметри комбо** Інформаційна панель → Налаштування → Маршрутизація → Combo Defaults** . Комбіновані цільові тайм-аути за умовчанням успадковують поточний тайм-аут запиту. використання** Цільовий час очікування (секунди)** на комбо за замовчуванням або окреме комбо лише тоді, коли коротший ліміт на ціль має ініціювати швидший відкат.
Комбінована оптимізація без затримки доступна. Залиште** Оптимізація без затримки** вимкнено, щоб запобігти цим функціям затримки перегони резервних цілей, пропускання цілей на основі історії TTFT або стиснення резервних запитів; його ввімкнення дозволяє налаштувати хеджування, прогнозовані пропуски TTFT і проактивне резервне стиснення для заміни точності routing/request на меншу затримку хвоста.
Вимкнути** Буфер маркера міркування** коли провайдери висхідного каналу вимагають суворих обмежень `max_tokens` / `maxOutputTokens`. Якщо ввімкнено, комбо-маршрутизація лише додає резерв для моделі аргументації для моделей із відомим обмеженням виведення та залишає ліміт маркерів клієнта незмінним, якщо безпечне буферизоване значення перевищить це обмеження. Якщо ліміт клієнта вже перевищує відомий ліміт, OmniRoute обмежує його до цього ліміту перед тим, як надсилати висхідний запит.
---
### Інформаційна панель здоров'я
Доступ через** Інформаційна панель → Health** . Огляд стану системи в реальному часі з 6 картками:
| картка | Що це показує |
| -------------------------- | ----------------------------------------------------------------------------- |
| **Статус системи** | Час роботи, версія, використання пам’яті, каталог даних |
| **Здоров'я постачальника** | Стан автоматичного вимикача глобального постачальника |
| **Обмеження швидкості** | Час відновлення активного з’єднання на обліковий запис із часом, що залишився |
| **Активні блокування** | Активні блокування на основі моделі та тимчасові виключення |
| **Кеш підписів** | Статистика кешу дедуплікації (активні ключі, частота звернень) |
| **Телеметрія затримки** | агрегування часу затримки p50/p95/p99 для кожного постачальника |
**Порада професіонала:** Сторінка Health автоматично оновлюється кожні 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)