# User Guide (Română)
🌐 **Languages:** 🇺🇸 [English](../../../../guides/USER_GUIDE.md) · 🇪🇹 [am](../../../am/docs/guides/USER_GUIDE.md) · 🇸🇦 [ar](../../../ar/docs/guides/USER_GUIDE.md) · 🇦🇿 [az](../../../az/docs/guides/USER_GUIDE.md) · 🇧🇬 [bg](../../../bg/docs/guides/USER_GUIDE.md) · 🇧🇩 [bn](../../../bn/docs/guides/USER_GUIDE.md) · 🇧🇦 [bs](../../../bs/docs/guides/USER_GUIDE.md) · 🇨🇿 [cs](../../../cs/docs/guides/USER_GUIDE.md) · 🇩🇰 [da](../../../da/docs/guides/USER_GUIDE.md) · 🇩🇪 [de](../../../de/docs/guides/USER_GUIDE.md) · 🇬🇷 [el](../../../el/docs/guides/USER_GUIDE.md) · 🇪🇸 [es](../../../es/docs/guides/USER_GUIDE.md) · 🇪🇪 [et](../../../et/docs/guides/USER_GUIDE.md) · 🇮🇷 [fa](../../../fa/docs/guides/USER_GUIDE.md) · 🇫🇮 [fi](../../../fi/docs/guides/USER_GUIDE.md) · 🇫🇷 [fr](../../../fr/docs/guides/USER_GUIDE.md) · 🇮🇪 [ga](../../../ga/docs/guides/USER_GUIDE.md) · 🇮🇳 [gu](../../../gu/docs/guides/USER_GUIDE.md) · 🇳🇬 [ha](../../../ha/docs/guides/USER_GUIDE.md) · 🇮🇱 [he](../../../he/docs/guides/USER_GUIDE.md) · 🇮🇳 [hi](../../../hi/docs/guides/USER_GUIDE.md) · 🇭🇷 [hr](../../../hr/docs/guides/USER_GUIDE.md) · 🇭🇺 [hu](../../../hu/docs/guides/USER_GUIDE.md) · 🇦🇲 [hy](../../../hy/docs/guides/USER_GUIDE.md) · 🇮🇩 [id](../../../id/docs/guides/USER_GUIDE.md) · 🇳🇬 [ig](../../../ig/docs/guides/USER_GUIDE.md) · 🇮🇹 [it](../../../it/docs/guides/USER_GUIDE.md) · 🇯🇵 [ja](../../../ja/docs/guides/USER_GUIDE.md) · 🇬🇪 [ka](../../../ka/docs/guides/USER_GUIDE.md) · 🇰🇭 [km](../../../km/docs/guides/USER_GUIDE.md) · 🇮🇳 [kn](../../../kn/docs/guides/USER_GUIDE.md) · 🇰🇷 [ko](../../../ko/docs/guides/USER_GUIDE.md) · 🇱🇹 [lt](../../../lt/docs/guides/USER_GUIDE.md) · 🇱🇻 [lv](../../../lv/docs/guides/USER_GUIDE.md) · 🇮🇳 [ml](../../../ml/docs/guides/USER_GUIDE.md) · 🇮🇳 [mr](../../../mr/docs/guides/USER_GUIDE.md) · 🇲🇾 [ms](../../../ms/docs/guides/USER_GUIDE.md) · 🇲🇹 [mt](../../../mt/docs/guides/USER_GUIDE.md) · 🇲🇲 [my](../../../my/docs/guides/USER_GUIDE.md) · 🇳🇵 [ne](../../../ne/docs/guides/USER_GUIDE.md) · 🇳🇱 [nl](../../../nl/docs/guides/USER_GUIDE.md) · 🇳🇴 [no](../../../no/docs/guides/USER_GUIDE.md) · 🇮🇳 [or](../../../or/docs/guides/USER_GUIDE.md) · 🇮🇳 [pa](../../../pa/docs/guides/USER_GUIDE.md) · 🇵🇭 [phi](../../../phi/docs/guides/USER_GUIDE.md) · 🇵🇱 [pl](../../../pl/docs/guides/USER_GUIDE.md) · 🇵🇹 [pt](../../../pt/docs/guides/USER_GUIDE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/guides/USER_GUIDE.md) · 🇷🇺 [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) · 🇧🇬 [bg](../../../bg/docs/guides/USER_GUIDE.md) · 🇧🇩 [bn](../../../bn/docs/guides/USER_GUIDE.md) · 🇧🇦 [bs](../../../bs/docs/guides/USER_GUIDE.md) · 🇨🇿 [cs](../../../cs/docs/guides/USER_GUIDE.md) · 🇩🇰 [da](../../../da/docs/guides/USER_GUIDE.md) · 🇩🇪 [de](../../../de/docs/guides/USER_GUIDE.md) · 🇬🇷 [el](../../../el/docs/guides/USER_GUIDE.md) · 🇪🇸 [es](../../../es/docs/guides/USER_GUIDE.md) · 🇪🇪 [et](../../../et/docs/guides/USER_GUIDE.md) · 🇮🇷 [fa](../../../fa/docs/guides/USER_GUIDE.md) · 🇫🇮 [fi](../../../fi/docs/guides/USER_GUIDE.md) · 🇫🇷 [fr](../../../fr/docs/guides/USER_GUIDE.md) · 🇮🇪 [ga](../../../ga/docs/guides/USER_GUIDE.md) · 🇮🇳 [gu](../../../gu/docs/guides/USER_GUIDE.md) · 🇳🇬 [ha](../../../ha/docs/guides/USER_GUIDE.md) · 🇮🇱 [he](../../../he/docs/guides/USER_GUIDE.md) · 🇮🇳 [hi](../../../hi/docs/guides/USER_GUIDE.md) · 🇭🇷 [hr](../../../hr/docs/guides/USER_GUIDE.md) · 🇭🇺 [hu](../../../hu/docs/guides/USER_GUIDE.md) · 🇦🇲 [hy](../../../hy/docs/guides/USER_GUIDE.md) · 🇮🇩 [id](../../../id/docs/guides/USER_GUIDE.md) · 🇳🇬 [ig](../../../ig/docs/guides/USER_GUIDE.md) · 🇮🇹 [it](../../../it/docs/guides/USER_GUIDE.md) · 🇯🇵 [ja](../../../ja/docs/guides/USER_GUIDE.md) · 🇬🇪 [ka](../../../ka/docs/guides/USER_GUIDE.md) · 🇰🇭 [km](../../../km/docs/guides/USER_GUIDE.md) · 🇮🇳 [kn](../../../kn/docs/guides/USER_GUIDE.md) · 🇰🇷 [ko](../../../ko/docs/guides/USER_GUIDE.md) · 🇱🇹 [lt](../../../lt/docs/guides/USER_GUIDE.md) · 🇱🇻 [lv](../../../lv/docs/guides/USER_GUIDE.md) · 🇮🇳 [ml](../../../ml/docs/guides/USER_GUIDE.md) · 🇮🇳 [mr](../../../mr/docs/guides/USER_GUIDE.md) · 🇲🇾 [ms](../../../ms/docs/guides/USER_GUIDE.md) · 🇲🇹 [mt](../../../mt/docs/guides/USER_GUIDE.md) · 🇲🇲 [my](../../../my/docs/guides/USER_GUIDE.md) · 🇳🇵 [ne](../../../ne/docs/guides/USER_GUIDE.md) · 🇳🇱 [nl](../../../nl/docs/guides/USER_GUIDE.md) · 🇳🇴 [no](../../../no/docs/guides/USER_GUIDE.md) · 🇮🇳 [or](../../../or/docs/guides/USER_GUIDE.md) · 🇮🇳 [pa](../../../pa/docs/guides/USER_GUIDE.md) · 🇵🇭 [phi](../../../phi/docs/guides/USER_GUIDE.md) · 🇵🇱 [pl](../../../pl/docs/guides/USER_GUIDE.md) · 🇵🇹 [pt](../../../pt/docs/guides/USER_GUIDE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/guides/USER_GUIDE.md) · 🇷🇺 [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)
Ghid complet pentru configurarea furnizorilor, crearea combinațiilor, integrarea instrumentelor CLI și implementarea OmniRoute.
---
## Cuprins
- [Prețuri pe scurt](#-pricing-at-a-glance)
- [Cazuri de utilizare](#-use-cases)
- [Configurarea furnizorilor](#-provider-setup)
- [Integrarea CLI](#-cli-integration)
- [Implementare](#-deployment)
- [Modele disponibile](#-available-models)
- [Funcții avansate](#-advanced-features)
- [Rutare automată (fără configurare)](#-auto-routing-zero-config)
- [Integrarea MCP și A2A](#-mcp--a2a-integration)
- [Sistemul de abilități](#-skills-system)
- [Sistemul de memorie](#-memory-system)
- [Webhook-uri](#-webhooks)
- [Agenți cloud](#-cloud-agents)
- [Gestionare programatică](#-programmatic-management)
- [CLI intern](#-internal-cli)
- [Aplicație desktop (Electron)](#-desktop-application-electron)
---
## 💰 Prețuri pe scurt
| Nivel | Furnizor | Cost | Resetarea cotei | Recomandat pentru |
| ---------------- | ----------------- | ------------------- | ------------------------------- | ------------------------------ |
| **💳 ABONAMENT** | Claude Code (Pro) | $20/lună | La 5 ore + săptămânal | Utilizatori deja abonați |
| | Codex (Plus/Pro) | $20-200/lună | La 5 ore + săptămânal | Utilizatori OpenAI |
| | GitHub Copilot | $10-19/lună | Lunar | Utilizatori GitHub |
| **🔑 CHEIE API** | DeepSeek | Plată per utilizare | Fără | Raționament ieftin |
| | Groq | Plată per utilizare | Fără | Inferență ultrarapidă |
| | xAI (Grok) | Plată per utilizare | Fără | Raționament cu Grok 4 |
| | Mistral | Plată per utilizare | Fără | Modele găzduite în UE |
| | Perplexity | Plată per utilizare | Fără | Căutare îmbunătățită |
| | Together AI | Plată per utilizare | Fără | Modele open-source |
| | Fireworks AI | Plată per utilizare | Fără | Imagini FLUX generate rapid |
| | Cerebras | Plată per utilizare | Fără | Viteză la scara plachetei |
| | Cohere | Plată per utilizare | Fără | RAG cu Command R+ |
| | NVIDIA NIM | Plată per utilizare | Fără | Modele pentru companii |
| | Baidu Qianfan | Plată per utilizare | Fără | Modele ERNIE |
| **💰 IEFTIN** | GLM-4.7 | $0.6/1M | Zilnic, la ora 10:00 | Variantă de rezervă economică |
| | MiniMax M2.1 | $0.2/1M | Fereastră glisantă de 5 ore | Cea mai ieftină opțiune |
| | Kimi K2 | $9/lună, tarif fix | 10M tokenuri/lună | Cost previzibil |
| **🆓 GRATUIT** | Qoder | $0 | Se aplică limitele furnizorului | Verificarea catalogului actual |
| | Kiro | $0 | ~50 de credite/lună | Claude gratuit |
---
## 🎯 Cazuri de utilizare
### Cazul 1: „Am un abonament Claude Pro”
**Problemă:** Cota expiră neutilizată, iar în timpul sesiunilor intensive de programare sunt atinse limitele de rată
```
Combinație: "maximize-claude"
1. cc/claude-opus-4-7 (folosește integral abonamentul)
2. glm/glm-4.7 (variantă de rezervă ieftină când cota se epuizează)
3. if/qwen3.8-max-preview (variantă gratuită de urgență)
Cost lunar: $20 (abonament) + ~$5 (rezervă) = $25 în total
față de $20 + atingerea limitelor = frustrare
```
### Cazul 2: „Nu vreau niciun cost”
**Problemă:** Nu-mi permit abonamente și am nevoie de un AI fiabil pentru programare
```
Combinație: "zero-cost"
1. if/kimi-k2.7-code (acces listat drept gratuit; se pot aplica limite de rată)
2. kr/qwen3-coder-next (variantă de rezervă gratuită prin Kiro)
Cost lunar: $0
Calitate: verificați modelul, limitele, confidențialitatea și SLA-ul pentru volumul dvs. de lucru
```
### Cazul 3: „Am nevoie să programez non-stop, fără întreruperi”
**Problemă:** Am termene-limită și nu-mi permit perioade de nefuncționare
```
Combinație: "always-on"
1. cc/claude-opus-4-7 (cea mai bună calitate)
2. cx/gpt-5.5 (al doilea abonament)
3. glm/glm-4.7 (ieftin, se resetează zilnic)
4. minimax/MiniMax-M2.1 (cel mai ieftin, resetare la 5 ore)
5. if/deepseek-v4-flash (acces listat drept gratuit; se pot aplica limite de rată)
Rezultat: 5 niveluri de rezervă sporesc reziliența; disponibilitatea serviciilor din amonte nu este garantată
Cost lunar: $20-200 (abonamente) + $10-20 (rezervă)
```
### Cazul 4: „Vreau AI GRATUIT în OpenClaw”
**Problemă:** Am nevoie de un asistent AI în aplicațiile de mesagerie, complet gratuit
```
Combinație: "openclaw-free"
1. if/qwen3.8-max-preview (acces listat drept gratuit; se pot aplica limite de rată)
2. if/deepseek-v4-flash (acces listat drept gratuit; se pot aplica limite de rată)
3. if/kimi-k2.7-code (acces listat drept gratuit; se pot aplica limite de rată)
Cost lunar: $0
Acces prin: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
```
---
## 📖 Configurarea furnizorilor
Pentru a adăuga în bloc conexiuni cu chei API dintr-un fișier CSV sau JSON, utilizați **Panou de control → Furnizori → Importă din fișier**. Coloanele sunt poziționale (`provider,name,apiKey,baseUrl,priority`); `provider` trebuie să existe deja ca furnizor gestionat sau ca nod compatibil. Consultați [Importarea furnizorilor dintr-un fișier CSV sau JSON](../providers/CSV-IMPORT.md).
### 🔐 Furnizori pe bază de abonament
#### Claude Code (Pro/Max)
```bash
Panou de control → Furnizori → Conectează Claude Code
→ Autentificare OAuth → Reîmprospătare automată a tokenului
→ Monitorizarea cotei la 5 ore + săptămânale
Modele:
cc/claude-opus-4-7
cc/claude-sonnet-4-6
cc/claude-haiku-4-5-20251001
```
**Sfat util:** Utilizați Opus pentru sarcini complexe și Sonnet pentru viteză. OmniRoute monitorizează cota pentru fiecare model!
Nu aveți un browser pe gazda OmniRoute? Rulați `claude setup-token` oriunde sunteți autentificat în Claude Code și inserați tokenul valabil un an în fila **Token de configurare**. Consultați [Claude Code cu un token de configurare](../providers/CLAUDE_CODE_SETUP_TOKEN.md).
Rutele compatibile cu Claude și Claude Code păstrează nivelul `max` al efortului de raționament pentru modelele Opus și Sonnet. Modelele Haiku nu acceptă nivelul de efort `max`, astfel încât OmniRoute reduce solicitarea la un buget ridicat de raționament înainte de a o trimite serviciului din amonte.
#### OpenAI Codex (Plus/Pro)
```bash
Panou de control → Furnizori → Conectează Codex
→ Autentificare OAuth (portul 1455)
→ Resetare la 5 ore + săptămânală
Modele:
cx/gpt-5.5
cx/gpt-5.4
cx/gpt-5.3-codex
cx/gpt-5.3-codex-spark
```
#### GitHub Copilot
```bash
Panou de control → Furnizori → Conectează GitHub
→ OAuth prin GitHub
→ Resetare lunară (în prima zi a lunii)
Modele:
gh/gpt-5.5
gh/gpt-5.4
gh/claude-sonnet-4.6
gh/claude-opus-4.7
gh/gemini-3.1-pro-preview
```
### 💰 Furnizori ieftini
#### GLM-4.7 (resetare zilnică, $0.6/1M)
1. Înregistrați-vă: [Zhipu AI](https://open.bigmodel.cn)
2. Obțineți cheia API din Coding Plan
3. Panou de control → Adaugă o cheie API: Furnizor: `glm`, Cheie API: `your-key`
**Utilizare:** `glm/glm-4.7` — **Sfat util:** Coding Plan oferă o cotă de 3× mai mare la 1/7 din cost! Se resetează zilnic la ora 10:00.
#### MiniMax M2.1 (resetare la 5 ore, $0.20/1M)
1. Înregistrați-vă: [MiniMax](https://www.minimax.io)
2. Obțineți cheia API → Panou de control → Adaugă o cheie API
**Utilizare:** `minimax/MiniMax-M2.1` — **Sfat util:** Cea mai ieftină opțiune pentru contexte lungi (1M tokenuri)!
#### Kimi K2 (tarif fix de $9/lună)
1. Abonați-vă: [Moonshot AI](https://platform.kimi.ai?aff=omniroute)
2. Obțineți cheia API → Panou de control → Adaugă o cheie API
**Utilizare:** `kimi/kimi-k2.5` — **Sfat util:** Tariful fix de $9/lună pentru 10M tokenuri înseamnă un cost efectiv de $0.90/1M!
#### Baidu Qianfan / ERNIE
1. Înregistrați-vă: [Baidu AI Cloud Qianfan](https://cloud.baidu.com/product/wenxinworkshop)
2. Creați o cheie API Qianfan → Panou de control → Adaugă o cheie API: Furnizor: `qianfan`
**Utilizare:** `qianfan/ernie-5.1`, `qianfan/ernie-x1.1` sau un alt ID de model Qianfan compatibil cu OpenAI.
### 🆓 Furnizori GRATUIȚI
Furnizorii gratuiți care nu necesită autentificare au un comutator lângă **Nu este necesară autentificarea** pe pagina furnizorului.
Dezactivarea acestuia dezactivează furnizorul, îl elimină din vizualizările configurată/compactă ale secțiunii Furnizori și
elimină modelele sale din `/v1/models`.
#### Qoder (9 modele GRATUITE)
```bash
Panou de control → Conectează Qoder → Autentificare OAuth → Accesul este supus limitelor actuale ale furnizorului
Modele: 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 GRATUIT)
```bash
Panou de control → Conectează Kiro → AWS Builder ID sau Google/GitHub → ~50 de credite/lună
Modele: kr/claude-sonnet-4.5, kr/claude-haiku-4.5
```
---
## 🎨 Combinații
Poți reordona cardurile combinațiilor direct în **Panou de control → Combinații**, trăgând mânerul de pe fiecare card. Ordinea este stocată în SQLite și restaurată la reîncărcare.
### Exemplul 1: Maximizarea abonamentului → Rezervă ieftină
```
Panou de control → Combinații → Creează una nouă
Nume: premium-coding
Modele:
1. cc/claude-opus-4-7 (Abonament principal)
2. glm/glm-4.7 (Rezervă ieftină, $0.6/1M)
3. minimax/MiniMax-M2.7 (Alternativă de ultimă instanță cu cel mai mic cost, $0.3/1M)
Utilizare în CLI: premium-coding
```
### Exemplul 2: Numai opțiuni gratuite (cost zero)
```
Nume: free-combo
Modele:
1. if/kimi-k2.7-code (acces gratuit conform informațiilor afișate; se pot aplica limitele furnizorului)
2. kr/qwen3-coder-next (alternativă gratuită Kiro)
Cost: afișat în prezent ca $0; termenii și disponibilitatea se pot modifica
```
---
## 🔧 Integrarea cu CLI
### Cursor IDE
**Utilizarea Cursor drept client OmniRoute** (direcționează conversațiile Cursor prin OmniRoute):
```
Setări → Modele → Avansat:
URL de bază pentru API-ul OpenAI: http://localhost:20128/v1
Cheie API OpenAI: [din panoul de control OmniRoute]
Model: cc/claude-opus-4-7
```
**Utilizarea OmniRoute drept furnizor Cursor** (OmniRoute apelează Cursor în amonte): este recomandat
**Panou de control → Furnizori → Cursor → Autentificare cu Cursor**. În Docker, consultă
[`docs/providers/CURSOR-DOCKER.md`](../providers/CURSOR-DOCKER.md).
### Claude Code
Editează `~/.claude/settings.json`:
```json
{
"env": {
"ANTHROPIC_BASE_URL": "http://localhost:20128",
"ANTHROPIC_AUTH_TOKEN": "your-omniroute-api-key"
}
}
```
Folosește aici punctul final rădăcină compatibil cu Claude. Nu adăuga `/v1` la `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
Editează `~/.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" }]
}
}
}
}
```
**Sau folosește panoul de control:** Instrumente CLI → OpenClaw → Configurare automată
### Cline / Continue / RooCode
```
Furnizor: Compatibil cu OpenAI
URL de bază: http://localhost:20128/v1
Cheie API: [din panoul de control]
Model: cc/claude-opus-4-7
```
---
## 🚀 Implementare
### Instalare globală cu npm (recomandat)
```bash
npm install -g omniroute
# Creează directorul de configurare
mkdir -p ~/.omniroute
# Creează fișierul .env (consultă .env.example)
cp .env.example ~/.omniroute/.env
# Pornește serverul
omniroute
# Sau cu un port personalizat:
omniroute --port 3000
```
CLI-ul încarcă automat `.env` din `~/.omniroute/.env` sau `./.env`.
### Modul bară de sistem
Pornește OmniRoute în bara de sistem:
```bash
omniroute serve --tray
```
Comanda se încheie după ce serverul și pictograma din bara de sistem sunt pregătite.
Serverul continuă să ruleze fără terminal.
Modul bară de sistem este compatibil cu macOS, Windows și sesiunile grafice Linux. Modul bară de sistem nu deschide automat panoul de control.
Folosește meniul din bara de sistem pentru următoarele acțiuni:
- Deschide panoul de control.
- Deschide `/dashboard/logs`.
- Modifică pornirea automată.
- Oprește OmniRoute.
Nu combina `--tray` cu următoarele opțiuni:
- `--daemon`
- `--log`
- `--no-recovery`
Aceste moduri necesită o administrare diferită a proceselor.
Activează pornirea la următoarea autentificare pe sistem:
```bash
omniroute autostart enable
```
Pornirea automată folosește modul bară de sistem pe macOS, Windows și în sesiunile grafice Linux. Sistemele Linux fără interfață grafică folosesc serviciul de utilizator systemd existent.
Dezactivează pornirea la autentificare:
```bash
omniroute autostart disable
```
### Dezinstalare
Când nu mai ai nevoie de OmniRoute, punem la dispoziție două scripturi rapide pentru eliminarea completă:
| Comandă | Acțiune |
| ------------------------ | ------------------------------------------------------------------------------------------------- |
| `npm run uninstall` | Elimină aplicația din sistem, dar **păstrează baza de date și configurațiile** în `~/.omniroute`. |
| `npm run uninstall:full` | Elimină aplicația ȘI **șterge definitiv toate configurațiile, cheile și bazele de date**. |
> Notă: Pentru a executa aceste comenzi, accesează directorul proiectului OmniRoute (dacă l-ai clonat) și rulează-le. Alternativ, dacă este instalat global, poți executa pur și simplu `npm uninstall -g omniroute`.
### Implementare pe 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
# Sau: pm2 start npm --name omniroute -- start
```
### Implementare cu PM2 (memorie redusă)
Pentru serverele cu memorie RAM limitată, folosește opțiunea de limitare a memoriei:
```bash
# Cu o limită de 512MB (implicită)
pm2 start npm --name omniroute -- start
# Sau cu o limită de memorie personalizată
OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start
# Sau folosind ecosystem.config.js
pm2 start ecosystem.config.js
```
Creează `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
# Construiește imaginea (implicit = runner-cli cu codex/claude/droid preinstalate)
docker build -t omniroute:cli .
# Mod portabil (recomandat)
docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli
```
Pentru modul integrat cu gazda, cu binare CLI, consultă secțiunea Docker din documentația principală.
### Void Linux (xbps-src)
Utilizatorii Void Linux pot împacheta și instala OmniRoute în mod nativ folosind cadrul de compilare încrucișată `xbps-src`. Acesta automatizează compilarea autonomă Node.js împreună cu legăturile native `better-sqlite3` necesare.
Vizualizați șablonul xbps-src
```bash
# Fișier șablon pentru „omniroute”
pkgname=omniroute
version=3.8.0
revision=1
hostmakedepends="nodejs python3 make"
depends="openssl"
short_desc="Universal AI gateway with smart routing for multiple LLM providers"
maintainer="zenobit "
license="MIT"
homepage="https://github.com/diegosouzapw/OmniRoute"
distfiles="https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz"
checksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b
system_accounts="_omniroute"
omniroute_homedir="/var/lib/omniroute"
export NODE_ENV=production
export npm_config_engine_strict=false
export npm_config_loglevel=error
export npm_config_fund=false
export npm_config_audit=false
do_build() {
# Determină arhitectura procesorului țintă pentru 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) Instalează toate dependențele – omite scripturile
NODE_ENV=development npm ci --ignore-scripts
# 2) Construiește pachetul autonom Next.js
npm run build
# 3) Copiază resursele statice în pachetul autonom
cp -r .next/static .next/standalone/.next/static
[ -d public ] && cp -r public .next/standalone/public || true
# 4) Compilează legătura nativă 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) Plasează legătura compilată în pachetul autonom
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) Elimină pachetele sharp specifice arhitecturii
rm -rf .next/standalone/node_modules/@img
# 7) Copiază dependențele de execuție pino omise de analiza statică 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
# Împiedică eliminarea directoarelor goale ale routerului aplicației Next.js de către mecanismul post-instalare
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
}
```
### Variabile de mediu
| Variabilă | Valoare implicită | Descriere |
| --------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `JWT_SECRET` | `omniroute-default-secret-change-me` | Secret pentru semnarea JWT (**modificați-l în producție**) |
| `INITIAL_PASSWORD` | `CHANGEME` | Parola pentru prima autentificare |
| `DATA_DIR` | `~/.omniroute` | Director de date (bază de date, utilizare, jurnale) |
| `PORT` | valoarea implicită a cadrului | Portul serviciului (`20128` în exemple) |
| `HOSTNAME` | valoarea implicită a cadrului | Gazda de ascultare (valoarea implicită pentru Docker este `0.0.0.0`) |
| `NODE_ENV` | valoarea implicită a mediului | Setați la `production` pentru implementare |
| `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128` | URL-ul de bază public afișat în panoul de control și expus serverului (înlocuiește vechiul `BASE_URL`) |
| `NEXT_PUBLIC_CLOUD_URL` | `https://omniroute.dev` | URL-ul de bază al punctului final pentru sincronizarea în cloud (înlocuiește vechiul `CLOUD_URL`) |
| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | Secret HMAC pentru cheile API generate |
| `REQUIRE_API_KEY` | `false` | Impune o cheie API Bearer pentru `/v1/*` |
| `ALLOW_API_KEY_REVEAL` | `false` | Permite utilizatorilor autentificați ai panoului de control să afișeze la cerere valorile complete ale cheilor API stocate |
| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Intervalul de reîmprospătare pe server pentru datele memorate în cache privind limitele furnizorilor; butoanele de reîmprospătare din interfața de utilizare declanșează în continuare sincronizarea manuală |
| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Dezactivează instantaneele SQLite automate înainte de scriere/importare/restaurare; copiile de siguranță manuale funcționează în continuare |
| `APP_LOG_TO_FILE` | `true` | Activează scrierea pe disc a jurnalelor aplicației și de audit |
| `AUTH_COOKIE_SECURE` | `false` | Impune atributul `Secure` pentru cookie-ul de autentificare (în spatele unui proxy invers HTTPS) |
| `CLOUDFLARED_BIN` | nesetat | Utilizează un binar `cloudflared` existent în locul descărcării gestionate |
| `CLOUDFLARED_PROTOCOL` | `http2` | Transportul pentru tunelurile rapide gestionate (`http2`, `quic` sau `auto`) |
| `OMNIROUTE_MEMORY_MB` | `512` | Limita heap-ului Node.js în MB |
| `PROMPT_CACHE_MAX_SIZE` | `50` | Numărul maxim de intrări în memoria cache pentru prompturi |
| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Numărul maxim de intrări în memoria cache semantică |
Pentru referința completă a variabilelor de mediu, consultați [README](../README.md).
---
## 📊 Modele disponibile
Vedeți toate modelele disponibile
> Lista de mai jos este selectată din `open-sse/config/providerRegistry.ts` pentru v3.8.0. Cataloagele cloud (Gemini, OpenRouter etc.) sunt sincronizate dinamic — pentru catalogul complet și actualizat, deschideți **Panou de control → Furnizori → [furnizor] → Modele disponibile** sau apelați `GET /api/models/catalog`.
>
> Dacă lista încorporată a unui furnizor nu mai este actualizată, utilizați **Importați din /models** pe pagina respectivă (sau activați **Sincronizare automată**) pentru a prelua catalogul actualizat din sursa din amonte. Acest lucru a fost verificat în v3.8.50 pentru LLM7.io (`gemini-3.1-flash-lite`) și UncloseAI (`solidrust/Hermes-3-Llama-3.1-8B-AWQ`); accesul anonim la Pollinations a rămas limitat de sursa din amonte în cadrul aceleiași serii de teste.
**Claude Code (`cc/`)** — OAuth Pro/Max: `cc/claude-opus-4-8`, `cc/claude-opus-4-7`, `cc/claude-opus-4-6`, `cc/claude-opus-4-5-20251101`, `cc/claude-sonnet-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
**Codex (`cx/`)** — OAuth Plus/Pro: `cx/gpt-5.5` (+ niveluri de efort: `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 GRATUIT: utilizați catalogul actualizat afișat în **Panou de control → Furnizori → Kiro → Modele disponibile**. Disponibilitatea depinde de cont și de abonament.
**Qoder (`if/`)** — OAuth GRATUIT: `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 USD/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 USD/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/`)** — tarif fix de 9 USD/lună sau plată per utilizare: `kimi/kimi-k2.6`, `kimi/kimi-k2.5`
**DeepSeek (`ds/`)** — cheie API: `ds/deepseek-v4-pro`, `ds/deepseek-v4-flash`
**Groq (`groq/`)** — ultrarapid: `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 nativ: `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/`)** — găzduit în UE: `mistral/mistral-large-latest`, `mistral/mistral-medium-3-5`, `mistral/mistral-small-latest`, `mistral/devstral-latest`, `mistral/codestral-latest`
**Perplexity (`pplx/`)** — îmbogățit cu funcții de căutare: `pplx/sonar-deep-research`, `pplx/sonar-reasoning-pro`, `pplx/sonar-pro`, `pplx/sonar`
**Together AI (`together/`)** — sursă deschisă: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo-Free` (gratuit), `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/`)** — inferență rapidă: `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/`)** — la scara unei plachete: `cerebras/zai-glm-4.7`, `cerebras/gpt-oss-120b`
**Cohere (`cohere/`)** — axat pe 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/`)** — pentru întreprinderi: `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/`)**: sincronizat în timp real din Google pentru fiecare cheie API — nu există o listă statică. Conectați o cheie în **Panou de control → Furnizori**, apoi utilizați **Modele disponibile** pentru a importa catalogul actual (de exemplu, `gemini/gemini-3-pro`, `gemini/gemini-3-flash`).
**Alți furnizori compatibili** (selecție): `cohere`, `databricks`, `snowflake`, `together`, `vertex`, `alibaba`, `alibaba-cn`, `bedrock` (prin `aws-bedrock`), `azure-ai`, `openrouter` (catalog transmis direct), `siliconflow`, `hyperbolic`, `huggingface`, `featherless-ai`, `cloudflare-ai`, `scaleway`, `deepinfra`, `vercel-ai-gateway`, `bazaarlink`, `friendliai`, `nous-research`, `reka`, `volcengine`, `ai21`, `gigachat`. Fiecare își menține propria listă de modele în `providerRegistry.ts` și poate fi sincronizat automat atunci când furnizorul expune un punct final `/models`.
**Notă privind ID-urile modelelor:** OmniRoute utilizează ID-uri native ale furnizorilor (`claude-opus-4-8`, `gpt-5.5`, `glm-5.1`, `MiniMax-M2.7`, `kimi-k2.5`, `grok-4.20-0309-reasoning`). Unele ID-uri includ versiuni cu puncte, deoarece acesta este formatul solicitat de API-ul din amonte. Dacă un model nu este enumerat mai sus, rulați `omniroute models --search ` sau accesați `GET /api/models/catalog` pentru a confirma disponibilitatea.
---
## 🧩 Funcționalități avansate
### Modele personalizate
Adăugați orice ID de model la orice furnizor fără să așteptați o actualizare a aplicației:
```bash
# Prin 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"}'
# Listare: curl http://localhost:20128/api/provider-models?provider=openai
# Eliminare: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-5.2"
```
Sau utilizați Panoul de control: **Furnizori → [Furnizor] → Modele personalizate**.
Note:
- Furnizorii compatibili cu OpenRouter și OpenAI/Anthropic sunt gestionați exclusiv din **Modele disponibile**. Adăugarea manuală, importul și sincronizarea automată ajung toate în aceeași listă de modele disponibile, astfel încât nu există o secțiune separată Modele personalizate pentru acești furnizori.
- Secțiunea **Modele personalizate** este destinată furnizorilor care nu oferă importuri gestionate de modele disponibile.
### Furnizori personalizați compatibili cu OpenAI
Orice gateway care utilizează API-ul OpenAI (un proxy găzduit local, vLLM, un agregator terț)
poate fi adăugat ca nod de furnizor separat:
1. **Furnizori → Adăugați un furnizor compatibil cu OpenAI**.
2. **Nume**: o etichetă afișată pentru nod.
3. **Prefix**: numele pentru rutare. Clienții apelează modelele ca `/`, astfel încât un nod cu
prefixul `mygw` deservește `mygw/gpt-4o-mini`. Obligatoriu; nu există restricții privind caracterele.
4. **Tip API**: familia de endpointuri deservită de gateway (Chat Completions, Responses,
Embeddings, audio, imagini).
5. **URL de bază**: rădăcina API-ului, până la și inclusiv `/v1` (de exemplu,
`https://gateway.example.com/v1`), nu calea completă `/chat/completions`. Gateway-urile cu
căi nestandardizate le configurează în **Setări avansate** (calea pentru chat, calea pentru modele).
6. Câmpul **Cheie API (pentru verificare)** doar testează conexiunea. După crearea nodului,
deschideți-l și utilizați **Adăugați o conexiune** pentru a stoca cheia pe care o vor utiliza solicitările.
Nodul primește un ID intern de forma `openai-compatible--`; nu trebuie
să îl introduceți niciodată, prefixul fiind numele public.
#### Prefixe rezervate
Un prefix nu poate fi ID-ul sau aliasul unui furnizor încorporat (de exemplu, `openai`, `cf`) și nici
ID-ul unui furnizor retras. Resolverul de modele verifică ID-urile și aliasurile încorporate înaintea
nodurilor personalizate, astfel încât un nod care utilizează unul dintre aceste prefixe nu va primi niciodată trafic:
`/model` va fi direcționat în schimb către furnizorul încorporat sau va eșua în mod securizat dacă furnizorul
respectiv a fost retras. Crearea sau editarea unui nod cu un astfel de prefix este respinsă cu:
```text
prefix: "" este un prefix rezervat pentru furnizori — alegeți un prefix diferit (ID-urile/aliasurile rezervate nu pot fi utilizate pentru noduri personalizate, deoarece solicitările precum /model sunt direcționate către un furnizor încorporat sau eșuează în mod securizat atunci când acesta este retras)
```
Alegeți un prefix distinct (`mygw`, `acme-proxy`). Dacă solicitările către un nod personalizat eșuează cu o
eroare care menționează un furnizor încorporat sau acreditările acestuia, verificați dacă prefixul nodului este
rezervat: nodurile salvate înainte de introducerea acestei reguli sunt încă păstrate, dar prefixul lor direcționează solicitările
către furnizorul încorporat. Editați nodul și atribuiți-i un prefix nou.
### Înlănțuirea instanțelor OmniRoute omoloage
Un alt gateway OmniRoute poate fi adăugat ca furnizor **personalizat compatibil cu OpenAI**. Utilizați
URL-ul de bază `/v1` al instanței omoloage și o cheie API dedicată, cu privilegii minime, emisă de aceasta.
Pentru lanțurile reciproce sau cu mai multe salturi, activați protecția opțională împotriva buclelor pe fiecare gateway:
```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
```
Doar solicitările trimise către un URL de instanță omoloagă inclus explicit în lista de permisiuni primesc antetul
`X-OmniRoute-Peer-Trace`. Un gateway respinge un ID de instanță repetat sau epuizarea numărului
de salturi cu HTTP `508 Loop Detected`; furnizorii upstream obișnuiți nu primesc metadate despre instanțele omoloage.
Înlănțuirea instanțelor omoloage nu reprezintă replicarea bazei de date sau failover-ul gazdei. Fiecare gateway păstrează
independent starea SQLite, cache-urile, contoarele de rată și sesiunile. Utilizați un proxy invers cu verificări de stare sau mecanisme
de failover la nivel de client pentru disponibilitate activă/pasivă sau activă/activă și nu montați niciodată aceeași bază de date SQLite
în mai multe instanțe OmniRoute care rulează simultan.
### Rute dedicate furnizorilor
Direcționați solicitările direct către un anumit furnizor, cu validarea modelului:
```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
```
Prefixul furnizorului este adăugat automat dacă lipsește. Modelele incompatibile returnează `400`.
### Configurarea proxy-ului de rețea
```bash
# Configurarea proxy-ului global
curl -X PUT http://localhost:20128/api/settings/proxy \
-d '{"global": {"type":"http","host":"proxy.example.com","port":"8080"}}'
# Proxy per furnizor
curl -X PUT http://localhost:20128/api/settings/proxy \
-d '{"providers": {"openai": {"type":"socks5","host":"proxy.example.com","port":"1080"}}}'
# Testarea proxy-ului
curl -X POST http://localhost:20128/api/settings/proxy/test \
-d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}'
```
**Precedență:** Specific cheii → Specific combinației → Specific furnizorului → Global → Mediu.
### API-ul catalogului de modele
```bash
curl http://localhost:20128/api/models/catalog
```
Returnează modelele grupate după furnizor, împreună cu tipurile (`chat`, `embedding`, `image`).
### Sincronizare în cloud
- Sincronizați furnizorii, combinațiile și setările între dispozitive
- Sincronizare automată în fundal, cu expirare și oprire rapidă în caz de eroare
- Preferați `NEXT_PUBLIC_BASE_URL`/`NEXT_PUBLIC_CLOUD_URL` pe partea de server în producție
### Tunel rapid Cloudflare
- Disponibil în **Dashboard → Endpoints** pentru Docker și alte implementări auto-găzduite
- Creează un URL temporar `https://*.trycloudflare.com` care redirecționează către endpointul `/v1` curent, compatibil cu OpenAI
- La prima activare, instalează `cloudflared` numai când este necesar; repornirile ulterioare reutilizează același binar gestionat
- Tunelurile rapide nu sunt restaurate automat după repornirea OmniRoute sau a containerului; reactivați-le din tabloul de bord când este necesar
- URL-urile tunelurilor sunt efemere și se schimbă de fiecare dată când opriți/porniți tunelul
- Tunelurile rapide gestionate utilizează implicit transportul HTTP/2 pentru a evita avertismentele zgomotoase privind bufferul UDP QUIC în containerele cu resurse limitate
- Setați `CLOUDFLARED_PROTOCOL=quic` sau `auto` dacă doriți să suprascrieți alegerea gestionată a transportului
- Setați `CLOUDFLARED_BIN` dacă preferați să utilizați un binar `cloudflared` preinstalat în locul descărcării gestionate
- Panourile Cloudflare Quick Tunnel, Tailscale Funnel și ngrok Tunnel pot fi afișate sau ascunse în **Settings → Appearance**. Ascunderea unui panou nu oprește un tunel care rulează.
### Inteligența gateway-ului LLM (Faza 9)
- **Cache semantic** — Memorează automat în cache răspunsurile fără streaming, cu temperature=0 (ocoliți cu `X-OmniRoute-No-Cache: true`)
- **Idempotența cererilor** — Deduplică cererile într-un interval de 5s prin antetul `Idempotency-Key` sau `X-Request-Id`
- **Urmărirea progresului** — Evenimente SSE `event: progress` opționale prin antetul `X-OmniRoute-Progress: true`
---
### Spațiu de testare pentru traducător
Accesați prin **Dashboard → Translator**. Depanați și vizualizați modul în care OmniRoute traduce cererile API între furnizori.
| Mod | Scop |
| --------------------- | ------------------------------------------------------------------------------------------------------- |
| **Spațiu de testare** | Selectați formatele sursă/țintă, lipiți o cerere și vedeți instantaneu rezultatul tradus |
| **Tester de chat** | Trimiteți mesaje de chat live prin proxy și inspectați întregul ciclu cerere/răspuns |
| **Banc de testare** | Rulați teste în lot pentru mai multe combinații de formate, pentru a verifica corectitudinea traducerii |
| **Monitorizare live** | Urmăriți traducerile în timp real pe măsură ce cererile trec prin proxy |
**Cazuri de utilizare:**
- Depanați motivul pentru care o anumită combinație client/furnizor eșuează
- Verificați dacă etichetele de raționament, apelurile de instrumente și prompturile de sistem sunt traduse corect
- Comparați diferențele de format dintre formatele OpenAI, Claude, Gemini și Responses API
---
### Strategii de rutare
Configurați prin **Dashboard → Settings → Routing**. Tabloul de bord prezintă cele șase strategii utilizate cel mai frecvent; combinațiile și routerul automat acceptă intern un set mai larg.
**Strategii vizibile în tabloul de bord (rutare la nivel de cont):**
| Strategie | Descriere |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| **Umplere în ordine** | Utilizează conturile în ordinea priorității — contul principal gestionează toate cererile până devine indisponibil |
| **Round Robin** | Parcurge ciclic toate conturile, cu o limită configurabilă de persistență (implicit: 3 apeluri per cont) |
| **P2C (Puterea a două opțiuni)** | Alege 2 conturi aleatorii și rutează către cel mai sănătos — echilibrează încărcarea ținând cont de starea lor |
| **Aleatoriu** | Selectează aleatoriu un cont pentru fiecare cerere folosind amestecarea Fisher-Yates |
| **Cel mai puțin utilizat** | Rutează către contul cu cel mai vechi marcaj temporal `lastUsedAt`, distribuind traficul uniform |
| **Optimizat pentru cost** | Rutează către contul cu cea mai mică valoare a priorității, optimizând pentru furnizorii cu cel mai redus cost |
**Strategii avansate pentru combinații și rutare automată** (configurabile pentru fiecare combinație sau prin prefixe `auto/*` — consultați [AUTO-COMBO.md](../routing/AUTO-COMBO.md)):
- `priority` — ordine strictă, fără utilizarea strategiei round-robin
- `weighted` — împărțire proporțională a traficului în funcție de ponderile fiecărui model
- `fill-first` — utilizează primul model până la atingerea limitelor
- `round-robin` / `strict-random` / `random`
- `p2c` (Puterea a două opțiuni)
- `least-used` și `cost-optimized`
- `auto` — rutare bazată pe scor pentru toți candidații
- `lkgp` (Ultimul furnizor cunoscut ca funcțional) — menține rutarea către ultimul furnizor care a răspuns cu succes, apoi revine la reguli
- `context-optimized` — alege modelul cu cea mai mare fereastră de context liberă
- `context-relay` — înlănțuie modele cu context extins pentru interacțiunile ulterioare
#### Antet extern pentru sesiuni persistente
Pentru afinitatea externă a sesiunilor (de exemplu, agenți Claude Code/Codex aflați în spatele unor proxy-uri inverse), trimiteți:
```http
X-Session-Id: your-session-key
```
OmniRoute acceptă și `x_session_id` și returnează cheia efectivă a sesiunii în `X-OmniRoute-Session-Id`.
Dacă utilizați Nginx și trimiteți antete care conțin caractere de subliniere, activați:
```nginx
underscores_in_headers on;
```
#### Aliasuri de modele cu metacaractere
Creați tipare cu metacaractere pentru a remapa numele modelelor:
```
Tipar: claude-sonnet-* → Țintă: cc/claude-sonnet-4-6
Tipar: gpt-* → Țintă: gh/gpt-5.3-codex
```
Metacaracterele acceptă `*` (orice caractere) și `?` (un singur caracter).
#### Lanțuri de rezervă
Definiți lanțuri globale de rezervă care se aplică tuturor cererilor:
```
Lanț: production-fallback
1. cc/claude-opus-4-7
2. gh/gpt-5.3-codex
3. glm/glm-4.7
```
---
### Combinații uzuale de furnizori și modele de rutare
Mai jos sunt exemple de modele pentru combinarea mai multor furnizori și rutarea între aceștia în OmniRoute:
#### 1. Combinație pentru agenți de programare: raționament avansat cu soluție de rezervă pentru cost/viteză
Ideală pentru agenții de programare (OpenCode, Claude Code, Cursor, Cline). Rutează inițial către modele de raționament de ultimă generație, trecând la modele rapide pentru programare în cazul epuizării cotei sau apariției erorilor.
- **Tablou de bord**: Combos → New Combo → Name: `agent-coding` → Strategy: `Priority`
- **Modele**:
1. `claude/claude-sonnet-4-6` (Agent principal de programare)
2. `openai/gpt-4o` (Soluție de rezervă secundară, de mare capacitate)
3. `deepseek/deepseek-v4-flash` (Soluție de rezervă de înaltă eficiență și rentabilă)
```bash
# Exemplu prin API
curl -X POST http://localhost:20128/api/combos \
-H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "agent-coding",
"strategy": "priority",
"models": [
{ "model": "claude/claude-sonnet-4-6" },
{ "model": "openai/gpt-4o" },
{ "model": "deepseek/deepseek-v4-flash" }
]
}'
```
#### 2. Combinație cu failover automat pentru nivelul gratuit
Înlănțuie mai mulți furnizori cu nivel gratuit și fără cheie pentru a maximiza disponibilitatea fără costuri pentru API.
- **Strategie**: `Least Used` sau `Round Robin` (distribuie sarcina între cote)
- **Modele**:
1. `groq/llama-3.3-70b-versatile`
2. `gemini/gemini-2.5-flash`
3. `cerebras/gpt-oss-120b`
```bash
# Exemplu prin CLI
omniroute combo create free-stack \
--models "groq/llama-3.3-70b-versatile,gemini/gemini-2.5-flash,cerebras/gpt-oss-120b" \
--strategy round-robin
```
#### 3. Flux multimodal / de procesare a imaginilor și textului
Asocierea modelelor specializate în procesarea imaginilor cu generarea de text de mare viteză pentru fluxuri de lucru care implică înțelegerea imaginilor și generarea de cod.
- **Model de utilizare**: O combinație `Priority` care listează mai întâi modelele capabile să proceseze imagini și la final un model cu debit ridicat pentru text/cod.
- **Modele**:
1. `gemini/gemini-2.5-pro` (Înțelegere avansată a imaginilor și a conținutului multimodal)
2. `openai/gpt-4o` (Procesare echilibrată a imaginilor și utilizare a instrumentelor)
3. `deepseek/deepseek-v4-flash` (Generare de text/cod)
---
### Reziliență și întrerupătoare de circuit
Configurați prin **Panou de control → Setări → Reziliență**.
OmniRoute implementează reziliența la nivel de furnizor prin cinci componente:
1. **Coadă de solicitări și ritmare** — Modelarea solicitărilor la nivel de sistem:
- **Solicitări pe minut (RPM)** — Numărul maxim de solicitări pe minut pentru fiecare cont
- **Timp minim între solicitări** — Intervalul minim, în milisecunde, dintre solicitări
- **Număr maxim de solicitări simultane** — Numărul maxim de solicitări simultane pentru fiecare cont
2. **Perioadă de așteptare a conexiunii** — Configurare pentru fiecare tip de autentificare al unei singure conexiuni, după erori care permit reîncercarea:
- **Perioadă de așteptare de bază** — Fereastra implicită de așteptare pentru erorile serviciilor din amonte care permit reîncercarea
- **Utilizarea indicațiilor de reîncercare din amonte** — Respectă indicațiile furnizate de sursa autorizată prin `Retry-After` sau cele de resetare, atunci când sunt disponibile
- **Număr maxim de pași pentru temporizare progresivă** — Nivelul maxim de temporizare exponențială pentru erori repetate
3. **Întrerupătorul de circuit al furnizorului** — Urmărește erorile complete ale furnizorului, marchează un furnizor ca degradat la atingerea pragului de avertizare configurat și deschide întrerupătorul când este atins pragul de eroare configurat:
- **Prag de degradare** — Numărul de erori consecutive ale furnizorului înainte de intrarea în starea `DEGRADED`
- **Prag de eroare** — Numărul de erori consecutive ale furnizorului înainte de intrarea în starea `OPEN`
- **Timp de așteptare pentru resetare** — Intervalul de timp înainte ca furnizorul să fie testat din nou
- **CLOSED** (Funcțional) — Solicitările sunt procesate normal
- **DEGRADED** — Solicitările continuă să fie procesate în timp ce este monitorizat numărul crescut de erori
- **OPEN** — Furnizorul este blocat temporar după erori repetate
- **HALF_OPEN** — Se testează dacă furnizorul și-a revenit
Limitările de rată `429` aferente conexiunilor rămân în **Perioada de așteptare a conexiunii** și nu sunt luate în calcul de întrerupătorul furnizorului.
Starea de execuție a întrerupătorului furnizorului este afișată numai în **Panou de control → Stare de funcționare**.
4. **Așteptarea încheierii perioadei de așteptare** — Dacă toate conexiunile candidate se află deja într-o perioadă de așteptare, OmniRoute poate aștepta încheierea celei mai apropiate perioade și poate reîncerca automat aceeași solicitare a clientului.
5. **Detectarea automată a limitării ratei** — Când furnizorii din amonte returnează ferestre explicite de așteptare, aceste indicații suprascriu perioada locală de așteptare a conexiunii dacă setarea este activată.
**Sfat util:** Utilizați pagina **Stare de funcționare** pentru a inspecta și reseta întrerupătoarele active ale furnizorilor după o întrerupere. Pagina Reziliență modifică numai configurația.
---
### Exportarea/importarea bazei de date
Gestionați copiile de rezervă ale bazei de date în **Panou de control → Setări → Sistem și stocare**.
| Acțiune | Descriere |
| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Exportarea bazei de date** | Descarcă baza de date SQLite curentă ca fișier `.sqlite` |
| **Exportarea completă (.tar.gz)** | Descarcă o arhivă completă de rezervă care include: baza de date, setările, combinațiile, conexiunile furnizorilor (fără date de autentificare), metadatele cheilor API |
| **Importarea bazei de date** | Încarcă un fișier `.sqlite` pentru a înlocui baza de date curentă. O copie de rezervă anterioară importului este creată automat, cu excepția cazului în care `DISABLE_SQLITE_AUTO_BACKUP=true` |
```bash
# API: Exportarea bazei de date
curl -o backup.sqlite http://localhost:20128/api/db-backups/export
# API: Exportarea completă (arhivă completă)
curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll
# API: Importarea bazei de date
curl -X POST http://localhost:20128/api/db-backups/import \
-F "file=@backup.sqlite"
```
**Validarea importului:** Fișierul importat este validat în privința integrității (verificare prin pragma SQLite), a tabelelor obligatorii (`provider_connections`, `provider_nodes`, `combos`, `api_keys`) și a dimensiunii (maximum 100 MB).
**Cazuri de utilizare:**
- Migrarea OmniRoute între sisteme
- Crearea unor copii de rezervă externe pentru recuperarea în caz de dezastru
- Partajarea configurațiilor între membrii echipei (exportare completă → partajarea arhivei)
---
### Panoul de control pentru setări
Pagina de setări este organizată în **7 file** pentru o navigare ușoară:
| Filă | Conținut |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Generale** | Instrumente de stocare ale sistemului, comportament implicit, vizibilitatea tunelurilor Endpoint |
| **Aspect** | Controale pentru temă (luminoasă/întunecată/sistem), vizibilitatea barei laterale, comutatoare de panou pentru cardurile tunelurilor Cloudflare/Tailscale/ngrok |
| **IA** | Buget de raționare (transmitere / eliminare automată / personalizat / adaptiv — consultați [THINKING_BUDGET.md](./THINKING_BUDGET.md)), prompt global de sistem, statistici cache pentru prompturi |
| **Securitate** | Setări de autentificare/parolă, controlul accesului IP, autentificare API pentru `/models`, blocarea furnizorilor, protecție împotriva injectării de prompturi |
| **Rutare** | Strategie globală de rutare (Completare prioritară / Round Robin / P2C / Aleatoriu / Cel mai puțin utilizat / Optimizat pentru cost), aliasuri de modele cu metacaractere, lanțuri de rezervă, valori implicite pentru combinații |
| **Reziliență** | Coadă de cereri, perioadă de așteptare pentru conexiuni, configurarea întrerupătorului pentru furnizori și comportamentul de așteptare a perioadei de răcire |
| **Avansate** | Configurarea globală a proxy-ului (HTTP/SOCKS5), suprascrieri ale proxy-ului pentru fiecare furnizor |
Secțiunea Generale nu mai duplică notele doar în citire privind jurnalizarea și memoria cache. Setările pentru păstrarea și
optimizarea bazei de date sunt salvate prin `/api/settings/database`; golirea manuală a memoriei cache utilizează
`DELETE /api/cache`. Limitele numărului de rânduri pentru jurnalele de cereri și proxy sunt controlate de
`CALL_LOGS_TABLE_MAX_ROWS` și `PROXY_LOGS_TABLE_MAX_ROWS`.
---
### Gestionarea costurilor și a bugetelor
Accesați prin **Panou de control → Costuri**.
| Filă | Scop |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------- |
| **Buget** | Setați limite de cheltuieli pentru fiecare cheie API, cu bugete zilnice/săptămânale/lunare și monitorizare în timp real |
| **Prețuri** | Vizualizați și editați intrările de preț pentru modele — cost per 1.000 de tokenuri de intrare/ieșire pentru fiecare furnizor |
```bash
# API: Setați un buget
curl -X POST http://localhost:20128/api/usage/budget \
-H "Content-Type: application/json" \
-d '{"keyId": "key-123", "limit": 50.00, "period": "monthly"}'
# API: Obțineți starea actuală a bugetului
curl http://localhost:20128/api/usage/budget
```
**Monitorizarea costurilor:** Fiecare cerere înregistrează utilizarea tokenurilor și calculează costul folosind tabelul de prețuri. Vizualizați defalcările în **Panou de control → Utilizare**, după furnizor, model și cheie API.
---
### Transcriere audio
OmniRoute acceptă transcrierea audio prin endpointul compatibil OpenAI:
```bash
POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data
# Exemplu cu 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` este ruta nativă Deepgram și necesită o cheie API Deepgram.
Dacă este configurat numai OpenRouter, utilizați `openrouter/deepgram/nova-3`.
Furnizori pentru **conversia vorbirii în text (transcriere)**:
- `openai/` (compatibil cu Whisper)
- `groq/` (Groq Whisper Turbo)
- `deepgram/` (familia Nova)
- `assemblyai/`
- `nvidia/` (Parakeet, Canary)
- `huggingface/` (variante Whisper)
- `qwen/`
Furnizori pentru **conversia textului în vorbire (`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/`
Formate audio acceptate pentru transcriere: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. Formatele de ieșire TTS depind de furnizor (mp3, wav, opus, pcm, mulaw).
---
### Strategii de echilibrare a combinațiilor
Configurați echilibrarea pentru fiecare combinație în **Panou de control → Combinații → Creare/Editare → Strategie**.
| Strategie | Descriere |
| -------------------------- | ------------------------------------------------------------------------------------------ |
| **Round-Robin** | Parcurge modelele secvențial |
| **Prioritate** | Încearcă întotdeauna primul model; recurge la rezervă numai în caz de eroare |
| **Aleatoriu** | Alege un model aleatoriu din combinație pentru fiecare cerere |
| **Ponderat** | Rutează proporțional pe baza ponderilor atribuite fiecărui model |
| **Cel mai puțin utilizat** | Rutează către modelul cu cele mai puține cereri recente (utilizează metricile combinației) |
| **Optimizat pentru cost** | Rutează către cel mai ieftin model disponibil (utilizează tabelul de prețuri) |
Valorile implicite globale pentru combinații pot fi setate în **Panou de control → Setări → Rutare → Valori implicite pentru combinații**.
În mod implicit, timpii de expirare ai țintelor combinației moștenesc timpul de expirare curent al cererii. Utilizați **Timp de expirare al țintei
(secunde)** în valorile implicite pentru combinații sau într-o combinație individuală numai atunci când o limită mai scurtă pentru fiecare țintă ar trebui
să declanșeze mai rapid trecerea la rezerva următoare.
Optimizările cu latență zero sunt opționale. Lăsați **Optimizări cu latență zero** dezactivate pentru
a împiedica aceste funcționalități de latență să lanseze în paralel țintele de rezervă, să omită ținte pe baza istoricului
TTFT sau să comprime cererile de rezervă; activarea permite lansarea speculativă configurată, omiterile predictive bazate pe TTFT
și comprimarea proactivă a rezervelor, sacrificând fidelitatea rutării/cererii în favoarea unei latențe de coadă mai mici.
Dezactivați **Memoria tampon pentru tokenuri de raționament** atunci când furnizorii din amonte impun limite stricte pentru
`max_tokens` / `maxOutputTokens`. Când este activată, rutarea combinată adaugă spațiu suplimentar pentru modelele de raționament
doar în cazul modelelor cu o limită de ieșire cunoscută și lasă neschimbată limita de tokenuri a clientului atunci când
valoarea sigură cu memorie tampon ar depăși limita respectivă. Dacă limita clientului depășește deja o limită cunoscută,
OmniRoute o reduce la acea limită înainte de a trimite cererea în amonte.
---
### Panoul de monitorizare a stării
Accesați-l prin **Panou de control → Stare**. Prezentare generală în timp real a stării sistemului, cu 6 carduri:
| Card | Ce afișează |
| ----------------------- | ------------------------------------------------------------------------------------ |
| **Starea sistemului** | Timpul de funcționare, versiunea, utilizarea memoriei, directorul de date |
| **Starea furnizorilor** | Starea de execuție a întrerupătorului global de circuit al furnizorilor |
| **Limite de rată** | Perioadele de așteptare active ale conexiunilor pentru fiecare cont, cu timpul rămas |
| **Blocări active** | Blocările active specifice modelelor și excluderile temporare |
| **Cache de semnături** | Statisticile cache-ului de deduplicare (chei active, rata de accesări) |
| **Telemetria latenței** | Agregarea latenței p50/p95/p99 pentru fiecare furnizor |
**Sfat util:** Pagina Stare se reîmprospătează automat la fiecare 10 secunde. Utilizați cardul întrerupătorului de circuit pentru a identifica furnizorii care întâmpină probleme.
---
## 🤖 Rutare automată (fără configurare)
OmniRoute include un **router automat bazat pe scoruri**, care alege cel mai bun model pentru fiecare solicitare dintre toți furnizorii conectați — fără combinații de întreținut. Trimiteți pur și simplu solicitarea folosind unul dintre prefixele `auto/*`, iar OmniRoute va asambla dinamic o combinație virtuală, evaluând candidații în funcție de latență, cost, rata de succes, compatibilitatea cu dimensiunea contextului, adecvarea modelului pentru sarcină, eșecurile recente, cotă și starea mecanismului de întrerupere a circuitului.
| Prefix | Optimizează pentru |
| -------------- | -------------------------------------------------------------------------------------------------------------- |
| `auto` | Opțiune implicită echilibrată (latență × cost × rata de succes) |
| `auto/coding` | Sarcini de programare: preferă Claude, GPT-5, GLM, Kimi, Qwen Coder, programatoarele DeepSeek |
| `auto/cheap` | Cel mai mic cost per token, acceptă o latență mai mare |
| `auto/fast` | Cea mai mică latență, ignoră costul |
| `auto/offline` | Numai furnizori locali (Ollama, vLLM, llama.cpp) — util pentru configurații izolate de rețea |
| `auto/smart` | Calitatea raționamentului pe primul loc (Opus, GPT-5 xhigh, R1, raționament GLM 5.1) |
| `auto/lkgp` | „Ultimul furnizor cunoscut ca funcțional” — fixează ultimul furnizor utilizat cu succes, apoi revine la reguli |
Exemplu:
```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": "Refactorizați această funcție Python" }],
"stream": true
}'
```
Routerul automat este descris în detaliu în [AUTO-COMBO.md](../routing/AUTO-COMBO.md) — inclusiv modul de ajustare a ponderilor de evaluare, de adăugare a furnizorilor pe lista neagră și de inspectare a deciziilor de rutare în **Panou de control → Combinație automată**.
---
## 🔌 Integrare MCP și A2A
OmniRoute este atât un **server MCP** (Model Context Protocol), cât și un **server A2A** (JSON-RPC 2.0 între agenți). Orice IDE sau gazdă de agenți compatibilă cu MCP poate apela direct instrumentele OmniRoute — fără a necesita un wrapper suplimentar.
### Transporturi MCP
- **SSE**: `http://localhost:20128/api/mcp/sse`
- **HTTP cu streaming**: `http://localhost:20128/api/mcp/stream`
- **stdio**: `omniroute --mcp` (pentru pluginurile IDE care preferă stdio)
### Conectarea Claude Desktop
Editați `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) sau fișierul echivalent pe Windows/Linux:
```json
{
"mcpServers": {
"omniroute": {
"command": "omniroute",
"args": ["--mcp"]
}
}
}
```
### Conectarea Cursor / Continue / VS Code MCP
Utilizați URL-ul SSE `http://localhost:20128/api/mcp/sse` și o cheie API Bearer generată în **Panou de control → Chei API**.
### Domenii de acces
MCP definește în prezent 32 de domenii de acces denumite. Fiecare cheie Bearer poate fi limitată la anumite domenii de acces — consultați [MCP-SERVER.md](../frameworks/MCP-SERVER.md) pentru lista oficială a domeniilor de acces și a instrumentelor și [A2A-SERVER.md](../frameworks/A2A-SERVER.md) pentru schema JSON-RPC.
---
## 🧠 Sistemul de abilități
OmniRoute oferă un **cadru extensibil pentru abilități** (`src/lib/skills/`), astfel încât agenții și endpointul A2A să poată executa rutine specifice domeniului (de exemplu, `code-review`, `summarize`, `extract-facts`, `web-research`).
- **Interfață Marketplace** — Răsfoiți și instalați abilități din **Panou de control → Abilități**
- **Domenii per cheie** — Restricționați abilitățile pe care le poate invoca fiecare cheie API
- **Abilități personalizate** — Adăugați un fișier TypeScript în `src/lib/a2a/skills/`, înregistrați-l și acesta devine imediat invocabil prin A2A
Referință completă: [SKILLS.md](../frameworks/SKILLS.md).
---
## 💾 Sistemul de memorie
OmniRoute păstrează **memoria conversațională pe termen lung** folosind regăsirea hibridă:
- **SQLite FTS5** pentru căutarea după cuvinte-cheie în interacțiunile anterioare
- **Depozit vectorial Qdrant** (opțional) pentru regăsirea semantică
- **Extragere automată a faptelor** — entitățile, preferințele și deciziile sunt rezumate după fiecare sesiune și stocate în tabelul `memory_facts`
- Memoriile sunt delimitate pentru fiecare cheie API și fiecare sesiune
Gestionați memoriile în **Panou de control → Memorie** (căutare, editare, exportare, ștergere). Interfața HTTP (`/api/memory/*`) permite agenților să trimită și să interogheze fapte în mod programatic — consultați [MEMORY.md](../frameworks/MEMORY.md).
---
## 🔔 Webhookuri
Abonați-vă la evenimentele OmniRoute pentru monitorizare și automatizare în timp real.
- Creați un webhook în **Panou de control → Webhookuri**, folosind URL-ul țintă și secretul de semnare HMAC
- Evenimente disponibile: `request.completed`, `request.failed`, `provider.unavailable`, `budget.exceeded`, `combo.switched`, `circuit_breaker.opened`, `circuit_breaker.closed`
- Fiecare sarcină utilă include `X-OmniRoute-Signature` (HMAC-SHA256) pentru verificare
- Reîncercări: 3 încercări cu întârziere exponențială, urmate de trimiterea în coada pentru mesaje nelivrate
Schema completă este disponibilă în [WEBHOOKS.md](../frameworks/WEBHOOKS.md).
---
## ☁️ Agenți în cloud
OmniRoute se integrează cu agenți de programare în cloud (**OpenAI Codex Cloud**, **Devin**, **Jules**, **Antigravity**), astfel încât să puteți expedia sarcini de lungă durată din același panou de control care gestionează rutarea locală.
- Creați sarcini în **Panou de control → Agenți în cloud** sau prin `POST /api/v1/agents/tasks`
- Urmăriți starea, jurnalele și artefactele fiecărei sarcini
- Folosiți propria cheie API pentru fiecare furnizor — datele de autentificare nu părăsesc niciodată instanța OmniRoute
Referință completă: [CLOUD_AGENT.md](../frameworks/CLOUD_AGENT.md).
---
## 🛠️ Gestionare programatică
Puteți gestiona fiecare resursă OmniRoute (furnizori, combinații, chei, setări) prin HTTP, utilizând o **cheie Bearer cu domeniul `manage`**.
Generați cheia în **Panou de control → Chei API → Cheie nouă → Domeniu: manage**, apoi:
```bash
# Listează furnizorii
curl http://localhost:20128/api/providers \
-H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY"
# Adaugă o conexiune la un furnizor
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" }'
# Creează o combinație
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" }] }'
# Listează/creează chei 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"] }'
```
Consultați [API_REFERENCE.md](../reference/API_REFERENCE.md) pentru catalogul complet de endpointuri și schemele solicitărilor/răspunsurilor.
---
## 💻 CLI intern
OmniRoute include un CLI intern (`omniroute …`) pentru configurare, diagnosticare și control în timpul rulării. Acesta este **separat de pagina „Instrumente CLI” din panoul de control**, care configurează CLI-uri terțe (Claude Code, Cursor, Codex, Cline, …), astfel încât acestea să poată comunica cu OmniRoute.
```bash
omniroute setup # Expert interactiv (parolă, furnizori, combinații)
omniroute setup --non-interactive # Adecvat pentru CI
omniroute doctor # Diagnosticarea stării (director de date, BD, furnizori, porturi)
omniroute providers available # Listează furnizorii acceptați
omniroute providers list # Listează conexiunile configurate
omniroute providers test # Testează în timp real conexiunea unui furnizor
omniroute combos list # Listează combinațiile
omniroute combos switch # Setează combinația implicită
omniroute models # Listează modelele disponibile (--json, --search)
omniroute keys add | list | remove # Gestionează cheile API din terminal
omniroute backup # Creează un instantaneu al configurației + BD
omniroute restore [] # Restaurează dintr-un instantaneu
omniroute health # Stare detaliată (întrerupătoare, cache, memorie)
omniroute quota # Utilizarea cotei furnizorului
omniroute mcp status # Starea serverului MCP
omniroute a2a status # Starea serverului A2A
omniroute tunnel list|create|stop # Tuneluri Cloudflare/Tailscale/ngrok
omniroute reset-password # Resetează parola de administrator
omniroute --mcp # Pornește serverul MCP prin stdio
omniroute --port 3000 # Pornește serverul pe un port personalizat
```
Sfat: utilizați `omniroute doctor --json` împreună cu instrumentul dumneavoastră de monitorizare pentru a primi alerte privind conexiunile nesănătoase ale furnizorilor.
---
## 🖥️ Aplicație desktop (Electron)
OmniRoute este disponibil ca aplicație desktop nativă pentru Windows, macOS și Linux.
### Instalare
```bash
# Din directorul electron:
cd electron
npm install
# Mod de dezvoltare (se conectează la serverul de dezvoltare Next.js care rulează):
npm run dev
# Mod de producție (utilizează versiunea autonomă):
npm start
```
### Crearea programelor de instalare
```bash
cd electron
npm run build # Platforma curentă
npm run build:win # Windows (.exe NSIS)
npm run build:mac # macOS (.dmg universal)
npm run build:linux # Linux (.AppImage)
```
Rezultat → `electron/dist-electron/`
### Funcționalități principale
| Funcționalitate | Descriere |
| ----------------------------------------- | -------------------------------------------------------------------------------------- |
| **Disponibilitatea serverului** | Interoghează serverul înainte de afișarea ferestrei (fără ecran gol) |
| **Zona de notificare** | Minimizare în zona de notificare, schimbarea portului și închidere din meniul acesteia |
| **Gestionarea portului** | Schimbă portul serverului din zona de notificare (repornește automat serverul) |
| **Politica de securitate a conținutului** | CSP restrictivă prin anteturile sesiunii |
| **Instanță unică** | Poate rula o singură instanță a aplicației simultan |
| **Mod offline** | Serverul Next.js inclus funcționează fără internet |
### Variabile de mediu
| Variabilă | Valoare implicită | Descriere |
| --------------------- | ----------------- | -------------------------------------- |
| `OMNIROUTE_PORT` | `20128` | Portul serverului |
| `OMNIROUTE_MEMORY_MB` | `512` | Limita heap-ului Node.js (64–16384 MB) |
📖 Documentație completă: [`electron/README.md`](../../electron/README.md)