# User Guide (Igbo)
🌐 **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) · 🇮🇹 [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) · 🇧🇬 [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) · 🇮🇹 [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)
Nduzi zuru ezu maka ịhazi ndị na-enye ọrụ, imepụta combo, ijikọ ngwa CLI, na ibunye OmniRoute.
---
## Ndepụta Ihe Dị n’Ime
- [Ọnụahịa na Nlele Ngwa Ngwa](#-pricing-at-a-glance)
- [Ọnọdụ Ojiji](#-use-cases)
- [Nhazi Provider](#-provider-setup)
- [Njikọ CLI](#-cli-integration)
- [Mbugharị](#-deployment)
- [Ụdị Model Dị](#-available-models)
- [Atụmatụ Dị Elu](#-advanced-features)
- [Auto-Routing (Nhazi efu)](#-auto-routing-zero-config)
- [Njikọ MCP & A2A](#-mcp--a2a-integration)
- [Sistemụ Skills](#-skills-system)
- [Sistemụ Memory](#-memory-system)
- [Webhooks](#-webhooks)
- [Cloud Agents](#-cloud-agents)
- [Nlekọta Site na Mmemme](#-programmatic-management)
- [CLI Dị n’Ime](#-internal-cli)
- [Ngwa Desktop (Electron)](#-desktop-application-electron)
---
## 💰 Ọnụahịa na Nlele Ngwa Ngwa
| Ọkwa | Provider | Ọnụahịa | Ntọgharị Quota | Nke Ọ Kachasị Mma Maka |
| ------------------- | ----------------- | -------------------- | -------------------------- | --------------------------- |
| **💳 NDEBANYE AHA** | Claude Code (Pro) | $20/ọnwa | 5h + kwa izu | Ndị debanyerela aha |
| | Codex (Plus/Pro) | $20-200/ọnwa | 5h + kwa izu | Ndị ọrụ OpenAI |
| | GitHub Copilot | $10-19/ọnwa | Kwa ọnwa | Ndị ọrụ GitHub |
| **🔑 API KEY** | DeepSeek | Kwụọ ka i si jiri ya | Enweghị | Ntụgharị uche dị ọnụ ala |
| | Groq | Kwụọ ka i si jiri ya | Enweghị | Inference dị oke ọsọ |
| | xAI (Grok) | Kwụọ ka i si jiri ya | Enweghị | Ntụgharị uche Grok 4 |
| | Mistral | Kwụọ ka i si jiri ya | Enweghị | Model ndị a na-akwado na EU |
| | Perplexity | Kwụọ ka i si jiri ya | Enweghị | Nke ọchụchọ kwalitere |
| | Together AI | Kwụọ ka i si jiri ya | Enweghị | Model ndị open-source |
| | Fireworks AI | Kwụọ ka i si jiri ya | Enweghị | Onyonyo FLUX dị ọsọ |
| | Cerebras | Kwụọ ka i si jiri ya | Enweghị | Ọsọ wafer-scale |
| | Cohere | Kwụọ ka i si jiri ya | Enweghị | Command R+ RAG |
| | NVIDIA NIM | Kwụọ ka i si jiri ya | Enweghị | Model ụlọ ọrụ |
| | Baidu Qianfan | Kwụọ ka i si jiri ya | Enweghị | Model ERNIE |
| **💰 ỌNỤ ALA** | GLM-4.7 | $0.6/1M | Kwa ụbọchị n’elekere 10AM | Ndabere mmefu ego |
| | MiniMax M2.1 | $0.2/1M | Ọ na-atụgharị kwa awa 5 | Nhọrọ kacha ọnụ ala |
| | Kimi K2 | $9/ọnwa kpọmkwem | 10M tokens/ọnwa | Ọnụahịa a pụrụ ibu amụma |
| **🆓 N’EFU** | Qoder | $0 | Oke provider na-emetụta ya | Nyochaa katalọgụ dị ugbu a |
| | Kiro | $0 | ~50 credits/ọnwa | Claude n’efu |
---
## 🎯 Ọnọdụ Ojiji
### Ọnọdụ 1: "Enwere m ndenye aha Claude Pro"
**Nsogbu:** Quota na-ekubi ume n’ejighị ya, a na-enwe oke ọnụego n’oge ide code siri ike
```
Ngwakọta: "maximize-claude"
1. cc/claude-opus-4-7 (jiri ndenye aha ahụ mee ihe n’uju)
2. glm/glm-4.7 (ndabere dị ọnụ ala mgbe quota gwụrụ)
3. if/qwen3.8-max-preview (ndabere mberede n’efu)
Ọnụahịa kwa ọnwa: $20 (ndenye aha) + ~$5 (ndabere) = $25 n’ozuzu
ma e jiri ya tụnyere $20 + iru oke = iwe
```
### Ọnọdụ 2: "Achọrọ m ka ọ ghara ịdị ọnụ"
**Nsogbu:** Enweghị m ike ịkwụ ụgwọ ndenye aha, achọrọ m AI a pụrụ ịdabere na ya maka ide code
```
Ngwakọta: "zero-cost"
1. if/kimi-k2.7-code (edepụtara nnweta n’efu; oke ọnụego nwere ike ịdị)
2. kr/qwen3-coder-next (ndabere Kiro n’efu)
Ọnụahịa kwa ọnwa: $0
Ogo: nyochaa model ahụ, oke ya, nzuzo ya, na SLA ya maka ibu ọrụ gị
```
### Ọnọdụ 3: "Achọrọ m ide code 24/7, na-enweghị nkwụsị"
**Nsogbu:** Oge ngwụcha ọrụ, enweghị m ike ịnabata oge sistemụ anaghị arụ ọrụ
```
Ngwakọta: "always-on"
1. cc/claude-opus-4-7 (ogo kacha mma)
2. cx/gpt-5.5 (ndenye aha nke abụọ)
3. glm/glm-4.7 (dị ọnụ ala, na-atụgharị kwa ụbọchị)
4. minimax/MiniMax-M2.1 (kacha ọnụ ala, ntọgharị 5h)
5. if/deepseek-v4-flash (edepụtara nnweta n’efu; oke ọnụego nwere ike ịdị)
Nsonaazụ: Ọkwa ndabere 5 na-eme ka nkwụsi ike gbasaa; anaghị ekwe nkwa nnweta sitere n’aka ndị na-enye ọrụ elu
Ọnụahịa kwa ọnwa: $20-200 (ndenye aha) + $10-20 (ndabere)
```
### Ọnọdụ 4: "Achọrọ m AI N’EFU na OpenClaw"
**Nsogbu:** Achọrọ m onye enyemaka AI n’ime ngwa izipu ozi, n’efu kpamkpam
```
Ngwakọta: "openclaw-free"
1. if/qwen3.8-max-preview (edepụtara nnweta n’efu; oke ọnụego nwere ike ịdị)
2. if/deepseek-v4-flash (edepụtara nnweta n’efu; oke ọnụego nwere ike ịdị)
3. if/kimi-k2.7-code (edepụtara nnweta n’efu; oke ọnụego nwere ike ịdị)
Ọnụahịa kwa ọnwa: $0
Nweta site na: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
```
---
## 📖 Nhazi Ndị Na-enye Ọrụ
Iji tinye ọtụtụ njikọ igodo API n'otu oge site na faịlụ CSV ma ọ bụ JSON, jiri **Ogwe njikwa → Ndị na-enye ọrụ → Bubata site na faịlụ**. A na-ahazi kọlụm dịka ọnọdụ ha si dị (`provider,name,apiKey,baseUrl,priority`); `provider` ga-adịrịrị dịka onye na-enye ọrụ a na-achịkwa ma ọ bụ node dakọtara. Hụ [Bubata ndị na-enye ọrụ site na faịlụ CSV ma ọ bụ JSON](../providers/CSV-IMPORT.md).
### 🔐 Ndị Na-enye Ọrụ Ndebanye Aha
#### Claude Code (Pro/Max)
```bash
Ogwe njikwa → Ndị na-enye ọrụ → Jikọọ Claude Code
→ Nbanye OAuth → Mmelite token akpaka
→ Nnyocha oke ojiji awa 5 + kwa izu
Ụdị:
cc/claude-opus-4-7
cc/claude-sonnet-4-6
cc/claude-haiku-4-5-20251001
```
**Ndụmọdụ Ọkachamara:** Jiri Opus maka ọrụ ndị gbagwojuru anya, Sonnet maka ọsọ. OmniRoute na-enyocha oke ojiji maka ụdị ọ bụla!
Ụzọ ndị dakọtara na Claude na Claude Code na-echekwa mbọ iche echiche `max` maka ụdị Opus na Sonnet. Ụdị Haiku anaghị anabata ọkwa mbọ `max`, ya mere OmniRoute na-ewedata arịrịọ ahụ gaa na oke mmefu iche echiche dị elu tupu o ziga ya n'elu usoro.
#### OpenAI Codex (Plus/Pro)
```bash
Ogwe njikwa → Ndị na-enye ọrụ → Jikọọ Codex
→ Nbanye OAuth (ọdụ ụgbọ mmiri 1455)
→ Ntọgharị awa 5 + kwa izu
Ụdị:
cx/gpt-5.5
cx/gpt-5.4
cx/gpt-5.3-codex
cx/gpt-5.3-codex-spark
```
#### GitHub Copilot
```bash
Ogwe njikwa → Ndị na-enye ọrụ → Jikọọ GitHub
→ OAuth site na GitHub
→ Ntọgharị kwa ọnwa (ụbọchị mbụ nke ọnwa)
Ụdị:
gh/gpt-5.5
gh/gpt-5.4
gh/claude-sonnet-4.6
gh/claude-opus-4.7
gh/gemini-3.1-pro-preview
```
### 💰 Ndị Na-enye Ọrụ Dị Ọnụ Ala
#### GLM-4.7 (Ntọgharị kwa ụbọchị, $0.6/1M)
1. Debanye aha: [Zhipu AI](https://open.bigmodel.cn)
2. Nweta igodo API site na Coding Plan
3. Ogwe njikwa → Tinye Igodo API: Onye na-enye ọrụ: `glm`, Igodo API: `your-key`
**Ojiji:** `glm/glm-4.7` — **Ndụmọdụ Ọkachamara:** Coding Plan na-enye oke ojiji 3× na 1/7 nke ọnụ ahịa! Ọ na-atọgharị kwa ụbọchị n'elekere 10:00 nke ụtụtụ.
#### MiniMax M2.1 (Ntọgharị awa 5, $0.20/1M)
1. Debanye aha: [MiniMax](https://www.minimax.io)
2. Nweta igodo API → Ogwe njikwa → Tinye Igodo API
**Ojiji:** `minimax/MiniMax-M2.1` — **Ndụmọdụ Ọkachamara:** Nhọrọ kachasị ọnụ ala maka context ogologo (token 1M)!
#### Kimi K2 ($9/ọnwa n'ọnụ ahịa kwụ ọtọ)
1. Debanye aha na ọrụ ahụ: [Moonshot AI](https://platform.kimi.ai?aff=omniroute)
2. Nweta igodo API → Ogwe njikwa → Tinye Igodo API
**Ojiji:** `kimi/kimi-k2.5` — **Ndụmọdụ Ọkachamara:** $9/ọnwa kwụ ọtọ maka token 10M = ọnụ ahịa dị irè nke $0.90/1M!
#### Baidu Qianfan / ERNIE
1. Debanye aha: [Baidu AI Cloud Qianfan](https://cloud.baidu.com/product/wenxinworkshop)
2. Mepụta igodo API Qianfan → Ogwe njikwa → Tinye Igodo API: Onye na-enye ọrụ: `qianfan`
**Ojiji:** `qianfan/ernie-5.1`, `qianfan/ernie-x1.1`, ma ọ bụ ID ụdị Qianfan ọzọ dakọtara na OpenAI.
### 🆓 Ndị Na-enye Ọrụ N'EFU
Ndị na-enye ọrụ efu na-achọghị nkwenye njirimara nwere mgba ọkụ n'akụkụ **Achọghị nkwenye njirimara** na ibe onye na-enye ọrụ ha.
Ịgbanyụ ya na-eme ka onye na-enye ọrụ ahụ kwụsị ịrụ ọrụ, na-ewepụ ya na nlele Ndị na-enye ọrụ ahaziri/kọmpat, ma
na-ewepụ ụdị ya na `/v1/models`.
#### Qoder (ụdị 9 N'EFU)
```bash
Ogwe njikwa → Jikọọ Qoder → Nbanye OAuth → Ịnweta ya dabere na oke onye na-enye ọrụ dị ugbu a
Ụdị: 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 N'EFU)
```bash
Ogwe njikwa → Jikọọ Kiro → AWS Builder ID ma ọ bụ Google/GitHub → ~kredit 50/ọnwa
Ụdị: kr/claude-sonnet-4.5, kr/claude-haiku-4.5
```
---
## 🎨 Ngwakọta
Ị nwere ike ịhazigharị kaadị ngwakọta ozugbo na **Dashboard → Combos** site n’ịdọrọ aka njide dị na kaadị ọ bụla. A na-echekwa usoro ahụ na SQLite ma weghachite ya mgbe ebughachiri ibe ahụ ọzọ.
### Ọmụmaatụ 1: Mee Ka Ndebanye Aha Ruo Oke → Nkwado Ndabere Dị Ọnụ Ala
```
Dashboard → Combos → Mepụta Nke Ọhụrụ
Aha: premium-coding
Ụdị:
1. cc/claude-opus-4-7 (Ndebanye aha bụ isi)
2. glm/glm-4.7 (Nkwado ndabere dị ọnụ ala, $0.6/1M)
3. minimax/MiniMax-M2.7 (Nhọrọ ikpeazụ kacha dị ọnụ ala, $0.3/1M)
Jiri na CLI: premium-coding
```
### Ọmụmaatụ 2: Naanị Nke Efughị Ego (Ọnụ Ahịa Efughị Ihe)
```
Aha: free-combo
Ụdị:
1. if/kimi-k2.7-code (edepụtara na enwere ike iji ya n’efu; oke onye na-eweta ọrụ nwere ike ịdị)
2. kr/qwen3-coder-next (Nhọrọ ndabere Kiro n’efu)
Ọnụ ahịa: edepụtara ugbu a dị ka $0; usoro na nnweta nwere ike ịgbanwe
```
---
## 🔧 Njikọta CLI
### Cursor IDE
**Iji Cursor dịka onye ahịa OmniRoute** (zipụ nkata Cursor site na OmniRoute):
```
Ntọala → Ụdị → Nke Di Elu:
OpenAI API Base URL: http://localhost:20128/v1
OpenAI API Key: [si na dashboard omniroute]
Ụdị: cc/claude-opus-4-7
```
**Iji OmniRoute dịka onye na-eweta Cursor** (OmniRoute na-akpọ Cursor upstream): họrọ
**Dashboard → Providers → Cursor → Login with Cursor**. Na Docker, lee
[`docs/providers/CURSOR-DOCKER.md`](../providers/CURSOR-DOCKER.md).
### Claude Code
Dezie `~/.claude/settings.json`:
```json
{
"env": {
"ANTHROPIC_BASE_URL": "http://localhost:20128",
"ANTHROPIC_AUTH_TOKEN": "your-omniroute-api-key"
}
}
```
Jiri root endpoint kwekọrọ na Claude ebe a. Etinyekwala `/v1` na `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
Dezie `~/.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" }]
}
}
}
}
```
**Ma ọ bụ jiri Dashboard:** CLI Tools → OpenClaw → Auto-config
### Cline / Continue / RooCode
```
Onye na-eweta: Dakọtara na OpenAI
Base URL: http://localhost:20128/v1
API Key: [si na dashboard]
Ụdị: cc/claude-opus-4-7
```
---
## 🚀 Mbugharị
### Nwụnye npm zuru ụwa ọnụ (A tụrụ aro)
```bash
npm install -g omniroute
# Mepụta ndekọ nhazi
mkdir -p ~/.omniroute
# Mepụta faịlụ .env (lee .env.example)
cp .env.example ~/.omniroute/.env
# Bido sava
omniroute
# Ma ọ bụ jiri ọdụ ụgbọ mmiri nke gị:
omniroute --port 3000
```
CLI na-ebunye `.env` na-akpaghị aka site na `~/.omniroute/.env` ma ọ bụ `./.env`.
### Ọnọdụ tray
Bido OmniRoute na tray sistemụ:
```bash
omniroute serve --tray
```
Iwu ahụ ga-akwụsị mgbe sava na tray dị njikere.
Sava ahụ na-aga n’ihu na-enweghị terminal.
Ọnọdụ tray na-akwado macOS, Windows, na nnọkọ Linux nwere eserese. Ọnọdụ tray anaghị emepe dashboard na-akpaghị aka.
Jiri menu tray maka omume ndị a:
- Mepee dashboard.
- Mepee `/dashboard/logs`.
- Gbanwee mbido akpaka.
- Kwụsị OmniRoute.
Ejikọla `--tray` na nhọrọ ndị a:
- `--daemon`
- `--log`
- `--no-recovery`
Ọnọdụ ndị a chọrọ njikwa usoro dị iche iche.
Kwado ka ọ malite n'oge nbanye kọmputa na-esote:
```bash
omniroute autostart enable
```
Mbido akpaka na-eji ọnọdụ tray na macOS, Windows, na nnọkọ Linux nwere eserese. Linux na-enweghị interface eserese na-eji ọrụ onye ọrụ systemd dịbu adị.
Gbanyụọ mbido n'oge nbanye:
```bash
omniroute autostart disable
```
### Iwepụ Nwụnye
Mgbe ị chọghịzi OmniRoute, anyị na-enye script abụọ ngwa ngwa maka iwepụ ya nke ọma:
| Iwu | Omume |
| ------------------------ | ---------------------------------------------------------------------------------------- |
| `npm run uninstall` | Na-ewepụ ngwa sistemụ ahụ mana **na-edobe DB na nhazi gị** na `~/.omniroute`. |
| `npm run uninstall:full` | Na-ewepụ ngwa ahụ MA na-adịgide adịgide **na-ehichapụ nhazi, igodo, na database niile**. |
> Rịba ama: Iji mee iwu ndị a, gaa na folda ọrụ OmniRoute (ọ bụrụ na i mere clone ya) wee mee ha. N’ụzọ ọzọ, ọ bụrụ na arụnyere ya n’ụwa niile, ị nwere ike naanị ime `npm uninstall -g omniroute`.
### Mbugharị 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
# Ma ọ bụ: pm2 start npm --name omniroute -- start
```
### Mbugharị PM2 (Nchekwa Dị Ala)
Maka sava nwere RAM pere mpe, jiri nhọrọ oke nchekwa:
```bash
# Jiri oke 512MB (ndabara)
pm2 start npm --name omniroute -- start
# Ma ọ bụ jiri oke nchekwa nke gị
OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start
# Ma ọ bụ jiri ecosystem.config.js
pm2 start ecosystem.config.js
```
Mepụta `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
# Wuo image (ndabara = runner-cli nke etinyerela codex/claude/droid)
docker build -t omniroute:cli .
# Ọnọdụ enwere ike ibugharị (a tụrụ aro)
docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli
```
Maka ọnọdụ ejikọtara na host nke nwere binary CLI, lee ngalaba Docker na akwụkwọ ndu ndị bụ isi.
### Void Linux (xbps-src)
Ndị ọrụ Void Linux nwere ike ịkwakọba ma wụnye OmniRoute n'ụzọ sistemụ site n’iji usoro cross-compilation `xbps-src`. Nke a na-eme ka owuwu standalone nke Node.js yana native bindings `better-sqlite3` ndị achọrọ rụọ ọrụ na-akpaghị aka.
Lee template xbps-src
```bash
# Faịlụ template maka 'omniroute'
pkgname=omniroute
version=3.8.0
revision=1
hostmakedepends="nodejs python3 make"
depends="openssl"
short_desc="Ọnụ ụzọ AI zuru ụwa ọnụ nwere routing nwere ọgụgụ isi maka ọtụtụ ndị na-enye 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() {
# Chọpụta ụkpụrụ ụlọ CPU ezubere maka 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) Wụnye dependencies niile – mafere scripts
NODE_ENV=development npm ci --ignore-scripts
# 2) Wuo standalone bundle nke Next.js
npm run build
# 3) Detuo static assets n'ime standalone
cp -r .next/static .next/standalone/.next/static
[ -d public ] && cp -r public .next/standalone/public || true
# 4) Kpọkọta native binding nke 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) Tinye binding a kpọkọtara n'ime standalone bundle
local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
mkdir -p "$_bs3_release"
cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
# 6) Wepụ sharp bundles ndị akọwapụtara maka ụkpụrụ ụlọ
rm -rf .next/standalone/node_modules/@img
# 7) Detuo runtime dependencies nke pino nke static analysis nke Next.js hapụrụ:
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
# Gbochie post-install hook ihichapụ directories Next.js app router ndị tọgbọ chakoo
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
}
```
### Environment Variables
| Mgbanwe | Ndabara | Nkọwa |
| --------------------------------------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
| `JWT_SECRET` | `omniroute-default-secret-change-me` | Ihe nzuzo e ji abịanye aka na JWT (**gbanwee ya na production**) |
| `INITIAL_PASSWORD` | `CHANGEME` | Okwuntughe nbanye mbụ |
| `DATA_DIR` | `~/.omniroute` | Ndekọ data (db, ojiji, ndekọ ihe omume) |
| `PORT` | ndabara framework | Port ọrụ (`20128` n'ihe atụ) |
| `HOSTNAME` | ndabara framework | Host a ga-ejikọta na ya (ndabara Docker bụ `0.0.0.0`) |
| `NODE_ENV` | ndabara runtime | Tọọ `production` maka mbugote |
| `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128` | URL ntọala ọha egosiri na dashboard ma mee ka sava nweta ya (na-anọchi `BASE_URL` ochie) |
| `NEXT_PUBLIC_CLOUD_URL` | `https://omniroute.dev` | URL ntọala endpoint maka mmekọrịta cloud (na-anọchi `CLOUD_URL` ochie) |
| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | Ihe nzuzo HMAC maka igodo API ndị emepụtara |
| `REQUIRE_API_KEY` | `false` | Manye igodo API Bearer na `/v1/*` |
| `ALLOW_API_KEY_REVEAL` | `false` | Kwe ka ndị ọrụ dashboard akwadoro kpughee ụkpụrụ igodo API zuru ezu echekwara mgbe ha chọrọ |
| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Ugboro sava na-eme ka data Provider Limits echekwara ọhụrụ; bọtịnụ imegharị UI ka na-akpalite mmekọrịta aka |
| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Gbanyụọ snapshot SQLite akpaka tupu ide/mbubata/mweghachi; backup aka ka na-arụ ọrụ |
| `APP_LOG_TO_FILE` | `true` | Na-eme ka mmepụta ndekọ ngwa na ndekọ nyocha gaa na diski |
| `AUTH_COOKIE_SECURE` | `false` | Manye cookie nkwenye `Secure` (n'azụ HTTPS reverse proxy) |
| `CLOUDFLARED_BIN` | edoghị ya | Jiri binary `cloudflared` dị adị kama nbudata a na-achịkwa |
| `CLOUDFLARED_PROTOCOL` | `http2` | Ụzọ mbufe maka Quick Tunnels a na-achịkwa (`http2`, `quic`, ma ọ bụ `auto`) |
| `OMNIROUTE_MEMORY_MB` | `512` | Oke heap Node.js na MB |
| `PROMPT_CACHE_MAX_SIZE` | `50` | Ọnụọgụ ndenye kachasị na cache prompt |
| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Ọnụọgụ ndenye kachasị na cache semantic |
Maka ntụaka zuru ezu gbasara mgbanwe gburugburu, lee [README](../README.md).
---
## 📊 Ụdịdịdị Dịnụ
Lelee ụdịdịdị niile dịnụ
> A họpụtara ndepụta dị n'okpuru site na `open-sse/config/providerRegistry.ts` maka v3.8.0. A na-emekọrịta katalọgụ igwe ojii (Gemini, OpenRouter, wdg.) n'ụzọ akpaaka — iji hụ katalọgụ zuru ezu dị ugbu a, mepee **Dashboard → Providers → [provider] → Available Models** ma ọ bụ kpọọ `GET /api/models/catalog`.
>
> Ọ bụrụ na ndepụta etinyere n'ime nke onye na-eweta ọrụ agbanweela, jiri **Import from /models** na peeji ahụ (ma ọ bụ gbanye **Auto-Sync**) iji dọpụta katalọgụ dị ugbu a site na isi mmalite. E kwadoro nke a na v3.8.50 maka LLM7.io (`gemini-3.1-flash-lite`) na UncloseAI (`solidrust/Hermes-3-Llama-3.1-8B-AWQ`); ohere Pollinations na-enweghị njirimara ka nọgidere bụrụ nke isi mmalite machibidoro n'oge otu ule ahụ.
**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` (+ ọkwa mgbalị: `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 N'EFU: jiri katalọgụ dị ugbu a nke egosiri n'okpuru **Dashboard → Providers → Kiro → Available Models**. Ịdịnụ ya dabere na akaụntụ na atụmatụ.
**Qoder (`if/`)** — OAuth N'EFU: `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/ọnwa otu ọnụahịa ma ọ bụ ụgwọ dabere n'ojiji: `kimi/kimi-k2.6`, `kimi/kimi-k2.5`
**DeepSeek (`ds/`)** — Igodo API: `ds/deepseek-v4-pro`, `ds/deepseek-v4-flash`
**Groq (`groq/`)** — Ọsọ dị ukwuu: `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 nke mbụ: `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/`)** — A na-akwado ya na EU: `mistral/mistral-large-latest`, `mistral/mistral-medium-3-5`, `mistral/mistral-small-latest`, `mistral/devstral-latest`, `mistral/codestral-latest`
**Perplexity (`pplx/`)** — Nchọ na-agbakwụnye ike: `pplx/sonar-deep-research`, `pplx/sonar-reasoning-pro`, `pplx/sonar-pro`, `pplx/sonar`
**Together AI (`together/`)** — Isi mmalite mepere emepe: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo-Free` (n'efu), `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/`)** — Ntụpụta ngwa ngwa: `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/`)** — N'ogo wafer: `cerebras/zai-glm-4.7`, `cerebras/gpt-oss-120b`
**Cohere (`cohere/`)** — Lekwasịrị anya na 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/`)** — Maka ụlọ ọrụ: `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/`)**: A na-emekọrịta ya ozugbo site na Google dịka igodo API si dị — enweghị ndepụta na-adịgide adịgide. Jikọọ igodo na **Dashboard → Providers**, wee jiri **Available Models** bubata katalọgụ dị ugbu a (dịka `gemini/gemini-3-pro`, `gemini/gemini-3-flash`).
**Ndị ọzọ na-eweta ọrụ dakọtara** (ndị ahọpụtara): `cohere`, `databricks`, `snowflake`, `together`, `vertex`, `alibaba`, `alibaba-cn`, `bedrock` (site na `aws-bedrock`), `azure-ai`, `openrouter` (katalọgụ a na-ebufe ozugbo), `siliconflow`, `hyperbolic`, `huggingface`, `featherless-ai`, `cloudflare-ai`, `scaleway`, `deepinfra`, `vercel-ai-gateway`, `bazaarlink`, `friendliai`, `nous-research`, `reka`, `volcengine`, `ai21`, `gigachat`. Onye ọ bụla na-edobe ndepụta ụdịdị nke ya na `providerRegistry.ts`, a pụkwara ịmekọrịta ya n'ụzọ akpaaka mgbe onye na-eweta ọrụ gosipụtara njedebe `/models`.
**Nkọwa gbasara ID ụdịdị:** OmniRoute na-eji ID ndị sitere n'aka onye na-eweta ọrụ (`claude-opus-4-8`, `gpt-5.5`, `glm-5.1`, `MiniMax-M2.7`, `kimi-k2.5`, `grok-4.20-0309-reasoning`). Ụfọdụ ID nwere ụdị mbipụta nwere ntụpọ n'ihi na ọ bụ otu API nke isi mmalite si atụ anya ha. Ọ bụrụ na edepụtaghị otu ụdịdị n'elu, gbaa `omniroute models --search ` ma ọ bụ kpọọ `GET /api/models/catalog` iji kwado na ọ dịnụ.
---
## 🧩 Njirimara Ndị Dị Elu
### Model Ndị Ahaziri
Tinye ID model ọ bụla na provider ọ bụla n'echeghị mmelite ngwa:
```bash
# Site na 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"}'
# Depụta: curl http://localhost:20128/api/provider-models?provider=openai
# Wepụ: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-5.2"
```
Ma ọ bụ jiri Dashboard: **Providers → [Provider] → Custom Models**.
Ndetu:
- A na-ejikwa OpenRouter na provider ndị dakọtara na OpenAI/Anthropic naanị site na **Available Models**. Ntinye aka, mbubata, na mmekọrịta akpaghị aka niile na-abanye n'otu ndepụta model ndị dị, ya mere enweghị ngalaba Custom Models dị iche maka provider ndị ahụ.
- Ezubere ngalaba **Custom Models** maka provider ndị na-adịghị enye mbubata model ndị dị nke a na-achịkwa.
### Ijikọta OmniRoute Peers n'Usoro
Enwere ike ịgbakwunye gateway OmniRoute ọzọ dịka provider **Custom OpenAI-compatible**. Jiri URL ntọala `/v1` nke peer ahụ na API key pụrụ iche nwere ikike kacha nta nke peer ahụ nyere.
Maka njikọ na-agaghachi ibe ha ma ọ bụ njikọ nwere ọtụtụ nzọụkwụ, gbanye ihe nche loop nke a na-ahọrọ iji na gateway ọ bụla:
```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
```
Ọ bụ naanị arịrịọ ezitere na URL peer e tinyere kpọmkwem na ndepụta ikike na-enweta header
`X-OmniRoute-Peer-Trace`. Gateway na-ajụ ID instance e megharịrị ma ọ bụ oke hop
gwụchara site na HTTP `508 Loop Detected`; provider upstream nkịtị anaghị enweta metadata peer ọ bụla.
Ijikọta peer abụghị mmepụta oyiri database ma ọ bụ failover host. Gateway ọ bụla na-edobe state
SQLite, cache, counter rate, na session nke ya. Jiri reverse proxy nwere health check ma ọ bụ
failover client maka nnweta active/passive ma ọ bụ active/active, ma etinyekwala otu database SQLite
n'ime ọtụtụ instance OmniRoute na-arụ ọrụ.
### Ụzọ Provider Pụrụ Iche
Duga arịrịọ ozugbo na provider akọwapụtara ma nyochaa model:
```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
```
A na-agbakwunye prefix provider na-akpaghị aka ma ọ bụrụ na ọ dịghị. Model ndị na-adabaghị na-eweghachi `400`.
### Nhazi Proxy Netwọk
```bash
# Tọọ proxy zuru ụwa ọnụ
curl -X PUT http://localhost:20128/api/settings/proxy \
-d '{"global": {"type":"http","host":"proxy.example.com","port":"8080"}}'
# Proxy maka provider ọ bụla
curl -X PUT http://localhost:20128/api/settings/proxy \
-d '{"providers": {"openai": {"type":"socks5","host":"proxy.example.com","port":"1080"}}}'
# Nwalee proxy
curl -X POST http://localhost:20128/api/settings/proxy/test \
-d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}'
```
**Usoro Ibu Ụzọ:** Nke metụtara Key → Nke metụtara Combo → Nke metụtara Provider → Zuru ụwa ọnụ → Environment.
### API Katalọgụ Model
```bash
curl http://localhost:20128/api/models/catalog
```
Na-eweghachi model ndị a chịkọtara dịka provider si dị, tinyere ụdị (`chat`, `embedding`, `image`).
### Mmekọrịta Cloud
- Mekọrịta provider, combo, na ntọala n'ofe ngwaọrụ
- Mmekọrịta ndabere akpaghị aka nwere timeout + fail-fast
- Họrọ `NEXT_PUBLIC_BASE_URL`/`NEXT_PUBLIC_CLOUD_URL` nke server-side na production
### Cloudflare Quick Tunnel
- Dị na **Dashboard → Endpoints** maka Docker na deployment ndị ọzọ a na-akwado n'onwe
- Na-emepụta URL `https://*.trycloudflare.com` nwa oge nke na-ebuga arịrịọ na endpoint `/v1` gị ugbu a nke dakọtara na OpenAI
- Mgbanye mbụ na-etinye `cloudflared` naanị mgbe achọrọ ya; restart ndị ọzọ na-eji otu binary a na-achịkwa
- A naghị eweghachi Quick Tunnels na-akpaghị aka mgbe OmniRoute ma ọ bụ container malitegharịrị; gbanye ha ọzọ site na dashboard mgbe achọrọ
- URL tunnel bụ nwa oge ma na-agbanwe oge ọ bụla ị kwụsịrị/malite tunnel
- Quick Tunnels a na-achịkwa na-eji transport HTTP/2 na ndabara iji zere ịdọ aka ná ntị QUIC UDP buffer na-eme mkpọtụ n'ime container nwere oke akụrụngwa
- Tọọ `CLOUDFLARED_PROTOCOL=quic` ma ọ bụ `auto` ma ọ bụrụ na ịchọrọ ịgbanwe nhọrọ transport a na-achịkwa
- Tọọ `CLOUDFLARED_BIN` ma ọ bụrụ na ịchọrọ iji binary `cloudflared` etinyelarị kama download a na-achịkwa
- Enwere ike igosi ma ọ bụ zoo panel Cloudflare Quick Tunnel, Tailscale Funnel, na ngrok Tunnel na **Settings → Appearance**. Izo panel anaghị akwụsị tunnel na-arụ ọrụ.
### Ọgụgụ Isi LLM Gateway (Phase 9)
- **Semantic Cache** — Na-echekwa nzaghachi na-adịghị streaming, temperature=0 na-akpaghị aka (jiri `X-OmniRoute-No-Cache: true` gafere ya)
- **Request Idempotency** — Na-ewepụ arịrịọ oyiri n'ime 5s site na header `Idempotency-Key` ma ọ bụ `X-Request-Id`
- **Progress Tracking** — Event SSE `event: progress` a na-ahọrọ iji site na header `X-OmniRoute-Progress: true`
---
### Ebe Nnwale Translator
Nweta ya site na **Dashboard → Translator**. Chọpụta nsogbu ma hụ anya otu OmniRoute si atụgharị arịrịọ API n'etiti provider.
| Ọnọdụ | Ebumnuche |
| ---------------- | --------------------------------------------------------------------------------------- |
| **Playground** | Họrọ format isi/mmalite na nke ebumnuche, mado arịrịọ, wee hụ output a tụgharịrị ozugbo |
| **Chat Tester** | Zipụ ozi chat dị ndụ site na proxy ma nyochaa usoro arịrịọ/nzaghachi zuru ezu |
| **Test Bench** | Mee ule batch n'ofe ọtụtụ ngwakọta format iji kwado izi ezi nke ntụgharị |
| **Live Monitor** | Lelee ntụgharị ozugbo ka arịrịọ na-agafe na proxy |
**Ọnọdụ eji ya eme ihe:**
- Chọpụta ihe kpatara otu ngwakọta client/provider ji ada
- Kwenye na a tụgharịrị thinking tags, tool calls, na system prompts nke ọma
- Tụnyere ọdịiche format n'etiti format OpenAI, Claude, Gemini, na Responses API
---
### Atụmatụ Routing
Hazie ya site na **Dashboard → Settings → Routing**. Dashboard na-egosi usoro isii a kacha eji; ngwakọta na auto-router na-akwado usoro ndị ọzọ sara mbara n'ime ya.
**Usoro ndị a na-ahụ na Dashboard (ntụgharị ụzọ n'ogo akaụntụ):**
| Usoro | Nkọwa |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------ |
| **Buru Ụzọ Jupụta Nke Mbụ** | Na-eji akaụntụ dịka usoro mkpa ha si dị — akaụntụ bụ isi na-ahụ maka arịrịọ niile ruo mgbe ọ naghị adị |
| **Ntugharị Gburugburụ** | Na-agagharị n'ofe akaụntụ niile site na oke njigide a pụrụ ịhazi (ndabara: oku 3 n'otu akaụntụ) |
| **P2C (Ike Nhọrọ Abụọ)** | Na-ahọrọ akaụntụ 2 n'enweghị usoro ma na-eziga arịrịọ na nke ka mma — na-edozi ibu ọrụ ma na-ele ahụike anya |
| **Nhọrọ Enweghị Usoro** | Na-ahọrọ akaụntụ n'enweghị usoro maka arịrịọ ọ bụla site na iji Fisher-Yates shuffle |
| **Nke E Ji Obere Oge** | Na-eziga arịrịọ na akaụntụ nwere timestamp `lastUsedAt` kacha ochie, na-ekesa okporo ọrụ n'ụzọ hà nhata |
| **Nke E Haziri Maka Ọnụahịa** | Na-eziga arịrịọ na akaụntụ nwere uru mkpa kacha nta, iji họrọ ndị na-eweta ọrụ nwere ọnụahịa kacha ala |
**Ngwakọta dị elu na usoro auto** (a pụrụ ịhazi maka ngwakọta ọ bụla ma ọ bụ site na prefix `auto/*` — lee [AUTO-COMBO.md](../routing/AUTO-COMBO.md)):
- `priority` — usoro siri ike; ọ naghị eme round-robin ma ọlị
- `weighted` — nkewa okporo ọrụ n'ogo kwekọrọ na ibu enyere model ọ bụla
- `fill-first` — na-eji model mbụ ruo mgbe o rutere oke ya
- `round-robin` / `strict-random` / `random`
- `p2c` (Ike Nhọrọ Abụọ)
- `least-used` na `cost-optimized`
- `auto` — na-eji akara họrọ n'etiti ndị niile a ga-ahọrọ
- `lkgp` (Onye Na-eweta Ọrụ Ikpeazụ A Mara na Ọ Dị Mma) — na-ejigide onye na-eweta ọrụ ikpeazụ gara nke ọma, wee laghachi na iwu ma ọ bụrụ na ọ daa
- `context-optimized` — na-ahọrọ model nwere windo context efu kacha ibu
- `context-relay` — na-ejikọta model ndị nwere context ogologo maka ntụgharị mkparịta ụka ndị na-esochi
#### Header Oge Njigide Mpụga
Maka njikọta oge mpụga (dịka ọmụmaatụ, ndị nnọchi anya Claude Code/Codex nọ n'azụ reverse proxy), zipụ:
```http
X-Session-Id: your-session-key
```
OmniRoute na-anabatakwa `x_session_id` ma na-eweghachi igodo oge a na-eji n'ezie n'ime `X-OmniRoute-Session-Id`.
Ọ bụrụ na ị na-eji Nginx ma na-ezipụ header ndị nwere underscore, mee ka nke a rụọ ọrụ:
```nginx
underscores_in_headers on;
```
#### Aha Nhọrọ Model Wildcard
Mepụta pattern wildcard iji tụgharịa aha model:
```
Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-6
Pattern: gpt-* → Target: gh/gpt-5.3-codex
```
Wildcard na-akwado `*` (mkpụrụedemede ọ bụla) na `?` (otu mkpụrụedemede).
#### Agbụ Fallback
Kọwaa agbụ fallback zuru ụwa ọnụ nke na-emetụta arịrịọ niile:
```
Chain: production-fallback
1. cc/claude-opus-4-7
2. gh/gpt-5.3-codex
3. glm/glm-4.7
```
---
### Nkwụsi Ike & Circuit Breaker
Hazie ya site na **Dashboard → Settings → Resilience**.
OmniRoute na-enye nkwụsi ike n'ogo onye na-eweta ọrụ site na akụkụ ise:
1. **Ahịrị Arịrịọ & Nhazi Ọsọ** — Nhazi arịrịọ n'ogo sistemụ:
- **Arịrịọ Kwa Nkeji (RPM)** — Ọnụọgụ arịrịọ kachasị n'otu nkeji maka otu akaụntụ
- **Oge Kacha Nta N'etiti Arịrịọ** — Oghere kacha nta na millisecond n'etiti arịrịọ
- **Arịrịọ Ndị Na-aga N'otu Oge Kachasị Elu** — Ọnụọgụ arịrịọ kachasị nwere ike ịga n'otu oge maka otu akaụntụ
2. **Oge Nkwụsị Njikọ** — Nhazi maka ụdị auth ọ bụla maka otu njikọ mgbe ọdịda ndị a pụrụ ịnwa ọzọ mere:
- **Oge Nkwụsị Ndabere** — Window oge nkwụsị ndabara maka ọdịda upstream ndị a pụrụ ịnwa ọzọ
- **Jiri Ndụmọdụ Nnwale Ọzọ nke Upstream** — Na-agbaso `Retry-After` a pụrụ ịtụkwasị obi ma ọ bụ ndụmọdụ reset mgbe e nyere ha
- **Nzọụkwụ Backoff Kachasị Elu** — Ọkwa exponential backoff kachasị maka ọdịda ndị na-eme ugboro ugboro
3. **Circuit Breaker nke Onye Na-eweta Ọrụ** — Na-enyocha ọdịda onye na-eweta ọrụ site na mmalite ruo na njedebe, na-akara onye na-eweta ọrụ dị ka onye dara ogo mgbe o ruru oke ịdọ aka ná ntị ahaziri, ma na-emepe breaker mgbe o ruru oke ọdịda ahaziri:
- **Oke Mbelata Ogo** — Ọdịda onye na-eweta ọrụ na-esochi ibe ha tupu ịbanye `DEGRADED`
- **Oke Ọdịda** — Ọdịda onye na-eweta ọrụ na-esochi ibe ha tupu ịbanye `OPEN`
- **Oge Reset** — Window oge tupu a nwalee onye na-eweta ọrụ ọzọ
- **CLOSED** (Dị Mma) — Arịrịọ na-aga dịka o kwesịrị
- **DEGRADED** — Arịrịọ ka na-aga mgbe a na-enyocha mmụba ọdịda
- **OPEN** — A na-egbochi onye na-eweta ọrụ nwa oge mgbe ọdịda mere ugboro ugboro
- **HALF_OPEN** — Na-anwale ma onye na-eweta ọrụ agbakeela
Oke ọsọ `429` metụtara njikọ na-anọgide na **Oge Nkwụsị Njikọ** ma a naghị agụ ya dịka akụkụ nke breaker onye na-eweta ọrụ.
A na-egosi ọnọdụ runtime nke breaker onye na-eweta ọrụ naanị na **Dashboard → Health**.
4. **Chere Ka Oge Nkwụsị Gafee** — Ọ bụrụ na njikọ niile a pụrụ ịhọrọ anọworị n'oge nkwụsị, OmniRoute nwere ike ichere oge nkwụsị kacha nso wee nwaa otu arịrịọ client ahụ ọzọ na-akpaghị aka.
5. **Nchọpụta Oke Ọsọ na Akpaghị Aka** — Mgbe ndị na-eweta ọrụ upstream weghachiri window nchere doro anya, ndụmọdụ ndị ahụ ga-anọchi oge nkwụsị njikọ mpaghara mgbe agbanyere ntọala a.
**Ndụmọdụ Ọkachamara:** Jiri ibe **Health** nyochaa ma reset breaker ndị na-eweta ọrụ na-arụ ọrụ mgbe outage gasịrị. Ibe Resilience na-agbanwe naanị nhazi.
---
### Mbupụ / Mbubata Database
Jikwaa backup database na **Dashboard → Settings → System & Storage**.
| Omume | Nkọwa |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Bupụ Ebe Nchekwa Data** | Na-ebudata ebe nchekwa data SQLite dị ugbu a dịka faịlụ `.sqlite` |
| **Bupụ Ihe Niile (.tar.gz)** | Na-ebudata ebe nchekwa ndabere zuru ezu nke gụnyere: ebe nchekwa data, ntọala, combos, njikọ ndị na-eweta ọrụ (enweghị nzere), metadata igodo API |
| **Bubata Ebe Nchekwa Data** | Na-ebugote faịlụ `.sqlite` iji dochie ebe nchekwa data dị ugbu a. A na-emepụta ebe nchekwa ndabere tupu mbubata na-akpaghị aka ma ọ bụrụ na `DISABLE_SQLITE_AUTO_BACKUP=true` |
```bash
# API: Bupụ ebe nchekwa data
curl -o backup.sqlite http://localhost:20128/api/db-backups/export
# API: Bupụ ihe niile (ebe nchekwa zuru ezu)
curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll
# API: Bubata ebe nchekwa data
curl -X POST http://localhost:20128/api/db-backups/import \
-F "file=@backup.sqlite"
```
**Nnyocha Mbubata:** A na-enyocha faịlụ ebubatara iji hụ na ọ zuru oke (nyocha SQLite pragma), na tebụl ndị achọrọ (`provider_connections`, `provider_nodes`, `combos`, `api_keys`) dị, nakwa nha ya (kachasị 100MB).
**Ụzọ E Si Eji Ya:**
- Bugharịa OmniRoute n'etiti kọmputa
- Mepụta ebe nchekwa ndabere mpụga maka mgbake mgbe ọdachi mere
- Kekọrịta nhazi n'etiti ndị otu (bupụ ihe niile → kesaa ebe nchekwa ahụ)
---
### Dashboard Ntọala
A haziri ibe ntọala ahụ n'ime **taabụ 7** iji mee ka ịgagharị dị mfe:
| Taabụ | Ihe Ndị Dị N'ime Ya |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Izugbe** | Ngwaọrụ nchekwa sistemụ, omume ndabara, ọhụhụ ọwara Endpoint |
| **Ọdịdị** | Njikwa isiokwu (ọkụ/ọchịchịrị/sistemụ), ọhụhụ sidebar, na mgba ọkụ panel maka kaadị ọwara Cloudflare/Tailscale/ngrok |
| **AI** | Oke echiche (passthrough / iwepụ-na-akpaghị-aka / omenala / mgbanwe — lee [THINKING_BUDGET.md](./THINKING_BUDGET.md)), system prompt zuru ụwa ọnụ, ọnụ ọgụgụ prompt cache |
| **Nchekwa** | Ntọala nbanye/Okwuntughe, Njikwa Nnweta IP, nkwenye API maka `/models`, Mgbochi Onye Na-eweta Ọrụ, nchedo megide prompt-injection |
| **Nduzi Ụzọ** | Atụmatụ nduzi ụzọ zuru ụwa ọnụ (Buru Ụzọ Jupụta / Gbanwee n'Okirikiri / P2C / N'amaghị Ama / Nke E Ji Obere / Nke Ahaziri Maka Ọnụ Ahịa), aha ọzọ wildcard maka model, usoro fallback, ndabara combo |
| **Ịnagide Nsogbu** | Ahịrị arịrịọ, oge izu ike njikọ, nhazi breaker nke onye na-eweta ọrụ, na omume ichere ruo mgbe oge izu ike gwụchara |
| **Nke Dị Elu** | Nhazi proxy zuru ụwa ọnụ (HTTP/SOCKS5), ntọala proxy pụrụ iche maka onye na-eweta ọrụ ọ bụla |
Izugbe anaghịzi emepụtaghachi ndetu ndekọ na cache ndị bụ naanị maka ịgụ. A na-echekwa ntọala njigide na
nkwalite ebe nchekwa data site na `/api/settings/database`; ihichapụ cache n'aka na-eji
`DELETE /api/cache`. Ọ bụ `CALL_LOGS_TABLE_MAX_ROWS` na `PROXY_LOGS_TABLE_MAX_ROWS`
na-achị oke ahịrị ndekọ arịrịọ na proxy.
---
### Njikwa Ọnụ Ahịa & Mmefu Ego
Nweta ya site na **Dashboard → Ọnụ Ahịa**.
| Taabụ | Ebumnuche |
| ------------- | ----------------------------------------------------------------------------------------------------------------- |
| **Mmefu Ego** | Tọọ oke mmefu maka igodo API ọ bụla site na mmefu ego kwa ụbọchị/izu/ọnwa yana nsochi ozugbo |
| **Ọnụ Ahịa** | Lelee ma dezie ndebanye ọnụ ahịa model — ọnụ ahịa maka token ntinye/mpụta 1K ọ bụla maka onye na-eweta ọrụ ọ bụla |
```bash
# API: Tọọ mmefu ego
curl -X POST http://localhost:20128/api/usage/budget \
-H "Content-Type: application/json" \
-d '{"keyId": "key-123", "limit": 50.00, "period": "monthly"}'
# API: Nweta ọnọdụ mmefu ego ugbu a
curl http://localhost:20128/api/usage/budget
```
**Nsochi Ọnụ Ahịa:** Arịrịọ ọ bụla na-edekọ ojiji token ma na-agbakọ ọnụ ahịa site n'iji tebụl ọnụ ahịa. Lelee nkọwa ya na **Dashboard → Ojiji** dịka onye na-eweta ọrụ, model, na igodo API si dị.
---
### Ntụgharị Ọdịyo Ka Ọ Bụrụ Ederede
OmniRoute na-akwado ntụgharị ọdịyo ka ọ bụrụ ederede site na endpoint dakọtara na OpenAI:
```bash
POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data
# Ọmụmaatụ site na iji 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` bụ ụzọ Deepgram nke mbụ ma chọọ igodo API Deepgram.
Ọ bụrụ na ọ bụ naanị OpenRouter ka ahaziri, jiri `openrouter/deepgram/nova-3`.
Ndị na-eweta ọrụ **Okwu-gaa-na-Ederede (ntụgharị ederede)**:
- `openai/` (dakọtara na whisper)
- `groq/` (Groq Whisper Turbo)
- `deepgram/` (ezinụlọ Nova)
- `assemblyai/`
- `nvidia/` (Parakeet, Canary)
- `huggingface/` (ụdị whisper dị iche iche)
- `qwen/`
Ndị na-eweta ọrụ **Ederede-gaa-na-Okwu (`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/`
Ụdị ọdịyo a na-akwado maka ntụgharị ederede: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. Ụdị mmepụta TTS dabere na onye na-eweta ọrụ (mp3, wav, opus, pcm, mulaw).
---
### Atụmatụ Ịhazigharị Combo
Hazie nhazigharị combo ọ bụla na **Dashboard → Combos → Mepụta/Dezie → Atụmatụ**.
| Atụmatụ | Nkọwa |
| ------------------------- | --------------------------------------------------------------------------------------------- |
| **Ntụgharị n'Usoro** | Na-agafe n'ụdịdị ndị ahụ n'otu n'otu |
| **Ibu Ụzọ** | Na-ebu ụzọ anwale ụdịdị nke mbụ mgbe niile; ọ na-eji nke ọzọ naanị ma njehie mee |
| **Nhọrọ n'Enweghị Usoro** | Na-ahọrọ otu ụdịdị n'Enweghị usoro site na ngwakọta ahụ maka arịrịọ ọ bụla |
| **Dabere n'Ibu** | Na-ekesa arịrịọ n'ogo kwesịrị ekwesị dabere n'ibu e kenyere ụdịdị ọ bụla |
| **Nke Ejikarịchaghị** | Na-eziga arịrịọ na ụdịdị nwere arịrịọ ndị na-adịbeghị anya kacha nta (na-eji metrik ngwakọta) |
| **Nkwalite Ọnụ Ahịa** | Na-eziga arịrịọ na ụdịdị dị ọnụ ala kacha dị (na-eji tebụl ọnụ ahịa) |
Enwere ike ịtọ ndabara ngwakọta zuru ụwa ọnụ na **Dashboard → Settings → Routing → Combo Defaults**.
Oge nkwụsị nke ebumnuche ngwakọta na-eketa oge nkwụsị nke arịrịọ dị ugbu a na ndabara. Jiri **Target timeout
(seconds)** na ndabara ngwakọta ma ọ bụ n'otu ngwakọta naanị mgbe oke oge dị mkpụmkpụ maka otu ebumnuche kwesịrị
ịkpalite iji nke ọzọ ngwa ngwa.
Nkwalite ngwakọta enweghị nkwụsị oge bụ nke a ga-eji aka họrọ. Hapụ **Zero-latency optimizations** ka ọ bụrụ nke agbanyụrụ iji
gbochie atụmatụ ndị a metụtara nkwụsị oge ịsọ mpi na ebumnuche ndị ọzọ, ịwụfe ebumnuche dabere na akụkọ
TTFT, ma ọ bụ ịkpakọta arịrịọ ndị ọzọ; ịgbanye ya na-enye ohere ka mgbochi ihe ize ndụ ahaziri, mwụfe TTFT
nke amụma, na mkpakọta arịrịọ ndị ọzọ n'ọrụ tupu oge eruo jiri izi ezi nke nhazi ụzọ/arịrịọ zụta mbelata
nkwụsị oge kachasị njọ.
Gbanyụọ **Reasoning token buffer** mgbe ndị na-eweta ọrụ dị n'elu chọrọ oke
`max_tokens` / `maxOutputTokens` siri ike. Mgbe agbanyere ya, nhazi ụzọ ngwakọta na-agbakwunye naanị ohere
maka ụdịdị echiche n'ụdịdị nwere oke mmepụta a maara, ma na-ahapụ oke token nke onye ahịa ka ọ ghara ịgbanwe mgbe
uru echekwara nke ọma ga-agafe oke ahụ. Ọ bụrụ na oke onye ahịa adịlarị elu karịa oke a maara,
OmniRoute na-ewedata ya ruo n'oke ahụ tupu izipu arịrịọ ahụ n'elu.
---
### Dashboard Ahụike
Nweta ya site na **Dashboard → Health**. Nchịkọta ozugbo nke ahụike sistemụ nwere kaadị 6:
| Kaadị | Ihe Ọ Na-egosi |
| ---------------------------- | ------------------------------------------------------------------------ |
| **Ọnọdụ Sistemụ** | Oge ọrụ, ụdị mbipute, ojiji ebe nchekwa, ndekọ data |
| **Ahụike Onye Na-eweta Ọrụ** | Ọnọdụ ọrụ ozugbo nke ihe nkwụsị sekit zuru ụwa ọnụ nke onye na-eweta ọrụ |
| **Oke Ọsọ** | Oge nkwụsị njikọ na-arụ ọrụ maka akaụntụ ọ bụla tinyere oge fọdụrụ |
| **Mkpọchi Na-arụ Ọrụ** | Mkpọchi metụtara otu ụdịdị na mwepụ nwa oge ndị na-arụ ọrụ |
| **Cache Mbinye Aka** | Ọnụọgụ cache mwepụ oyiri (igodo na-arụ ọrụ, ọnụego nchọta gara nke ọma) |
| **Telemetry Nkwụsị Oge** | Nchịkọta nkwụsị oge p50/p95/p99 maka onye na-eweta ọrụ ọ bụla |
**Ndụmọdụ Ọkachamara:** Ihupe Ahụike na-emegharị onwe ya kwa sekọnd 10. Jiri kaadị ihe nkwụsị sekit chọpụta ndị na-eweta ọrụ na-enwe nsogbu.
---
## 🤖 Auto-Routing (Nhazi ụzọ akpaaka na-enweghị nhazi ọ bụla)
OmniRoute nwere **auto-router nke akara na-achịkwa** nke na-ahọrọ model kacha mma maka arịrịọ ọ bụla n'ofe provider niile ejikọrọ — enweghị combo ị ga na-elekọta. Naanị jiri otu n'ime prefix `auto/*` zipụ arịrịọ ahụ, OmniRoute ga-emepụta virtual combo ozugbo, na-enye ndị a na-atụle akara dabere na latency, ọnụahịa, ọnụego ihe ịga nke ọma, ndakọrịta context, ịdị mma model maka ọrụ ahụ, ọdịda ndị mere na nso nso a, quota, na ọnọdụ circuit-breaker.
| Prefix | Ihe ọ na-ebuli ka mma |
| -------------- | ------------------------------------------------------------------------------------------------------------- |
| `auto` | Nhazi ndabara ziri ezi (latency × ọnụahịa × ọnụego ihe ịga nke ọma) |
| `auto/coding` | Ọrụ coding: na-ahọrọkarị Claude, GPT-5, GLM, Kimi, Qwen Coder, ndị coder DeepSeek |
| `auto/cheap` | $/token kacha ala, na-anabata latency dị elu |
| `auto/fast` | Latency kacha ala, na-eleghara ọnụahịa anya |
| `auto/offline` | Naanị provider mpaghara (Ollama, vLLM, llama.cpp) — bara uru maka nhazi air-gapped |
| `auto/smart` | Ogo reasoning bụ ihe mbụ (Opus, GPT-5 xhigh, R1, GLM 5.1 reasoning) |
| `auto/lkgp` | "Provider Ikpeazụ Amaara na Ọ Dị Mma" — na-arapara na provider ikpeazụ gara nke ọma, ma mesịa laghachi na iwu |
Ọmụmaatụ:
```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
}'
```
A kọwara auto-router n'ụzọ zuru ezu na [AUTO-COMBO.md](../routing/AUTO-COMBO.md) — gụnyere otu esi edozi ibu akara, tinye provider na blacklist, ma nyochaa mkpebi nhazi ụzọ na **Dashboard → Auto Combo**.
---
## 🔌 Njikọ MCP & A2A
OmniRoute bụ ma **MCP server** (Model Context Protocol) ma **A2A server** (Agent-to-Agent JSON-RPC 2.0). IDE ọ bụla kwekọrọ na MCP ma ọ bụ host agent nwere ike ịkpọ ngwaọrụ OmniRoute ozugbo — achọghị wrapper ọzọ.
### Ụzọ mbufe MCP
- **SSE**: `http://localhost:20128/api/mcp/sse`
- **HTTP nwere ike ịkwasa data**: `http://localhost:20128/api/mcp/stream`
- **stdio**: `omniroute --mcp` (maka plugin IDE ndị na-ahọrọ stdio)
### Jikọọ Claude Desktop
Dezie `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) ma ọ bụ nke kwekọrọ na ya na Windows/Linux:
```json
{
"mcpServers": {
"omniroute": {
"command": "omniroute",
"args": ["--mcp"]
}
}
}
```
### Jikọọ Cursor / Continue / VS Code MCP
Jiri URL SSE `http://localhost:20128/api/mcp/sse` na igodo API Bearer e mepụtara na **Dashboard → API Keys**.
### Scopes
MCP na-akọwapụta scopes 32 nwere aha ugbu a. Enwere ike ịmachi igodo Bearer ọ bụla ka ọ bụrụ naanị scopes akọwapụtara — lee [MCP-SERVER.md](../frameworks/MCP-SERVER.md) maka ndepụta scope na ngwaọrụ bụ isi na [A2A-SERVER.md](../frameworks/A2A-SERVER.md) maka schema JSON-RPC.
---
## 🧠 Usoro Nkà
OmniRoute na-enye **usoro nkà** (`src/lib/skills/`) enwere ike ịgbatị ka ndị nnọchiteanya na endpoint A2A nwee ike ịrụ usoro ọrụ ndị metụtara ngalaba kpọmkwem (dịka `code-review`, `summarize`, `extract-facts`, `web-research`).
- **UI Ahịa** — Chọgharịa ma wụnye nkà site na **Dashboard → Skills**
- **Oke ikike n'otu igodo** — Machibido nkà ndị igodo API ọ bụla nwere ike ịkpọ
- **Nkà ahaziri iche** — Tinye faịlụ TypeScript na `src/lib/a2a/skills/`, debanye ya aha, a ga-enwekwa ike ịkpọ ya ozugbo site na A2A
Ntụaka zuru ezu: [SKILLS.md](../frameworks/SKILLS.md).
---
## 💾 Usoro Ncheta
OmniRoute na-echekwa **ncheta mkparịta ụka ogologo oge** site na iji iweghachite ngwakọta:
- **SQLite FTS5** maka ịchọ mkpụrụokwu n'ime mkparịta ụka ndị gara aga
- **Qdrant vector store** (nhọrọ) maka icheta ihe dabere na nghọta
- **Mwepụta eziokwu akpaka** — a na-achịkọta ihe dị iche iche, mmasị, na mkpebi mgbe nnọkọ ọ bụla gasịrị ma chekwaa ha na tebl `memory_facts`
- A na-ekewa ncheta dịka igodo API ọ bụla na nnọkọ ọ bụla si dị
Jikwaa ncheta na **Dashboard → Memory** (chọọ, dezie, bupụ, hichapụ). Ebe HTTP (`/api/memory/*`) na-enye ndị nnọchiteanya ohere iziga na ịjụ eziokwu site na mmemme — lee [MEMORY.md](../frameworks/MEMORY.md).
---
## 🔔 Webhooks
Debanye aha maka mmemme OmniRoute iji mee nlekota na akpaaka ozugbo.
- Mepụta webhook na **Dashboard → Webhooks** site na iji URL ebumnuche na ihe nzuzo mbinye aka HMAC
- Mmemme ndị dị: `request.completed`, `request.failed`, `provider.unavailable`, `budget.exceeded`, `combo.switched`, `circuit_breaker.opened`, `circuit_breaker.closed`
- Payload ọ bụla gụnyere `X-OmniRoute-Signature` (HMAC-SHA256) maka nkwenye
- Nnwale ọzọ: mgbalị 3 nwere oge nchere na-abawanye n'usoro exponential, emesịa ebufe ya na dead-letter queue
Schema zuru ezu dị na [WEBHOOKS.md](../frameworks/WEBHOOKS.md).
---
## ☁️ Ndị Nnọchiteanya Cloud
OmniRoute na-ejikọta na ndị nnọchiteanya cloud maka ide koodu (**OpenAI Codex Cloud**, **Devin**, **Jules**, **Antigravity**) ka ị nwee ike iziga ọrụ ndị na-ewe ogologo oge site n'otu dashboard ahụ nke na-ahụ maka routing mpaghara gị.
- Mepụta ọrụ na **Dashboard → Cloud Agents** ma ọ bụ site na `POST /api/v1/agents/tasks`
- Soro ọnọdụ, ndekọ, na artifacts nke ọrụ ọ bụla
- Weta igodo API nke gị maka provider ọ bụla — ozi nzere anaghị apụ n'ime instance OmniRoute
Ntụaka zuru ezu: [CLOUD_AGENT.md](../frameworks/CLOUD_AGENT.md).
---
## 🛠️ Njikwa Site na Mmemme
Ị nwere ike ijikwa akụrụngwa OmniRoute niile (providers, combos, keys, settings) site na HTTP, site n'iji **igodo Bearer nwere scope `manage`**.
Mepụta igodo ahụ na **Dashboard → API Keys → New Key → Scope: manage**, emesịa:
```bash
# Depụta ndị provider
curl http://localhost:20128/api/providers \
-H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY"
# Tinye njikọ provider
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" }'
# Mepụta combo
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" }] }'
# Depụta/mepụta igodo 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"] }'
```
Lee [API_REFERENCE.md](../reference/API_REFERENCE.md) maka katalọgụ endpoint zuru ezu na schema arịrịọ/nzaghachi.
---
## 💻 CLI Dị N'ime
OmniRoute na-abịa na CLI dị n'ime (`omniroute …`) maka nhazi, nchọpụta nsogbu, na njikwa oge ọ na-arụ ọrụ. Nke a **dị iche na ibe "CLI Tools" dị na dashboard**, nke na-ahazi CLI nke ndị ọzọ (Claude Code, Cursor, Codex, Cline, …) ka ha nwee ike ịkparịta ụka na OmniRoute.
```bash
omniroute setup # Ọkachamara nhazi mmekọrịta (paswọọdụ, ndị na-eweta ọrụ, ngwakọta)
omniroute setup --non-interactive # Kwesịrị ekwesị maka CI
omniroute doctor # Nchọpụta ọnọdụ ọrụ (ebe data dị, DB, ndị na-eweta ọrụ, ọdụ ụgbọ)
omniroute providers available # Depụta ndị na-eweta ọrụ a na-akwado
omniroute providers list # Depụta njikọ ndị ahaziri
omniroute providers test # Nwalee njikọ onye na-eweta ọrụ ozugbo
omniroute combos list # Depụta ngwakọta
omniroute combos switch # Tọọ ngwakọta ndabara
omniroute models # Depụta ụdịdị dị (--json, --search)
omniroute keys add | list | remove # Jikwaa igodo API site na terminal
omniroute backup # Mepụta snapshot nke nhazi + DB
omniroute restore [] # Weghachite site na snapshot
omniroute health # Ọnọdụ ọrụ zuru ezu (ndị nkwụsị, cache, ebe nchekwa)
omniroute quota # Ojiji oke onye na-eweta ọrụ
omniroute mcp status # Ọnọdụ sava MCP
omniroute a2a status # Ọnọdụ sava A2A
omniroute tunnel list|create|stop # Ọwara Cloudflare/Tailscale/ngrok
omniroute reset-password # Tọgharịa paswọọdụ onye nchịkwa
omniroute --mcp # Malite sava MCP site na stdio
omniroute --port 3000 # Malite sava na ọdụ ụgbọ ahaziri iche
```
Ndụmọdụ: jikọta `omniroute doctor --json` na ngwa nlekota gị iji nye ọkwa mgbe njikọ onye na-eweta ọrụ adịghị mma.
---
## 🖥️ Ngwa Desktọpụ (Electron)
OmniRoute dị ka ngwa desktọpụ nke e wuru kpọmkwem maka Windows, macOS, na Linux.
### Nwụnye
```bash
# Site na ndekọ electron:
cd electron
npm install
# Ọnọdụ mmepe (jikọọ na sava mmepe Next.js na-arụ ọrụ):
npm run dev
# Ọnọdụ mmepụta (na-eji standalone build):
npm start
```
### Iwu Ihe Nwụnye
```bash
cd electron
npm run build # Platform dị ugbu a
npm run build:win # Windows (.exe NSIS)
npm run build:mac # macOS (.dmg universal)
npm run build:linux # Linux (.AppImage)
```
Nsonaazụ → `electron/dist-electron/`
### Njirimara Ndị Dị Mkpa
| Njirimara | Nkọwa |
| ----------------------------- | ------------------------------------------------------------------------ |
| **Njikere Sava** | Na-enyocha sava tupu igosi windo (enweghị ihuenyo efu) |
| **Tray Sistemụ** | Belata gaa na tray, gbanwee ọdụ ụgbọ, kwụsị site na menu tray |
| **Njikwa Ọdụ Ụgbọ** | Gbanwee ọdụ ụgbọ sava site na tray (na-amalitegharị sava na-akpaghị aka) |
| **Iwu Nchekwa Ọdịnaya** | CSP siri ike site na headers nke session |
| **Otu Instance** | Naanị otu instance nke ngwa nwere ike ịrụ ọrụ n'otu oge |
| **Ọnọdụ Na-enweghị Ịntanetị** | Sava Next.js e tinyere n'ime ya na-arụ ọrụ na-enweghị ịntanetị |
### Mgbanwe Gburugburuwu
| Mgbanwe | Ndabara | Nkọwa |
| --------------------- | ------- | ------------------------------ |
| `OMNIROUTE_PORT` | `20128` | Ọdụ ụgbọ sava |
| `OMNIROUTE_MEMORY_MB` | `512` | Oke heap Node.js (64–16384 MB) |
📖 Akwụkwọ nkọwa zuru ezu: [`electron/README.md`](../../electron/README.md)