<div align="center">
  <img src="./docs/screenshots/MainOmniRoute.png" alt="OmniRoute Dashboard" width="800"/>
  
  # 🚀 OmniRoute — Бесплатный AI Gateway

### Никогда не прекращайте программировать. Умная маршрутизация к **БЕСПЛАТНЫМ и дешёвым AI-моделям** с автоматическим fallback.

_Ваш универсальный API-прокси — одна точка доступа, 36+ провайдеров, нулевой простой._

**Chat Completions • Embeddings • Генерация изображений • Аудио • Reranking • 100% TypeScript**

---

### 🚀 New in v2.0.9+ — Playground, CLI Fingerprints & ACP

| Feature                                    | What It Does                                                                                                                                  |
| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| 🎮 **Model Playground**                    | Dashboard page to test any model directly — provider/model/endpoint selectors, Monaco Editor, streaming, abort, timing                        |
| 🔏 **CLI Fingerprint Matching**            | Per-provider header/body ordering to match native CLI signatures — toggle per provider in Settings > Security. **Your proxy IP is preserved** |
| 🤝 **ACP Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw), process spawner, `/api/acp/agents` endpoint                                 |
| 🤖 **ACP Agents Dashboard**                | Debug > Agents page — grid of 14 agents with install status, version, custom agent form for any CLI tool                                      |
| 🔧 **Custom Model `apiFormat` Routing**    | Custom models with `apiFormat: "responses"` now correctly route to the Responses API translator                                               |
| 🏢 **Codex Workspace Isolation**           | Multiple Codex workspaces per email — OAuth correctly separates connections by workspace ID                                                   |
| 🔄 **Electron Auto-Update**                | Desktop app checks for updates + auto-install on restart                                                                                      |

### 🤖 Бесплатный AI-провайдер для ваших любимых агентов программирования

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

  <table>
    <tr>
      <td align="center" width="110">
        <a href="https://github.com/cline/cline">
          <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>

---

