# 🚀 OmniRoute — безкоштовний ШІ-шлюз

### Ніколи не припиняйте кодувати. Розумна маршрутизація до **БЕЗКОШТОВНИХ і недорогих моделей штучного інтелекту** з автоматичним резервним копіюванням.

_Ваш універсальний API-проксі — одна кінцева точка, 67+ провайдерів, нуль простоїв. Тепер з оркестровкою агента **MCP & A2A**._

**Завершення чату • Вбудовування • Генерація зображень • Відео • Музика • Аудіо • Реранжування • **Веб-пошук** • Сервер MCP • Протокол A2A • 100% TypeScript**

---

<div align="center">

[![npm version](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute)
[![npm downloads](https://img.shields.io/npm/dm/omniroute?color=cb3837&logo=npm&label=npm%20downloads)](https://www.npmjs.com/package/omniroute)
[![Docker Hub](https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https://hub.docker.com/r/diegosouzapw/omniroute)
[![Docker Pulls](https://img.shields.io/docker/pulls/diegosouzapw/omniroute?logo=docker&color=2496ED&label=docker%20pulls)](https://hub.docker.com/r/diegosouzapw/omniroute)
[![License](https://img.shields.io/github/license/diegosouzapw/OmniRoute)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
[![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online)
[![WhatsApp](https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)

[🌐 Website](https://omniroute.online) • [🚀 Quick Start](#-quick-start) • [💡 Features](#-key-features) • [📖 Docs](#-documentation) • [💰 Pricing](#-pricing-at-a-glance) • [💬 WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)

</div>

🌐 **Доступно в:** 🇺🇸 [English](README.md) | 🇧🇷 [Português (Brasil)](docs/i18n/pt-BR/README.md) | 🇪🇸 [Español](docs/i18n/es/README.md) | 🇫🇷 [Français](docs/i18n/fr/README.md) | 🇮🇹 [Italiano](docs/i18n/it/README.md) | 🇷🇺 [Русский](docs/i18n/ru/README.md) | 🇨🇳 [中文 (简体)](docs/i18n/zh-CN/README.md) | 🇩🇪 [Deutsch](docs/i18n/de/README.md) | 🇮🇳 [हिन्दी](docs/i18n/in/README.md) | 🇹🇭 [ไทย](docs/i18n/th/README.md) | 🇺🇦 [Українська](docs/i18n/uk-UA/README.md) | 🇸🇦 [العربية](docs/i18n/ar/README.md) | 🇯🇵 [日本語](docs/i18n/ja/README.md) | 🇻🇳 [Tiếng Việt](docs/i18n/vi/README.md) | 🇧🇬 [Български](docs/i18n/bg/README.md) | 🇩🇰 [Dansk](docs/i18n/da/README.md) | 🇫🇮 [Suomi](docs/i18n/fi/README.md) | 🇮🇱 [עברית](docs/i18n/he/README.md) | 🇭🇺 [Magyar](docs/i18n/hu/README.md) | 🇮🇩 [Bahasa Indonesia](docs/i18n/id/README.md) | 🇰🇷 [한국어](docs/i18n/ko/README.md) | 🇲🇾 [Bahasa Melayu](docs/i18n/ms/README.md) | 🇳🇱 [Nederlands](docs/i18n/nl/README.md) | 🇳🇴 [Norsk](docs/i18n/no/README.md) | 🇵🇹 [Português (Portugal)](docs/i18n/pt/README.md) | 🇷🇴 [Română](docs/i18n/ro/README.md) | 🇵🇱 [Polski](docs/i18n/pl/README.md) | 🇸🇰 [Slovenčina](docs/i18n/sk/README.md) | 🇸🇪 [Svenska](docs/i18n/sv/README.md) | 🇵🇭 [Filipino](docs/i18n/phi/README.md) | 🇨🇿 [Čeština](docs/i18n/cs/README.md)

---

## 🆕 Що нового у v3.0.0

> **Оновлення з версії 2.9.5?** — див. [full CHANGELOG](CHANGELOG.md#300--2026-03-22-release-candidate--not-yet-merged-to-main) для всіх змін.

| Площа                                    | Змінити                                                                                                                                                                                                               |
| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 🔒 **CodeQL Security**                   | Виправлено 10+ попереджень CodeQL: поліноміальне повторення, небезпечна випадковість, виправлення ін’єкції оболонки                                                                                                   |
| ✅ **Перевірка маршруту**                | Усі 176 маршрутів API тепер перевірено за допомогою схем Zod + `validateBody()` — пропуски CI `check:route-validation:t06`                                                                                            |
| 🐛 **Витік тегів omniModel**             | Внутрішні теги `<omniModel>` більше не просочуються до клієнтів у потокових відповідях SSE (#585)                                                                                                                     |
| 🔑 **API зареєстрованих ключів**         | Автоматичне надання ключів API через `POST /api/v1/registered-keys` із застосуванням квот для кожного постачальника/облікового запису, ідемпотентністю, сховищем SHA-256 і додатковим звітуванням про проблеми GitHub |
| 🎨 **Значки постачальників**             | 130+ логотипів постачальників через `@lobehub/icons` (SVG) із PNG → загальний резервний ланцюжок                                                                                                                      |
| 🔄 **Автосинхронізація моделі**          | 24-годинний планувальник і ручне перемикання інтерфейсу користувача для синхронізації списків моделей для вбудованих і спеціальних OpenAI-сумісних провайдерів                                                        |
| 🌐 **OpenCode Zen/Go**                   | Два нових постачальника від @kang-heewon через PR #530: безкоштовний рівень + рівень підписки через `OpencodeExecutor`                                                                                                |
| 🐛 **Gemini CLI OAuth**                  | Помилка дії, коли `GEMINI_OAUTH_CLIENT_SECRET` відсутній у Docker (це була загадкова помилка Google)                                                                                                                  |
| 🐛 **Конфігурація OpenCode**             | `saveOpenCodeConfig()` тепер правильно записує TOML у `XDG_CONFIG_HOME`                                                                                                                                               |
| 🐛 **Перевизначення закріпленої моделі** | `body.model` правильно встановлено на `pinnedModel` для захисту контекстного кешу                                                                                                                                     |
| 🐛 **петля Кодексу/Клода**               | Блоки `tool_result` тепер перетворюються на текст, щоб зупинити нескінченні цикли                                                                                                                                     |
| 🐛 **Переадресація входу**               | Логін більше не зависає після пропуску встановлення пароля                                                                                                                                                            |
| 🐛 **Шляхи Windows**                     | Шляхи MSYS2/Git-Bash (`/c/...`) автоматично нормалізовано до `C:\...`                                                                                                                                                 |

---

## 🖼️ Головна інформаційна панель

<div align="center">
  <img src="./docs/screenshots/MainOmniRoute.png" alt="OmniRoute Dashboard" width="800"/>
</div>

---

## 📸 Попередній перегляд інформаційної панелі

<details>
<summary><b>Натисніть, щоб переглянути знімки панелі інструментів</b></summary>

| Сторінка                 | Скріншот                                          |
| ------------------------ | ------------------------------------------------- |
| **Постачальники**        | ![Providers](docs/screenshots/01-providers.png)   |
| **Комбінації**           | ![Combos](docs/screenshots/02-combos.png)         |
| **Аналітика**            | ![Analytics](docs/screenshots/03-analytics.png)   |
| **Здоров'я**             | ![Health](docs/screenshots/04-health.png)         |
| **Перекладач**           | ![Translator](docs/screenshots/05-translator.png) |
| **Налаштування**         | ![Settings](docs/screenshots/06-settings.png)     |
| **Інструменти CLI**      | ![CLI Tools](docs/screenshots/07-cli-tools.png)   |
| **Журнали використання** | ![Usage](docs/screenshots/08-usage.png)           |
| **Кінцеві точки**        | ![Endpoints](docs/screenshots/09-endpoint.png)    |

</details>

---

### 🤖 Безкоштовний постачальник AI для ваших улюблених агентів кодування

_Підключіть будь-який інструмент IDE або CLI на основі штучного інтелекту через OmniRoute — безкоштовний шлюз API для необмеженого програмування._

  <table>
    <tr>
      <td align="center" width="110">
        <a href="https://github.com/openclaw/openclaw">
          <img src="./public/providers/openclaw.png" alt="OpenClaw" width="48"/><br/>
          <b>OpenClaw</b>
        </a><br/>
        <sub>⭐ 205K</sub>
      </td>
      <td align="center" width="110">
        <a href="https://github.com/HKUDS/nanobot">
          <img src="./public/providers/nanobot.png" alt="NanoBot" width="48"/><br/>
          <b>NanoBot</b>
        </a><br/>
        <sub>⭐ 20.9K</sub>
      </td>
      <td align="center" width="110">
        <a href="https://github.com/sipeed/picoclaw">
          <img src="./public/providers/picoclaw.jpg" alt="PicoClaw" width="48"/><br/>
          <b>PicoClaw</b>
        </a><br/>
        <sub>⭐ 14.6K</sub>
      </td>
      <td align="center" width="110">
        <a href="https://github.com/zeroclaw-labs/zeroclaw">
          <img src="./public/providers/zeroclaw.png" alt="ZeroClaw" width="48"/><br/>
          <b>ZeroClaw</b>
        </a><br/>
        <sub>⭐ 9.9K</sub>
      </td>
      <td align="center" width="110">
        <a href="https://github.com/nearai/ironclaw">
          <img src="./public/providers/ironclaw.png" alt="IronClaw" width="48"/><br/>
          <b>IronClaw</b>
        </a><br/>
        <sub>⭐ 2.1K</sub>
      </td>
    </tr>
    <tr>
      <td align="center" width="110">
        <a href="https://github.com/anomalyco/opencode">
          <img src="./public/providers/opencode.svg" alt="OpenCode" width="48"/><br/>
          <b>OpenCode</b>
        </a><br/>
        <sub>⭐ 106K</sub>
      </td>
      <td align="center" width="110">
        <a href="https://github.com/openai/codex">
          <img src="./public/providers/codex.png" alt="Codex CLI" width="48"/><br/>
          <b>Codex CLI</b>
        </a><br/>
        <sub>⭐ 60.8K</sub>
      </td>
      <td align="center" width="110">
        <a href="https://github.com/anthropics/claude-code">
          <img src="./public/providers/claude.png" alt="Claude Code" width="48"/><br/>
          <b>Claude Code</b>
        </a><br/>
        <sub>⭐ 67.3K</sub>
      </td>
      <td align="center" width="110">
        <a href="https://github.com/google-gemini/gemini-cli">
          <img src="./public/providers/gemini-cli.png" alt="Gemini CLI" width="48"/><br/>
          <b>Gemini CLI</b>
        </a><br/>
        <sub>⭐ 94.7K</sub>
      </td>
      <td align="center" width="110">
        <a href="https://github.com/Kilo-Org/kilocode">
          <img src="./public/providers/kilocode.png" alt="Kilo Code" width="48"/><br/>
          <b>Kilo Code</b>
        </a><br/>
        <sub>⭐ 15.5K</sub>
      </td>
    </tr>
  </table>

<sub>📡 Усі агенти підключаються через <code>http://localhost:20128/v1</code> або <code>http://cloud.omniroute.online/v1</code> — одна конфігурація, необмежена кількість моделей і квота</sub>

---

## 🤔 Чому OmniRoute?

**Припиніть витрачати гроші та досягати лімітів:**

- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> Квота підписки закінчується без використання кожного місяця
- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> Обмеження швидкості перешкоджають кодуванню в середині
- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> Дорогі API ($20-50/місяць за постачальника)
- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> Ручне перемикання між провайдерами

**OmniRoute вирішує цю проблему:**

- ✅ **Збільште кількість підписок** - Відстежуйте квоту, використовуйте кожен біт перед скиданням
- ✅ **Автоматичний резерв** - Підписка → Ключ API → Дешево → Безкоштовно, без простоїв
- ✅ **Кілька облікових записів** - Циклічний цикл між обліковими записами кожного постачальника
- ✅ **Універсальний** - Працює з Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, будь-яким інструментом CLI

---

## 📧 Підтримка

> 💬 **Приєднуйтесь до нашої спільноти!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — отримуйте допомогу, діліться порадами та будьте в курсі подій.

- **Веб-сайт**: [omniroute.online](https://omniroute.online)
- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- **Проблеми**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
- **Допомога**: перегляньте [CONTRIBUTING.md](CONTRIBUTING.md), відкрийте PR або виберіть `good first issue`
- **Оригінальний проект**: [9router by decolua](https://github.com/decolua/9router)

### 🐛 Повідомити про помилку?

Відкриваючи проблему, виконайте команду system-info та прикріпіть згенерований файл:

```bash
npm run system-info
```

Це генерує `system-info.txt` з вашою версією Node.js, версією OmniRoute, деталями ОС, встановленими інструментами CLI (iflow, gemini, claude, codex, antigravity, droid тощо), статусом Docker/PM2 і системними пакетами — усім, що нам потрібно для швидкого відтворення вашої проблеми. Прикріпіть файл безпосередньо до свого випуску GitHub.

---

## 🔄 Як це працює

```
┌─────────────┐
│  Your CLI   │  (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)
│   Tool      │
└──────┬──────┘
       │ http://localhost:20128/v1
       ↓
┌─────────────────────────────────────────┐
│           OmniRoute (Smart Router)        │
│  • Format translation (OpenAI ↔ Claude) │
│  • Quota tracking + Embeddings + Images │
│  • Auto token refresh                   │
└──────┬──────────────────────────────────┘
       │
       ├─→ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI
       │   ↓ quota exhausted
       ├─→ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.
       │   ↓ budget limit
       ├─→ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)
       │   ↓ budget limit
       └─→ [Tier 4: FREE] iFlow, Qwen, Kiro (unlimited)

Result: Never stop coding, minimal cost
```

---

## 🎯 Що вирішує OmniRoute — 30 реальних проблем і варіантів використання

> **Кожен розробник, який використовує інструменти штучного інтелекту, щодня стикається з цими проблемами.** OmniRoute було створено, щоб вирішити їх усі — від перевитрати коштів до регіональних блокувань, від порушених потоків OAuth до операцій протоколу та можливості спостереження на підприємстві.

<details>
<summary><b>💸 1. «Я плачу за дорогу підписку, але мене все одно переривають через обмеження»</b></summary>

Розробники платять 20–200 доларів на місяць за Claude Pro, Codex Pro або GitHub Copilot. Навіть якщо платити, квота має максимальну межу — 5 годин використання, тижневі ліміти або ліміти за хвилину. У середині сеансу кодування постачальник перестає відповідати, а розробник втрачає швидкість і продуктивність.

**Як це вирішує OmniRoute:**

- **Smart 4-Tier Fallback** — якщо квота підписки закінчується, автоматично перенаправляється до API Key → Дешево → Безкоштовно без ручного втручання
- **Відстеження квот у реальному часі** — показує споживання токенів у реальному часі зі зворотним відліком скидання (5 годин, щодня, щотижня)
- **Підтримка кількох облікових записів** — кілька облікових записів у кожного постачальника з автоматичним циклічним перебором — коли один закінчується, перемикається на наступний
- **Користувацькі комбо** — резервні ланцюжки, які можна налаштувати, із 6 стратегіями балансування (спочатку заповнення, циклічний, P2C, випадковий, найменш використовуваний, оптимізований за витратами)
- **Бізнес-квоти Codex** — Моніторинг квот робочого простору бізнесу/команди безпосередньо на інформаційній панелі

</details>

<details>
<summary><b>🔌 2. «Мені потрібно використовувати кілька провайдерів, але кожен має інший API»</b></summary>

OpenAI використовує один формат, Claude (Anthropic) використовує інший, Gemini ще інший. Якщо розробник хоче перевірити моделі від різних постачальників або повернутися до них, йому потрібно переналаштувати SDK, змінити кінцеві точки, мати справу з несумісними форматами. Спеціальні постачальники (FriendLI, NIM) мають нестандартні кінцеві точки моделі.

**Як це вирішує OmniRoute:**

- **Unified Endpoint** — єдиний `http://localhost:20128/v1` служить проксі-сервером для всіх 67+ постачальників
- **Переклад форматів** — автоматичний і прозорий: OpenAI ↔ Claude ↔ Gemini ↔ Responses API
- **Response Sanitization** — видаляє нестандартні поля (`x_groq`, `usage_breakdown`, `service_tier`), які порушують OpenAI SDK v1.83+
- **Нормалізація ролі** — перетворює `developer` → `system` для постачальників, які не є OpenAI; `system` → `user` для GLM/ERNIE
- **Think Tag Extraction** — витягує блоки `<think>` з таких моделей, як DeepSeek R1, у стандартизований `reasoning_content`
- **Структурований вихід для Gemini** — `json_schema` → `responseMimeType`/`responseSchema` автоматичне перетворення
- **`stream` за замовчуванням `false`** — узгоджується зі специфікацією OpenAI, уникаючи неочікуваних SSE у Python/Rust/Go SDK

</details>

<details>
<summary><b>🌐 3. «Мій постачальник штучного інтелекту блокує мій регіон/країну»</b></summary>

Такі постачальники, як OpenAI/Codex, блокують доступ із певних географічних регіонів. Користувачі отримують помилки на зразок `unsupported_country_region_territory` під час з’єднань OAuth і API. Це особливо засмучує розробників із країн, що розвиваються.

**Як це вирішує OmniRoute:**

- **3-рівнева конфігурація проксі-сервера** — налаштовується проксі-сервер на 3 рівнях: глобальний (увесь трафік), для кожного постачальника (лише один постачальник) і для кожного підключення/ключа
- **Значки проксі-сервера з кольоровим кодуванням** — Візуальні індикатори: 🟢 глобальний проксі, 🟡 проксі-сервер постачальника, 🔵 проксі-сервер підключення, завжди показує IP-адресу
- **Обмін маркерами OAuth через проксі** — потік OAuth також проходить через проксі, вирішуючи проблему `unsupported_country_region_territory`
- **Тестування з’єднання через проксі** — тестування з’єднання використовує налаштований проксі (без прямого обходу)
- **Підтримка SOCKS5** — повна підтримка проксі SOCKS5 для вихідної маршрутизації
- **TLS Fingerprint Spoofing** — відбиток TLS, подібний до браузера, через `wreq-js` для обходу виявлення ботів
- **🔏 Зіставлення відбитків CLI** — змінює порядок заголовків і полів основного вмісту, щоб відповідати власним двійковим підписам CLI, суттєво знижуючи ризик позначення облікового запису. IP-адреса проксі-сервера зберігається — ви отримуєте приховане **і** маскування IP-адреси одночасно

</details>

<details>
<summary><b>🆓 4. «Я хочу використовувати ШІ для кодування, але в мене немає грошей»</b></summary>

Не кожен може платити 20–200 доларів на місяць за підписку на AI. Студентам, розробникам із країн, що розвиваються, любителям і фрілансерам потрібен доступ до якісних моделей за нульовою ціною.

**Як це вирішує OmniRoute:**

- **Вбудовані безкоштовні постачальники рівня** — Вбудована підтримка 100% безкоштовних постачальників: iFlow (5 необмежених моделей через OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 необмежені моделі: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID безкоштовно), Gemini CLI (180K токенів/місяць безкоштовно)
- **Ollama Cloud** — хмарні моделі Ollama на `api.ollama.com` з безкоштовним рівнем «Light usage»; використовуйте префікс `ollamacloud/<model>`
- **Безкоштовні комбінації** — ланцюжок `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = 0 доларів США на місяць без простоїв
- **Безкоштовний доступ до NVIDIA NIM** — ~40 об./хв. для розробників назавжди безкоштовний доступ до 70+ моделей на build.nvidia.com (перехід від кредитів до чистих обмежень швидкості)
- **Стратегія оптимізації витрат** — стратегія маршрутизації, яка автоматично вибирає найдешевшого доступного постачальника

</details>

<details>
<summary><b>🔒 5. «Мені потрібно захистити мій ШІ-шлюз від несанкціонованого доступу»</b></summary>

Коли шлюз штучного інтелекту надається мережі (LAN, VPS, Docker), будь-хто, хто має адресу, може використовувати токени/квоту розробника. Без захисту API вразливі до неправильного використання, швидкого впровадження та зловживання.

**Як це вирішує OmniRoute:**

- **Керування ключами API** — генерація, ротація та визначення обсягу для кожного постачальника за допомогою спеціальної сторінки `/dashboard/api-manager`
- **Дозволи на рівні моделі** — обмежте ключі API певними моделями (`openai/*`, шаблони узагальнення) з перемикачем «Дозволити все»/«Обмежити»
- **API Endpoint Protection** — вимагати ключ для `/v1/models` та блокувати певних постачальників зі списку
- **Auth Guard + CSRF Protection** — усі маршрути інформаційної панелі захищено проміжним програмним забезпеченням `withAuth` + маркерами CSRF
- **Обмежувач швидкості** — обмеження швидкості за IP-адресою з настроюваними вікнами
- **IP Filtering** — список дозволених/чорних адрес для контролю доступу
- **Prompt Injection Guard** — очищення від шкідливих шаблонів підказок
- **Шифрування AES-256-GCM** — облікові дані зашифровані в стані спокою

</details>

<details>
<summary><b>🛑 6. «Мій постачальник не працює, і я втратив потік кодування»</b></summary>

Постачальники AI можуть стати нестабільними, повертати помилки 5xx або досягати тимчасових обмежень швидкості. Якщо розробник залежить від одного постачальника, вони перериваються. Без автоматичних вимикачів повторні спроби можуть призвести до збою програми.

**Як це вирішує OmniRoute:**

- **Автоматичний вимикач для кожної моделі** — Автоматичне розмикання/замикання з настроюваними пороговими значеннями та часом охолодження (замкнуто/розімкнуто/напіврозімкнуто), для кожної моделі, щоб уникнути каскадних блокувань
- **Exponential Backoff** — прогресивні затримки повторних спроб
- **Anti-Thundering Herd** — Mutex + захист семафора від одночасних повторних штормів
- **Комбіновані запасні ланцюги** — якщо основний постачальник виходить з ладу, автоматично проходить через ланцюжок без втручання.
- **Combo Circuit Breaker** — автоматично вимикає несправні постачальники в комбінованому ланцюжку
- **Health Dashboard** — Моніторинг безвідмовної роботи, стани автоматичного вимикача, блокування, статистика кешу, затримка p50/p95/p99

</details>

<details>
<summary><b>🔧 7. «Налаштування кожного інструменту штучного інтелекту є виснажливим і повторюваним процесом»</b></summary>

Розробники використовують Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Кожному інструменту потрібна інша конфігурація (кінцева точка API, ключ, модель). Перенастроювання при зміні постачальника чи моделі – марна трата часу.

**Як це вирішує OmniRoute:**

- **Панель інструментів CLI** — спеціальна сторінка з налаштуванням одним клацанням для Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline
- **GitHub Copilot Config Generator** — генерує `chatLanguageModels.json` для коду VS із масовим вибором моделі
- **Майстер адаптації** — 4-етапне налаштування для тих, хто вперше користується
- **Одна кінцева точка, усі моделі** — налаштуйте `http://localhost:20128/v1` один раз, отримайте доступ до 67+ постачальників

</details>

<details>
<summary><b>🔑 8. «Керування токенами OAuth від кількох постачальників — це пекло»</b></summary>

Claude Code, Codex, Gemini CLI, Copilot — усі використовують OAuth 2.0 із терміном дії маркерів. Розробникам потрібно постійно проходити повторну автентифікацію, мати справу з `client_secret is missing`, `redirect_uri_mismatch` та збоями на віддалених серверах. OAuth у LAN/VPS є особливо проблематичним.

**Як це вирішує OmniRoute:**

- **Auto Token Refresh** — маркери OAuth оновлюються у фоновому режимі до завершення терміну дії
- **Вбудований OAuth 2.0 (PKCE)** — автоматичний потік для Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow
- **Multi-Account OAuth** — кілька облікових записів на постачальника за допомогою вилучення токенів JWT/ID
- **OAuth LAN/Remote Fix** — виявлення приватної IP-адреси для `redirect_uri` + ручний режим URL-адреси для віддалених серверів
- **OAuth за Nginx** — використовує `window.location.origin` для зворотної сумісності проксі
- **Remote OAuth Guide** — покроковий посібник для облікових даних Google Cloud на VPS/Docker

</details>

<details>
<summary><b>📊 9. «Я не знаю, скільки я витрачаю і куди»</b></summary>

Розробники використовують кілька платних постачальників, але не мають єдиного уявлення про витрати. Кожен постачальник має власну платіжну панель, але немає консолідованого перегляду. Несподівані витрати можуть накопичитися.

**Як це вирішує OmniRoute:**

- **Інформаційна панель аналізу витрат** — відстеження вартості кожного токена та керування бюджетом для кожного постачальника
- **Бюджетні обмеження на рівень** — максимальна сума витрат на рівень, що запускає автоматичний відкат
- **Конфігурація ціни за модель** — налаштовувані ціни за модель
- **Статистика використання за ключ API** — кількість запитів і позначка часу останнього використання для кожного ключа
- **Інформаційна панель аналітики** — картки зі статистичними даними, діаграма використання моделі, таблиця постачальників із показниками успіху та затримкою

</details>

<details>
<summary><b>🐛 10. «Я не можу діагностувати помилки та проблеми під час викликів ШІ»</b></summary>

Коли виклик не вдається, розробник не знає, чи це було обмеження швидкості, прострочений маркер, неправильний формат чи помилка постачальника. Фрагментовані журнали на різних терміналах. Без спостережливості налагодження відбувається методом проб і помилок.

**Як це вирішує OmniRoute:**

- **Інформаційна панель уніфікованих журналів** — 4 вкладки: журнали запитів, журнали проксі, журнали аудиту, консоль
- **Console Log Viewer** — засіб перегляду терміналу в режимі реального часу з кольоровими рівнями, автопрокручуванням, пошуком, фільтром
- **Проксі-журнали SQLite** — постійні журнали, які залишаються після перезапуску сервера
- **Translator Playground** — 4 режими налагодження: Playground (переклад формату), Chat Tester (туди й назад), Test Bench (пакет), Live Monitor (у реальному часі)
- **Запит телеметрії** — затримка p50/p95/p99 + трасування X-Request-Id
- **Логування на основі файлів із ротацією** — консольний перехоплювач записує все в журнал JSON із ротацією на основі розміру
- **Інформаційний звіт про систему** — `npm run system-info` генерує `system-info.txt` з повним середовищем (версія Node, версія OmniRoute, ОС, інструменти CLI, статус Docker/PM2). Додайте його під час повідомлення про проблеми для миттєвого сортування.

</details>

<details>
<summary><b>🏗️ 11. «Розгортання та підтримка шлюзу складна»</b></summary>

Встановлення, налаштування та обслуговування проксі ШІ в різних середовищах (локальне, VPS, Docker, хмара) є трудомістким. Такі проблеми, як жорстко закодовані шляхи, `EACCES` в каталогах, конфлікти портів і кросплатформні збірки, додають проблем.

**Як це вирішує OmniRoute:**

- **npm global install** — `npm install -g omniroute && omniroute` — готово
- **Мультиплатформенний Docker** — нативний AMD64 + ARM64 (Apple Silicon, AWS Graviton, Raspberry Pi)
- **Профілі створення Docker** — `base` (без інструментів CLI) і `cli` (з Claude Code, Codex, OpenClaw)
- **Electron Desktop App** — рідна програма для Windows/macOS/Linux із системним треєм, автозапуском, офлайн-режимом
- **Режим розділеного порту** — API та інформаційна панель на окремих портах для розширених сценаріїв (зворотний проксі, мережа контейнерів)
- **Cloud Sync** — синхронізація налаштувань між пристроями через Cloudflare Workers
- **Резервне копіювання БД** — автоматичне резервне копіювання, відновлення, експорт та імпорт усіх налаштувань

</details>

<details>
<summary><b>🌍 12. «Інтерфейс лише англійською мовою, і моя команда не розмовляє англійською»</b></summary>

Команди в неангломовних країнах, особливо в Латинській Америці, Азії та Європі, стикаються з інтерфейсами лише англійською мовою. Мовні бар’єри зменшують адаптацію та збільшують кількість помилок конфігурації.

**Як це вирішує OmniRoute:**

- **Інформаційна панель i18n — 30 мов** — перекладено всі 500+ клавіш, включаючи арабську, болгарську, датську, німецьку, іспанську, фінську, французьку, іврит, гінді, угорську, індонезійську, італійську, японську, корейську, малайську, голландську, норвезьку, польську, португальську (PT/BR), румунську, російську, словацьку, шведську, тайську, українську, в’єтнамську, китайська, філіппінська, англійська
- **Підтримка RTL** — підтримка арабської та івриту справа наліво
- **Багатомовні файли README** — 30 повних перекладів документації
- **Вибір мови** — значок глобуса в заголовку для перемикання в реальному часі

</details>

<details>
<summary><b>🔄 13. «Мені потрібно більше, ніж чат — мені потрібні вставки, зображення, аудіо»</b></summary>

ШІ — це не просто завершення чату. Розробникам потрібно генерувати зображення, транскрибувати аудіо, створювати вбудовування для RAG, змінювати рейтинг документів і модерувати вміст. Кожен API має різну кінцеву точку та формат.

**Як це вирішує OmniRoute:**

- **Вбудовування** — `/v1/embeddings` з 6 постачальниками та 9+ моделями
- **Генерація зображень** — `/v1/images/generations` з 10 постачальниками та понад 20 моделями (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)
- **Текст у відео** — `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) і SD WebUI
- **Текст у музику** — `/v1/music/generations` — ComfyUI (Stable Audio Open, MusicGen)
- **Транскрипція аудіо** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3
- **Перетворення тексту в мовлення** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld**, **Cartesia**, **PlayHT**, + існуючі постачальники
- **Модерація** — `/v1/moderations` — Перевірка безпеки вмісту
- **Переранжування** — `/v1/rerank` — Переранжування релевантності документа
- **Responses API** — повна підтримка `/v1/responses` для Codex

</details>

<details>
<summary><b>🧪 14. «У мене немає можливості перевірити та порівняти якість різних моделей»</b></summary>

Розробники хочуть знати, яка модель найкраще підходить для їхнього випадку використання — код, переклад, міркування — але порівнювати вручну повільно. Інтегрованих інструментів оцінювання не існує.

**Як це вирішує OmniRoute:**

- **Оцінки LLM** — Золотий набір тестів із 10 попередньо завантаженими випадками, що охоплюють привітання, математику, географію, генерацію коду, відповідність JSON, переклад, уцінку, відмову безпеки
- **4 стратегії збігу** — `exact`, `contains`, `regex`, `custom` (функція JS)
- **Translator Playground Test Bench** — Пакетне тестування з кількома входами та очікуваними результатами, порівняння між постачальниками
- **Chat Tester** — повний цикл із візуальним відтворенням відповідей
- **Live Monitor** — потік усіх запитів, що проходять через проксі, у реальному часі

</details>

<details>
<summary><b>📈 15. «Мені потрібно масштабувати без втрати продуктивності»</b></summary>

Оскільки кількість запитів зростає, без кешування ті самі запитання створюють дублюючі витрати. Без ідемпотентності, дублікат запитів обробки відходів. Необхідно дотримуватися обмежень тарифів для кожного постачальника.

**Як це вирішує OmniRoute:**

- **Семантичний кеш** — дворівневий кеш (підпис + семантичний) зменшує вартість і затримку
- **Request Idempotency** — вікно дедуплікації 5 с для ідентичних запитів
- **Виявлення ліміту швидкості** — RPM для кожного постачальника, мінімальний розрив і максимальне одночасне відстеження
- **Обмеження швидкості, які можна редагувати** — налаштування за замовчуванням у Параметрах → Стійкість із наполегливістю
- **API Key Validation Cache** — 3-рівневий кеш для продуктивності
- **Інформаційна панель справності з телеметрією** — затримка p50/p95/p99, статистика кешу, час роботи

</details>

<details>
<summary><b>🤖 16. «Я хочу глобально контролювати поведінку моделі»</b></summary>

Розробники, які хочуть, щоб усі відповіді відповідали певною мовою, з певним тоном або хочуть обмежити маркери міркування. Налаштовувати це в кожному інструменті/запиті є недоцільним.

**Як це вирішує OmniRoute:**

- **Впровадження системної підказки** — глобальна підказка застосовується до всіх запитів
- **Thinking Budget Validation** — Контроль розподілу токенів міркувань за запитом (прохідний, автоматичний, спеціальний, адаптивний)
- **6 стратегій маршрутизації** — глобальні стратегії, які визначають спосіб розподілу запитів
- **Wildcard Router** — шаблони `provider/*` динамічно направляють до будь-якого постачальника
- **Увімкнути/вимкнути комбо** — перемикайте комбо безпосередньо з інформаційної панелі
- **Перемикнути постачальника** — увімкнути/вимкнути всі з’єднання для постачальника одним клацанням миші
- **Заблоковані постачальники** — виключити певних постачальників зі списку `/v1/models`

</details>

<details>
<summary><b>🧰 17. «Мені потрібні інструменти MCP як першокласні можливості продукту»</b></summary>

Багато шлюзів ШІ розкривають MCP лише як приховану деталь реалізації. Командам потрібен видимий, керований рівень операцій.

**Як це вирішує OmniRoute:**

- MCP з’являється на панелі навігації та на вкладці протоколу кінцевої точки
- Спеціальна сторінка керування MCP із процесом, інструментами, обсягами й аудитом
- Вбудований швидкий запуск для `omniroute --mcp` та адаптація клієнта

</details>

<details>
<summary><b>🧠 18. «Мені потрібна оркестровка A2A із синхронізацією + шляхи завдань потоку»</b></summary>

Робочі процеси агента потребують як прямих відповідей, так і тривалого потокового виконання з контролем життєвого циклу.

**Як це вирішує OmniRoute:**

- Кінцева точка A2A JSON-RPC (`POST /a2a`) з `message/send` і `message/stream`
- Потокова передача SSE з розповсюдженням стану терміналу
- API життєвого циклу завдань для `tasks/get` та `tasks/cancel`

</details>

<details>
<summary><b>🛰️ 19. «Мені потрібна реальна справність процесу MCP, а не вгаданий статус»</b></summary>

Операційним групам потрібно знати, чи справді MCP активний, а не лише те, чи доступний API.

**Як це вирішує OmniRoute:**

- Файл серцевого ритму виконання з PID, часовими мітками, транспортом, кількістю інструментів і режимом області
- API статусу MCP, що поєднує серцебиття + останню активність
- Картки стану інтерфейсу користувача для процесу/часу безперебійної роботи/свіжості пульсу

</details>

<details>
<summary><b>📋 20. «Мені потрібне виконання інструменту MCP з можливістю перевірки»</b></summary>

Коли інструменти змінюють конфігурацію або запускають операційні дії, командам потрібна криміналістична відстежуваність.

**Як це вирішує OmniRoute:**

— Журнал аудиту з підтримкою SQLite для викликів інструментів MCP

- Фільтри за інструментом, успіхом/невдачею, ключем API та розбивкою на сторінки
- Таблиця аудиту інформаційної панелі + кінцеві точки статистики для автоматизації

</details>

<details>
<summary><b>🔐 21. «Мені потрібні обмежені дозволи MCP для інтеграції»</b></summary>

Різні клієнти повинні мати мінімальний доступ до категорій інструментів.

**Як це вирішує OmniRoute:**

- 9 детальних областей MCP для контрольованого доступу до інструменту
- Застосування обсягу та видимість в інтерфейсі користувача керування MCP
- Безпечна поза за замовчуванням для робочих інструментів

</details>

<details>
<summary><b>⚙️ 22. «Мені потрібен оперативний контроль без перерозподілу»</b></summary>

Командам потрібні швидкі зміни часу виконання під час інцидентів або витрат.

**Як це вирішує OmniRoute:**

- Перемикання комбо-активації безпосередньо з інформаційної панелі MCP
- Застосовуйте профілі стійкості з попередньо визначених пакетів політик
- Скинути стан автоматичного вимикача з тієї ж панелі керування

</details>

<details>
<summary><b>🔄 23. «Мені потрібна видимість і скасування життєвого циклу завдання A2A»</b></summary>

Без видимості життєвого циклу інциденти завдань стає важко сортувати.

**Як це вирішує OmniRoute:**

— Список завдань/фільтрування за станом/навиками з розбивкою на сторінки

- Деталізація метаданих завдань, подій і артефактів
- Кінцева точка скасування завдання та дія інтерфейсу користувача з підтвердженням

</details>

<details>
<summary><b>🌊 24. «Мені потрібні активні метрики потоку для завантаження A2A»</b></summary>

Робочі процеси потокової передачі вимагають оперативного розуміння паралельності та живих з’єднань.

**Як це вирішує OmniRoute:**

— Лічильники активних потоків інтегровані в статус A2A

- Мітка часу останнього завдання та підрахунок стану
- Картки інформаційної панелі A2A для моніторингу операцій у реальному часі

</details>

<details>
<summary><b>🪪 25. «Мені потрібне стандартне виявлення агента для клієнтів»</b></summary>

Зовнішнім клієнтам і оркестрантам потрібні машинозчитувані метадані для адаптації.

**Як це вирішує OmniRoute:**

- Картка агента розкрита в `/.well-known/agent.json`
- Можливості та навички, показані в інтерфейсі користувача користувача
- API стану A2A включає метадані виявлення для автоматизації

</details>

<details>
<summary><b>🧭 26. «Мені потрібна можливість виявлення протоколу в UX продукту»</b></summary>

Якщо користувачі не можуть виявити поверхні протоколу, якість впровадження та підтримки падає.

**Як це вирішує OmniRoute:**

- Консолідована сторінка **Кінцеві точки** з вкладками для кінцевих точок проксі, MCP, A2A та API
  — Перемикання стану вбудованої служби (онлайн/офлайн) для MCP і A2A
- Посилання з огляду на спеціальні вкладки керування

</details>

<details>
<summary><b>🧪 27. «Мені потрібна наскрізна перевірка протоколу з реальними клієнтами»</b></summary>

Пробних тестів недостатньо для перевірки сумісності протоколу перед випуском.

**Як це вирішує OmniRoute:**

- Комплект E2E, який завантажує програму та використовує реальний клієнтський транспорт MCP SDK
- Клієнт A2A перевіряє потоки виявлення, надсилання, потокової передачі, отримання та скасування
- Перехресна перевірка тверджень щодо аудиту MCP та API завдань A2A

</details>

<details>
<summary><b>📡 28. «Мені потрібна уніфікована можливість спостереження на всіх інтерфейсах»</b></summary>

Поділ спостережуваності за протоколом створює сліпі зони та довший MTTR.

**Як це вирішує OmniRoute:**

- Уніфіковані інформаційні панелі/журнали/аналітика в одному продукті
- Справність + аудит + телеметрія запитів на рівнях OpenAI, MCP і A2A
- Операційні API для статусу та автоматизації

</details>

<details>
<summary><b>💼 29. «Мені потрібен один час виконання для проксі + інструменти + оркестрація агента»</b></summary>

Запуск багатьох окремих служб збільшує експлуатаційні витрати та частоту збоїв.

**Як це вирішує OmniRoute:**

- OpenAI-сумісний проксі, сервер MCP і сервер A2A в одному стеку
- Спільна автентифікація, стійкість, зберігання даних і можливість спостереження
- Послідовна модель політики на всіх поверхнях взаємодії

</details>

<details>
<summary><b>🚀 30. «Мені потрібно надсилати агентські робочі процеси без розповсюдження коду клею»</b></summary>

Команди втрачають швидкість під час з’єднання кількох спеціальних служб і сценаріїв.

**Як це вирішує OmniRoute:**

- Уніфікована стратегія кінцевих точок для клієнтів і агентів
  — Вбудовані інтерфейси керування протоколами та шляхи перевірки диму
- Основи, готові до виробництва (безпека, журналювання, стійкість, резервне копіювання)

</details>

### Приклади Playbooks (Integrated Use Cases)

**Playbook A: Максимальна кількість платної підписки + дешеве резервне копіювання**

```txt
Combo: "maximize-claude"
  1. cc/claude-opus-4-6
  2. glm/glm-4.7
  3. if/kimi-k2-thinking

Monthly cost: $20 + small backup spend
Outcome: higher quality, near-zero interruption
```

**Playbook B: стек кодування без витрат**

```txt
Combo: "free-forever"
  1. gc/gemini-3-flash
  2. if/kimi-k2-thinking
  3. qw/qwen3-coder-plus

Monthly cost: $0
Outcome: stable free coding workflow
```

**Playbook C: резервний ланцюжок 24/7**

```txt
Combo: "always-on"
  1. cc/claude-opus-4-6
  2. cx/gpt-5.2-codex
  3. glm/glm-4.7
  4. minimax/MiniMax-M2.1
  5. if/kimi-k2-thinking

Outcome: deep fallback depth for deadline-critical workloads
```

**Playbook D: Операції агента з MCP + A2A**

```txt
1) Start MCP transport (`omniroute --mcp`) for tool-driven operations
2) Run A2A tasks via `message/send` and `message/stream`
3) Observe via /dashboard/endpoint (MCP and A2A tabs)
4) Toggle services via inline status controls
```

---

## 🆓 Почніть безкоштовно — нульова вартість конфігурації

> Налаштуйте кодування AI за лічені хвилини за **$0/місяць**. Підключіть ці безкоштовні облікові записи та використовуйте вбудовану комбінацію **Free Stack**.

| Крок | Дія                                                     | Постачальники розблоковано                                          |
| ---- | ------------------------------------------------------- | ------------------------------------------------------------------- |
| 1    | Підключіть **Kiro** (AWS Builder ID OAuth)              | Клод Сонет 4.5, Хайку 4.5 — **необмежений**                         |
| 2    | Підключіть **iFlow** (Google OAuth)                     | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... — **необмежено** |
| 3    | Підключіть **Qwen** (код пристрою)                      | qwen3-coder-plus, qwen3-coder-flash... — **необмежено**             |
| 4    | Підключіть **Gemini CLI** (Google OAuth)                | gemini-3-flash, gemini-2.5-pro — **180K/міс безкоштовно**           |
| 5    | `/dashboard/combos` → Шаблон **Безкоштовний стек ($0)** | Циклічний цикл усіх безкоштовних постачальників автоматично         |

**Направте будь-який IDE/CLI на:** `http://localhost:20128/v1` · API-ключ: `any-string` · Готово.

> **Додаткове покриття (також безкоштовно):** ключ Groq API (30 об/хв безкоштовно), NVIDIA NIM (40 об/хв безкоштовно, 70+ моделей), Cerebras (1 млн токів/день), ключ API LongCat (50 млн токенів/день!), Cloudflare Workers AI (10 тис. нейронів/день, 50+ моделей).

## ⚡ Швидкий старт

### 1) Встановити та запустити

```bash
npm install -g omniroute
omniroute
```

> **користувачі pnpm:** запустіть `pnpm approve-builds -g` після інсталяції, щоб увімкнути власні сценарії збірки, необхідні для `better-sqlite3` та `@swc/core`:
>
> ```bash
> pnpm install -g omniroute
> pnpm approve-builds -g   # Select all packages → approve
> omniroute
> ```

Інформаційна панель відкривається за адресою `http://localhost:20128`, а базова URL-адреса API – `http://localhost:20128/v1`.

| Команда                 | Опис                                                                        |
| ----------------------- | --------------------------------------------------------------------------- |
| `omniroute`             | Запустити сервер (`PORT=20128`, API та інформаційна панель на одному порту) |
| `omniroute --port 3000` | Установіть канонічний/API порт на 3000                                      |
| `omniroute --mcp`       | Запустіть сервер MCP (транспорт stdio)                                      |
| `omniroute --no-open`   | Не відкривати автоматично браузер                                           |
| `omniroute --help`      | Показати довідку                                                            |

Додатковий режим розділеного порту:

```bash
PORT=20128 DASHBOARD_PORT=20129 omniroute
# API:       http://localhost:20128/v1
# Dashboard: http://localhost:20129
```

### 2) Підключіть постачальників і створіть свій ключ API

1. Відкрийте Інформаційну панель → `Providers` та підключіть принаймні одного постачальника (ключ OAuth або API).
2. Відкрийте Інформаційну панель → `Endpoints` та створіть ключ API.
3. (Необов’язково) Відкрийте інформаційну панель → `Combos` та встановіть запасний ланцюжок.

### 3) Спрямуйте свій інструмент кодування на OmniRoute

```txt
Base URL: http://localhost:20128/v1
API Key:  [copy from Endpoint page]
Model:    if/kimi-k2-thinking (or any provider/model prefix)
```

Працює з Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode та SDK, сумісними з OpenAI.

### 4) Увімкнення та перевірка протоколів (версія 2.0)

**MCP (для операцій, керованих інструментом):**

```bash
omniroute --mcp
```

Потім підключіть свій клієнт MCP через `stdio` та перевірте такі інструменти, як:

- `omniroute_get_health`
- `omniroute_list_combos`

**A2A (для робочих процесів між агентами):**

```bash
curl http://localhost:20128/.well-known/agent.json
```

```bash
curl -X POST http://localhost:20128/a2a \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":"quickstart","method":"message/send","params":{"skill":"quota-management","messages":[{"role":"user","content":"Give me a short quota summary."}]}}'
```

### 5) Перевірте все наскрізно (рекомендовано)

```bash
npm run test:protocols:e2e
```

Цей набір перевіряє реальні потоки клієнтів MCP і A2A на запущену програму.

### Альтернатива: запустити з джерела

```bash
cp .env.example .env
npm install
PORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev
```

---

## 🐳 Докер

OmniRoute доступний як загальнодоступний образ Docker на [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).

**Швидкий біг:**

```bash
docker run -d \
  --name omniroute \
  --restart unless-stopped \
  -p 20128:20128 \
  -v omniroute-data:/app/data \
  diegosouzapw/omniroute:latest
```

**З файлом середовища:**

```bash
# Copy and edit .env first
cp .env.example .env

docker run -d \
  --name omniroute \
  --restart unless-stopped \
  --env-file .env \
  -p 20128:20128 \
  -v omniroute-data:/app/data \
  diegosouzapw/omniroute:latest
```

**Використання Docker Compose:**

```bash
# Base profile (no CLI tools)
docker compose --profile base up -d

# CLI profile (Claude Code, Codex, OpenClaw built-in)
docker compose --profile cli up -d
```

| Зображення               | Тег      | Розмір  | Опис                       |
| ------------------------ | -------- | ------- | -------------------------- |
| `diegosouzapw/omniroute` | `latest` | ~250 МБ | Останній стабільний випуск |
| `diegosouzapw/omniroute` | `1.0.3`  | ~250 МБ | Поточна версія             |

---

## 🖥️ Додаток для настільних ПК — офлайн і завжди ввімкнено

> 🆕 **НОВИНКА!** OmniRoute тепер доступний як **власна настільна програма** для Windows, macOS і Linux.

Запустіть OmniRoute як окрему настільну програму — для локальних моделей не потрібен ні термінал, ні браузер, ні Інтернет. Додаток на базі Electron включає:

- 🖥️ **Рідне вікно** — спеціальне вікно програми з інтеграцією в системний трей
- 🔄 **Автозапуск** — запустіть OmniRoute після входу в систему
- 🔔 **Власні сповіщення** — отримуйте сповіщення про вичерпання квоти або проблеми з постачальником
- ⚡ **Встановлення в один клік** — NSIS (Windows), DMG (macOS), AppImage (Linux)
- 🌐 **Офлайн-режим** — працює повністю в автономному режимі з доданим сервером

### Швидкий старт

```bash
# Development mode
npm run electron:dev

# Build for your platform
npm run electron:build         # Current platform
npm run electron:build:win     # Windows (.exe)
npm run electron:build:mac     # macOS (.dmg) — x64 & arm64
npm run electron:build:linux   # Linux (.AppImage)
```

### Системний трей

У згорнутому стані OmniRoute живе в панелі завдань із швидкими діями:

- Відкрити інформаційну панель
- Змінити порт сервера
- Вийти з програми

📖 Повна документація: [**OMNI_TOKEN_153**](electron/README.md)

---

## 💰 Огляд цін

| Рівень             | Постачальник                | Вартість                           | Скидання квоти                | Найкраще для                                |
| ------------------ | --------------------------- | ---------------------------------- | ----------------------------- | ------------------------------------------- |
| **💳 ПІДПИСКА**    | Клод Код (Pro)              | 20 доларів США на місяць           | 5 годин + щотижня             | Вже підписані                               |
|                    | Codex (Plus/Pro)            | $20-200/міс                        | 5 годин + щотижня             | Користувачі OpenAI                          |
|                    | Gemini CLI                  | **БЕЗКОШТОВНО**                    | 180 тис./місяць + 1 тис./день | всі!                                        |
|                    | Копілот GitHub              | $10-19/міс                         | Щомісяця                      | Користувачі GitHub                          |
| **🔑 КЛЮЧ API**    | NVIDIA NIM                  | **БЕЗКОШТОВНО** (dev forever)      | ~40 обертів за хвилину        | 70+ відкритих моделей                       |
|                    | Головний мозок              | **БЕЗКОШТОВНО** (1 млн ток/день)   | 60K TPM / 30 RPM              | Найшвидший у світі                          |
|                    | Groq                        | **БЕЗКОШТОВНО** (30 об/хв)         | 14.4K RPD                     | Надшвидкий Llama/Gemma                      |
|                    | DeepSeek V3.2               | 0,27 $/1,10 $ за 1 млн             | Жодного                       | Найкраща ціна/якість                        |
|                    | xAI Grok-4 Fast             | **$0,20/$0,50 за 1 млн** 🆕        | Жодного                       | Найшвидший + виклик інструменту, наднизький |
|                    | xAI Grok-4 (стандарт)       | 0,20 $/1,50 $ за 1 млн. 🆕         | Жодного                       | Розумний флагман від xAI                    |
|                    | Містраль                    | Безкоштовна пробна версія + платна | Оцінка обмежена               | Європейський ШІ                             |
|                    | OpenRouter                  | Оплата за використання             | Жодного                       | 100+ моделей агр.                           |
| **💰 ДЕШЕВО**      | GLM-5 (через Z.AI) 🆕       | 0,5 $/1 млн                        | Щодня о 10 ранку              | Вихід 128K, найновіший флагман              |
|                    | GLM-4.7                     | $0,6/1 млн                         | Щодня о 10 ранку              | Резервне копіювання бюджету                 |
|                    | MiniMax M2.5 🆕             | $0,3/1 млн вхідних даних           | 5-годинний роликовий          | Міркування + агентурні завдання             |
|                    | MiniMax M2.1                | $0,2/1 млн                         | 5-годинний роликовий          | Найдешевший варіант                         |
|                    | Kimi K2.5 (Moonshot API) 🆕 | Оплата за використання             | Жодного                       | Прямий доступ до Moonshot API               |
|                    | Кімі К2                     | 9 $/міс квартира                   | 10 млн токенів/міс            | Передбачувана вартість                      |
| **🆓 БЕЗКОШТОВНО** | iFlow                       | **$0**                             | Необмежений                   | 5 моделей без обмежень                      |
|                    | Квен                        | **$0**                             | Необмежений                   | 4 моделі без обмежень                       |
|                    | Кіро                        | **$0**                             | Необмежений                   | Клод Сонет/Хайку (AWS Builder)              |
|                    | LongCat Flash-Lite 🆕       | **$0** (50 млн ток/день 🔥)        | 1 RPS                         | Найбільша безкоштовна квота на Землі        |
|                    | Запилення AI 🆕             | **$0** (ключ не потрібен)          | 1 запит/15 с                  | GPT-5, Клод, DeepSeek, Лама 4               |
|                    | Cloudflare Workers AI 🆕    | **$0** (10 тис. нейронів/день)     | ~150 повторів/день            | 50+ моделей, глобальна перевага             |
|                    | Scaleway AI 🆕              | **$0** (усього 1 млн токенів)      | Оцінка обмежена               | ЄС/GDPR, Qwen3 235B, Llama 70B              |

> 🆕 **Додано нові моделі (березень 2026):** Сімейство Grok-4 Fast за $0,20/$0,50/M (тестування 1143 мс — на 30% швидше, ніж Gemini 2.5 Flash), GLM-5 через Z.AI із виведенням 128K, аргументація MiniMax M2.5, оновлена ціна DeepSeek V3.2, Kimi K2.5 через Moonshot direct API.

**💡 Комбінований стек за $0 — повне безкоштовне налаштування:**

```
# 🆓 Ultimate Free Stack 2026 — 11 Providers, $0 Forever
Kiro (kr/)             → Claude Sonnet/Haiku UNLIMITED
iFlow (if/)            → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED
LongCat Lite (lc/)     → LongCat-Flash-Lite — 50M tokens/day 🔥
Pollinations (pol/)    → GPT-5, Claude, DeepSeek, Llama 4 — no key needed
Qwen (qw/)             → qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED
Gemini (gemini/)       → Gemini 2.5 Flash — 1,500 req/day free API key
Cloudflare AI (cf/)    → Llama 70B, Gemma 3, Mistral — 10K Neurons/day
Scaleway (scw/)        → Qwen3 235B, Llama 70B — 1M free tokens (EU)
Groq (groq/)           → Llama/Gemma ultra-fast — 14.4K req/day
NVIDIA NIM (nvidia/)   → 70+ open models — 40 RPM forever
Cerebras (cerebras/)   → Llama/Qwen world-fastest — 1M tok/day
```

**Нульова вартість. Ніколи не припиняє кодування.** Налаштуйте це як одну комбінацію OmniRoute, і всі резервні варіанти відбуватимуться автоматично — жодного ручного перемикання.

---

---

## 🆓 Безкоштовні моделі — те, що ви насправді отримуєте

> Усі наведені нижче моделі **на 100% безкоштовні, кредитна картка не потрібна**. OmniRoute автоматично маршрутизує між ними, коли одна квота вичерпується — об’єднайте їх усі для непорушної комбінації 0 доларів США.

### 🔵 CLAUDE MODELS (через Kiro — ідентифікатор AWS Builder)

| Модель              | Префікс | Ліміт           | Обмеження швидкості                     |
| ------------------- | ------- | --------------- | --------------------------------------- |
| `claude-sonnet-4.5` | `kr/`   | **Необмежений** | Немає повідомлень про щоденне обмеження |
| `claude-haiku-4.5`  | `kr/`   | **Необмежений** | Немає повідомлень про щоденне обмеження |
| `claude-opus-4.6`   | `kr/`   | **Необмежений** | Останній Opus через Kiro                |

### 🟢 МОДЕЛІ IFLOW (безкоштовний OAuth — без кредитної картки)

| Модель             | Префікс | Ліміт           | Обмеження швидкості             |
| ------------------ | ------- | --------------- | ------------------------------- |
| `kimi-k2-thinking` | `if/`   | **Необмежений** | Немає повідомлень про обмеження |
| `qwen3-coder-plus` | `if/`   | **Необмежений** | Немає повідомлень про обмеження |
| `deepseek-r1`      | `if/`   | **Необмежений** | Немає повідомлень про обмеження |
| `minimax-m2.1`     | `if/`   | **Необмежений** | Немає повідомлень про обмеження |
| `kimi-k2`          | `if/`   | **Необмежений** | Немає повідомлень про обмеження |

### 🟡 МОДЕЛІ QWEN (автентифікація коду пристрою)

| Модель              | Префікс | Ліміт           | Обмеження швидкості             |
| ------------------- | ------- | --------------- | ------------------------------- |
| `qwen3-coder-plus`  | `qw/`   | **Необмежений** | Немає повідомлень про обмеження |
| `qwen3-coder-flash` | `qw/`   | **Необмежений** | Немає повідомлень про обмеження |
| `qwen3-coder-next`  | `qw/`   | **Необмежений** | Немає повідомлень про обмеження |
| `vision-model`      | `qw/`   | **Необмежений** | Мультимодальний (зображення)    |

### 🟣 GEMINI CLI (Google OAuth)

| Модель                   | Префікс | Ліміт                           | Обмеження швидкості |
| ------------------------ | ------- | ------------------------------- | ------------------- |
| `gemini-3-flash-preview` | `gc/`   | **180K ток/місяць** + 1K/день   | Щомісячне скидання  |
| `gemini-2.5-pro`         | `gc/`   | 180 тис./місяць (загальний пул) | Висока якість       |

### ⚫ NVIDIA NIM (безкоштовний ключ API — build.nvidia.com)

| Рівень            | Денний ліміт              | Обмеження швидкості | Примітки                                                            |
| ----------------- | ------------------------- | ------------------- | ------------------------------------------------------------------- |
| Безкоштовно (Dev) | Немає обмеження на маркер | **~40 об/хв**       | 70+ моделей; перехід на чисті обмеження ставок у середині 2025 року |

Популярні безкоштовні моделі: `moonshotai/kimi-k2.5` (Kimi K2.5), `z-ai/glm4.7` (GLM 4.7), `deepseek-ai/deepseek-v3.2` (DeepSeek V3.2), `nvidia/llama-3.3-70b-instruct`, `deepseek/deepseek-r1`

### ⚪ CEREBRAS (Безкоштовний ключ API — inference.cerebras.ai)

| Рівень      | Денний ліміт           | Обмеження швидкості | Примітки                                      |
| ----------- | ---------------------- | ------------------- | --------------------------------------------- |
| Безкоштовно | **1 млн токенів/день** | 60K TPM / 30 RPM    | Найшвидший у світі LLM висновок; скидає щодня |

Доступно безкоштовно: `llama-3.3-70b`, `llama-3.1-8b`, `deepseek-r1-distill-llama-70b`

### 🔴 GROQ (безкоштовний ключ API — console.groq.com)

| Рівень      | Денний ліміт      | Обмеження швидкості             | Примітки                                              |
| ----------- | ----------------- | ------------------------------- | ----------------------------------------------------- |
| Безкоштовно | **14,4 тис. RPD** | 30 обертів на хвилину на модель | Без кредитної картки; 429 на ліміті, не тарифікується |

Доступно безкоштовно: `llama-3.3-70b-versatile`, `gemma2-9b-it`, `mixtral-8x7b`, `whisper-large-v3`

### 🔴 LONGCAT AI (безкоштовний ключ API — longcat.chat) 🆕

| Модель                        | Префікс | Щоденна безкоштовна квота   | Примітки                              |
| ----------------------------- | ------- | --------------------------- | ------------------------------------- |
| `LongCat-Flash-Lite`          | `lc/`   | **50 мільйонів токенів** 💥 | Найбільша безкоштовна квота в історії |
| `LongCat-Flash-Chat`          | `lc/`   | 500 тисяч токенів           | Багатоповоротний чат                  |
| `LongCat-Flash-Thinking`      | `lc/`   | 500 тисяч токенів           | Міркування / CoT                      |
| `LongCat-Flash-Thinking-2601` | `lc/`   | 500 тисяч токенів           | Версія січня 2026                     |
| `LongCat-Flash-Omni-2603`     | `lc/`   | 500 тисяч токенів           | Мультимодальний                       |

> 100% безкоштовно під час публічної бета-версії. Зареєструйтеся на [longcat.chat](https://longcat.chat) за допомогою електронної пошти або телефону. Скидає щодня о 00:00 UTC.

### 🟢 POLLINATIONS AI (ключ API не потрібен) 🆕

| Модель     | Префікс | Обмеження швидкості | Постачальник за   |
| ---------- | ------- | ------------------- | ----------------- |
| `openai`   | `pol/`  | 1 запит/15 с        | ГПТ-5             |
| `claude`   | `pol/`  | 1 запит/15 с        | Антропний Клод    |
| `gemini`   | `pol/`  | 1 запит/15 с        | Google Gemini     |
| `deepseek` | `pol/`  | 1 запит/15 с        | DeepSeek V3       |
| `llama`    | `pol/`  | 1 запит/15 с        | Мета Лама 4 Скаут |
| `mistral`  | `pol/`  | 1 запит/15 с        | Містраль А. І.    |

> ✨ **Нульове тертя:** Без реєстрації, без ключа API. Додайте постачальника Pollinations із порожнім ключовим полем, і він запрацює негайно.

### 🟠 CLOUDFLARE WORKERS AI (безкоштовний ключ API — cloudflare.com) 🆕

| Рівень      | Щоденні нейрони | Еквівалентне використання                    | Примітки                 |
| ----------- | --------------- | -------------------------------------------- | ------------------------ |
| Безкоштовно | **10 000**      | ~150 LLM resp / 500 с аудіо / 15K вбудованих | Global edge, 50+ моделей |

Популярні безкоштовні моделі: `@cf/meta/llama-3.3-70b-instruct`, `@cf/google/gemma-3-12b-it`, `@cf/openai/whisper-large-v3-turbo` (безкоштовний звук!), `@cf/qwen/qwen2.5-coder-15b-instruct`

> Потрібен маркер API + ідентифікатор облікового запису з [dash.cloudflare.com](https://dash.cloudflare.com). Зберігайте ідентифікатор облікового запису в налаштуваннях провайдера.

### 🟣 SCALEWAY AI (1 млн безкоштовних токенів — scaleway.com) 🆕

| Рівень      | Безкоштовна квота | Розташування | Примітки                                      |
| ----------- | ----------------- | ------------ | --------------------------------------------- |
| Безкоштовно | **1 млн токенів** | 🇫🇷 Париж, ЄС | Кредитна картка не потрібна в рамках обмежень |

Доступно безкоштовно: `qwen3-235b-a22b-instruct-2507` (Qwen3 235B!), `llama-3.1-70b-instruct`, `mistral-small-3.2-24b-instruct-2506`, `deepseek-v3-0324`

> Відповідає вимогам ЄС/GDPR. Отримайте ключ API за адресою [console.scaleway.com](https://console.scaleway.com).

> **💡 Найкращий безкоштовний пакет (11 постачальників, 0 доларів назавжди):**
>
> ```
> Kiro (kr/)             → Claude Sonnet/Haiku UNLIMITED
> iFlow (if/)            → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED
> LongCat Lite (lc/)     → LongCat-Flash-Lite — 50M tokens/day 🔥
> Pollinations (pol/)    → GPT-5, Claude, DeepSeek, Llama 4 — no key needed
> Qwen (qw/)             → qwen3-coder models UNLIMITED
> Gemini (gemini/)       → Gemini 2.5 Flash — 1,500 req/day free
> Cloudflare AI (cf/)    → 50+ models — 10K Neurons/day
> Scaleway (scw/)        → Qwen3 235B, Llama 70B — 1M free tokens (EU)
> Groq (groq/)           → Llama/Gemma — 14.4K req/day ultra-fast
> NVIDIA NIM (nvidia/)   → 70+ open models — 40 RPM forever
> Cerebras (cerebras/)   → Llama/Qwen world-fastest — 1M tok/day
> ```

## 🎙️ Комбінація безкоштовних транскрипцій

> Транскрибуйте будь-яке аудіо/відео за **$0** — Deepgram лідирує з $200 безкоштовно, AssemblyAI $50 резервний варіант, Groq Whisper як необмежену екстрену резервну копію.

| Постачальник      | Безкоштовні кредити               | Краща модель                                                     | Обмеження швидкості                        |
| ----------------- | --------------------------------- | ---------------------------------------------------------------- | ------------------------------------------ |
| 🟢 **Deepgram**   | **$200 безкоштовно** (реєстрація) | `nova-3` — найкраща точність, 30+ мов                            | Немає ліміту RPM для безкоштовних кредитів |
| 🔵 **AssemblyAI** | **$50 безкоштовно** (реєстрація)  | `universal-3-pro` — розділи, почуття, ідентифікаційна інформація | Немає ліміту RPM для безкоштовних кредитів |
| 🔴 **Groq**       | **Безкоштовно назавжди**          | `whisper-large-v3` — OpenAI Whisper                              | 30 обертів за хвилину (швидкість обмежена) |

**Запропонований комбо в `/dashboard/combos`:**

```
Name: free-transcription
Strategy: Priority
Nodes:
  [1] deepgram/nova-3          → uses $200 free first
  [2] assemblyai/universal-3-pro → fallback when Deepgram credits run out
  [3] groq/whisper-large-v3    → free forever, emergency fallback
```

Потім у `/dashboard/media` → вкладка **Транскрипція**: завантажте будь-який аудіо- чи відеофайл → виберіть комбіновану кінцеву точку → отримайте транскрипцію в підтримуваних форматах.

## 💡 Основні характеристики

OmniRoute v2.0 створено як операційну платформу, а не просто проксі-ретранслятор.

### 🆕 Нове — покращення, натхненні ClawRouter (березень 2026 р.)

| Особливість                                   | Що він робить                                                                                                      |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| ⚡ **Грок-4 Швидка Сімейка**                  | моделі xAI за $0,20/$0,50/М — тестування 1143 мс (на 30% швидше, ніж Gemini 2.5 Flash)                             |
| 🧠 **GLM-5 через Z.AI**                       | Контекст виводу 128K, $0,5/1M — найновіший флагман із сімейства GLM                                                |
| 🔮 **MiniMax M2.5**                           | Розуміння + агентські завдання за $0,30/1 млн — значне оновлення з M2.1                                            |
| 🎯 **Прапор виклику інструментів для моделі** | Для кожної моделі `toolCalling: true/false` в реєстрі — AutoCombo пропускає моделі, які не підтримують інструменти |
| 🌍 **Виявлення багатомовного наміру**         | Ключові слова PT/ZH/ES/AR у балах AutoCombo — кращий вибір моделі для вмісту не англійською мовою                  |
| 📊 **Резервні тести**                         | Справжня затримка p95 від живих запитів, комбінованих каналів — AutoCombo вивчає фактичні дані                     |
| 🔁 **Надіслати запит на дедуплікацію**        | Вікно дедуплювання на основі хешу вмісту — мультиагентний захист, запобігає повторюваним стягненням                |
| 🔌 **Pluggable RouterStrategy**               | Розширюваний інтерфейс `RouterStrategy` — додайте спеціальну логіку маршрутизації як плагіни                       |

### 🚀 Попередня версія 2.0.9+ — Playground, CLI Fingerprints & ACP

| Особливість                                        | Що він робить                                                                                                                                                                                                                                                                                                         |
| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 🎮 **Модельний майданчик**                         | Сторінка інформаційної панелі для безпосереднього тестування будь-якої моделі — селектори провайдера/моделі/кінцевої точки, редактор Monaco, потокове передавання, припинення, час                                                                                                                                    |
| 🔏 **Зіставлення відбитків пальців CLI**           | Упорядкування заголовків/тіла для кожного постачальника відповідно до власних підписів CLI — перемикайте для кожного постачальника в меню «Налаштування» > «Безпека». **IP-адресу вашого проксі-сервера збережено**                                                                                                   |
| 🤝 **Підтримка ACP (протокол клієнта агента)**     | Виявлення агента CLI (Codex, Claude, Goose, Gemini CLI, OpenClaw + ще 9), створення процесів, кінцева точка `/api/acp/agents`                                                                                                                                                                                         |
| 🤖 **Інформаційна панель агентів ACP**             | Налагодження › Сторінка агентів — таблиця з 14 агентів із статусом встановлення, версією, користувацькою формою агента для будь-якого інструменту CLI. Користувачі **OpenCode** отримують кнопку «Завантажити opencode.json», яка автоматично генерує готову до використання конфігурацію для всіх доступних моделей. |
| 🔧 **Спеціальна модель `apiFormat` Маршрутизація** | Спеціальні моделі з `apiFormat: "responses"` тепер правильно направляють до перекладача Responses API                                                                                                                                                                                                                 |
| 🏢 **Ізоляція робочої області Codex**              | Кілька робочих областей Codex на електронну пошту — OAuth правильно розділяє підключення за ідентифікатором робочої області                                                                                                                                                                                           |
| 🔄 **Електронне автоматичне оновлення**            | Додаток для комп’ютера перевіряє наявність оновлень + автоматичне встановлення після перезавантаження                                                                                                                                                                                                                 |

### 🤖 Операції агента та протоколу (версія 2.0)

| Особливість                                   | Що він робить                                                                                               |
| --------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| 🔧 **MCP Server (16 інструментів)**           | Інструменти IDE/агента через 3 транспорти: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`) |
| 🤝 **Сервер A2A (JSON-RPC + SSE)**            | Виконання завдань між агентами із синхронізацією та потоковими потоками                                     |
| 🧭 **Консолідована сторінка кінцевих точок**  | Сторінка керування вкладками з вкладками Endpoint Proxy, MCP, A2A та API Endpoints                          |
| 🎚️ **Перемикачі ввімкнення/вимкнення служби** | Перемикачі ON/OFF для MCP та A2A зі збереженням налаштувань (за замовчуванням: OFF)                         |
| 🛰️ **MCP Runtime Heartbeat**                  | Справжній статус процесу (pid, безвідмовна робота, вік серцевого ритму, транспорт, режим обсягу)            |
| 📋 **Аудит MCP**                              | Фільтрувані журнали аудиту з успіхом/невдачею та ключовими атрибутами                                       |
| 🔐 **Застосування обсягу MCP**                | 9 детальних дозволів для контрольованого доступу до інструментів                                            |
| 📡 **Керування життєвим циклом завдань A2A**  | Список/фільтр завдань, перевірка подій/артефактів, скасування запущених завдань                             |
| 📋 **Виявлення картки агента**                | `/.well-known/agent.json` для автоматичного виявлення клієнта                                               |
| 🧪 **Тестовий джгут протоколу E2E**           | Real MCP SDK + A2A client flows in `test:protocols:e2e`                                                     |
| ⚙️ **Операційний контроль**                   | Комбінація перемикачів, застосування профілів стійкості, скидання вимикачів з однієї контрольної поверхні   |

### 🧠 Маршрутизація та інтелект

| Особливість                                        | Що він робить                                                                    |
| -------------------------------------------------- | -------------------------------------------------------------------------------- |
| 🎯 **Розумний 4-рівневий резервний варіант**       | Авто-маршрут: Підписка → Ключ API → Дешево → Безкоштовно                         |
| 📊 **Відстеження квот у реальному часі**           | Підрахунок живих токенів + скидання зворотного відліку для кожного постачальника |
| 🔄 **Формат перекладу**                            | OpenAI ↔ Claude ↔ Gemini ↔ Відповіді з перетвореннями, безпечними для схеми      |
| 👥 **Підтримка кількох облікових записів**         | Кілька облікових записів на постачальника з інтелектуальним вибором              |
| 🔄 **Автоматичне оновлення токенів**               | Маркери OAuth оновлюються автоматично з повторною спробою                        |
| 🎨 **Користувацькі комбо**                         | 6 стратегій балансування + резервне керування ланцюгом                           |
| 🌐 **Wildcard Router**                             | `provider/*` динамічна маршрутизація                                             |
| 🧠 **Думаючи контролювати бюджет**                 | Наскрізні, автоматичні, користувальницькі та адаптивні межі міркування           |
| 🔀 **Псевдоніми моделей**                          | Вбудована + спеціальна модель псевдонімів і безпека міграції                     |
| ⚡ **Погіршення фону**                             | Направляйте низькопріоритетні фонові завдання на дешевші моделі                  |
| 🧪 **Розумна маршрутизація з урахуванням завдань** | Автовибір моделі за типом вмісту (кодування/бачення/аналіз/узагальнення)         |
| 💬 **Швидке впровадження системи**                 | Послідовне застосування глобальних засобів контролю поведінки                    |
| 📄 **Сумісність API відповідей**                   | Повна підтримка `/v1/responses` Codex і розширених агентських робочих процесів   |

### 🎵 Мультимодальні API

| Особливість                        | Що він робить                                                                                                                                                                      |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 🖼️ **Створення зображень**         | `/v1/images/generations` з хмарою та локальним сервером                                                                                                                            |
| 📐 **Вбудовування**                | `/v1/embeddings` для конвеєрів пошуку та RAG                                                                                                                                       |
| 🎤 **Транскрипція аудіо**          | `/v1/audio/transcriptions` — 7 провайдерів (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), автоматичне визначення мови, підтримка MP4/MP3/WAV |
| 🔊 **Створення тексту в мовлення** | `/v1/audio/speech` — 10 провайдерів (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) з правильними повідомленнями про помилки   |
| 🎬 **Створення відео**             | `/v1/videos/generations` (робочі процеси ComfyUI + SD WebUI)                                                                                                                       |
| 🎵 **Музичне покоління**           | `/v1/music/generations` (робочі процеси ComfyUI)                                                                                                                                   |
| 🛡️ **Модерації**                   | `/v1/moderations` перевірки безпеки                                                                                                                                                |
| 🔀 **Переранжування**              | `/v1/rerank` для підрахунку релевантності                                                                                                                                          |
| 🔍 **Веб-пошук** 🆕                | `/v1/search` — 5 провайдерів (Serper, Brave, Perplexity, Exa, Tavily), 6500+ безкоштовних/місяць, автоматичне переключення, кеш                                                    |

### 🛡️ Стійкість, безпека та управління

| Особливість                                | Що він робить                                                                                            |
| ------------------------------------------ | -------------------------------------------------------------------------------------------------------- |
| 🔌 **Автоматичні вимикачі**                | Відключення/відновлення для кожної моделі з контролем порогових значень                                  |
| 🎯 **Моделі з урахуванням кінцевих точок** | Спеціальні моделі декларують підтримувані кінцеві точки + формат API                                     |
| 🛡️ **Anti-Thundering Herd**                | Mutex + захист семафора від подій повторних спроб/швидкості                                              |
| 🧠 **Семантика + кеш підпису**             | Зниження вартості/затримки за допомогою двох рівнів кешу                                                 |
| ⚡ **Запит на ідемпотентність**            | Дублікат вікна захисту                                                                                   |
| 🔒 **Підробка відбитків пальців TLS**      | Браузерний відбиток TLS — **зменшує виявлення ботів і позначення облікових записів**                     |
| 🔏 **Зіставлення відбитків пальців CLI**   | Відповідає власним підписам запиту CLI — **зменшує ризик заборони, зберігаючи IP-адресу проксі-сервера** |
| 🌐 **IP-фільтрація**                       | Керування білим/чорним списком для відкритих розгортань                                                  |
| 📊 **Редаговані ліміти ставок**            | Конфігуровані глобальні обмеження/ліміти на рівні постачальника з постійністю                            |
| 🔑 **API Key Management + Scoping**        | Безпечна видача/ротація ключів і засоби керування моделлю/постачальником                                 |
| 👁️ **Scoped API Key Reveal** 🆕            | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL`                                                   |
| 🛡️ **Захищено `/models`**                  | Додаткова автентифікація та приховування постачальника для каталогу моделей                              |

### 📊 Спостережливість і аналітика

| Особливість                                | Що він робить                                                       |
| ------------------------------------------ | ------------------------------------------------------------------- |
| 📝 **Запит + реєстрація проксі**           | Повний журнал запитів/відповідей і проксі                           |
| 📉 **Streamed Detailed Logs** 🆕           | Reconstructs SSE payload streams cleanly into the UI                |
| 📋 **Інформаційна панель єдиних журналів** | Перегляди запитів, проксі, аудиту та консолі на одній сторінці      |
| 🔍 **Надіслати запит на телеметрію**       | p50/p95/p99 затримка та відстеження запитів                         |
| 🏥 **Інформаційна панель здоров’я**        | Час роботи, стани поломки, блокування, статистика кешу              |
| 💰 **Відстеження витрат**                  | Контроль бюджету та видимість ціноутворення для кожної моделі       |
| 📈 **Аналітичні візуалізації**             | Статистика використання моделі/постачальника та перегляди тенденцій |
| 🧪 **Рамка оцінювання**                    | Тестування золотого набору з конфігурованими стратегіями матчу      |

### ☁️ Розгортання та платформа

| Особливість                                 | Що він робить                                                                  |
| ------------------------------------------- | ------------------------------------------------------------------------------ |
| 🌐 **Розгортайте будь-де**                  | Localhost, VPS, Docker, хмарні середовища                                      |
| 💾 **Хмарна синхронізація**                 | Синхронізація конфігурації через Cloud Worker                                  |
| 🔄 **Резервне копіювання/відновлення**      | Потоки експорту/імпорту та аварійного відновлення                              |
| 🧙 **Майстер адаптації**                    | Кероване налаштування під час першого запуску                                  |
| 🔧 **Інформаційна панель інструментів CLI** | Налаштування в один клік для популярних інструментів кодування                 |
| 🎮 **Модельний майданчик**                  | Перевірте будь-якого постачальника/модель/кінцеву точку з інформаційної панелі |
| 🔏 **Перемикач відбитків пальців CLI**      | Зіставлення відбитків пальців кожного постачальника в Налаштуваннях > Безпека  |
| 🌐 **i18n (30 мов)**                        | Повна інформаційна панель + підтримка мови документів із покриттям RTL         |
| 🧹 **Очистити всі моделі**                  | Очищення списку моделей одним натисканням у деталях провайдера                 |
| 👁️ **Sidebar Controls** 🆕                  | Hide components and integrations from Appearance Settings                      |
| 📋 **Шаблони проблем**                      | Стандартизовані шаблони GitHub для помилок і функцій                           |
| 📂 **Каталог користувацьких даних**         | `DATA_DIR` замінити місце зберігання                                           |

### Функція Deep Dive

#### Розумний резерв із практичним контролем витрат

```txt
Combo: "my-coding-stack"
  1. cc/claude-opus-4-6
  2. nvidia/llama-3.3-70b
  3. glm/glm-4.7
  4. if/kimi-k2-thinking
```

Якщо квота, швидкість або працездатність вичерпуються, OmniRoute автоматично переходить до наступного кандидата без перемикання вручну.

#### Керування протоколом, яке є видимим і доступним для роботи

- MCP + A2A можна знайти в інтерфейсі користувача та документах (не приховано)
- API статусу протоколу надають поточні робочі дані (`/api/mcp/*`, `/api/a2a/*`)
- Інформаційні панелі включають дії для операцій другого дня (комбіновані перемикачі, скидання вимикача, скасування завдання)

#### Перекладач + процес перевірки

Область перекладача включає:

- **Playground**: вимагати перевірки трансформації
- **Chat Tester**: повний запит/відповідь туди й назад
- **Test Bench**: кілька випадків за один запуск
- **Live Monitor**: перегляд заторів у реальному часі

Плюс перевірка протоколу з реальними клієнтами через `npm run test:protocols:e2e`.

> 📖 **[MCP Server README](open-sse/mcp-server/README.md)** — довідка про інструмент, конфігурації IDE та приклади клієнтів
>
> 📖 **[A2A Server README](src/lib/a2a/README.md)** — Навички, методи JSON-RPC, потокове передавання та життєвий цикл завдань

## 🧪 Оцінки (Evals)

OmniRoute містить вбудовану систему оцінювання для перевірки якості відповіді LLM на відповідність золотому набору. Доступ до нього через **Аналітика → Оцінки** на інформаційній панелі.

### Вбудований Золотий набір

Попередньо завантажений «Золотий набір OmniRoute» містить тестові випадки для:

- Привітання, математика, географія, генерація коду
- Відповідність формату JSON, переклад, генерація уцінки
- Відмова безпеки (шкідливий контент), підрахунок, булева логіка

### Стратегії оцінювання

| Стратегія  | Опис                                                           | Приклад                          |
| ---------- | -------------------------------------------------------------- | -------------------------------- |
| `exact`    | Вихідні дані повинні точно відповідати                         | `"4"`                            |
| `contains` | Вихідні дані повинні містити підрядок (незалежно від регістру) | `"Paris"`                        |
| `regex`    | Вихідні дані мають відповідати шаблону регулярного виразу      | `"1.*2.*3"`                      |
| `custom`   | Спеціальна функція JS повертає true/false                      | `(output) => output.length > 10` |

---

## 📖 Посібник із налаштування

### Налаштування протоколу (MCP + A2A)

<details>
<summary><b>🧩 Налаштування MCP (протокол контексту моделі)</b></summary>

Запустіть транспорт MCP у режимі stdio:

```bash
omniroute --mcp
```

Рекомендований процес перевірки:

1. Підключіть клієнт MCP через stdio.
2. Запустіть `omniroute_get_health`.
3. Запустіть `omniroute_list_combos`.
4. Відкрийте `/dashboard/mcp`, щоб підтвердити серцебиття, активність і аудит.

Корисні API для автоматизації:

- `GET /api/mcp/status`
- `GET /api/mcp/tools`
- `GET /api/mcp/audit`
- `GET /api/mcp/audit/stats`

</details>

<details>
<summary><b>🤝 Налаштування A2A (Agent2Agent)</b></summary>

Відкрийте агента:

```bash
curl http://localhost:20128/.well-known/agent.json
```

Надіслати завдання:

```bash
curl -X POST http://localhost:20128/a2a \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":"setup-a2a","method":"message/send","params":{"skill":"quota-management","messages":[{"role":"user","content":"Summarize quota status."}]}}'
```

Керувати життєвим циклом:

- `GET /api/a2a/status`
- `GET /api/a2a/tasks`
- `GET /api/a2a/tasks/:id`
- `POST /api/a2a/tasks/:id/cancel`

Операційний інтерфейс користувача:

- `/dashboard/a2a` для спостереження за завданням/станом/потоком і димових дій

</details>

<details>
<summary><b>🧪 Наскрізна перевірка протоколу</b></summary>

Перевірте обидва протоколи реальними клієнтами:

```bash
npm run test:protocols:e2e
```

Це підтверджує:

- Підключення клієнта MCP SDK/список/виклик
- Відкриття A2A/надсилання/потік/отримання/скасування
- Перехресна перевірка даних в аудиті MCP та API керування завданнями A2A

</details>

<details>
<summary><b>💳 Постачальники підписки</b></summary>

### Claude Code (Pro/Max)

```bash
Dashboard → Providers → Connect Claude Code
→ OAuth login → Auto token refresh
→ 5-hour + weekly quota tracking

Models:
  cc/claude-opus-4-6
  cc/claude-sonnet-4-5-20250929
  cc/claude-haiku-4-5-20251001
```

**Професійна порада:** використовуйте Opus для складних завдань, Sonnet для швидкості. OmniRoute відстежує квоту на модель!

### OpenAI Codex (Plus/Pro)

```bash
Dashboard → Providers → Connect Codex
→ OAuth login (port 1455)
→ 5-hour + weekly reset

Models:
  cx/gpt-5.2-codex
  cx/gpt-5.1-codex-max
```

#### Управління лімітами облікового запису Codex (5 годин + щотижня)

Кожен обліковий запис Codex тепер має параметри політики в `Dashboard -> Providers`:

- `5h` (УВІМК./ВИМК.): застосувати політику порогового значення 5-годинного вікна.
- `Weekly` (УВІМК./ВИМК.): застосовувати політику тижневого порогового значення вікна.
- Порогова поведінка: коли ввімкнене вікно досягає >=90% використання, цей обліковий запис пропускається.
- Поведінка ротації: OmniRoute автоматично направляє до наступного відповідного облікового запису Codex.
- Поведінка скидання: коли постачальник `resetAt` мине час, обліковий запис автоматично знову стає придатним.

Сценарії:

- `5h ON` + `Weekly ON`: обліковий запис пропускається, коли будь-яке вікно досягає порогового значення.
- `5h OFF` + `Weekly ON`: лише щотижневе використання може заблокувати обліковий запис.
- `5h ON` + `Weekly OFF`: обліковий запис можна заблокувати лише протягом 5 годин використання.
- `resetAt` пройдено: обліковий запис автоматично повертається до ротації (без повторного ввімкнення вручну).

### Gemini CLI (БЕЗКОШТОВНО 180K/місяць!)

```bash
Dashboard → Providers → Connect Gemini CLI
→ Google OAuth
→ 180K completions/month + 1K/day

Models:
  gc/gemini-3-flash-preview
  gc/gemini-2.5-pro
```

**Найкраще:** Величезний безкоштовний рівень! Використовуйте це перед платними рівнями.

### Копілот GitHub

```bash
Dashboard → Providers → Connect GitHub
→ OAuth via GitHub
→ Monthly reset (1st of month)

Models:
  gh/gpt-5
  gh/claude-4.5-sonnet
  gh/gemini-3-pro
```

</details>

<details>
<summary><b>🔑 Постачальники ключів API</b></summary>

### NVIDIA NIM (БЕЗКОШТОВНИЙ доступ розробника — 70+ моделей)

1. Зареєструйтеся: [build.nvidia.com](https://build.nvidia.com)
2. Отримайте безкоштовний ключ API (1000 кредитів включено)
3. Інформаційна панель → Додати постачальника → NVIDIA NIM:
   - Ключ API: `nvapi-your-key`

**Моделі:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct` та понад 50 інших

**Порада професіонала:** OpenAI-сумісний API — бездоганно працює з перекладом формату OmniRoute!

### DeepSeek

1. Зареєструйтеся: [platform.deepseek.com](https://platform.deepseek.com)
2. Отримайте ключ API
3. Інформаційна панель → Додати постачальника → DeepSeek

**Моделі:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder`

### Groq (доступний безкоштовний рівень!)

1. Зареєструйтесь: [console.groq.com](https://console.groq.com)
2. Отримайте ключ API (включає безкоштовний рівень)
3. Інформаційна панель → Додати постачальника → Groq

**Моделі:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b`

**Професійна порада:** Надшвидкий висновок — найкращий для кодування в реальному часі!

### OpenRouter (100+ моделей)

1. Зареєструйтеся: [openrouter.ai](https://openrouter.ai)
2. Отримайте ключ API
3. Інформаційна панель → Додати провайдера → OpenRouter

**Моделі:** Отримуйте доступ до понад 100 моделей від усіх основних постачальників за допомогою єдиного ключа API.

</details>

<details>
<summary><b>💰 Дешеві постачальники (резервні)</b></summary>

### GLM-4.7 (щоденне скидання, $0,6/1 млн)

1. Зареєструйтеся: [Zhipu AI](https://open.bigmodel.cn/)
2. Отримайте ключ API від Coding Plan
3. Інформаційна панель → Додати ключ API:
   - Постачальник: `glm`
   - Ключ API: `your-key`

**Використання:** `glm/glm-4.7`

**Професійна порада:** План кодування пропонує 3x квоту за 1/7 вартості! Скидання щодня о 10:00.

### MiniMax M2.1 (5 годин скидання, $0,20/1 млн)

1. Зареєструйтеся: [MiniMax](https://www.minimax.io/)
2. Отримайте ключ API
3. Інформаційна панель → Додати ключ API

**Використання:** `minimax/MiniMax-M2.1`

**Порада:** Найдешевший варіант для довгого контексту (1 млн токенів)!

### Kimi K2 ($9/місяць)

1. Підпишіться: [Moonshot AI](https://platform.moonshot.ai/)
2. Отримайте ключ API
3. Інформаційна панель → Додати ключ API

**Використання:** `kimi/kimi-latest`

**Професійна порада:** Фіксовані 9 доларів США на місяць за 10 мільйонів токенів = 0,90 доларів США за 1 млн. ефективних витрат!

</details>

<details>
<summary><b>🆓 БЕЗКОШТОВНІ постачальники (аварійне резервне копіювання)</b></summary>

### iFlow (5 БЕЗКОШТОВНИХ моделей через OAuth)

```bash
Dashboard → Connect iFlow
→ iFlow OAuth login
→ Unlimited usage

Models:
  if/kimi-k2-thinking
  if/qwen3-coder-plus
  if/glm-4.7
  if/minimax-m2
  if/deepseek-r1
```

### Qwen (4 БЕЗКОШТОВНІ моделі через код пристрою)

```bash
Dashboard → Connect Qwen
→ Device code authorization
→ Unlimited usage

Models:
  qw/qwen3-coder-plus
  qw/qwen3-coder-flash
```

### Кіро (Клод БЕЗКОШТОВНО)

```bash
Dashboard → Connect Kiro
→ AWS Builder ID or Google/GitHub
→ Unlimited usage

Models:
  kr/claude-sonnet-4.5
  kr/claude-haiku-4.5
```

</details>

<details>
<summary><b>🎨 Створення комбо</b></summary>

### Приклад 1: максимізація підписки → дешеве резервне копіювання

```
Dashboard → Combos → Create New

Name: premium-coding
Models:
  1. cc/claude-opus-4-6 (Subscription primary)
  2. glm/glm-4.7 (Cheap backup, $0.6/1M)
  3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)

Use in CLI: premium-coding
```

### Приклад 2: лише безкоштовно (нульова вартість)

```
Name: free-combo
Models:
  1. gc/gemini-3-flash-preview (180K free/month)
  2. if/kimi-k2-thinking (unlimited)
  3. qw/qwen3-coder-plus (unlimited)

Cost: $0 forever!
```

</details>

<details>
<summary><b>🔧 Інтеграція CLI</b></summary>

### Курсор IDE

```
Settings → Models → Advanced:
  OpenAI API Base URL: http://localhost:20128/v1
  OpenAI API Key: [from OmniRoute dashboard]
  Model: cc/claude-opus-4-6
```

### Клод Код

Використовуйте сторінку **Інструменти CLI** на інформаційній панелі для налаштування одним клацанням миші або редагуйте `~/.claude/settings.json` вручну.

### Codex CLI

```bash
export OPENAI_BASE_URL="http://localhost:20128"
export OPENAI_API_KEY="your-omniroute-api-key"

codex "your prompt"
```

### OpenClaw

**Варіант 1 — Інформаційна панель (рекомендовано):**

```
Dashboard → CLI Tools → OpenClaw → Select Model → Apply
```

**Варіант 2 — вручну:** Редагувати `~/.openclaw/openclaw.json`:

```json
{
  "models": {
    "providers": {
      "omniroute": {
        "baseUrl": "http://127.0.0.1:20128/v1",
        "apiKey": "sk_omniroute",
        "api": "openai-completions"
      }
    }
  }
}
```

> **Примітка:** OpenClaw працює лише з локальним OmniRoute. Щоб уникнути проблем із вирішенням IPv6, використовуйте `127.0.0.1` замість `localhost`.

### Cline / Продовжити / RooCode

```
Settings → API Configuration:
  Provider: OpenAI Compatible
  Base URL: http://localhost:20128/v1
  API Key: [from OmniRoute dashboard]
  Model: if/kimi-k2-thinking
```

### OpenCode

**Крок 1:** Додайте OmniRoute як спеціального постачальника:

```bash
opencode
/connect
# Select "Other" → Enter ID: "omniroute" → Enter your OmniRoute API key
```

**Крок 2:** Створіть/відредагуйте `opencode.json` в корені вашого проекту:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "omniroute": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "OmniRoute",
      "options": {
        "baseURL": "http://localhost:20128/v1"
      },
      "models": {
        "cc/claude-sonnet-4-20250514": { "name": "Claude Sonnet 4" },
        "gg/gemini-2.5-pro": { "name": "Gemini 2.5 Pro" },
        "if/kimi-k2-thinking": { "name": "Kimi K2 (Free)" }
      }
    }
  }
}
```

**Крок 3:** Виберіть модель у OpenCode:

```bash
/models
# Select any OmniRoute model from the list
```

> **Порада.** Додайте будь-яку модель, доступну в кінцевій точці OmniRoute `/v1/models`, до розділу `models`. Використовуйте формат `provider/model-id` на інформаційній панелі OmniRoute.

</details>

---

## 🐛 Усунення несправностей

<details>
<summary><b>Натисніть, щоб розгорнути посібник з усунення несправностей</b></summary>

**"Мовна модель не надавала повідомлень"**

- Квота постачальника вичерпана → Перевірте систему відстеження квот на інформаційній панелі
- Рішення: скористайтеся комбінованим альтернативним варіантом або перейдіть на дешевший рівень

**Обмеження швидкості**

— Вичерпана квота на підписку → Повернення до GLM/MiniMax

- Додати комбо: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`

**Термін дії маркера OAuth минув**

— Автоматично оновлено OmniRoute

- Якщо проблеми не зникають: Інформаційна панель → Постачальник → Повторне підключення

**Високі витрати**

- Перевірте статистику використання в Інформаційній панелі → Витрати
- Переключіть основну модель на GLM/MiniMax
- Використовуйте безкоштовний рівень (Gemini CLI, iFlow) для некритичних завдань

**Порти приладової панелі/API неправильні**

- `PORT` є канонічним базовим портом (і портом API за замовчуванням)
- `API_PORT` перевизначає лише сумісний із OpenAI слухач API
- `DASHBOARD_PORT` замінює лише інформаційну панель/прослуховувач Next.js
- Установіть `NEXT_PUBLIC_BASE_URL` на свою інформаційну панель/загальнодоступну URL-адресу (для зворотних викликів OAuth)

**Помилки хмарної синхронізації**

- Переконайтеся, що `BASE_URL` вказує на ваш запущений екземпляр
- Перевірте `CLOUD_URL` вказує на очікувану кінцеву точку хмари
- Зберігайте значення `NEXT_PUBLIC_*` у відповідності зі значеннями на стороні сервера

**Перший вхід не працює**

- Перевірте `INITIAL_PASSWORD` в `.env`
- Якщо не встановлено, резервний пароль `123456`

**Немає журналів запитів**

- Установіть `ENABLE_REQUEST_LOGS=true` в `.env`

**Тест з’єднання показує «Недійсне» для OpenAI-сумісних постачальників**

- Багато постачальників не розкривають кінцеву точку `/models`
- OmniRoute v1.0.6+ включає резервну перевірку через завершення чату
- Переконайтеся, що базова URL-адреса містить суфікс `/v1`

### 🔐 OAuth на віддаленому сервері

<a name="oauth-on-a-remote-server"></a>
<a name="oauth-em-servidor-remoto"></a>

> **⚠️ Важливо для користувачів, які використовують OmniRoute на VPS, Docker або будь-якому віддаленому сервері**

#### Чому Antigravity / Gemini CLI OAuth не працює на віддалених серверах?

Постачальники **Antigravity** і **Gemini CLI** використовують **Google OAuth 2.0**. Google вимагає, щоб `redirect_uri` у потоці OAuth точно відповідав одному з попередньо зареєстрованих URI у Google Cloud Console програми.

Облікові дані OAuth, включені в OmniRoute, зареєстровані **лише для `localhost`**. Коли ви отримуєте доступ до OmniRoute на віддаленому сервері (наприклад, `https://omniroute.myserver.com`), Google відхиляє автентифікацію за допомогою:

```
Error 400: redirect_uri_mismatch
```

#### Рішення: налаштуйте власні облікові дані OAuth

Вам потрібно створити **Ідентифікатор клієнта OAuth 2.0** у Google Cloud Console з URI вашого сервера.

#### Крок за кроком

**1. Відкрийте Google Cloud Console**

Перейти до: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)

**2. Створіть новий ідентифікатор клієнта OAuth 2.0**

- Натисніть **"+ Створити облікові дані"** → **"Ідентифікатор клієнта OAuth"**
- Тип програми: **"Веб-програма"**
- Ім'я: будь-яке, що вам подобається (наприклад, `OmniRoute Remote`)

**3. Додати авторизовані URI перенаправлення**

У полі **"Авторизовані URI перенаправлення"** додайте:

```
https://your-server.com/callback
```

> Замініть `your-server.com` доменом або IP-адресою вашого сервера (за необхідності вкажіть порт, наприклад `http://45.33.32.156:20128/callback`).

**4. Збережіть і скопіюйте облікові дані**

Після створення Google покаже **Ідентифікатор клієнта** та **Секрет клієнта**.

**5. Встановити змінні середовища**

У вашому `.env` (або змінних середовища Docker):

```bash
# For Antigravity:
ANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com
ANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret

# For Gemini CLI:
GEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com
GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret
GEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret
```

**6. Перезапустіть OmniRoute**

```bash
# npm:
npm run dev

# Docker:
docker restart omniroute
```

**7. Спробуйте підключитися знову**

Інформаційна панель → Постачальники → Antigravity (або Gemini CLI) → OAuth

Тепер Google правильно переспрямовуватиме на `https://your-server.com/callback`.

---

#### Тимчасовий обхідний шлях (без спеціальних облікових даних)

Якщо ви не хочете налаштовувати власні облікові дані прямо зараз, ви можете скористатися **ручним потоком URL-адреси**:

1. OmniRoute відкриває URL-адресу авторизації Google
2. Після авторизації Google намагається переспрямувати на `localhost` (це не вдається на віддаленому сервері)
3. **Скопіюйте повну URL-адресу** з адресного рядка браузера (навіть якщо сторінка не завантажується)
4. Вставте цю URL-адресу в поле, що відображається в режимі підключення OmniRoute
5. Натисніть **"Підключити"**

> Це працює, оскільки код авторизації в URL-адресі дійсний незалежно від того, чи завантажено сторінку переспрямування.

---

<details>
<summary><b>🇧🇷 Versão em Português</b></summary>

#### Чи OAuth для Antigravity / Gemini CLI не підтримує віддалені сервери?

Провідники **Antigravity** і **Gemini CLI** використовують **Google OAuth 2.0** для автентифікації. Google вимагає, щоб `redirect_uri` не використовував fluxo OAuth, який **exatamente** має URI перед кадастрадами без Google Cloud Console у програмі.

Оскільки повноваження OAuth embutidas не OmniRoute estão cadastradas **apenas para `localhost`**. Якщо ви маєте доступ до OmniRoute у віддаленому сервері (наприклад: `https://omniroute.meuservidor.com`), або Google rejeita a autenticação com:

```
Error 400: redirect_uri_mismatch
```

#### Рішення: налаштуйте власні облікові записи OAuth

Потрібно точно написати **Ідентифікатор клієнта OAuth 2.0** у Google Cloud Console через URI вашого сервера.

#### Passo a passo

**1. Доступ до Google Cloud Console**

Abra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)

**2. Crie um novo OAuth 2.0 ID клієнта**

- Натисніть **"+ Створити облікові дані"** → **"Ідентифікатор клієнта OAuth"**
- Tipo de aplicativo: **"Веб-програма"**
- Назва: escolha qualquer nome (наприклад: `OmniRoute Remote`)

**3. Додайте як авторизовані URI перенаправлення**

Без поля **"Авторизовані URI перенаправлення"**, додайте:

```
https://seu-servidor.com/callback
```

> Замініть `seu-servidor.com` домен або IP на свій сервер (включно з необхідним портом, наприклад: `http://45.33.32.156:20128/callback`).

**4. Зберегти електронну копію як ідентифікацію**

Наприклад, Google показує **Ідентифікатор клієнта** і **Секрет клієнта**.

**5. Налаштувати як variáveis de ambiente**

Немає `.env` (або наших варіантів середовища Docker):

```bash
# Para Antigravity:
ANTIGRAVITY_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com
ANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret

# Para Gemini CLI:
GEMINI_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com
GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret
GEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret
```

**6. Reinicie o OmniRoute**

```bash
# Se usando npm:
npm run dev

# Se usando Docker:
docker restart omniroute
```

**7. Tente conectar novamente**

Інформаційна панель → Постачальники → Антигравітація (або Gemini CLI) → OAuth

Agora o Google redirecionará corretamente para `https://seu-servidor.com/callback` e a authenticação funcionará.

---

#### Тимчасове вирішення проблеми (необхідне налаштування повноважень)

Se não quiser criar credenciais próprias agora, ainda é possível usar o fluxo **manual de URL**:

1. OmniRoute скидає URL-адресу авторизації Google
2. Якщо ви авторизуєтеся, або перенаправлення даних Google для `localhost` (це неможливість віддаленого сервера)
3. **Скопіюйте повну URL-адресу** для переходу до вашого браузера (повідомте, що сторінка не створена)
4. Cole essa URL no campo que aparece no modal de conexão do OmniRoute
5. Натисніть **"Підключитися"**

> Este workaround funciona porque o código de autorização na URL é válido independente do redirect ter carregado ou não.

</details>

---

</details>

## 🛠️ Tech Stack

<details>
<summary><b>Натисніть, щоб розгорнути деталі технічного стеку</b></summary>

- **Серед виконання**: Node.js 18–22 LTS (⚠️ Node.js 24+ **не підтримується** — рідні двійкові файли `better-sqlite3` несумісні)
- **Мова**: TypeScript 5.9 — **100% TypeScript** для `src/` та `open-sse/` (нуль `any` в основних модулях, починаючи з версії 2.0)
- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4
- **База даних**: LowDB (JSON) + SQLite (стан домену + журнали проксі + аудит MCP + рішення про маршрутизацію)
- **Схеми**: Zod (перевірка введення/виведення інструменту MCP, контракти API)
- **Протоколи**: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)
- **Потокове передавання**: події, надіслані сервером (SSE)
- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys + MCP Scoped Authorization
- **Тестування**: програма для виконання тестів Node.js + Vitest (900+ тестів, включаючи блоки, інтеграцію, E2E)
- **CI/CD**: дії GitHub (автоматична публікація npm + Docker Hub після випуску)
- **Веб-сайт**: [omniroute.online](https://omniroute.online)
- **Пакет**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)
- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)
- **Стійкість**: автоматичний вимикач, експоненціальна віддача, захист від гриму, підробка TLS, автоматичне самовідновлення комбо

</details>

---

## 📖 Документація

| Документ                                       | Опис                                                                       |
| ---------------------------------------------- | -------------------------------------------------------------------------- |
| [User Guide](docs/USER_GUIDE.md)               | Постачальники, комбо, інтеграція CLI, розгортання                          |
| [API Reference](docs/API_REFERENCE.md)         | Усі кінцеві точки з прикладами                                             |
| [MCP Server](open-sse/mcp-server/README.md)    | 16 інструментів MCP, конфігурації IDE, клієнти Python/TS/Go                |
| [A2A Server](src/lib/a2a/README.md)            | Протокол JSON-RPC 2.0, навички, потокове передавання, керування завданнями |
| [Auto-Combo Engine](docs/auto-combo.md)        | 6-факторна оцінка, пакети режимів, самовідновлення                         |
| [Troubleshooting](docs/TROUBLESHOOTING.md)     | Загальні проблеми та рішення                                               |
| [Architecture](docs/ARCHITECTURE.md)           | Архітектура системи та внутрішні                                           |
| [Contributing](CONTRIBUTING.md)                | Розробка установки та рекомендацій                                         |
| [OpenAPI Spec](docs/openapi.yaml)              | Специфікація OpenAPI 3.0                                                   |
| [Security Policy](SECURITY.md)                 | Повідомлення про вразливості та методи безпеки                             |
| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md)   | Повний посібник: налаштування VM + nginx + Cloudflare                      |
| [Features Gallery](docs/FEATURES.md)           | Огляд інформаційної панелі зі знімками екрана                              |
| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Етапи перевірки перед випуском                                             |

---

## 🗺️ Дорожня карта

OmniRoute має **заплановано понад 210 функцій** на кількох етапах розробки. Ось ключові області:

| Категорія                        | Заплановані особливості | Основні моменти                                                                                                           |
| -------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| 🧠 **Маршрутизація та інтелект** | 25+                     | Маршрутизація з найменшою затримкою, маршрутизація на основі тегів, попередній перегляд квот, вибір облікового запису P2C |
| 🔒 **Безпека та відповідність**  | 20+                     | Захист SSRF, маскування облікових даних, обмеження швидкості для кінцевої точки, визначення обсягу ключа керування        |
| 📊 **Спостережливість**          | 15+                     | Інтеграція OpenTelemetry, моніторинг квот у реальному часі, відстеження витрат на модель                                  |
| 🔄 **Інтеграція постачальників** | 20+                     | Реєстр динамічної моделі, час відновлення провайдера, Codex із кількома обліковими записами, розбір квоти Copilot         |
| ⚡ **Виконання**                 | 15+                     | Подвійний рівень кешу, кеш запитів, кеш відповідей, потокове підтримання активності, пакетний API                         |
| 🌐 **Екосистема**                | 10+                     | API WebSocket, гаряче перезавантаження конфігурації, розподілене сховище конфігурацій, комерційний режим                  |

### 🔜 Незабаром

- 🔗 **Інтеграція OpenCode** — власна підтримка постачальника для IDE кодування OpenCode AI
- 🔗 **Інтеграція TRAE** — повна підтримка інфраструктури розробки TRAE AI
- 📦 **Batch API** — асинхронна пакетна обробка масових запитів
- 🎯 **Маршрутизація на основі тегів** — Маршрутизація запитів на основі спеціальних тегів і метаданих
- 💰 **Стратегія найнижчої вартості** — автоматично вибирайте найдешевшого доступного постачальника

> 📝 Повні специфікації функцій доступні в [**OMNI_TOKEN_342**](docs/new-features/) (217 детальних специфікацій)

---

## 👥 Автори

[![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)

### Як зробити внесок

1. Розгалужте репозиторій
2. Створіть свою гілку функцій (`git checkout -b feature/amazing-feature`)
3. Зафіксуйте свої зміни (`git commit -m 'Add amazing feature'`)
4. Push до відділення (`git push origin feature/amazing-feature`)
5. Відкрийте Pull Request

Див. [CONTRIBUTING.md](CONTRIBUTING.md), щоб отримати докладні вказівки.

### Випуск нової версії

```bash
# Create a release — npm publish happens automatically
gh release create v2.0.0 --title "v2.0.0" --generate-notes
```

---

## 📊 Зоряна історія

## Звіздарі з часом

## [![Stargazers over time](https://starchart.cc/diegosouzapw/OmniRoute.svg?variant=adaptive)](https://starchart.cc/diegosouzapw/OmniRoute)

## 🙏 Подяка

Особлива подяка **[9router](https://github.com/decolua/9router)** від **[decolua](https://github.com/decolua)** — оригінального проекту, який надихнув цей форк. OmniRoute спирається на цю неймовірну основу завдяки додатковим функціям, мультимодальним API і повному перепису TypeScript.

Особлива подяка **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — оригінальній реалізації Go, яка надихнула цей порт JavaScript.

---

## 📄 Ліцензія

Ліцензія Массачусетського технологічного інституту – подробиці див. [LICENSE](LICENSE).

---

<div align="center">
  <sub>Створено з ❤️ для розробників, які працюють у режимі 24/7</sub>
  <br/>
  <sub><a href="https://omniroute.online">omniroute.online</a></sub>
</div>
<!-- Обговорення GitHub увімкнено для запитань і відповідей спільноти -->
