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