[![npm version](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](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)
[![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)

[🌐 Сайт](https://omniroute.online) • [🚀 Быстрый старт](#-быстрый-старт) • [💡 Функции](#-основные-функции) • [📖 Документация](#-документация) • [💰 Цены](#-обзор-цен)

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

</div>

---

## 🖼️

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

---

## 📸

<details>
<summary><b>...</b></summary>

| #     | #                                        |
| ----- | ---------------------------------------- |
| **1** | ![1](docs/screenshots/01-providers.png)  |
| **2** | ![2](docs/screenshots/02-combos.png)     |
| **3** | ![3](docs/screenshots/03-analytics.png)  |
| **4** | ![4](docs/screenshots/04-health.png)     |
| **5** | ![5](docs/screenshots/05-translator.png) |
| **6** | ![6](docs/screenshots/06-settings.png)   |
| **7** | ![7](docs/screenshots/07-cli-tools.png)  |
| **8** | ![8](docs/screenshots/08-usage.png)      |
| **9** | ![9](docs/screenshots/09-endpoint.png)   |

</details>

---

## 🤔 Почему 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 решает это:**

- ✅ **Максимизируйте подписки** — Отслеживайте квоты, используйте всё до сброса
- ✅ **Автоматический fallback** — Подписка → API Key → Дешёвый → Бесплатный, нулевой простой
- ✅ **Мульти-аккаунт** — Round-robin между аккаунтами каждого провайдера
- ✅ **Универсальный** — Работает с Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, любым CLI-инструментом

---

## 📧 Поддержка

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

- **Сайт**: [omniroute.online](https://omniroute.online)
- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
- **WhatsApp**: [Группа сообщества](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
- **Оригинальный проект**: [9router от decolua](https://github.com/decolua/9router)

---

## 🔄 Как это работает

```
┌─────────────┐
│  Ваш CLI    │  (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)
│   Tool      │
└──────┬──────┘
       │ http://localhost:20128/v1
       ↓
┌─────────────────────────────────────────┐
│        OmniRoute (Умный маршрутизатор)   │
│  • Трансляция формата (OpenAI ↔ Claude) │
│  • Отслеживание квот + Embeddings + Изображения │
│  • Автообновление токенов               │
└──────┬──────────────────────────────────┘
       │
       ├─→ [Tier 1: ПОДПИСКА] Claude Code, Codex, Gemini CLI
       │   ↓ квота исчерпана
       ├─→ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM и др.
       │   ↓ лимит бюджета
       ├─→ [Tier 3: ДЕШЁВЫЙ] GLM ($0.6/1M), MiniMax ($0.2/1M)
       │   ↓ лимит бюджета
       └─→ [Tier 4: БЕСПЛАТНЫЙ] iFlow, Qwen, Kiro (неограниченно)

Результат: Никогда не прекращайте программировать, минимальные затраты
```

---

## 🎯 Что решает OmniRoute — 30 реальных проблем и вариантов использования

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

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

Разработчики платят 20–200 долларов в месяц за Claude Pro, Codex Pro или GitHub Copilot. Даже при оплате квота имеет потолок — 5 часов использования, еженедельные лимиты или поминутные ограничения. В середине сеанса кодирования провайдер перестает отвечать, и разработчик теряет поток и производительность.

**Как OmniRoute решает эту проблему:**

- **Умный 4-уровневый резерв** — если квота подписки исчерпана, происходит автоматическое перенаправление на API-ключ → Дешево → Бесплатно без вмешательства вручную.
- **Отслеживание квот в реальном времени** — показывает потребление токенов в режиме реального времени с обратным отсчетом сброса (5 часов, ежедневно, еженедельно).
- **Поддержка нескольких учетных записей** — Несколько учетных записей у каждого провайдера с автоматическим циклическим перебором — когда один из них заканчивается, переключается на следующий
- **Пользовательские комбинации** — Настраиваемые резервные цепочки с 6 стратегиями балансировки (сначала заполняемые, циклический, P2C, случайные, наименее используемые, с оптимизацией затрат)
- **Бизнес-квоты Кодекса** — мониторинг квот рабочего пространства для бизнеса/команды непосредственно на панели управления.

</details>

<details>
<summary><b>🔌 2. «Мне нужно использовать несколько поставщиков, но у каждого свой API» </b></summary>

OpenAI использует один формат, Claude (Anthropic) — другой, Gemini — третий. Если разработчик хочет протестировать модели от разных поставщиков или использовать резервный вариант между ними, ему необходимо перенастроить SDK, изменить конечные точки, разобраться с несовместимыми форматами. Пользовательские поставщики (FriendLI, NIM) имеют нестандартные конечные точки модели.

**Как OmniRoute решает эту проблему:**

- **Единая конечная точка** — один `http://localhost:20128/v1` служит прокси для всех 36+ провайдеров.
- **Перевод формата** — Автоматический и прозрачный: OpenAI ↔ Claude ↔ Gemini ↔ API ответов
- **Очистка ответов** — удаляются нестандартные поля (`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 в SDK Python/Rust/Go.

</details>

<details>
<summary><b>🌐 3. «Мой провайдер ИИ блокирует мой регион/страну» </b></summary>

Такие провайдеры, как OpenAI/Codex, блокируют доступ из определенных географических регионов. Пользователи получают ошибки типа `unsupported_country_region_territory` во время подключений OAuth и API. Особенно это расстраивает разработчиков из развивающихся стран.

**Как OmniRoute решает эту проблему:**

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

</details>

<details>
<summary><b>🆓 4. «Я хочу использовать ИИ для кодирования, но у меня нет денег» </b></summary>

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

**Как OmniRoute решает эту проблему:**

- **Встроенные провайдеры уровня бесплатного пользования** — Встроенная поддержка 100% бесплатных провайдеров: iFlow (8 моделей с неограниченным количеством пользователей), Qwen (3 модели с неограниченным количеством пользователей), Kiro (Claude бесплатно), Gemini CLI (180 тысяч в месяц бесплатно).
- **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` with free "Light usage" tier; use `ollamacloud/<model>` prefix
- **Комбинации только бесплатно** — цепочка `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = 0 долларов США в месяц без простоев.
- **Бесплатные кредиты NVIDIA NIM** — интегрировано 1000 бесплатных кредитов.
- **Стратегия оптимизации затрат** — стратегия маршрутизации, которая автоматически выбирает самого дешевого доступного провайдера.

</details>

<details>
<summary><b>🔒 5. «Мне нужно защитить мой AI-шлюз от несанкционированного доступа» </b></summary>

При предоставлении доступа к сети AI-шлюза (LAN, VPS, Docker) любой, у кого есть адрес, может использовать токены/квоту разработчика. Без защиты API уязвимы для неправильного использования, быстрого внедрения и злоупотреблений.

**Как OmniRoute решает эту проблему:**

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

</details>

<details>
<summary><b>🛑 6. «Мой провайдер вышел из строя, и я потерял процесс кодирования» </b></summary>

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

**Как OmniRoute решает эту проблему:**

- **Выключатель для каждого поставщика** — автоматическое открытие/закрытие с настраиваемыми пороговыми значениями и временем восстановления (закрыто/открыто/полуоткрыто).
- **Экспоненциальная задержка** – прогрессивная задержка повторных попыток.
- **Anti-Thundering Herd** — Мьютекс + защита семафора от одновременных штормов повторных попыток.
- **Комбо-резервные цепочки** — в случае сбоя основного поставщика автоматически проходит через цепочку без вмешательства.
- **Комбо-выключатель** — автоматически отключает неисправных поставщиков в комбинированной цепочке.
- **Панель работоспособности** — мониторинг работоспособности, состояния автоматических выключателей, блокировки, статистика кэша, задержка 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** — генерирует `chatLanguageModels.json` для кода VS с массовым выбором модели.
- **Мастер адаптации** — пошаговая пошаговая настройка для начинающих пользователей.
- **Одна конечная точка, все модели** — настройте `http://localhost:20128/v1` один раз и получите доступ к более чем 36 поставщикам услуг.

</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 решает эту проблему:**

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

</details>

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

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

**Как OmniRoute решает эту проблему:**

- **Панель анализа затрат** — отслеживание затрат на каждый токен и управление бюджетом для каждого поставщика.
- **Ограничения бюджета на уровень** — потолок расходов на уровень, который запускает автоматический возврат к резервному варианту.
- **Конфигурация цен на модель** — настраиваемые цены на модель.
- **Статистика использования каждого ключа API** — количество запросов и временная метка последнего использования для каждого ключа.
- **Панель аналитики** — карточки статистики, диаграмма использования модели, таблица поставщиков с показателями успеха и задержкой.

</details>

<details>
<summary><b>🐛 10. «Я не могу диагностировать ошибки и проблемы в вызовах ИИ» </b></summary>

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

**Как OmniRoute решает эту проблему:**

- **Панель управления унифицированными журналами** — 4 вкладки: журналы запросов, журналы прокси, журналы аудита, консоль.
- **Консольный просмотр журнала** — просмотрщик в режиме терминала в режиме реального времени с уровнями с цветовой кодировкой, автоматической прокруткой, поиском и фильтрацией.
- **Журналы прокси-сервера SQLite** — постоянные журналы, сохраняющиеся после перезапуска сервера.
- **Площадка переводчика** — 4 режима отладки: Площадка (перевод формата), Тестер чата (туда и обратно), Тестовый стенд (пакетный), Мониторинг в реальном времени (в режиме реального времени).
- **Запрос телеметрии** — задержка p50/p95/p99 + отслеживание X-Request-Id
- **Журналирование на основе файлов с ротацией** — перехватчик консоли записывает все в журнал JSON с ротацией на основе размера.

</details>

<details>
<summary><b>🏗️ 11. «Развертывание и обслуживание шлюза сложны» </b></summary>

Установка, настройка и обслуживание прокси-сервера AI в различных средах (локальных, VPS, Docker, облаке) — трудоемкий процесс. Такие проблемы, как жестко запрограммированные пути, `EACCES` в каталогах, конфликты портов и кроссплатформенные сборки, добавляют проблем.

**Как OmniRoute решает эту проблему:**

- **глобальная установка npm** — `npm install -g omniroute && omniroute` — выполнено
- **Мультиплатформенность Docker** — встроенная версия AMD64 + ARM64 (Apple Silicon, AWS Graviton, Raspberry Pi)
- **Профили Docker Compose** — `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, Antigradity, 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` — Изменение ранжирования релевантности документа.
- **API ответов** — полная поддержка `/v1/responses` для Кодекса.

</details>

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

Разработчики хотят знать, какая модель лучше всего подходит для их варианта использования (код, перевод, рассуждения), но сравнивать вручную — это медленно. Интегрированных инструментов оценки не существует.

**Как OmniRoute решает эту проблему:**

- **Оценки LLM** — тестирование золотого набора с 10 предварительно загруженными вариантами, охватывающими приветствия, математику, географию, генерацию кода, соответствие JSON, перевод, уценку, отказ от безопасности.
- **4 стратегии сопоставления** — `exact`, `contains`, `regex`, `custom` (функция JS)
- **Тестовый стенд Translator Playground** — пакетное тестирование с несколькими входными данными и ожидаемыми результатами, сравнение между поставщиками.
- **Тестер чата** — полный цикл с визуальным отображением ответов.
- **Живой монитор** — поток всех запросов, проходящих через прокси, в реальном времени.

</details>

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

По мере роста объема запросов без кэширования одних и тех же вопросов возникают дублирующие затраты. Без идемпотентности дублирование запросов приводит к отходам обработки. Необходимо соблюдать ограничения по тарифам для каждого поставщика.

**Как OmniRoute решает эту проблему:**

- **Семантический кеш** — двухуровневый кеш (сигнатура + семантика) снижает стоимость и задержку.
- **Request Idempotency** — окно дедупликации 5 с для идентичных запросов.
- **Обнаружение ограничения скорости** — число оборотов в минуту для каждого провайдера, минимальный разрыв и максимальное одновременное отслеживание.
- **Редактируемые ограничения скорости** — настраиваемые значения по умолчанию в меню «Настройки» → «Устойчивость с постоянством».
- **Кэш проверки ключей API** — трехуровневый кеш для повышения производительности.
- **Панель состояния с телеметрией** — задержка p50/p95/p99, статистика кэша, время безотказной работы.

</details>

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

Разработчики, которым нужны все ответы на определенном языке, с определенным тоном или которые хотят ограничить количество токенов рассуждения. Настраивать это в каждом инструменте/запросе непрактично.

**Как OmniRoute решает эту проблему:**

- **Внедрение системных подсказок** — глобальное приглашение применяется ко всем запросам.
- **Продуманная проверка бюджета** — контроль распределения токенов для каждого запроса (сквозной, автоматический, пользовательский, адаптивный)
- **6 стратегий маршрутизации** — глобальные стратегии, определяющие распределение запросов.
- **Маршрутизатор с подстановочными знаками** — шаблоны `provider/*` динамически маршрутизируются к любому поставщику.
- **Переключение/включение комбо** — переключение комбо непосредственно с панели управления.
- **Переключение поставщика** — включение/отключение всех подключений к провайдеру одним щелчком мыши.
- **Заблокированные поставщики** — исключить определенных поставщиков из списка `/v1/models`.

</details>

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

Многие шлюзы AI предоставляют 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.
- Вкладка «Протоколы» на странице конечной точки с быстрым запуском и статусом.
- Ссылки из обзора на специальные панели управления.

</details>

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

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

**Как OmniRoute решает эту проблему:**

- Пакет E2E, который загружает приложение и использует настоящий клиентский транспорт MCP SDK.
- Клиент A2A тестирует потоки обнаружения, отправки, потоковой передачи, получения и отмены.
- Перекрестная проверка утверждений с помощью API-интерфейсов аудита MCP и задач 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>

### Примеры сборников сценариев (интегрированные варианты использования)

**Пособие А: максимальное использование платной подписки + дешевое резервное копирование**

```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
```

**Пособие Б: стек кодирования с нулевой стоимостью**

```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
```

**Пособие 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
```

**Сборник 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/mcp and /dashboard/a2a
4) Control incidents with resilience profile + task cancellation
```

---

## ⚡ Быстрый старт

**1. Установите глобально:**

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

🎉 Dashboard открывается на `http://localhost:20128`

| Команда                 | Описание                                   |
| ----------------------- | ------------------------------------------ |
| `omniroute`             | Запустить сервер (порт по умолчанию 20128) |
| `omniroute --port 3000` | Использовать другой порт                   |
| `omniroute --no-open`   | Не открывать браузер автоматически         |
| `omniroute --help`      | Показать справку                           |

**2. Подключите БЕСПЛАТНОГО провайдера:**

Dashboard → Провайдеры → Подключить **Claude Code** или **Antigravity** → OAuth вход → Готово!

**3. Используйте в CLI-инструменте:**

```
Claude Code/Codex/Gemini CLI/OpenClaw/Cursor/Cline Настройки:
  Endpoint: http://localhost:20128/v1
  API Key: [скопируйте из dashboard]
  Model: if/kimi-k2-thinking
```

**Готово!** Начните программировать с БЕСПЛАТНЫМИ AI-моделями.

**Альтернатива — запуск из исходного кода:**

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

---

## 🐳 Docker

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
# Скопируйте и отредактируйте .env
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
# Базовый профиль (без CLI-инструментов)
docker compose --profile base up -d

# CLI-профиль (Claude Code, Codex, OpenClaw встроены)
docker compose --profile cli up -d
```

| Образ                    | Тег      | Размер | Описание                   |
| ------------------------ | -------- | ------ | -------------------------- |
| `diegosouzapw/omniroute` | `latest` | ~250MB | Последний стабильный релиз |
| `diegosouzapw/omniroute` | `1.0.6`  | ~250MB | Текущая версия             |

---

---

## 🖥️

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

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

```bash
npm run electron:dev           # Режим разработки
npm run electron:build         # Текущая платформа
npm run electron:build:win     # Windows (.exe)
npm run electron:build:mac     # macOS (.dmg)
npm run electron:build:linux   # Linux (.AppImage)
```

📖 Полная документация: [`electron/README.md`](electron/README.md)

---

## 💰 Обзор цен

| Tier              | Провайдер         | Стоимость                     | Сброс квоты        | Лучше всего для                  |
| ----------------- | ----------------- | ----------------------------- | ------------------ | -------------------------------- |
| **💳 ПОДПИСКА**   | Claude Code (Pro) | $20/мес                       | 5ч + еженедельно   | Уже подписан                     |
|                   | Codex (Plus/Pro)  | $20-200/мес                   | 5ч + еженедельно   | Пользователи OpenAI              |
|                   | Gemini CLI        | **БЕСПЛАТНО**                 | 180K/мес + 1K/день | Все!                             |
|                   | GitHub Copilot    | $10-19/мес                    | Ежемесячно         | Пользователи GitHub              |
| **🔑 API KEY**    | NVIDIA NIM        | **БЕСПЛАТНО** (1000 кредитов) | Одноразово         | Бесплатное тестирование          |
|                   | DeepSeek          | По использованию              | Нет                | Лучшее соотношение цена/качество |
|                   | Groq              | Беспл. уровень + платный      | Ограничено         | Сверхбыстрый вывод               |
|                   | xAI (Grok)        | По использованию              | Нет                | Модели Grok                      |
|                   | Mistral           | Беспл. уровень + платный      | Ограничено         | Европейский AI                   |
|                   | OpenRouter        | По использованию              | Нет                | 100+ моделей                     |
| **💰 ДЕШЁВЫЙ**    | GLM-4.7           | $0.6/1M                       | Ежедневно 10ч      | Бюджетный бэкап                  |
|                   | MiniMax M2.1      | $0.2/1M                       | 5ч ротация         | Самый дешёвый вариант            |
|                   | Kimi K2           | $9/мес фикс                   | 10M токенов/мес    | Предсказуемая цена               |
| **🆓 БЕСПЛАТНЫЙ** | iFlow             | $0                            | Неограниченно      | 8 бесплатных моделей             |
|                   | Qwen              | $0                            | Неограниченно      | 3 бесплатные модели              |
|                   | Kiro              | $0                            | Неограниченно      | Claude бесплатно                 |

**💡 Совет:** Начните с Gemini CLI (180K бесплатно/мес) + iFlow (неограниченно бесплатно) = $0!

---

## 💡 Основные функции

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

| Функция                                     | Что делает                                                                    |
| ------------------------------------------- | ----------------------------------------------------------------------------- |
| 🎯 **Умный 4-уровневый Fallback**           | Авто-маршрутизация: Подписка → API Key → Дешёвый → Бесплатный                 |
| 📊 **Отслеживание квот в реальном времени** | Счётчик токенов в реальном времени + обратный отсчёт до сброса                |
| 🔄 **Трансляция формата**                   | OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro бесшовно                             |
| 👥 **Мульти-аккаунт**                       | Несколько аккаунтов на провайдера с интеллектуальным выбором                  |
| 🔄 **Автообновление токенов**               | OAuth-токены обновляются автоматически с повторами                            |
| 🎨 **Пользовательские комбо**               | 6 стратегий: fill-first, round-robin, p2c, random, least-used, cost-optimized |
| 🧩 **Пользовательские модели**              | Добавьте любой ID модели к любому провайдеру                                  |
| 🌐 **Wildcard-маршрутизатор**               | Маршрутизируйте паттерны `provider/*` к любому провайдеру динамически         |
| 🧠 **Бюджет рассуждений**                   | Режимы passthrough, auto, custom и adaptive для моделей рассуждений           |
| 🔀 **Model Aliases**                        | Auto-forward deprecated model IDs to current replacements (built-in + custom) |
| ⚡ **Background Degradation**               | Auto-route background tasks (titles, summaries) to cheaper models             |
| 💬 **Инъекция System Prompt**               | Глобальный system prompt для всех запросов                                    |
| 📄 **API Responses**                        | Полная поддержка OpenAI Responses API (`/v1/responses`) для Codex             |

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

| Функция                      | Что делает                                          |
| ---------------------------- | --------------------------------------------------- |
| 🖼️ **Генерация изображений** | `/v1/images/generations` — 4 провайдера, 9+ моделей |
| 📐 **Embeddings**            | `/v1/embeddings` — 6 провайдеров, 9+ моделей        |
| 🎤 **Транскрипция аудио**    | `/v1/audio/transcriptions` — Совместимо с Whisper   |
| 🔊 **Текст в речь**          | `/v1/audio/speech` — Мульти-провайдерный синтез     |
| 🛡️ **Модерация**             | `/v1/moderations` — Проверки безопасности контента  |
| 🔀 **Reranking**             | `/v1/rerank` — Переранжирование релевантности       |

### 🛡️ Устойчивость и безопасность

| Функция                          | Что делает                                                                             |
| -------------------------------- | -------------------------------------------------------------------------------------- |
| 🔌 **Circuit Breaker**           | Авто-открытие/закрытие по провайдеру с настраиваемыми порогами                         |
| 🎯 **Endpoint-Aware Models**     | Custom models declare supported endpoints + API format                                 |
| 🛡️ **Anti-Thundering Herd**      | Mutex + семафор для API key провайдеров                                                |
| 🧠 **Семантический кеш**         | Двухуровневый кеш (сигнатура + семантика) снижает стоимость                            |
| ⚡ **Идемпотентность запросов**  | 5с окно дедупликации для дублирующихся запросов                                        |
| 🔒 **Спуфинг TLS Fingerprint**   | Обход обнаружения ботов через wreq-js                                                  |
| 🔏 **CLI Fingerprint Matching**  | Matches native CLI request signatures — **reduces ban risk while preserving proxy IP** |
| 🌐 **Фильтрация IP**             | Allowlist/blocklist для контроля доступа к API                                         |
| 📊 **Настраиваемые Rate Limits** | Настраиваемые RPM, минимальный интервал, макс. конкуррентность                         |
| 💾 **Rate Limit Persistence**    | Learned limits survive restarts via SQLite with 60s debounce + 24h staleness           |
| 🔄 **Token Refresh Resilience**  | Per-provider circuit breaker (5 fails→30min) + 30s timeout per attempt                 |

### 📊 Наблюдаемость и аналитика

| Функция                       | Что делает                                                               |
| ----------------------------- | ------------------------------------------------------------------------ |
| 📝 **Логи запросов**          | Режим debug с полными логами запросов/ответов                            |
| 💾 **Логи SQLite**            | Постоянные proxy-логи переживают перезапуски                             |
| 📊 **Dashboard аналитики**    | Recharts: карточки статистики, график использования, таблица провайдеров |
| 📈 **Отслеживание прогресса** | Opt-in SSE-события прогресса для стриминга                               |
| 🧪 **Оценки LLM**             | Тестирование с golden set и 4 стратегиями сравнения                      |
| 🔍 **Телеметрия запросов**    | Агрегация латентности p50/p95/p99 + трекинг X-Request-Id                 |
| 📋 **Логи + Квоты**           | Отдельные страницы для просмотра логов и отслеживания квот               |
| 🏥 **Dashboard здоровья**     | Uptime, состояния circuit breaker, блокировки, статистика кеша           |
| 💰 **Отслеживание стоимости** | Управление бюджетом + настройка цен по моделям                           |

### ☁️ Деплой и синхронизация

| Функция                    | Что делает                                                                  |
| -------------------------- | --------------------------------------------------------------------------- |
| 💾 **Cloud Sync**          | Синхронизация настроек между устройствами через Cloudflare Workers          |
| 🌐 **Деплой куда угодно**  | Localhost, VPS, Docker, Cloudflare Workers                                  |
| 🔑 **Управление API Keys** | Генерация, ротация и настройка scope API keys по провайдерам                |
| 🧙 **Мастер настройки**    | 4-шаговая настройка для новых пользователей                                 |
| 🔧 **Dashboard CLI Tools** | Настройка в один клик для Claude, Codex, Cline, OpenClaw, Kilo, Antigravity |
| 🔄 **Бэкапы БД**           | Автоматическое резервное копирование и восстановление всех настроек         |

<details>
<summary><b>📖 Подробности функций</b></summary>

### 🎯 Умный 4-уровневый Fallback

Создавайте комбо с автоматическим fallback:

```
Combo: "my-coding-stack"
  1. cc/claude-opus-4-6        (ваша подписка)
  2. nvidia/llama-3.3-70b      (бесплатный NVIDIA API)
  3. glm/glm-4.7               (дешёвый бэкап, $0.6/1M)
  4. if/kimi-k2-thinking       (бесплатный fallback)

→ Автоматически переключается при исчерпании квоты или ошибках
```

### 📊 Отслеживание квот в реальном времени

- Потребление токенов по провайдерам
- Обратный отсчёт до сброса (5 часов, ежедневно, еженедельно)
- Оценка стоимости для платных уровней
- Ежемесячные отчёты о расходах

### 🔄 Трансляция формата

Бесшовная трансляция между форматами:

- **OpenAI** ↔ **Claude** ↔ **Gemini** ↔ **OpenAI Responses**
- Ваш CLI отправляет формат OpenAI → OmniRoute транслирует → Провайдер получает нативный формат
- Работает с любым инструментом, поддерживающим пользовательские OpenAI endpoints

### 👥 Мульти-аккаунт

- Добавляйте несколько аккаунтов на провайдера
- Автоматический round-robin или маршрутизация по приоритету
- Fallback на следующий аккаунт при исчерпании квоты

### 🔄 Автообновление токенов

- OAuth-токены обновляются автоматически до истечения
- Без необходимости ручной повторной аутентификации
- Бесшовный опыт по всем провайдерам

### 🎨 Пользовательские комбо

- Создавайте неограниченные комбинации моделей
- 6 стратегий: fill-first, round-robin, power-of-two-choices, random, least-used, cost-optimized
- Делитесь комбо между устройствами с Cloud Sync

### 🏥 Dashboard здоровья

- Статус системы (uptime, версия, использование памяти)
- Состояния circuit breaker по провайдерам (Closed/Open/Half-Open)
- Статус rate limit и активные блокировки
- Статистика кеша сигнатур
- Телеметрия латентности (p50/p95/p99) + кеш промптов
- Сброс состояния здоровья одним кликом

### 🔧 Playground транслятора

- Отладка, тестирование и визуализация трансляции форматов API
- Отправляйте запросы и смотрите, как OmniRoute транслирует между форматами провайдеров
- Бесценно для устранения проблем интеграции

### 💾 Cloud Sync

- Синхронизация провайдеров, комбо и настроек между устройствами
- Автоматическая фоновая синхронизация
- Безопасное шифрованное хранилище

</details>

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

OmniRoute включает встроенный фреймворк оценки для тестирования качества ответов LLM по golden set. Доступ через **Analytics → Evals** в dashboard.

### Встроенный Set

Предзагруженный «OmniRoute Golden Set» содержит 10 тестов:

- Приветствия, математика, география, генерация кода
- Соответствие формату JSON, перевод, markdown
- Отказ от небезопасного контента, подсчёт, булева логика

### Стратегии оценки

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

---

## 📖 Руководство по настройке

<details>
<summary><b>💳 Провайдеры по подписке</b></summary>

### Claude Code (Pro/Max)

```bash
Dashboard → Провайдеры → Подключить Claude Code
→ OAuth вход → Автообновление токенов
→ Отслеживание квоты 5ч + еженедельно

Модели:
  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 → Провайдеры → Подключить Codex
→ OAuth вход (порт 1455)
→ Сброс 5ч + еженедельно

Модели:
  cx/gpt-5.2-codex
  cx/gpt-5.1-codex-max
```

### Gemini CLI (БЕСПЛАТНО 180K/мес!)

```bash
Dashboard → Провайдеры → Подключить Gemini CLI
→ Google OAuth
→ 180K completions/мес + 1K/день

Модели:
  gc/gemini-3-flash-preview
  gc/gemini-2.5-pro
```

**Лучшая ценность:** Огромный бесплатный уровень! Используйте перед платными.

### GitHub Copilot

```bash
Dashboard → Провайдеры → Подключить GitHub
→ OAuth через GitHub
→ Ежемесячный сброс (1-е число)

Модели:
  gh/gpt-5
  gh/claude-4.5-sonnet
  gh/gemini-3-pro
```

</details>

<details>
<summary><b>🔑 Провайдеры по API Key</b></summary>

### NVIDIA NIM (БЕСПЛАТНО 1000 кредитов!)

1. Регистрация: [build.nvidia.com](https://build.nvidia.com)
2. Получите бесплатный API key (1000 кредитов включены)
3. Dashboard → Добавить провайдера → NVIDIA NIM:
   - API Key: `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 key
3. Dashboard → Добавить провайдера → DeepSeek

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

### Groq (Бесплатный уровень доступен!)

1. Регистрация: [console.groq.com](https://console.groq.com)
2. Получите API key (бесплатный уровень включён)
3. Dashboard → Добавить провайдера → Groq

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

**Совет:** Сверхбыстрый вывод — лучший для программирования в реальном времени!

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

1. Регистрация: [openrouter.ai](https://openrouter.ai)
2. Получите API key
3. Dashboard → Добавить провайдера → OpenRouter

**Модели:** Доступ к 100+ моделям от всех основных провайдеров через один API key.

</details>

<details>
<summary><b>💰 Дешёвые провайдеры (Бэкап)</b></summary>

### GLM-4.7 (Ежедневный сброс, $0.6/1M)

1. Регистрация: [Zhipu AI](https://open.bigmodel.cn/)
2. Получите API key из Coding Plan
3. Dashboard → Добавить API Key:
   - Провайдер: `glm`
   - API Key: `your-key`

**Используйте:** `glm/glm-4.7`

**Совет:** Coding Plan предлагает 3× квоту по цене 1/7! Ежедневный сброс в 10:00.

### MiniMax M2.1 (Сброс 5ч, $0.20/1M)

1. Регистрация: [MiniMax](https://www.minimax.io/)
2. Получите API key
3. Dashboard → Добавить API Key

**Используйте:** `minimax/MiniMax-M2.1`

**Совет:** Самый дешёвый вариант для длинного контекста (1M токенов)!

### Kimi K2 ($9/мес фикс)

1. Подпишитесь: [Moonshot AI](https://platform.moonshot.ai/)
2. Получите API key
3. Dashboard → Добавить API Key

**Используйте:** `kimi/kimi-latest`

**Совет:** Фикс $9/мес за 10M токенов = $0.90/1M эффективная стоимость!

</details>

<details>
<summary><b>🆓 БЕСПЛАТНЫЕ провайдеры (Аварийный бэкап)</b></summary>

### iFlow (8 БЕСПЛАТНЫХ моделей)

```bash
Dashboard → Подключить iFlow
→ OAuth вход iFlow
→ Неограниченное использование

Модели:
  if/kimi-k2-thinking
  if/qwen3-coder-plus
  if/glm-4.7
  if/minimax-m2
  if/deepseek-r1
```

### Qwen (3 БЕСПЛАТНЫЕ модели)

```bash
Dashboard → Подключить Qwen
→ Авторизация по коду устройства
→ Неограниченное использование

Модели:
  qw/qwen3-coder-plus
  qw/qwen3-coder-flash
```

### Kiro (Claude БЕСПЛАТНО)

```bash
Dashboard → Подключить Kiro
→ AWS Builder ID или Google/GitHub
→ Неограниченное использование

Модели:
  kr/claude-sonnet-4.5
  kr/claude-haiku-4.5
```

</details>

<details>
<summary><b>🎨 Создание комбо</b></summary>

### Пример 1: Максимизация подписки → Дешёвый бэкап

```
Dashboard → Комбо → Создать новое

Название: premium-coding
Модели:
  1. cc/claude-opus-4-6 (Основная подписка)
  2. glm/glm-4.7 (Дешёвый бэкап, $0.6/1M)
  3. minimax/MiniMax-M2.1 (Самый дешёвый fallback, $0.20/1M)

Используйте в CLI: premium-coding
```

### Пример 2: Только бесплатные (Нулевая стоимость)

```
Название: free-combo
Модели:
  1. gc/gemini-3-flash-preview (180K бесплатно/мес)
  2. if/kimi-k2-thinking (неограниченно)
  3. qw/qwen3-coder-plus (неограниченно)

Стоимость: $0 навсегда!
```

</details>

<details>
<summary><b>🔧 Интеграция с CLI</b></summary>

### Cursor IDE

```
Настройки → Модели → Расширенные:
  OpenAI API Base URL: http://localhost:20128/v1
  OpenAI API Key: [из dashboard OmniRoute]
  Model: cc/claude-opus-4-6
```

### Claude Code

Используйте страницу **CLI Tools** в dashboard для настройки в один клик, или редактируйте `~/.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 (рекомендуется):**

```
Dashboard → CLI Tools → OpenClaw → Выбрать модель → Применить
```

**Вариант 2 — Вручную:** Редактируйте `~/.openclaw/openclaw.json`:

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

> **Примечание:** OpenClaw работает только с локальным OmniRoute. Используйте `127.0.0.1` вместо `localhost` для избежания проблем с IPv6.

### Cline / Continue / RooCode

```
Настройки → Конфигурация API:
  Провайдер: OpenAI Compatible
  Base URL: http://localhost:20128/v1
  API Key: [из dashboard OmniRoute]
  Model: if/kimi-k2-thinking
```

</details>

---

## 🐛 Устранение неполадок

<details>
<summary><b>Нажмите для раскрытия руководства</b></summary>

**«Language model did not provide messages»**

- Квота провайдера исчерпана → Проверьте трекер квот в dashboard
- Решение: Используйте комбо с fallback или переключитесь на более дешёвый уровень

**Rate limiting**

- Квота подписки исчерпана → Fallback на GLM/MiniMax
- Добавьте комбо: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`

**OAuth-токен истёк**

- Обновляется автоматически OmniRoute
- Если проблема сохраняется: Dashboard → Провайдер → Переподключить

**Высокие расходы**

- Проверьте статистику в Dashboard → Расходы
- Переключите основную модель на GLM/MiniMax
- Используйте бесплатный уровень (Gemini CLI, iFlow) для некритичных задач

**Dashboard открывается на неправильном порту**

- Установите `PORT=20128` и `NEXT_PUBLIC_BASE_URL=http://localhost:20128`

**Ошибки cloud sync**

- Проверьте что `BASE_URL` указывает на ваш запущенный экземпляр
- Проверьте что `CLOUD_URL` указывает на правильный облачный endpoint
- Держите значения `NEXT_PUBLIC_*` синхронизированными с серверными значениями

**Первый вход не работает**

- Проверьте `INITIAL_PASSWORD` в `.env`
- Если не задан, пароль по умолчанию `123456`

**Нет логов запросов**

- Установите `ENABLE_REQUEST_LOGS=true` в `.env`

**Тест подключения показывает «Invalid» для OpenAI-совместимых провайдеров**

- Многие провайдеры не предоставляют endpoint `/models`
- OmniRoute v1.0.6+ включает fallback-валидацию через chat completions
- Убедитесь что base URL содержит суффикс `/v1`

</details>

---

## 🛠️

- **Runtime**: Node.js 20+
- **Язык**: TypeScript 5.9 — **100% TypeScript** в `src/` и `open-sse/` (v1.0.6)
- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4
- **База данных**: LowDB (JSON) + SQLite (состояние домена + proxy-логи)
- **Стриминг**: Server-Sent Events (SSE)
- **Аутентификация**: OAuth 2.0 (PKCE) + JWT + API Keys
- **Тестирование**: Node.js test runner (368+ юнит-тестов)
- **CI/CD**: GitHub Actions (авто-публикация 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)
- **Устойчивость**: Circuit breaker, экспоненциальный backoff, anti-thundering herd, TLS-спуфинг

---

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

| Документ                                        | Описание                                         |
| ----------------------------------------------- | ------------------------------------------------ |
| [Руководство пользователя](docs/USER_GUIDE.md)  | Провайдеры, комбо, интеграция CLI, деплой        |
| [Справка API](docs/API_REFERENCE.md)            | Все endpoints с примерами                        |
| [Устранение неполадок](docs/TROUBLESHOOTING.md) | Частые проблемы и решения                        |
| [Архитектура](docs/ARCHITECTURE.md)             | Архитектура системы и внутреннее устройство      |
| [Как внести вклад](CONTRIBUTING.md)             | Настройка разработки и руководящие принципы      |
| [Спецификация OpenAPI](docs/openapi.yaml)       | Спецификация OpenAPI 3.0                         |
| [Политика безопасности](SECURITY.md)            | Сообщение об уязвимостях и практики безопасности |

---

## 🗺️

## 👥 Участники

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

### Как внести вклад

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

См. [CONTRIBUTING.md](CONTRIBUTING.md) для подробных рекомендаций.

### Выпуск новой версии

```bash
# Создайте релиз — публикация в npm происходит автоматически
gh release create v1.0.6 --title "v1.0.6" --generate-notes
```

---

## 📊 История звёзд

<a href="https://star-history.com/#diegosouzapw/OmniRoute&Date">
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=diegosouzapw/OmniRoute&type=Date&theme=dark" />
   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=diegosouzapw/OmniRoute&type=Date" />
   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=diegosouzapw/OmniRoute&type=Date" />
 </picture>
</a>

---

## 🙏 Благодарности

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

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

---

## 📄 Лицензия

Лицензия MIT — см. [LICENSE](LICENSE) для подробностей.

---

<div align="center">
  <sub>Сделано с ❤️ для разработчиков, которые программируют 24/7</sub>
  <br/>
  <sub><a href="https://omniroute.online">omniroute.online</a></sub>
</div>
