# User Guide (አማርኛ)

🌐 **Languages:** 🇺🇸 [English](../../../../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) · 🇷🇴 [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) · 🇸🇦 [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) · 🇷🇴 [ro](../../../ro/docs/guides/USER_GUIDE.md) · 🇷🇺 [ru](../../../ru/docs/guides/USER_GUIDE.md) · 🇱🇰 [si](../../../si/docs/guides/USER_GUIDE.md) · 🇸🇰 [sk](../../../sk/docs/guides/USER_GUIDE.md) · 🇸🇮 [sl](../../../sl/docs/guides/USER_GUIDE.md) · 🇷🇸 [sr](../../../sr/docs/guides/USER_GUIDE.md) · 🇸🇪 [sv](../../../sv/docs/guides/USER_GUIDE.md) · 🇰🇪 [sw](../../../sw/docs/guides/USER_GUIDE.md) · 🇮🇳 [ta](../../../ta/docs/guides/USER_GUIDE.md) · 🇮🇳 [te](../../../te/docs/guides/USER_GUIDE.md) · 🇹🇭 [th](../../../th/docs/guides/USER_GUIDE.md) · 🇹🇷 [tr](../../../tr/docs/guides/USER_GUIDE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/guides/USER_GUIDE.md) · 🇵🇰 [ur](../../../ur/docs/guides/USER_GUIDE.md) · 🇺🇿 [uz](../../../uz/docs/guides/USER_GUIDE.md) · 🇻🇳 [vi](../../../vi/docs/guides/USER_GUIDE.md) · 🇳🇬 [yo](../../../yo/docs/guides/USER_GUIDE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/guides/USER_GUIDE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/guides/USER_GUIDE.md)

አቅራቢዎችን ለማዋቀር፣ ጥምረቶችን ለመፍጠር፣ የCLI መሣሪያዎችን ለማቀናጀት እና OmniRouteን ለማሰማራት የተሟላ መመሪያ።

---

## የይዘት ማውጫ

- [የዋጋ አወጣጥ በአጭሩ](#-pricing-at-a-glance)
- [የአጠቃቀም ሁኔታዎች](#-use-cases)
- [የአቅራቢ ማዋቀር](#-provider-setup)
- [የCLI ውህደት](#-cli-integration)
- [ማሰማራት](#-deployment)
- [የሚገኙ ሞዴሎች](#-available-models)
- [የላቁ ባህሪያት](#-advanced-features)
- [ራስ-ሰር ማስተላለፍ (ያለ ውቅረት)](#-auto-routing-zero-config)
- [የMCP እና A2A ውህደት](#-mcp--a2a-integration)
- [የክህሎቶች ሥርዓት](#-skills-system)
- [የማስታወሻ ሥርዓት](#-memory-system)
- [Webhooks](#-webhooks)
- [የደመና ወኪሎች](#-cloud-agents)
- [ፕሮግራማዊ አስተዳደር](#-programmatic-management)
- [ውስጣዊ CLI](#-internal-cli)
- [የዴስክቶፕ መተግበሪያ (Electron)](#-desktop-application-electron)

---

## 💰 የዋጋ አወጣጥ በአጭሩ

| ደረጃ                 | አቅራቢ              | ወጪ            | የኮታ ዳግም ማስጀመሪያ        | በጣም ተስማሚ የሆነው ለ    |
| ------------------- | ----------------- | ------------- | --------------------- | ------------------ |
| **💳 የደንበኝነት ምዝገባ** | Claude Code (Pro) | $20/በወር       | 5 ሰዓት + በየሳምንቱ        | አስቀድመው ለተመዘገቡ      |
|                     | Codex (Plus/Pro)  | $20-200/በወር   | 5 ሰዓት + በየሳምንቱ        | የOpenAI ተጠቃሚዎች     |
|                     | GitHub Copilot    | $10-19/በወር    | በየወሩ                  | የGitHub ተጠቃሚዎች     |
| **🔑 API ቁልፍ**      | DeepSeek          | በአጠቃቀም ልክ ክፍያ | የለም                   | ርካሽ የማመዛዘን ችሎታ     |
|                     | Groq              | በአጠቃቀም ልክ ክፍያ | የለም                   | እጅግ ፈጣን ኢንፈረንስ     |
|                     | xAI (Grok)        | በአጠቃቀም ልክ ክፍያ | የለም                   | የGrok 4 የማመዛዘን ችሎታ |
|                     | Mistral           | በአጠቃቀም ልክ ክፍያ | የለም                   | በEU የተስተናገዱ ሞዴሎች   |
|                     | Perplexity        | በአጠቃቀም ልክ ክፍያ | የለም                   | በፍለጋ የተጠናከረ        |
|                     | Together AI       | በአጠቃቀም ልክ ክፍያ | የለም                   | ክፍት-ምንጭ ሞዴሎች       |
|                     | Fireworks AI      | በአጠቃቀም ልክ ክፍያ | የለም                   | ፈጣን የFLUX ምስሎች     |
|                     | Cerebras          | በአጠቃቀም ልክ ክፍያ | የለም                   | የዌፈር-ደረጃ ፍጥነት      |
|                     | Cohere            | በአጠቃቀም ልክ ክፍያ | የለም                   | Command R+ RAG     |
|                     | NVIDIA NIM        | በአጠቃቀም ልክ ክፍያ | የለም                   | የድርጅት ሞዴሎች         |
|                     | Baidu Qianfan     | በአጠቃቀም ልክ ክፍያ | የለም                   | ERNIE ሞዴሎች         |
| **💰 ርካሽ**          | GLM-4.7           | $0.6/1M       | በየቀኑ 10AM             | ዝቅተኛ በጀት መጠባበቂያ    |
|                     | MiniMax M2.1      | $0.2/1M       | በየ5 ሰዓቱ ተንከባላይ        | በጣም ርካሹ አማራጭ       |
|                     | Kimi K2           | $9/በወር ቋሚ     | 10M ቶከኖች/በወር          | ሊተነበይ የሚችል ወጪ      |
| **🆓 ነፃ**           | Qoder             | $0            | የአቅራቢው ገደቦች ተፈጻሚ ይሆናሉ | የአሁኑን ካታሎግ ያረጋግጡ   |
|                     | Kiro              | $0            | ~50 ክሬዲቶች/በወር         | Claude በነፃ         |

---

## 🎯 የአጠቃቀም ሁኔታዎች

### ሁኔታ 1: "የClaude Pro የደንበኝነት ምዝገባ አለኝ"

**ችግር:** ኮታው ጥቅም ላይ ሳይውል ያበቃል፤ ከባድ የኮድ ሥራ ሲሠራ የፍጥነት ገደቦች ይኖራሉ

```
ጥምረት: "maximize-claude"
  1. cc/claude-opus-4-7        (የደንበኝነት ምዝገባውን ሙሉ በሙሉ ይጠቀሙ)
  2. glm/glm-4.7               (ኮታው ሲያልቅ ርካሽ መጠባበቂያ)
  3. if/qwen3.8-max-preview       (ነፃ የአደጋ ጊዜ አማራጭ)

ወርሃዊ ወጪ: $20 (የደንበኝነት ምዝገባ) + ~$5 (መጠባበቂያ) = በድምሩ $25
ከ $20 + ገደቦች ላይ መድረስ = ብስጭት ጋር ሲነጻጸር
```

### ሁኔታ 2: "ምንም ወጪ እንዳይኖር እፈልጋለሁ"

**ችግር:** የደንበኝነት ምዝገባዎችን መክፈል አልችልም፤ አስተማማኝ የAI ኮድ ሥራ እፈልጋለሁ

```
ጥምረት: "zero-cost"
  1. if/kimi-k2.7-code          (በዝርዝሩ ውስጥ ነፃ መዳረሻ፤ የፍጥነት ገደቦች ሊተገበሩ ይችላሉ)
  2. kr/qwen3-coder-next        (የKiro ነፃ አማራጭ)

ወርሃዊ ወጪ: $0
ጥራት: ለሥራዎ ሞዴሉን፣ ገደቦቹን፣ ግላዊነቱን እና SLAውን ያረጋግጡ
```

### ሁኔታ 3: "ያለማቋረጥ 24/7 ኮድ መጻፍ እፈልጋለሁ"

**ችግር:** የጊዜ ገደቦች አሉ፤ የሥራ መቋረጥን መቋቋም አልችልም

```
ጥምረት: "always-on"
  1. cc/claude-opus-4-7        (ምርጥ ጥራት)
  2. cx/gpt-5.5                (ሁለተኛ የደንበኝነት ምዝገባ)
  3. glm/glm-4.7               (ርካሽ፣ በየቀኑ ዳግም ይጀምራል)
  4. minimax/MiniMax-M2.1      (በጣም ርካሹ፣ በ5 ሰዓት ዳግም ይጀምራል)
  5. if/deepseek-v4-flash       (በዝርዝሩ ውስጥ ነፃ መዳረሻ፤ የፍጥነት ገደቦች ሊተገበሩ ይችላሉ)

ውጤት: 5 የመጠባበቂያ ንብርብሮች የመቋቋም አቅምን ያሰፋሉ፤ የዋና አቅራቢዎች ተገኝነት ዋስትና የለውም
ወርሃዊ ወጪ: $20-200 (የደንበኝነት ምዝገባዎች) + $10-20 (መጠባበቂያ)
```

### ሁኔታ 4: "በOpenClaw ውስጥ ነፃ AI እፈልጋለሁ"

**ችግር:** በመልዕክት መተግበሪያዎች ውስጥ ሙሉ በሙሉ ነፃ የሆነ የAI ረዳት እፈልጋለሁ

```
ጥምረት: "openclaw-free"
  1. if/qwen3.8-max-preview     (በዝርዝሩ ውስጥ ነፃ መዳረሻ፤ የፍጥነት ገደቦች ሊተገበሩ ይችላሉ)
  2. if/deepseek-v4-flash       (በዝርዝሩ ውስጥ ነፃ መዳረሻ፤ የፍጥነት ገደቦች ሊተገበሩ ይችላሉ)
  3. if/kimi-k2.7-code          (በዝርዝሩ ውስጥ ነፃ መዳረሻ፤ የፍጥነት ገደቦች ሊተገበሩ ይችላሉ)

ወርሃዊ ወጪ: $0
መዳረሻ በ: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
```

---

## 📖 የአቅራቢ ማዋቀር

ከCSV ወይም JSON ፋይል የAPI ቁልፍ ግንኙነቶችን በጅምላ ለመጨመር **Dashboard → Providers → Import from file** ይጠቀሙ። ዓምዶቹ በቦታ ተመድበዋል (`provider,name,apiKey,baseUrl,priority`)፤ `provider` እንደ የሚተዳደር አቅራቢ ወይም ተኳሃኝ ኖድ አስቀድሞ መኖር አለበት። [አቅራቢዎችን ከCSV ወይም JSON ፋይል አስመጣ](../providers/CSV-IMPORT.md) ይመልከቱ።

### 🔐 የምዝገባ አቅራቢዎች

#### Claude Code (Pro/Max)

```bash
Dashboard → Providers → Connect Claude Code
→ የOAuth መግቢያ → ራስ-ሰር የቶከን እድሳት
→ የ5 ሰዓት + ሳምንታዊ ኮታ ክትትል

ሞዴሎች:
  cc/claude-opus-4-7
  cc/claude-sonnet-4-6
  cc/claude-haiku-4-5-20251001
```

**የባለሙያ ምክር፦** ለውስብስብ ሥራዎች Opus፣ ለፍጥነት Sonnet ይጠቀሙ። OmniRoute ኮታን በሞዴል ይከታተላል!

በOmniRoute አስተናጋጅ ላይ አሳሽ የለም? Claude Code የገባበትን ቦታ ሁሉ `claude setup-token` ያስኪዱና የአንድ ዓመት ቶከኑን ወደ **Setup Token** ትር ይለጥፉ። [Claude Code ከማዋቀሪያ ቶከን ጋር](../providers/CLAUDE_CODE_SETUP_TOKEN.md) ይመልከቱ።

ከClaude እና Claude Code ጋር ተኳሃኝ የሆኑ መስመሮች ለOpus እና Sonnet
ሞዴሎች `max` የአስተሳሰብ ጥረትን እንደተጠበቀ ያስቀምጣሉ። የHaiku ሞዴሎች
የ`max` ጥረት ደረጃን አይቀበሉም፤ ስለዚህ OmniRoute ይህን ጥያቄ
ወደ ከፍተኛ የአስተሳሰብ በጀት ዝቅ አድርጎ ወደ ላይኛው አገልግሎት ይልከዋል።

#### OpenAI Codex (Plus/Pro)

```bash
Dashboard → Providers → Connect Codex
→ የOAuth መግቢያ (ፖርት 1455)
→ የ5 ሰዓት + ሳምንታዊ ዳግም ማስጀመር

ሞዴሎች:
  cx/gpt-5.5
  cx/gpt-5.4
  cx/gpt-5.3-codex
  cx/gpt-5.3-codex-spark
```

#### GitHub Copilot

```bash
Dashboard → Providers → Connect GitHub
→ በGitHub በኩል OAuth
→ ወርሃዊ ዳግም ማስጀመር (በወሩ 1ኛ ቀን)

ሞዴሎች:
  gh/gpt-5.5
  gh/gpt-5.4
  gh/claude-sonnet-4.6
  gh/claude-opus-4.7
  gh/gemini-3.1-pro-preview
```

**የAI ክሬዲቶች (በቶከን ላይ የተመሠረተ ክፍያ)።** GitHub ለመለያው
`credits_used` ሲያሳውቅ፣ የአቅራቢ ገደቦች ካርዱ በአሁኑ የክፍያ ጊዜ ውስጥ
የተጠቀሙትን ክሬዲቶች የሚያሳይ **የAI ክሬዲቶች** ረድፍ ያሳያል፤ ይህም
ያልተገደቡ የድርጅት ዕቅዶችን ጨምሮ ይሠራል።

**የአካባቢ የAI ክሬዲቶች ገደብ።** የGitHub ግንኙነትን ያርትዑና **በክፍያ
ጊዜ ውስጥ የAI ክሬዲቶች ገደብ** (`providerSpecificData.githubCreditLimit`) ያዘጋጁ።
ባዶ ከሆነ ያሰናክለዋል፤ `0` ከሆነ ግንኙነቱን ሁልጊዜ ይዘላል። የመጨረሻው
የአጠቃቀም ንባብ ከገደቡ ጋር እኩል ወይም ከዚያ በላይ ሲሆን፣ የመለያ ምርጫ
ይህን ግንኙነት ይዘላል፤ መስመራዊ ማድረግም ወደ ሌሎች ግንኙነቶችዎ ይመለሳል፣
ልክ እንደ የኮታ ፖሊሲ መቁረጫ። ምርመራው በየጊዜው የኮታ እድሳት ቀድሞ
የሚሰበስበውን አጠቃቀም ያነባል — በጥያቄ መንገድ ላይ GitHubን በፍጹም
አይጠራም — እንዲሁም በክፍት ሁኔታ ይሰራል፦ የጎደለ ወይም ያረጀ ንባብ
(ከ15 ደቂቃ በላይ የሆነ፣ ወይም ቀድሞ ዳግም ከተጀመረ የክፍያ ጊዜ የመጣ)
ግንኙነቱን አይከለክልም። ይህ የአካባቢ ጥበቃ ዘዴ እንጂ **የተረጋገጠ
የወጪ ጣሪያ አይደለም**፤ የGitHub ሪፖርት መዘግየቶች፣ የእድሳት ጊዜ ልዩነት፣
በሂደት ላይ ያሉ ጥያቄዎች እና ከOmniRoute ውጭ ያለ አጠቃቀም ከዚህ ሊበልጡ
ይችላሉ። ጠንካራ ገደብ ለማድረግ የGitHub የራሱን የወጪ ቁጥጥሮች ይጠቀሙ።

### 💰 ርካሽ አቅራቢዎች

#### GLM-4.7 (በየቀኑ ዳግም ማስጀመር፣ $0.6/1M)

1. ይመዝገቡ፦ [Zhipu AI](https://open.bigmodel.cn)
2. ከCoding Plan የAPI ቁልፍ ያግኙ
3. Dashboard → Add API Key: አቅራቢ፦ `glm`፣ API ቁልፍ፦ `your-key`

**አጠቃቀም፦** `glm/glm-4.7` — **የባለሙያ ምክር፦** Coding Plan በ1/7 ወጪ 3× ኮታ ያቀርባል! በየቀኑ 10:00 AM ዳግም ይጀምራል።

#### MiniMax M2.1 (በ5 ሰዓት ዳግም ማስጀመር፣ $0.20/1M)

1. ይመዝገቡ፦ [MiniMax](https://www.minimax.io)
2. የAPI ቁልፍ ያግኙ → Dashboard → Add API Key

**አጠቃቀም፦** `minimax/MiniMax-M2.1` — **የባለሙያ ምክር፦** ለረጅም አውድ (1M ቶከኖች) በጣም ርካሹ አማራጭ ነው!

#### Kimi K2 ($9/ወር ቋሚ)

1. ይመዝገቡ፦ [Moonshot AI](https://platform.kimi.ai?aff=omniroute)
2. የAPI ቁልፍ ያግኙ → Dashboard → Add API Key

**አጠቃቀም፦** `kimi/kimi-k2.5` — **የባለሙያ ምክር፦** ለ10M ቶከኖች ቋሚ $9/ወር = በተግባር $0.90/1M ወጪ!

#### Baidu Qianfan / ERNIE

1. ይመዝገቡ፦ [Baidu AI Cloud Qianfan](https://cloud.baidu.com/product/wenxinworkshop)
2. የQianfan API ቁልፍ ይፍጠሩ → Dashboard → Add API Key: አቅራቢ፦ `qianfan`

**አጠቃቀም፦** `qianfan/ernie-5.1`፣ `qianfan/ernie-x1.1`፣ ወይም ሌላ ከQianfan ጋር ተኳሃኝ የOpenAI ሞዴል ID።

### 🆓 ነፃ አቅራቢዎች

ማረጋገጫ የማይፈልጉ ነፃ አቅራቢዎች በአቅራቢ ገጻቸው ላይ **ማረጋገጫ አያስፈልግም** ከሚለው አጠገብ መቀያየሪያ አላቸው።
ይህን ማጥፋት አቅራቢውን ያሰናክላል፣ ከተዋቀሩ አቅራቢዎች/አጭር እይታዎች ያስወግደዋል፣
እንዲሁም ሞዴሎቹን ከ`/v1/models` ያስወግዳል።

#### Qoder (9 ነፃ ሞዴሎች)

```bash
Dashboard → Connect Qoder → የOAuth መግቢያ → መዳረሻው አሁን ባሉ የአቅራቢው ገደቦች ይወሰናል

ሞዴሎች: if/qwen3.8-max-preview, if/qwen3.7-max, if/qwen3.7-plus, if/kimi-k3, if/kimi-k2.7-code, if/glm-5.2, if/deepseek-v4-pro, if/deepseek-v4-flash, if/minimax-m3
```

#### Kiro (Claude ነፃ)

```bash
Dashboard → Connect Kiro → AWS Builder ID ወይም Google/GitHub → በወር ወደ 50 ክሬዲቶች

ሞዴሎች: kr/claude-sonnet-4.5, kr/claude-haiku-4.5
```

---

## 🎨 ጥምረቶች

በእያንዳንዱ ካርድ ላይ ያለውን መያዣ በመጎተት፣ የጥምረት ካርዶችን በቀጥታ በ**ዳሽቦርድ → ጥምረቶች** ውስጥ እንደገና ማደራጀት ይችላሉ። ቅደም ተከተሉ በSQLite ውስጥ ይቀመጣል፣ ዳግም ሲጫንም ይመለሳል።

### ምሳሌ 1፦ የደንበኝነት ምዝገባን ከፍተኛ አጠቃቀም → ርካሽ ምትኬ

```
ዳሽቦርድ → ጥምረቶች → አዲስ ፍጠር

ስም፦ premium-coding
ሞዴሎች፦
  1. cc/claude-opus-4-7 (ዋና የደንበኝነት ምዝገባ)
  2. glm/glm-4.7 (ርካሽ ምትኬ፣ $0.6/1M)
  3. minimax/MiniMax-M2.7 (በጣም ርካሹ አማራጭ፣ $0.3/1M)

በCLI ውስጥ ይጠቀሙ፦ premium-coding
```

### ምሳሌ 2፦ ነፃ-ብቻ (ዜሮ ወጪ)

```
ስም፦ free-combo
ሞዴሎች፦
  1. if/kimi-k2.7-code (ነፃ መዳረሻ እንዳለው ተዘርዝሯል፤ የአቅራቢው ገደቦች ሊተገበሩ ይችላሉ)
  2. kr/qwen3-coder-next (ነፃ የKiro ምትኬ)

ወጪ፦ በአሁኑ ጊዜ $0 ተብሎ ተዘርዝሯል፤ ውሎችና ተገኝነት ሊለወጡ ይችላሉ
```

---

## 🔧 የCLI ውህደት

### Cursor IDE

**Cursorን እንደ OmniRoute ደንበኛ መጠቀም** (የCursor ውይይትን በOmniRoute በኩል ማስተላለፍ)፦

```
ቅንብሮች → ሞዴሎች → የላቀ፦
  OpenAI API መሠረታዊ URL፦ http://localhost:20128/v1
  OpenAI API ቁልፍ፦ [ከomniroute ዳሽቦርድ]
  ሞዴል፦ cc/claude-opus-4-7
```

**OmniRouteን እንደ Cursor አቅራቢ መጠቀም** (OmniRoute ወደላይ ያለውን Cursor ይጠራል)፦
**ዳሽቦርድ → አቅራቢዎች → Cursor → በCursor ግባ** የሚለው ይመረጣል። በDocker ውስጥ
[`docs/providers/CURSOR-DOCKER.md`](../providers/CURSOR-DOCKER.md)ን ይመልከቱ።

### Claude Code

`~/.claude/settings.json`ን ያርትዑ፦

```json
{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:20128",
    "ANTHROPIC_AUTH_TOKEN": "your-omniroute-api-key"
  }
}
```

እዚህ Claude-ተኳሃኝ የሆነውን ዋና endpoint ይጠቀሙ። ወደ `ANTHROPIC_BASE_URL` `/v1`ን አይጨምሩ።

### Codex CLI

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

### OpenClaw

`~/.openclaw/openclaw.json`ን ያርትዑ፦

```json
{
  "agents": {
    "defaults": {
      "model": { "primary": "omniroute/if/kimi-k2.7-code" }
    }
  },
  "models": {
    "providers": {
      "omniroute": {
        "baseUrl": "http://localhost:20128/v1",
        "apiKey": "your-omniroute-api-key",
        "api": "openai-completions",
        "models": [{ "id": "if/kimi-k2.7-code", "name": "Kimi K2.7 Code" }]
      }
    }
  }
}
```

**ወይም ዳሽቦርድን ይጠቀሙ፦** CLI መሣሪያዎች → OpenClaw → ራስ-ሰር ውቅር

### Cline / Continue / RooCode

```
አቅራቢ፦ ከOpenAI ጋር ተኳሃኝ
መሠረታዊ URL፦ http://localhost:20128/v1
API ቁልፍ፦ [ከዳሽቦርድ]
ሞዴል፦ cc/claude-opus-4-7
```

---

## 🚀 ማሰማራት

### ዓለም አቀፍ npm መጫን (የሚመከር)

```bash
npm install -g omniroute

# Create config directory
mkdir -p ~/.omniroute

# Create .env file (see .env.example)
cp .env.example ~/.omniroute/.env

# Start server
omniroute
# Or with custom port:
omniroute --port 3000
```

CLI በራስሰር `.env` ከ `~/.omniroute/.env` ወይም `./.env` ይጭናል። በስራ ማውጫው ውስጥ ያለው `./.env` አጭር የተፈቀደ ቁልፍ ዝርዝር ብቻ ሊያዘጋጅ ይችላል (ወደቦች ፣ `REQUIRE_API_KEY`፣ የአካባቢ እና የቀለም ቅንጅቶች)። ሁሉንም ነገር በ `~/.omniroute/.env` ውስጥ ያስቀምጡ. [CLI ማስጀመሪያ ውሎችን](CLI-LAUNCH-CONTRACTS.md#working-directory-env) ይመልከቱ።

### የትሪ ሁነታ

በስርዓት መሣቢያው ውስጥ OmniRoute ጀምር

```bash
omniroute serve --tray
```

ትዕዛዙ አገልጋዩ እና ትሪው ዝግጁ ከሆኑ በኋላ ይመለሳል።

አገልጋዩ ያለ ተርሚናል ይቀጥላል።

ትሬይ ሁነታ macOS, Windows, እና በግራፊክ Linux ክፍለ ጊዜዎችን ይደግፋል. የትሬይ ሁነታ ዳሽቦርዱን በራስ ሰር አይከፍትም።

ለእነዚህ ድርጊቶች የትሪ ምናሌውን ይጠቀሙ፡-

- ዳሽቦርዱን ይክፈቱ።
- `/dashboard/logs` ን ይክፈቱ።
- ራስ-ሰር ጅምርን ይቀይሩ።
- OmniRoute አቁም .

`--tray` ከእነዚህ አማራጮች ጋር አታጣምር፡-

- `--daemon`
- `--log`
- `--no-recovery`

እነዚህ ሁነታዎች የተለያየ የሂደት ባለቤትነት ያስፈልጋቸዋል።

በሚቀጥለው የማሽን መግቢያ ላይ ጅምርን አንቃ፡-

```bash
omniroute autostart enable
```

ራስ-ጀምር በ macOS፣ Windows እና በግራፊክ Linux ክፍለ-ጊዜዎች ላይ የመሳቢያ ሁነታን ይጠቀማል። ጭንቅላት የሌለው Linux ያለውን የስርዓት ተጠቃሚ አገልግሎት ይጠቀማል።

በመግቢያው ላይ ጅምርን ያሰናክሉ፡

```bash
omniroute autostart disable
```

### በማራገፍ ላይ

OmniRoute በማይፈልጉበት ጊዜ፣ ለንፁህ ማስወገጃ ሁለት ፈጣን ስክሪፕቶችን እናቀርባለን።

| ትዕዛዝ                     | ድርጊት                                                                   |
| ------------------------ | ---------------------------------------------------------------------- |
| `npm run uninstall`      | የስርዓት መተግበሪያን ያስወግዳል ግን** የእርስዎን DB እና ውቅሮች ይጠብቃል።** በ `~/.omniroute`. |
| `npm run uninstall:full` | መተግበሪያው AND በቋሚነት ያስወግዳል** ሁሉንም አወቃቀሮች፣ ቁልፎች እና የውሂብ ጎታዎችን ይሰርዛል** .   |

> ማሳሰቢያ፡ እነዚህን ትዕዛዞች ለማስኬድ ወደ OmniRoute ፕሮጀክት ማህደር (ክሎድ ካደረጉት) ይሂዱ እና ያሂዱ። በአማራጭ፣ በአለምአቀፍ ደረጃ ከተጫነ በቀላሉ `npm uninstall -g omniroute` ማሄድ ይችላሉ።

### VPS ማሰማራት

```bash
git clone https://github.com/diegosouzapw/OmniRoute.git
cd OmniRoute && npm install && npm run build

export JWT_SECRET="your-secure-secret-change-this"
export INITIAL_PASSWORD="your-password"
export DATA_DIR="/var/lib/omniroute"
export PORT="20128"
export HOSTNAME="0.0.0.0"
export NODE_ENV="production"
export NEXT_PUBLIC_BASE_URL="http://localhost:20128"
export API_KEY_SECRET="endpoint-proxy-api-key-secret"

npm run start
# Or: pm2 start npm --name omniroute -- start
```

### PM2 ማሰማራት (ዝቅተኛ ማህደረ ትውስታ)

ውስን RAM ላላቸው አገልጋዮች የማህደረ ትውስታ ገደብ አማራጩን ይጠቀሙ፡-

```bash
# With 512MB limit (default)
pm2 start npm --name omniroute -- start

# Or with custom memory limit
OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start

# Or using ecosystem.config.js
pm2 start ecosystem.config.js
```

`ecosystem.config.js` ይፍጠሩ:

```javascript
module.exports = {
  apps: [
    {
      name: "omniroute",
      script: "npm",
      args: "start",
      env: {
        NODE_ENV: "production",
        OMNIROUTE_MEMORY_MB: "512",
        JWT_SECRET: "your-secret",
        INITIAL_PASSWORD: "your-password",
      },
      node_args: "--max-old-space-size=512",
      max_memory_restart: "300M",
    },
  ],
};
```

### Docker

```bash
# Build image (default = runner-cli with codex/claude/droid preinstalled)
docker build -t omniroute:cli .

# Portable mode (recommended)
docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli
```

ለአስተናጋጅ የተዋሃደ ሁነታ ከ CLI ሁለትዮሾች ጋር፣ በዋናው ሰነዶች ውስጥ የ Docker ክፍልን ይመልከቱ።

### ባዶ Linux (xbps-src)

ባዶ Linux ተጠቃሚዎች የ `xbps-src` ማጠቃለያ ማዕቀፍን በመጠቀም OmniRoute ማሸግ እና መጫን ይችላሉ። ይህ የ Node.js ብቻውን ግንባታ ከሚፈለገው `better-sqlite3` ቤተኛ ማሰሪያዎች ጋር በራስ ሰር ያደርገዋል።

<details>
<summary><b>የ xbps-src አብነት ይመልከቱ</b></summary>

```bash
# Template file for '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 <zenobit@disroot.org>"
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() {
	# Determine target CPU arch for 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) Install all deps – skip scripts
	NODE_ENV=development npm ci --ignore-scripts

	# 2) Build the Next.js standalone bundle
	npm run build

	# 3) Copy static assets into standalone
	cp -r .next/static .next/standalone/.next/static
	[ -d public ] && cp -r public .next/standalone/public || true

	# 4) Compile better-sqlite3 native binding
	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) Place the compiled binding into the 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) Remove arch-specific sharp bundles
	rm -rf .next/standalone/node_modules/@img

	# 7) Copy pino runtime deps omitted by Next.js static analysis:
	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

	# Prevent removal of empty Next.js app router dirs by the post-install hook
	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
}
```

</details>

### የአካባቢ ተለዋዋጮች

| ተለዋዋጭ                                   | ነባሪ                      | መግለጫ                                                                                                  |
| --------------------------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------- |
| `JWT_SECRET`                            | _(በራስ-ሰር የተፈጠረ)_         | JWT ፊርማ ሚስጥራዊ — በራስ የመነጨ በመጀመሪያ ሩጫ እና እስከ `server.env` ድረስ ቀጠለ; የውሂብ ማውጫው ጊዜያዊ በሚሆንበት ጊዜ በግልጽ ያስቀምጡት። |
| `INITIAL_PASSWORD`                      | _(ያልተቀናበረ)_              | መጀመሪያ የመግቢያ የይለፍ ቃል. npm/source ጭነቶች በ `CHANGEME` ይጀምራሉ: ይተኩ. አልተዋቀረም፡ የመሳፈር አዋቂ                      |
| `DATA_DIR`                              | `~/.omniroute`           | የውሂብ ማውጫ (ዲቢ፣ አጠቃቀም፣ ምዝግብ ማስታወሻዎች)                                                                    |
| `PORT`                                  | ማዕቀፍ ነባሪ                 | የአገልግሎት ወደብ (`20128` በምሳሌዎች)                                                                          |
| `HOSTNAME`                              | ማዕቀፍ ነባሪ                 | አስረው አስተናጋጅ (Docker ነባሪ ወደ `0.0.0.0`)                                                                 |
| `NODE_ENV`                              | የሩጫ ጊዜ ነባሪ               | ለማሰማራት `production` አዘጋጅ                                                                              |
| `NEXT_PUBLIC_BASE_URL`                  | `http://localhost:20128` | የህዝብ መሰረት URL ወደ ዳሽቦርዱ ወጣ እና ለአገልጋዩ ተጋልጧል (የቆየ `BASE_URL` ይተካዋል)                                      |
| `NEXT_PUBLIC_CLOUD_URL`                 | `https://omniroute.dev`  | የክላውድ ማመሳሰል የመጨረሻ ነጥብ ቤዝ URL (የቆየ `CLOUD_URL` ን ይተካዋል)                                                |
| `API_KEY_SECRET`                        | _(በራስ-ሰር የተፈጠረ)_         | HMAC ሚስጥር ለተፈጠሩ API ቁልፎች — በራስ ሰር የተፈጠረ እና በ `server.env` ጸንቷል                                        |
| `REQUIRE_API_KEY`                       | `false`                  | Bearer API ቁልፍን በ `/v1/*` ላይ ያስፈጽሙ                                                                    |
| `ALLOW_API_KEY_REVEAL`                  | `false`                  | የተረጋገጡ የዳሽቦርድ ተጠቃሚዎች ሙሉ የተከማቹ API ቁልፍ እሴቶችን በፍላጎት እንዲያሳዩ ይፍቀዱላቸው                                      |
| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70`                     | ለተሸጎጠ የአቅራቢ ገደብ ውሂብ የአገልጋይ-ጎን አድስ ማረጋገጫ; UI አድስ አዝራሮች አሁንም በእጅ ማመሳሰልን ይቀሰቅሳሉ                          |
| `DISABLE_SQLITE_AUTO_BACKUP`            | `false`                  | ከ writes/import/restore በፊት አውቶማቲክ SQLite ቅጽበተ-ፎቶዎችን አሰናክል; በእጅ ምትኬዎች አሁንም ይሰራሉ                       |
| `APP_LOG_TO_FILE`                       | `true`                   | የመተግበሪያ እና የኦዲት ምዝግብ ማስታወሻን ወደ ዲስክ ያነቃል።                                                              |
| `AUTH_COOKIE_SECURE`                    | `false`                  | `Secure` auth ኩኪን አስገድድ (ከ HTTPS ተገላቢጦሽ ፕሮክሲ ጀርባ)                                                     |
| `CLOUDFLARED_BIN`                       | አልተዋቀረም።                 | ከሚተዳደር ማውረድ ይልቅ ነባር `cloudflared` ሁለትዮሽ ይጠቀሙ                                                          |
| `CLOUDFLARED_PROTOCOL`                  | `http2`                  | ለሚተዳደሩ ፈጣን ዋሻዎች መጓጓዣ (`http2`፣ `quic` ወይም `auto`)                                                     |
| `OMNIROUTE_MEMORY_MB`                   | `512`                    | Node.js ክምር ገደብ በ MB                                                                                  |
| `PROMPT_CACHE_MAX_SIZE`                 | `50`                     | ከፍተኛው ፈጣን መሸጎጫ ግቤቶች                                                                                   |
| `SEMANTIC_CACHE_MAX_SIZE`               | `100`                    | ከፍተኛው የትርጉም መሸጎጫ ግቤቶች                                                                                 |

ለሙሉ አካባቢ ተለዋዋጭ ማጣቀሻ፣ [README](../README.md) ይመልከቱ።

---

## 📊 ያሉ ሞዴሎች

<details>
<summary><b>ያሉ ሁሉንም ሞዴሎች ይመልከቱ</b></summary>

> ከ `open-sse/config/providerRegistry.ts` ለ v3.8.0 የተመረጠ ዝርዝር ነው። የCloud ካታሎጎች (Gemini፣ OpenRouter፣ ወዘተ) በተለዋዋጭ ይመሳሰላሉ — ሙሉውን የቀጥታ ካታሎግ ለመክፈት **ዳሽቦርድ → አቅራቢዎች → [provider] → ያሉ ሞዴሎች** ይሂዱ ወይም `GET /api/models/catalog` ይጥሩ።
>
> የአንድ አቅራቢ አብሮ የተሰራ ዝርዝር ከቀጥታ ካታሎጉ ጋር ካልተመሳሰለ፣ በዚያ ገጽ ላይ **ከ /models አስመጣ** የሚለውን ይጠቀሙ (ወይም **ራስ-ሰር ማመሳሰል**ን ያንቁ)፤ ይህም የቀጥታ የupstream ካታሎግን ያመጣል። ይህ በ v3.8.50 ለ LLM7.io (`gemini-3.1-flash-lite`) እና UncloseAI (`solidrust/Hermes-3-Llama-3.1-8B-AWQ`) ተረጋግጧል፤ Pollinations የማይታወቅ መዳረሻ በዚያው የሙከራ ዙር ወቅት በupstream የተገደበ ሆኖ ቀርቷል።

**Claude Code (`cc/`)** — Pro/Max OAuth፦ `cc/claude-opus-4-8`, `cc/claude-opus-4-7`, `cc/claude-opus-4-6`, `cc/claude-opus-4-5-20251101`, `cc/claude-sonnet-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`

**Codex (`cx/`)** — Plus/Pro OAuth፦ `cx/gpt-5.5` (+ የጥረት ደረጃዎች፦ `gpt-5.5-xhigh`, `gpt-5.5-high`, `gpt-5.5-medium`, `gpt-5.5-low`), `cx/gpt-5.4`, `cx/gpt-5.4-mini`, `cx/gpt-5.3-codex`, `cx/gpt-5.3-codex-spark`

**GitHub Copilot (`gh/`)** — OAuth፦ `gh/gpt-5.5`, `gh/gpt-5.4`, `gh/gpt-5.4-mini`, `gh/gpt-5-mini`, `gh/gpt-5.3-codex`, `gh/claude-opus-4.7`, `gh/claude-opus-4.6`, `gh/claude-opus-4-5-20251101`, `gh/claude-sonnet-4.6`, `gh/claude-sonnet-4.5`, `gh/claude-haiku-4.5`, `gh/gemini-3.1-pro-preview`, `gh/gemini-3-flash-preview`, `gh/oswe-vscode-prime`

**Kiro (`kr/`)** — ነፃ OAuth፦ በ **ዳሽቦርድ → አቅራቢዎች → Kiro → ያሉ ሞዴሎች** ስር የሚታየውን የቀጥታ ካታሎግ ይጠቀሙ። ተገኝነቱ በመለያው እና በዕቅዱ ይወሰናል።

**Qoder (`if/`)** — ነፃ OAuth፦ `if/qwen3.8-max-preview`, `if/qwen3.7-max`, `if/qwen3.7-plus`, `if/kimi-k3`, `if/kimi-k2.7-code`, `if/glm-5.2`, `if/deepseek-v4-pro`, `if/deepseek-v4-flash`, `if/minimax-m3`

**GLM (`glm/`, `glm-cn/`, `zai/`, `glmt/`)** — $0.2–0.6/1M፦ `glm/glm-5.1`, `glm/glm-5`, `glm/glm-5-turbo`, `glm/glm-4.7`, `glm/glm-4.7-flash`, `glm/glm-4.6`, `glm/glm-4.6v`, `glm/glm-4.5`, `glm/glm-4.5v`, `glm/glm-4.5-air`

**MiniMax (`minimax/`, `minimax-cn/`)** — $0.2/1M፦ `minimax/MiniMax-M2.7`, `minimax/MiniMax-M2.7-highspeed`, `minimax/MiniMax-M2.5`, `minimax/MiniMax-M2.5-highspeed`

**Kimi (`kimi/`, `kimi-coding/`, `kimi-coding-apikey/`)** — $9/ወር ቋሚ ክፍያ ወይም በአጠቃቀም፦ `kimi/kimi-k2.6`, `kimi/kimi-k2.5`

**DeepSeek (`ds/`)** — የAPI ቁልፍ፦ `ds/deepseek-v4-pro`, `ds/deepseek-v4-flash`

**Groq (`groq/`)** — እጅግ ፈጣን፦ `groq/llama-3.3-70b-versatile`, `groq/meta-llama/llama-4-maverick-17b-128e-instruct`, `groq/qwen/qwen3-32b`, `groq/openai/gpt-oss-120b`

**xAI (`xai/`)** — ተፈጥሯዊ Grok፦ `xai/grok-4.3`, `xai/grok-4.20-multi-agent-0309`, `xai/grok-4.20-0309-reasoning`, `xai/grok-4.20-0309-non-reasoning`

**Mistral (`mistral/`)** — በEU የሚስተናገድ፦ `mistral/mistral-large-latest`, `mistral/mistral-medium-3-5`, `mistral/mistral-small-latest`, `mistral/codestral-latest`

**Perplexity (`pplx/`)** — በፍለጋ የተጨመረ፦ `pplx/sonar-deep-research`, `pplx/sonar-reasoning-pro`, `pplx/sonar-pro`, `pplx/sonar`

**Together AI (`together/`)** — ክፍት ምንጭ፦ `together/meta-llama/Llama-3.3-70B-Instruct-Turbo-Free` (ነፃ), `together/meta-llama/Llama-Vision-Free`, `together/deepseek-ai/DeepSeek-R1-Distill-Llama-70B-Free`, `together/deepseek-ai/DeepSeek-R1`, `together/Qwen/Qwen3-235B-A22B`, `together/meta-llama/Llama-4-Maverick-17B-128E-Instruct-FP8`

**Fireworks AI (`fireworks/`)** — ፈጣን ኢንፈረንስ፦ `fireworks/accounts/fireworks/models/kimi-k2p6`, `fireworks/accounts/fireworks/models/minimax-m2p7`, `fireworks/accounts/fireworks/models/qwen3p6-plus`, `fireworks/accounts/fireworks/models/glm-5p1`, `fireworks/accounts/fireworks/models/deepseek-v4-pro`

**Cerebras (`cerebras/`)** — በዋፈር ሚዛን፦ `cerebras/zai-glm-4.7`, `cerebras/gpt-oss-120b`

**Cohere (`cohere/`)** — በRAG ላይ ያተኮረ፦ `cohere/command-a-reasoning-08-2025`, `cohere/command-a-vision-07-2025`, `cohere/command-a-03-2025`, `cohere/command-r-08-2024`

**NVIDIA NIM (`nvidia/`)** — ለድርጅቶች፦ `nvidia/google/gemma-4-31b-it`, `nvidia/nvidia/nemotron-3.5-super-vl-120b-a12b`, `nvidia/nvidia/nemotron-3-ultra-550b-a55b`, `nvidia/nvidia/nemotron-3.5-lightning-30b-a3b`

**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/`)**፦ በGoogle በኩል ለእያንዳንዱ API ቁልፍ በቀጥታ ይመሳሰላል — ቋሚ ዝርዝር የለውም። ቁልፍ በ **ዳሽቦርድ → አቅራቢዎች** ያገናኙ፣ ከዚያ **ያሉ ሞዴሎች**ን በመጠቀም የአሁኑን ካታሎግ ያስመጡ (ለምሳሌ `gemini/gemini-3-pro`, `gemini/gemini-3-flash`)።

**ሌሎች ተኳኋኝ አቅራቢዎች** (የተመረጡ)፦ `cohere`, `databricks`, `snowflake`, `together`, `vertex`, `alibaba`, `alibaba-cn`, `bedrock` (በ `aws-bedrock` በኩል), `azure-ai`, `openrouter` (የሚያልፍ ካታሎግ), `siliconflow`, `hyperbolic`, `huggingface`, `featherless-ai`, `cloudflare-ai`, `scaleway`, `deepinfra`, `vercel-ai-gateway`, `bazaarlink`, `friendliai`, `nous-research`, `reka`, `volcengine`, `ai21`, `gigachat`። እያንዳንዱ በ `providerRegistry.ts` ውስጥ የራሱን የሞዴል ዝርዝር ያስተዳድራል፣ እና አቅራቢው `/models` የሚል endpoint ካቀረበ በራስ-ሰር ሊመሳሰል ይችላል።

**ስለ ሞዴል መለያዎች ማስታወሻ፦** OmniRoute የአቅራቢውን ተፈጥሯዊ መለያዎች ይጠቀማል (`claude-opus-4-8`, `gpt-5.5`, `glm-5.1`, `MiniMax-M2.7`, `kimi-k2.5`, `grok-4.20-0309-reasoning`)። አንዳንድ መለያዎች ነጥብ የያዙ ስሪቶችን ያካትታሉ፤ ምክንያቱም የupstream API እንዲሁ እንዲሆኑ ስለሚጠብቅ ነው። አንድ ሞዴል ከላይ በተዘረዘረው ውስጥ ካልተካተተ፣ ተገኝነቱን ለማረጋገጥ `omniroute models --search <term>` ያስኪዱ ወይም `GET /api/models/catalog` ይጠቀሙ።

</details>

---

## 🧩 የላቀ ባህሪያት

### ብጁ ሞዴሎች

የመተግበሪያ ዝማኔን ሳይጠብቁ ማንኛውንም ሞዴል ID ወደ ማንኛውም አቅራቢ ያክሉ።

```bash
# Via 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"}'

# List: curl http://localhost:20128/api/provider-models?provider=openai
# Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-5.2"
```

ወይም ዳሽቦርድን ተጠቀም፡-** አቅራቢዎች → [አቅራቢ] → ብጁ ሞዴሎች** .

ማስታወሻዎች፡-

- OpenRouter እና OpenAI/Anthropic-compatible አቅራቢዎች የሚተዳደሩት ከ** የሚገኙ ሞዴሎች** ብቻ። ሁሉንም መሬት በተመሳሳይ ሞዴል ዝርዝር ውስጥ በእጅ ያክሉ ፣ ያስመጡ እና በራስ-አመሳስል ፣ ስለዚህ ለእነዚያ አቅራቢዎች የተለየ የብጁ ሞዴሎች ክፍል የለም።
- የ** ብጁ ሞዴሎች** ክፍል የሚተዳደሩ የሚገኙ-ሞዴል ማስመጣቶችን ለማያጋለጡ አቅራቢዎች የታሰበ ነው።

### ብጁ ክፍት AI-ተኳሃኝ አቅራቢዎች

OpenAI API (በራስ የሚያስተናግድ ፕሮክሲ፣ vLLM፣ የሶስተኛ ወገን ሰብሳቢ) የሚናገር ማንኛውም መግቢያ እንደ የራሱ የአቅራቢ መስቀለኛ መንገድ መጨመር ይቻላል፡-

1. **አቅራቢዎች → አክል OpenAI የሚስማማ** .
2. **ስም** ለ መስቀለኛ መንገድ ማሳያ መለያ።
3. **ቅድመ ቅጥያ** : የማዞሪያ ስም. ደንበኞች ሞዴሎችን `<prefix>/<model>` ብለው ይጠሩታል፣ ስለዚህ `mygw` ቅድመ ቅጥያ ያለው መስቀለኛ መንገድ `mygw/gpt-4o-mini` ያገለግላል። የሚያስፈልግ; ምንም የባህሪ ገደብ የለም.
4. **API አይነት** መግቢያ በር የሚያገለግለው የመጨረሻው ነጥብ ቤተሰብ (የውይይት ማጠናቀቂያዎች፣ ምላሾች፣ መክተቻዎች፣ ኦዲዮ፣ ምስሎች)።
5. **ቤዝ URL** የ API ሥር፣ እስከ `/v1` ድረስ (ለምሳሌ `https://gateway.example.com/v1`)፣ ሙሉው `/chat/completions` መንገድ አይደለም። መደበኛ ያልሆኑ ዱካዎች ያላቸው በሮች ያስቀምጣቸዋል።** የላቁ ቅንብሮች** (የውይይት መንገድ፣ የሞዴሎች መንገድ)።
6. የ**API ቁልፍ (ለመፈተሽ)** መስክ ግንኙነቱን ብቻ ይፈትሻል. መስቀለኛ መንገድን ከፈጠሩ በኋላ ይክፈቱት እና ይጠቀሙ** ግንኙነት ጨምር** የሚጠይቀውን ቁልፍ ለማከማቸት።

መስቀለኛ መንገድ `openai-compatible-<apiType>-<uuid>` ያለውን ውስጣዊ መታወቂያ ያገኛል; እሱን መተየብ በጭራሽ አያስፈልግዎትም ፣ ቅድመ ቅጥያው የህዝብ ስም ነው።

#### የተጠበቁ ቅድመ ቅጥያዎች

ቅድመ ቅጥያ አብሮ የተሰራ አቅራቢ መታወቂያ ወይም ተለዋጭ ስም (ለምሳሌ `openai`፣ `cf`) ወይም የጡረታ አገልግሎት ሰጪ መታወቂያ ሊሆን አይችልም። የሞዴል ፈላጊው አብሮገነብ መታወቂያዎችን እና ተለዋጭ ስሞችን ከብጁ አንጓዎች በፊት ይፈትሻል፣ ስለዚህ ከነዚህ ቅድመ ቅጥያዎች ውስጥ አንዱን የሚጠቀም መስቀለኛ መንገድ በጭራሽ ትራፊክ አይቀበልም `<prefix>/model` በምትኩ ወደ አብሮገነብ አገልግሎት አቅራቢ ይሄዳል፣ ወይም ያ አቅራቢ ጡረታ ከወጣ አይዘጋም። እንደዚህ ያለ ቅድመ ቅጥያ ያለው መስቀለኛ መንገድ መፍጠር ወይም ማርትዕ በሚከተሉት ውድቅ ተደርጓል፡-

```text
prefix: "<prefix>" is a reserved provider prefix — choose a different prefix (reserved ids/aliases cannot be used for custom nodes because requests like <prefix>/model route to a built-in provider or fail closed when retired)
```

የተለየ ቅድመ ቅጥያ ይምረጡ (`mygw`፣ `acme-proxy`)። የብጁ መስቀለኛ መንገድ ጥያቄዎች አብሮ የተሰራውን አቅራቢን ወይም መታወቂያዎቹን በሚሰይም ስህተት ካልተሳካ፣ የመስቀለኛ መንገድ ቅድመ-ቅጥያ የተያዘ መሆኑን ያረጋግጡ፡ ይህ ደንብ ከመኖሩ በፊት የተቀመጡ አንጓዎች አሁንም ይቀመጣሉ፣ ነገር ግን ቅድመ ቅጥያ መንገዶቻቸው ወደ አብሮገነብ አቅራቢው ይመጣሉ። መስቀለኛ መንገድን ያርትዑ እና አዲስ ቅድመ ቅጥያ ይስጡት።

#### የግንኙነቶች መግቢያ አማራጮች

እነዚህ ቁልፎች በግንኙነት `providerSpecificData` ውስጥ ይሄዳሉ (ለምሳሌ በ `PUT /api/providers/{id}`)፡-

- `toolNameMaxLength` (ኢንቲጀር፣ 1–1024) — ለ OpenAI የውይይት-ቅርጸት ተኳሃኝ ግንኙነቶች መተላለፊያቸው ረጅም የመሳሪያ ስሞችን የማይቀበል። ረዣዥም ስሞች እንደ አጭር ተለዋጭ ስም ይላካሉ እና በምላሹ ወደነበሩበት ይመለሳሉ።
- `quotaEndpoint` — የመግቢያ መንገዱ quota/credits መጨረሻ ነጥብ፣ ለዳሽቦርድ ኮታ ስትሪፕ እና ኮታ-አዋቂ ማዘዋወር ያንብቡ። በሁለቱም በ OpenAI- እና Anthropic-ተኳሃኝ ግንኙነቶች ላይ ይሰራል; ሙሉው ቅርጽ በ `open-sse/services/usage/openaiCompatible.ts` ውስጥ ተመዝግቧል.

```json
{
  "toolNameMaxLength": 64,
  "quotaEndpoint": {
    "url": "https://gateway.example.com/key/info",
    "auth": "bearer",
    "quotas": {
      "budget": { "used": "$.info.spend", "total": "$.info.max_budget", "currency": "USD" }
    }
  }
}
```

### ሰንሰለት OmniRoute እኩዮች

ሌላ OmniRoute መግቢያ በር እንደ ሀ ሊጨመር ይችላል።** ብጁ OpenAI-ተኳሃኝ** አቅራቢ. የአቻውን `/v1` መሰረት URL እና በዛ እኩያ የተሰጠ ትንሽ ልዩ መብት ያለው API ቁልፍ ተጠቀም።

ለተገላቢጦሽ ወይም ለብዙ-ሆፕ ሰንሰለቶች የመርጦ መግቢያ ምልክቱን በእያንዳንዱ መግቢያ በር ላይ ያንቁት፡-

```bash
# gateway-a
OMNIROUTE_INSTANCE_ID=gateway-a
OMNIROUTE_PEER_URLS=http://gateway-b:20128/v1
OMNIROUTE_PEER_MAX_HOPS=4
```

```bash
# gateway-b
OMNIROUTE_INSTANCE_ID=gateway-b
OMNIROUTE_PEER_URLS=http://gateway-a:20128/v1
OMNIROUTE_PEER_MAX_HOPS=4
```

በግልጽ ለተፈቀደ አቻ URL የተላኩ ጥያቄዎች ብቻ የ `X-OmniRoute-Peer-Trace` ራስጌ ይቀበላሉ። መግቢያ በር ተደጋጋሚ ምሳሌ ID ወይም የተዳከመ የሆፕ በጀት ከ HTTP `508 Loop Detected` ጋር ውድቅ ያደርጋል። ተራ ጅረት አቅራቢዎች ምንም አቻ ዲበዳታ አይቀበሉም።

የአቻ ሰንሰለት ማባዛት ወይም አስተናጋጅ አለመሳካት የውሂብ ጎታ አይደለም። እያንዳንዱ መግቢያ በር ራሱን የቻለ SQLite ሁኔታን፣ መሸጎጫዎችን፣ የዋጋ ቆጣሪዎችን እና ክፍለ ጊዜዎችን ያቆያል። ለ active/passive ወይም active/active ተገኝነት በጤና የተረጋገጠ የተገላቢጦሽ ፕሮክሲ ወይም የደንበኛ ውድቀትን ተጠቀም እና መቼም አንድ SQLite ዳታቤዝ ወደ ብዙ አሂድ OmniRoute አብነቶች አትጫን።

### የወሰኑ አቅራቢ መንገዶች

የሞዴል ማረጋገጫ ወደ አንድ የተወሰነ አገልግሎት አቅራቢ መስመር ጥያቄዎችን ያቀርባል፡-

```bash
POST http://localhost:20128/v1/providers/openai/chat/completions
POST http://localhost:20128/v1/providers/openai/embeddings
POST http://localhost:20128/v1/providers/fireworks/images/generations
```

የአቅራቢው ቅድመ ቅጥያ ከጠፋ በራስ-ሰር ታክሏል። የማይዛመዱ ሞዴሎች `400` ይመለሳሉ.

### የአውታረ መረብ ተኪ ውቅር

```bash
# Set global proxy
curl -X PUT http://localhost:20128/api/settings/proxy \
  -d '{"global": {"type":"http","host":"proxy.example.com","port":"8080"}}'

# Per-provider proxy
curl -X PUT http://localhost:20128/api/settings/proxy \
  -d '{"providers": {"openai": {"type":"socks5","host":"proxy.example.com","port":"1080"}}}'

# Test proxy
curl -X POST http://localhost:20128/api/settings/proxy/test \
  -d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}'
```

**ቅድሚያ:** ቁልፍ-ተኮር → ጥምር-ተኮር → አቅራቢ-ተኮር → ግሎባል → አካባቢ።

### የሞዴል ካታሎግ API

```bash
curl http://localhost:20128/api/models/catalog
```

በአቅራቢው የተቧደኑ ሞዴሎችን ከአይነቶች (`chat`፣ `embedding`፣ `image` ይመልሳል)።

### የደመና ማመሳሰል

- በመሳሪያዎች ላይ አቅራቢዎችን፣ ጥንብሮችን እና ቅንብሮችን ያመሳስሉ።
- በራስ-ሰር የበስተጀርባ ማመሳሰል በጊዜ ማብቂያ + በፍጥነት አልተሳካም።
- በምርት ውስጥ የአገልጋይ ጎን `NEXT_PUBLIC_BASE_URL`/`NEXT_PUBLIC_CLOUD_URL` ይምረጡ

### Cloudflare ፈጣን መሿለኪያ

- ውስጥ ይገኛል** ዳሽቦርድ → የመጨረሻ ነጥቦች** ለ Docker እና ሌሎች በራሳቸው የሚስተናገዱ ማሰማራት
- ወደ የአሁኑ የOpenAI-ተኳሃኝ `/v1` የመጨረሻ ነጥብዎ የሚያስተላልፍ ጊዜያዊ `https://*.trycloudflare.com` URL ይፈጥራል
- በመጀመሪያ ሲፈለግ ብቻ `cloudflared` ጭነቶችን አንቃ; በኋላ እንደገና ይጀምራል ተመሳሳዩን የሚተዳደር ሁለትዮሽ እንደገና ይጠቀሙ
- ፈጣን ዋሻዎች OmniRoute ወይም መያዣ እንደገና ከጀመሩ በኋላ በራስ-ሰር ወደነበሩበት አይመለሱም። አስፈላጊ ሆኖ ሲገኝ ከዳሽቦርዱ እንደገና አንቃቸው
- Tunnel URLs ጊዜያዊ ናቸው እና መሿለኪያውን stop/start ቁጥር ይለዋወጣሉ።
- የሚተዳደሩ ፈጣን ዋሻዎች በተከለከሉ ኮንቴይነሮች ውስጥ ጫጫታ ያለውን QUIC UDP ቋት ማስጠንቀቂያዎችን ለማስቀረት ወደ HTTP/2 ትራንስፖርት ነባሪ።
- የሚተዳደረውን የትራንስፖርት ምርጫ ለመሻር ከፈለጉ `CLOUDFLARED_PROTOCOL=quic` ወይም `auto` ያዘጋጁ
- ከሚተዳደረው ማውረጃ ይልቅ ቀድሞ የተጫነ `cloudflared` ሁለትዮሽ መጠቀም ከመረጡ `CLOUDFLARED_BIN` ያዘጋጁ
- Cloudflare Quick Tunnel፣ Tailscale Funnel እና ngrok Tunnel panels ሊታዩ ወይም ሊደበቁ ይችላሉ።** ቅንብሮች → መልክ** . ፓነልን መደበቅ መሿለኪያ መሮጡን አያቆምም።

### LLM ጌትዌይ ኢንተለጀንስ (ደረጃ 9)

- **የትርጉም መሸጎጫ** - በራስ-ሰር መሸጎጫዎች የማይለቀቁ፣ የሙቀት = 0 ምላሾች (በ `X-OmniRoute-No-Cache: true` ማለፍ)
- **ያለመቻልን ጠይቅ** - ጥያቄዎችን በ 5s ውስጥ በ `Idempotency-Key` ወይም `X-Request-Id` ራስጌ ያጠፋል
- **የሂደት ክትትል** - በ `X-OmniRoute-Progress: true` ራስጌ መርጠው ይግቡ SSE `event: progress` ክስተቶች

---

### ተርጓሚ የመጫወቻ ሜዳ

በ በኩል መድረስ** ዳሽቦርድ → ተርጓሚ** . OmniRoute በአቅራቢዎች መካከል API ጥያቄዎችን እንዴት እንደሚተረጉም ማረም እና በዓይነ ሕሊናህ ተመልከት።

| ሁነታ           | ዓላማ                                                                 |
| ------------- | ------------------------------------------------------------------- |
| **የመጫወቻ ሜዳ**  | source/target ቅርጸቶችን ይምረጡ፣ ጥያቄ ይለጥፉ እና የተተረጎመውን ውጤት ወዲያውኑ ይመልከቱ     |
| **የውይይት ሞካሪ** | የቀጥታ የውይይት መልእክቶችን በፕሮክሲው በኩል ይላኩ እና ሙሉውን request/response ዑደት ይፈትሹ |
| **የሙከራ ቤንች**  | የትርጉም ትክክለኛነትን ለማረጋገጥ በበርካታ የቅርጸት ጥምሮች ላይ የቡድን ሙከራዎችን ያሂዱ           |
| **የቀጥታ ክትትል** | ጥያቄዎች በፕሮክሲው በኩል ሲፈስ ቅጽበታዊ ትርጉሞችን ይመልከቱ                             |

**ጉዳዮችን ተጠቀም፡**

- ለምን የተወሰነ client/provider ጥምረት እንዳልተሳካ ያርሙ
- የአስተሳሰብ መለያዎች፣ የመሳሪያ ጥሪዎች እና የስርዓት ጥያቄዎች በትክክል እንደሚተረጎሙ ያረጋግጡ
- OpenAI፣ Claude፣ Gemini እና ምላሾች API ቅርጸቶች መካከል የቅርጸት ልዩነቶችን ያወዳድሩ

---

### የማዞሪያ ስልቶች

በ በኩል ያዋቅሩ** ዳሽቦርድ → Settings → Routing** . ዳሽቦርዱ በጣም ጥቅም ላይ የዋሉ ስድስት ስልቶችን ያጋልጣል; combos እና ራስ-ራውተር ከውስጥ ሰፋ ያለ ስብስብን ይደግፋሉ።

**ዳሽቦርድ-የሚታዩ ስልቶች (የመለያ ደረጃ ማዘዋወር)**

| ስልት                      | መግለጫ                                                                      |
| ------------------------ | ------------------------------------------------------------------------- |
| **መጀመሪያ ሙላ**             | መለያዎችን በቅድሚያ ቅደም ተከተል ይጠቀማል - ዋናው መለያ እስካልተገኘ ድረስ ሁሉንም ጥያቄዎች ያስተናግዳል።     |
| **ክብ ሮቢን**               | ሊዋቀር በሚችል ተለጣፊ ገደብ በሁሉም መለያዎች ውስጥ ዑደቶች (በነባሪ፡ 3 ጥሪዎች በአንድ መለያ)            |
| **P2C (የሁለት ምርጫዎች ኃይል)** | 2 የዘፈቀደ ሂሳቦችን እና ወደ ጤናማው መንገድ ይመርጣል - ሸክሙን በጤና ግንዛቤ ላይ ያስተካክላል            |
| **በዘፈቀደ**                | Fisher-Yates shuffleን በመጠቀም ለእያንዳንዱ ጥያቄ በዘፈቀደ መለያ ይመርጣል                   |
| **በትንሹ ጥቅም ላይ የዋለ**      | ትራፊክን በእኩል በማሰራጨት በጣም ጥንታዊ በሆነው `lastUsedAt` የጊዜ ማህተም ወደ መለያው የሚወስዱ መንገዶች |
| **ወጪ ተመቻችቷል።**           | ዝቅተኛው የቅድሚያ ዋጋ ያለው ወደ መለያው የሚወስዱ መንገዶች፣ ለዝቅተኛ ወጪ አቅራቢዎች ማመቻቸት             |

**የላቀ ጥምር እና ራስ-ሰር ስትራቴጂዎች** (በአንድ ጥምር ወይም በ `auto/*` ቅድመ-ቅጥያዎች ሊዋቀር የሚችል - [AUTO-COMBO.md](../routing/AUTO-COMBO.md) ይመልከቱ):

- `priority` - ጥብቅ ቅደም ተከተል, በጭራሽ ክብ-ሮቢን
- `weighted` - የተመጣጣኝ ትራፊክ በእያንዳንዱ ሞዴል ክብደት የተከፈለ
- `fill-first` - ገደቦች እስኪደርሱ ድረስ የመጀመሪያውን ሞዴል ያጥፉ
- `round-robin` / `strict-random` / `random`
- `p2c` (የሁለት ምርጫዎች ኃይል)
- `least-used` እና `cost-optimized`
- `auto` - በሁሉም እጩዎች ላይ የሚመራ
- `lkgp` (ለመጨረሻ ጊዜ የታወቀው ጥሩ አቅራቢ) - ለመጨረሻው ስኬታማ አገልግሎት አቅራቢ ፒን ፣ ከዚያ ወደ ህጎች ይመለሳሉ
- `context-optimized` - ሞዴሉን በትልቁ ነፃ አውድ መስኮት ይመርጣል
- `context-relay` - ሰንሰለቶች ረጅም አውድ ሞዴሎች ለቀጣይ ማዞሪያዎች

#### ውጫዊ ተለጣፊ ክፍለ ጊዜ ራስጌ

ለውጫዊ ክፍለ ጊዜ ዝምድና (ለምሳሌ፡- Claude Code/Codex ወኪሎች በተገላቢጦሽ ፕሮክሲዎች ጀርባ)፣ ይላኩ፡-

```http
X-Session-Id: your-session-key
```

OmniRoute እንዲሁ `x_session_id` ይቀበላል እና በ `X-OmniRoute-Session-Id` ውስጥ ውጤታማውን የክፍለ ጊዜ ቁልፍ ይመልሳል።

Nginxን ከተጠቀሙ እና ከስር በታች አርዕስቶችን ከላኩ፣ አንቃ፡-

```nginx
underscores_in_headers on;
```

#### Wildcard ሞዴል ተለዋጭ ስሞች

የሞዴል ስሞችን ለመቀየር የዱር ካርድ ንድፎችን ይፍጠሩ፡

```
Pattern: claude-sonnet-*     →  Target: cc/claude-sonnet-4-6
Pattern: gpt-*               →  Target: gh/gpt-5.3-codex
```

Wildcards `*` (ማንኛውንም ቁምፊዎች) እና `?` (ነጠላ ቁምፊ) ይደግፋሉ።

#### የመውደቅ ሰንሰለቶች

በሁሉም ጥያቄዎች ላይ የሚተገበሩ አለምአቀፍ የመውደቅ ሰንሰለቶችን ይግለጹ፡

```
Chain: production-fallback
  1. cc/claude-opus-4-7
  2. gh/gpt-5.3-codex
  3. glm/glm-4.7
```

---

### የተለመዱ የአቅራቢዎች ጥምር እና የማዞሪያ ቅጦች

በ OmniRoute ውስጥ ብዙ አቅራቢዎችን ለማጣመር እና በመካከላቸው ለማስኬድ ምሳሌ ምሳሌዎች እዚህ አሉ።

#### 1. የኮዲንግ ወኪል ኮምቦ፡ ከፍተኛ-መጨረሻ ምክንያት ከ Cost/Speed Fallback ጋር

ለኮዲንግ ወኪሎች (OpenCode, Claude ኮድ, Cursor, Cline) ተስማሚ. መጀመሪያ ወደ ድንበር አመክንዮ ሞዴሎች የሚወስዱ መንገዶች፣ በኮታ ድካም ወይም ስህተቶች ላይ ወደ ፈጣን ኮድ ማድረጊያ ሞዴሎች ይመለሳሉ።

- **ዳሽቦርድ** Combos → አዲስ ጥምር → ስም `agent-coding` → ስልት `Priority`
- **ሞዴሎች** :
  1. `claude/claude-sonnet-4-6` (ዋና ኮድ ማድረጊያ ወኪል)
  2. `openai/gpt-4o` (ሁለተኛ ከፍተኛ አቅም ያለው ውድቀት)
  3. `deepseek/deepseek-v4-flash` (ከፍተኛ ቅልጥፍና፣ ወጪ ቆጣቢ ውድቀት)

```bash
# Example via 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. ነፃ-ደረጃ አውቶማቲክ ውድቀት ጥምር

ያለ API ወጪዎች የስራ ጊዜን ከፍ ለማድረግ ብዙ ነፃ-ደረጃ እና ቁልፍ የሌላቸው አቅራቢዎችን ያሰራል።

- **ስልት** `Least Used` ወይም `Round Robin` (ጭነቱን በኮታዎች ላይ ያከፋፍላል)
- **ሞዴሎች** :
  1. `groq/llama-3.3-70b-versatile`
  2. `gemini/gemini-2.5-flash`
  3. `cerebras/gpt-oss-120b`

```bash
# Example via 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. መልቲሞዳል / ራዕይ እና የጽሑፍ ቧንቧ

የምስል ግንዛቤን እና ኮድ ማመንጨትን ለሚያካትቱ የስራ ፍሰቶች ልዩ የእይታ ሞዴሎችን ከከፍተኛ ፍጥነት የጽሑፍ ማመንጨት ጋር ማጣመር።

- **ስርዓተ-ጥለት** : ራዕይ-የሚችሉ ሞዴሎችን መጀመሪያ የሚዘረዝር `Priority` ጥምር እና ከፍተኛ-ግፊት ያለው text/code ሞዴል የመጨረሻው።
- **ሞዴሎች** :
  1. `gemini/gemini-2.5-pro` (ጠንካራ image/multimodal የመረዳት ችሎታ)
  2. `openai/gpt-4o` (የተመጣጠነ እይታ እና የመሳሪያ አጠቃቀም)
  3. `deepseek/deepseek-v4-flash` (Text/code ትውልድ)

---

### የመቋቋም እና የወረዳ የሚላተም

በ በኩል ያዋቅሩ** ዳሽቦርድ → ቅንጅቶች → የመቋቋም ችሎታ** .

OmniRoute ከአምስት አካላት ጋር በአቅራቢ ደረጃ የመቋቋም ችሎታን ተግባራዊ ያደርጋል

1. **ወረፋ ጠይቅ እና መሮጥ** - የሥርዓት-ደረጃ ጥያቄ መቅረጽ
   - **ጥያቄዎች በደቂቃ (RPM)** - ከፍተኛ ጥያቄዎች በደቂቃ በአንድ መለያ
   - **በጥያቄዎች መካከል ያለው ደቂቃ** - በጥያቄዎች መካከል ያለው አነስተኛ ክፍተት በሚሊሰከንዶች
   - **ከፍተኛ የተጣጣሙ ጥያቄዎች** - በአንድ መለያ ከፍተኛው በአንድ ጊዜ የሚደረጉ ጥያቄዎች

2. **የግንኙነት ማቀዝቀዝ** - በድጋሚ ሊሞከሩ ከሚችሉ ውድቀቶች በኋላ ለአንድ ነጠላ ግንኙነት በፍቃድ አይነት ውቅር፡
   - **የመሠረት ማቀዝቀዝ** - ለዳግም መሞከር ለሚችሉ የላይ ዥረት ውድቀቶች ነባሪ የማቀዝቀዝ መስኮት
   - **ወደላይ እንደገና ሞክር ፍንጮችን ተጠቀም** - ስልጣን ያለው `Retry-After` ያከብራል ወይም ሲሰጥ ፍንጮችን ዳግም ያስጀምሩ
   - **ከፍተኛ የመጠባበቂያ እርምጃዎች** - ለተደጋጋሚ ውድቀቶች ከፍተኛው ገላጭ የኋላ ማፈግፈግ ደረጃ

3. **አቅራቢ የወረዳ ተላላፊ** — ከጫፍ እስከ ጫፍ የአቅራቢዎች አለመሳካቶችን ይከታተላል፣ አቅራቢው የተዋረደውን የማስጠንቀቂያ ገደብ ላይ ምልክት ያደርጋል፣ እና የተዋቀረው የውድቀት ጣራ ላይ ሲደርስ ሰባሪውን ይከፍታል።
   - **የማዋረድ ገደብ** - ወደ `DEGRADED` ከመግባትዎ በፊት ተከታታይ አቅራቢዎች ውድቀቶች
   - **የመውደቅ ገደብ** - ወደ `OPEN` ከመግባትዎ በፊት ተከታታይ አቅራቢዎች ውድቀቶች
   - **ጊዜው ያለፈበትን ዳግም አስጀምር** - አቅራቢው እንደገና ከመሞከሩ በፊት የሰዓት መስኮት
   - **CLOSED** (ጤናማ) - የጥያቄዎች መደበኛ ፍሰት
   - **DEGRADED** - ከፍ ያሉ ውድቀቶች ክትትል በሚደረግበት ጊዜ ጥያቄዎች አሁንም ይፈስሳሉ
   - **OPEN** - ከተደጋጋሚ ውድቀቶች በኋላ አቅራቢው ለጊዜው ታግዷል
   - **HALF_OPEN** - አቅራቢው ካገገመ በመሞከር ላይ

   በግንኙነት ስፋት ያለው `429` ተመን ገደቦች ይቆያሉ።** የግንኙነት ማቀዝቀዝ** እና ወደ አቅራቢው ሰባሪ አይቁጠሩ።

   የአቅራቢው ሰባሪ የአሂድ ጊዜ ሁኔታ በ ላይ ይታያል** ዳሽቦርድ → ጤና** ብቻ።

4. **እስኪቀዘቅዝ ይጠብቁ** — እያንዳንዱ እጩ ግንኙነት ቀድሞውኑ እየቀዘቀዘ ከሆነ፣ OmniRoute የመጀመሪያውን ማቀዝቀዝ መጠበቅ እና ተመሳሳይ የደንበኛ ጥያቄን በራስ-ሰር እንደገና መሞከር ይችላል።

5. **የፍጥነት ገደብ ራስ-ማወቂያ** - የላይ ዥረት አቅራቢዎች ግልጽ የሆኑ የመጠባበቅ መስኮቶችን ሲመልሱ፣ ቅንብሩ ሲነቃ እነዚያ ፍንጮች የአካባቢያዊ ግንኙነት ቅዝቃዜን ይሽረዋል።

**ጠቃሚ ምክር፡** የሚለውን ተጠቀም** ጤና** ከተቋረጠ በኋላ የቀጥታ አገልግሎት ሰጪ መግቻዎችን ለመመርመር እና ለማስጀመር ገጽ። የ Resilience ገጽ ውቅረትን ብቻ ይለውጣል።

---

### የውሂብ ጎታ ወደ ውጪ ላክ / አስመጣ

የውሂብ ጎታ ምትኬዎችን በ ውስጥ ያቀናብሩ** ዳሽቦርድ → ቅንብሮች → ስርዓት እና ማከማቻ** .

| ድርጊት                        | መግለጫ                                                                                                       |
| --------------------------- | ---------------------------------------------------------------------------------------------------------- |
| **የውሂብ ጎታ ወደ ውጪ ላክ**        | የአሁኑን SQLite ዳታቤዝ እንደ `.sqlite` ፋይል ያወርዳል                                                                  |
| **ሁሉንም ወደ ውጪ ላክ (.tar.gz)** | ሙሉ የመጠባበቂያ ማህደርን ያወርዳል፡ ዳታቤዝ፣ መቼቶች፣ ጥንብሮች፣ የአቅራቢ ግንኙነቶች (ምንም ምስክርነቶች)፣ API ቁልፍ ዲበ ውሂብ                      |
| **የውሂብ ጎታ አስመጣ**            | የአሁኑን ዳታቤዝ ለመተካት `.sqlite` ፋይል ይስቀሉ። `DISABLE_SQLITE_AUTO_BACKUP=true` ካልሆነ በስተቀር የማስመጣት ምትኬ በራስ-ሰር ይፈጠራል። |

```bash
# API: Export database
curl -o backup.sqlite http://localhost:20128/api/db-backups/export

# API: Export all (full archive)
curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll

# API: Import database
curl -X POST http://localhost:20128/api/db-backups/import \
  -F "file=@backup.sqlite"
```

**የማስመጣት ማረጋገጫ፡** ከውጭ የመጣው ፋይል የተረጋገጠው ለንጹህነት (SQLite pragma check)፣ አስፈላጊ ሰንጠረዦች (`provider_connections`፣ `provider_nodes`፣ `combos`፣ `api_keys`) እና መጠን (ከፍተኛ 100 ሜባ) ነው።

**ጉዳዮችን ተጠቀም**

- በማሽኖች መካከል OmniRoute ያዛውሩ
- ለአደጋ ማገገሚያ ውጫዊ ምትኬዎችን ይፍጠሩ
- በቡድን አባላት መካከል አወቃቀሮችን አጋራ (ሁሉንም → ማጋራት ማህደር ወደ ውጭ ላክ)

---

### ቅንብሮች ዳሽቦርድ

የቅንብሮች ገጽ የተደራጀው ወደ ውስጥ ነው።** 7 ትሮች** ለቀላል አሰሳ፡-

| ትር            | ይዘቶች                                                                                                                                |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| **አጠቃላይ**     | የስርዓት ማከማቻ መሳሪያዎች፣ ነባሪ ባህሪ፣ የመጨረሻ ነጥብ ዋሻ ታይነት                                                                                       |
| **መልክ**       | የገጽታ መቆጣጠሪያዎች (light/dark/system)፣ የጎን አሞሌ ታይነት፣ ለ Cloudflare/Tailscale/ngrok ዋሻ ካርዶች የፓነል መቀየሪያዎች                                  |
| **AI**        | የአስተሳሰብ በጀት (ማለፊያ / ራስ-ሰርፕ / ብጁ / አስማሚ - [THINKING_BUDGET.md](./THINKING_BUDGET.md) ይመልከቱ) ፣ ዓለም አቀፍ የስርዓት መጠየቂያ ፣ ፈጣን መሸጎጫ ስታቲስቲክስ |
| **ደህንነት**     | Login/Password መቼቶች፣ IP የመዳረሻ መቆጣጠሪያ፣ API auth ለ `/models`፣ አቅራቢን ማገድ፣ የፈጣን መርፌ ጠባቂ                                                 |
| **ማዘዋወር**     | ሁለንተናዊ የማዞሪያ ስልት (መጀመሪያ ሙላ / ዙር ሮቢን / P2C / በዘፈቀደ / በትንሹ ጥቅም ላይ የዋለ / ወጪ የተመቻቸ)፣ የዱር ካርድ ሞዴል ተለዋጭ ስሞች፣ የመመለሻ ሰንሰለቶች፣ ጥምር ነባሪዎች      |
| **የመቋቋም ችሎታ** | ወረፋ ይጠይቁ ፣ የግንኙነቶች ማቀዝቀዝ ፣ የአቅራቢ ቆራጭ ውቅረት እና የመጠባበቅ ባህሪ                                                                             |
| **የላቀ**       | የአለምአቀፍ ፕሮክሲ ውቅር (HTTP/SOCKS5)፣ በአቅራቢው ተኪ ይሽራል።                                                                                     |

አጠቃላይ ከአሁን በኋላ ተነባቢ-ብቻ ምዝግብ ማስታወሻዎችን እና የመሸጎጫ ማስታወሻዎችን አይባዛም። የውሂብ ጎታ ማቆየት እና የማመቻቸት ቅንጅቶች በ `/api/settings/database` በኩል ይቆያሉ; በእጅ መሸጎጫ ማጽዳት `DELETE /api/cache` ይጠቀማል. ጥያቄ እና የተኪ ሎግ ረድፎች በ `CALL_LOGS_TABLE_MAX_ROWS` እና `PROXY_LOGS_TABLE_MAX_ROWS` ቁጥጥር ይደረግባቸዋል።

---

### ወጪዎች እና የበጀት አስተዳደር

በ በኩል መድረስ** ዳሽቦርድ → ወጪዎች** .

| ትር           | ዓላማ                                                               |
| ------------ | ----------------------------------------------------------------- |
| **በጀት**      | በአንድ API ቁልፍ የወጪ ገደቦችን በ daily/weekly/monthly በጀቶች እና በቅጽበት መከታተል |
| **የዋጋ አሰጣጥ** | የሞዴል የዋጋ ግቤቶችን ይመልከቱ እና ያርትዑ — ዋጋ በ 1 ኪ input/output ቶከኖች በአቅራቢ   |

```bash
# API: Set a budget
curl -X POST http://localhost:20128/api/usage/budget \
  -H "Content-Type: application/json" \
  -d '{"keyId": "key-123", "limit": 50.00, "period": "monthly"}'

# API: Get current budget status
curl http://localhost:20128/api/usage/budget
```

**ወጪ መከታተል፡** እያንዳንዱ ጥያቄ የቶከን አጠቃቀምን ይመዘግባል እና የዋጋ ሰንጠረዡን በመጠቀም ወጪ ያሰላል። ውስጥ ዝርዝሮችን ይመልከቱ** ዳሽቦርድ → አጠቃቀም** በአቅራቢ፣ ሞዴል እና API ቁልፍ።

---

### የድምጽ ቅጂ

OmniRoute በOpenAI-ተኳሃኝ የመጨረሻ ነጥብ በኩል የድምጽ ቅጂን ይደግፋል፡-

```bash
POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data

# Example with curl
curl -X POST http://localhost:20128/v1/audio/transcriptions \
  -H "Authorization: Bearer your-api-key" \
  -F "file=@audio.mp3" \
  -F "model=openai/whisper-1"
```

`deepgram/nova-3` ቤተኛ Deepgram መንገድ ነው እና Deepgram API ቁልፍ ያስፈልገዋል። OpenRouter ብቻ ከተዋቀረ `openrouter/deepgram/nova-3` ይጠቀሙ።

**ንግግር-ወደ-ጽሑፍ (የጽሑፍ ግልባጭ)** አቅራቢዎች፡-

- `openai/` (ሹክሹክታ የሚስማማ)
- `groq/` (Groq ሹክሹክታ ቱርቦ)
- `deepgram/` (የኖቫ ቤተሰብ)
- `assemblyai/`
- `nvidia/` (ፓራኬት፣ ካናሪ)
- `huggingface/` (የሹክሹክታ ልዩነቶች)
- `qwen/`

**ጽሑፍ-ወደ-ንግግር (`POST /v1/audio/speech`)** አቅራቢዎች፡-

- `openai/` (tts-1፣ tts-1-hd)
- `hyperbolic/`
- `deepgram/` (ኦራ)
- `nvidia/` ( Magpie TTS)
- `elevenlabs/`
- `huggingface/`
- `inworld/`
- `cartesia/`
- `playht/`
- `kie/`
- `aws-polly/`
- `xiaomi-mimo/`
- `coqui/`, `tortoise/`
- `qwen/`

የሚደገፉ የድምጽ ቅርጸቶች ለጽሑፍ ግልባጭ `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. TTS የውጤት ቅርጸቶች በአቅራቢው (mp3, wav, opus, pcm, mulaw) ላይ ይወሰናሉ.

---

### ጥምር ማመጣጠን ስልቶች

በየጥምር ማመጣጠን ያዋቅሩ** ዳሽቦርድ → Combos → Create/Edit →** .

| ስልት                 | መግለጫ                                                  |
| ------------------- | ----------------------------------------------------- |
| **ዙር-ሮቢን**          | በቅደም ተከተል ሞዴሎች ውስጥ ይሽከረከራል                            |
| **ቅድሚያ**            | ሁልጊዜ የመጀመሪያውን ሞዴል ይሞክራል; የሚመለሰው በስህተት ላይ ብቻ ነው።       |
| **በዘፈቀደ**           | ለእያንዳንዱ ጥያቄ የዘፈቀደ ሞዴል ከኮምቦው ይመርጣል                     |
| **የተመዘነ**           | በእያንዳንዱ ሞዴል በተመደበው ክብደት ላይ በተመጣጣኝ መንገድ መስመሮች          |
| **በትንሹ ጥቅም ላይ የዋለ** | ወደ አምሳያው የሚወስዱት ጥቂት የቅርብ ጊዜ ጥያቄዎች (ጥምር መለኪያዎችን ይጠቀማል) |
| **ወጪ-የተመቻቸ**        | በጣም ርካሽ ወደሆነ ሞዴል የሚወስዱ መንገዶች (የዋጋ ሠንጠረዥን ይጠቀማል)       |

ሁለንተናዊ ጥምር ነባሪዎች ሊዋቀሩ ይችላሉ።** ዳሽቦርድ → Settings → Routing → ጥምር ነባሪዎች** . ጥምር ኢላማ ጊዜ ማብቂያዎች የአሁኑን የጥያቄ ጊዜ ማብቂያ በነባሪ ይወርሳሉ። ተጠቀም** የዒላማ ጊዜ ማብቂያ (ሰከንዶች)** በኮምቦ ነባሪዎች ወይም በግለሰብ ጥምር ላይ አጭር በአንድ ዒላማ ገደብ ፈጣን ውድቀትን ሲያስነሳ ብቻ ነው።

የዜሮ መዘግየት ጥምር ማትባቶች መርጠው ገብተዋል። ተወው** የዜሮ መዘግየት ማትባቶች** እነዚህ የመዘግየት ባህሪያት ከውድድር ወደ ኋላ መመለስ ዒላማዎች እንዳይሆኑ፣ TTFT ታሪክ ላይ ተመስርተው ኢላማዎችን መዝለል፣ ወይም የተመለስ ጥያቄዎችን ከመጭመቅ ለመከላከል የተሰናከለ፤ እሱን ማንቃት የተዋቀረ አጥርን ፣ ግምታዊ TTFT መዝለሎችን እና የነቃ የመውደቅ መጭመቅ ለዝቅተኛ የጅራት መዘግየት routing/request ታማኝነትን ለመገበያየት ያስችላል።

አሰናክል** ማስመሰያ ቋት ማመራመር** የላይኞቹ አቅራቢዎች ጥብቅ `max_tokens` / `maxOutputTokens` ገደቦችን ሲፈልጉ። ሲነቃ ኮምቦ ማዘዋወር የሚታወቅ የውጤት ቆብ ላላቸው ሞዴሎች የማመዛዘን-ሞዴል ዋና ክፍልን ብቻ ይጨምራል እና ደህንነቱ የተጠበቀው እሴት ከዚያ ካፕ በላይ በሚሆንበት ጊዜ የደንበኛው ማስመሰያ ገደብ ሳይቀየር ይተወዋል። የደንበኛው ገደቡ ቀድሞውኑ ከሚታወቅ ኮፍያ በላይ ከሆነ፣ OmniRoute የላይኛውን ጥያቄ ከመላክዎ በፊት ወደዚያ ካፕ ያዘው።

---

### የጤና ዳሽቦርድ

በ በኩል መድረስ** ዳሽቦርድ → ጤና** . የእውነተኛ ጊዜ ስርዓት የጤና አጠቃላይ እይታ ከ6 ካርዶች ጋር፡-

| ካርድ                   | ምን ያሳያል                                  |
| --------------------- | ---------------------------------------- |
| **የስርዓት ሁኔታ**         | የጊዜ ቆይታ፣ ስሪት፣ የማህደረ ትውስታ አጠቃቀም፣ የውሂብ ማውጫ |
| **አቅራቢ ጤና**           | ዓለም አቀፍ አቅራቢ የወረዳ የሚላተም የአሂድ ጊዜ ሁኔታ      |
| **የዋጋ ገደቦች**          | ገባሪ የግንኙነት ማቀዝቀዣዎች በአንድ መለያ ከቀሪው ጊዜ ጋር   |
| **ንቁ መቆለፊያዎች**        | ገባሪ ሞዴል ስፋት ያላቸው መቆለፊያዎች እና ጊዜያዊ ማግለያዎች  |
| **የፊርማ መሸጎጫ**         | የማባዛት መሸጎጫ ስታቲስቲክስ (ንቁ ቁልፎች፣ የመምታት መጠን)  |
| **Latency Telemetry** | p50/p95/p99 መዘግየት ድምር በአቅራቢ              |

**ጠቃሚ ምክር፡** የጤና ገጹ በየ10 ሰከንድ በራስ-ሰር ይታደሳል። የትኛዎቹ አቅራቢዎች ችግሮች እያጋጠሟቸው እንደሆነ ለመለየት የወረዳ የሚላተም ካርዱን ይጠቀሙ።

---

## 🤖 ራስ-ሰር ማዘዋወር (ያለ ውቅር)

OmniRoute በሁሉም የተገናኙ አቅራቢዎች ውስጥ ለእያንዳንዱ ጥያቄ ምርጡን ሞዴል የሚመርጥ **በውጤት-ነጥብ የሚመራ ራስ-ሰር ማዘዋወሪያ** ይዞ ይመጣል — የሚንከባከቡት ጥምረት የለም። ጥያቄውን ከ`auto/*` ቅድመ-ቅጥያዎች በአንዱ ብቻ ይላኩ፤ OmniRoute በቅጽበት ምናባዊ ጥምረት ይገነባል፣ እጩዎችንም በመዘግየት፣ ወጪ፣ የስኬት መጠን፣ ከዐውዱ ጋር መጣጣም፣ ሞዴሉ ለተግባሩ ያለው ብቃት፣ የቅርብ ጊዜ ውድቀቶች፣ ኮታ እና የወረዳ-ቆራጭ ሁኔታ መሠረት ይመዝናል።

| ቅድመ-ቅጥያ        | የሚያመቻቸው                                                                    |
| -------------- | -------------------------------------------------------------------------- |
| `auto`         | ሚዛናዊ ነባሪ (መዘግየት × ወጪ × የስኬት መጠን)                                           |
| `auto/coding`  | የኮድ ሥራዎች፦ Claude፣ GPT-5፣ GLM፣ Kimi፣ Qwen Coder እና DeepSeek codersን ይመርጣል   |
| `auto/cheap`   | ዝቅተኛው $/token፣ ከፍተኛ መዘግየትን ይቀበላል                                           |
| `auto/fast`    | ዝቅተኛው መዘግየት፣ ወጪን ችላ ይላል                                                    |
| `auto/offline` | በአካባቢው ያሉ አቅራቢዎች ብቻ (Ollama፣ vLLM፣ llama.cpp) — ከአውታረ መረብ ለተለዩ ውቅሮች ጠቃሚ ነው |
| `auto/smart`   | መጀመሪያ የማመዛዘን ጥራት (Opus፣ GPT-5 xhigh፣ R1፣ GLM 5.1 reasoning)                |
| `auto/lkgp`    | "የመጨረሻው የታወቀ ጥሩ አቅራቢ" — በመጨረሻ ለተሳካው አቅራቢ ያስቀምጣል፣ ከዚያም ወደ ደንቦች ይመለሳል        |

ምሳሌ፦

```bash
curl -X POST http://localhost:20128/v1/chat/completions \
  -H "Authorization: Bearer $OMNIROUTE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto/coding",
    "messages": [{ "role": "user", "content": "Refactor this Python function" }],
    "stream": true
  }'
```

ራስ-ሰር ማዘዋወሪያው በ[AUTO-COMBO.md](../routing/AUTO-COMBO.md) ውስጥ ሙሉ በሙሉ ተገልጿል — ይህም የውጤት-ነጥብ ክብደቶችን እንዴት ማስተካከል፣ አቅራቢዎችን በጥቁር ዝርዝር ማስገባት እና በ**ዳሽቦርድ → ራስ-ሰር ጥምረት** ውስጥ የማዘዋወር ውሳኔዎችን መመርመርን ያካትታል።

---

## 🔌 የMCP & A2A ውህደት

OmniRoute **የMCP አገልጋይ** (Model Context Protocol) እና **የA2A አገልጋይ** (Agent-to-Agent JSON-RPC 2.0) ነው። ማንኛውም ከMCP ጋር ተኳኋኝ የሆነ IDE ወይም የወኪል አስተናጋጅ የOmniRoute መሣሪያዎችን በቀጥታ ሊጠራ ይችላል — ተጨማሪ መጠቅለያ አያስፈልግም።

### የMCP ማጓጓዣዎች

- **SSE**፦ `http://localhost:20128/api/mcp/sse`
- **ሊለቀቅ የሚችል HTTP**፦ `http://localhost:20128/api/mcp/stream`
- **stdio**፦ `omniroute --mcp` (stdioን ለሚመርጡ የIDE ተሰኪዎች)

### Claude Desktopን ማገናኘት

በmacOS ላይ `~/Library/Application Support/Claude/claude_desktop_config.json`ን ወይም በWindows/Linux ላይ ተመጣጣኙን ፋይል ያርትዑ፦

```json
{
  "mcpServers": {
    "omniroute": {
      "command": "omniroute",
      "args": ["--mcp"]
    }
  }
}
```

### Cursor / Continue / VS Code MCPን ማገናኘት

የSSE URL `http://localhost:20128/api/mcp/sse`ን እና በ**ዳሽቦርድ → API ቁልፎች** ውስጥ የተፈጠረ Bearer API ቁልፍ ይጠቀሙ።

### የፈቃድ ወሰኖች

MCP በአሁኑ ጊዜ 32 ስያሜ ያላቸው የፈቃድ ወሰኖችን ይገልጻል። እያንዳንዱ Bearer ቁልፍ ለተወሰኑ የፈቃድ ወሰኖች ብቻ ሊገደብ ይችላል — ለዋናው የፈቃድ ወሰንና የመሣሪያ ዝርዝር [MCP-SERVER.md](../frameworks/MCP-SERVER.md)ን፣ ለJSON-RPC መርሐግብር ደግሞ [A2A-SERVER.md](../frameworks/A2A-SERVER.md)ን ይመልከቱ።

---

## 🧠 የክህሎት ስርዓት

OmniRoute ኤጀንቶች እና የA2A መገናኛ ነጥብ ለተወሰኑ ዘርፎች የተዘጋጁ ሂደቶችን (ለምሳሌ፦ `code-review`፣ `summarize`፣ `extract-facts`፣ `web-research`) ማስኬድ እንዲችሉ ሊስፋፋ የሚችል **የክህሎት ማዕቀፍ** (`src/lib/skills/`) ያቀርባል።

- **የገበያ ቦታ በይነገጽ** — ክህሎቶችን ከ**Dashboard → Skills** ያስሱ እና ይጫኑ
- **የየቁልፍ ወሰኖች** — የትኞቹ API ቁልፎች የትኞቹን ክህሎቶች መጥራት እንደሚችሉ ይገድቡ
- **ብጁ ክህሎቶች** — የTypeScript ፋይልን በ`src/lib/a2a/skills/` ውስጥ ያስቀምጡ፣ ይመዝግቡት፣ ከዚያም ወዲያውኑ በA2A በኩል ሊጠራ ይችላል

ሙሉ ማጣቀሻ፦ [SKILLS.md](../frameworks/SKILLS.md)።

---

## 💾 የማስታወሻ ስርዓት

OmniRoute በድብልቅ ሰርስሮ ማውጣት አማካኝነት **የረጅም ጊዜ የውይይት ማስታወሻን** በቋሚነት ያከማቻል፦

- **SQLite FTS5** ባለፉ የውይይት ተራዎች ውስጥ በቁልፍ ቃል ለመፈለግ
- **Qdrant vector store** (አማራጭ) ለትርጉማዊ ማስታወስ
- **ራስ-ሰር የእውነታ ማውጣት** — አካላት፣ ምርጫዎች እና ውሳኔዎች ከእያንዳንዱ ክፍለ ጊዜ በኋላ ተጠቃለው በ`memory_facts` ሰንጠረዥ ውስጥ ይቀመጣሉ
- ማስታወሻዎች በእያንዳንዱ API ቁልፍ እና ክፍለ ጊዜ የተወሰኑ ናቸው

ማስታወሻዎችን በ**Dashboard → Memory** ውስጥ ያስተዳድሩ (ይፈልጉ፣ ያርትዑ፣ ወደ ውጭ ይላኩ፣ ያጽዱ)። የHTTP በይነገጽ (`/api/memory/*`) ኤጀንቶች እውነታዎችን በፕሮግራም እንዲጨምሩ እና እንዲጠይቁ ያስችላቸዋል — [MEMORY.md](../frameworks/MEMORY.md) ይመልከቱ።

---

## 🔔 Webhooks

ለቅጽበታዊ ክትትል እና ራስ-ሰር አሰራር የOmniRoute ክስተቶችን ይመዝገቡ።

- በ**Dashboard → Webhooks** ውስጥ የመድረሻ URL እና የHMAC ፊርማ ሚስጥር በመጠቀም webhook ይፍጠሩ
- የሚገኙ ክስተቶች፦ `request.completed`፣ `request.failed`፣ `provider.unavailable`፣ `budget.exceeded`፣ `combo.switched`፣ `circuit_breaker.opened`፣ `circuit_breaker.closed`
- እያንዳንዱ የውሂብ ጭነት ለማረጋገጫ `X-OmniRoute-Signature` (HMAC-SHA256) ያካትታል
- ዳግም ሙከራዎች፦ እየጨመረ በሚሄድ የጥበቃ ጊዜ 3 ሙከራዎች፣ ከዚያም ያልተሳኩ መልዕክቶች ወረፋ

ሙሉው እቅድ በ[WEBHOOKS.md](../frameworks/WEBHOOKS.md) ውስጥ ይገኛል።

---

## ☁️ የደመና ኤጀንቶች

OmniRoute ረጅም ጊዜ የሚወስዱ ተግባራትን የአካባቢዎን ማስተላለፊያ ከሚያስተዳድረው ተመሳሳይ ዳሽቦርድ ለመላክ እንዲችሉ ከደመና የኮድ ኤጀንቶች (**OpenAI Codex Cloud**፣ **Devin**፣ **Jules**፣ **Antigravity**) ጋር ይዋሃዳል።

- ተግባራትን በ**Dashboard → Cloud Agents** ውስጥ ወይም በ`POST /api/v1/agents/tasks` በኩል ይፍጠሩ
- የእያንዳንዱን ተግባር ሁኔታ፣ ምዝግቦች እና ውጤቶች ይከታተሉ
- ለእያንዳንዱ አቅራቢ የራስዎን API ቁልፍ ይጠቀሙ — የመግቢያ ማስረጃዎች ከOmniRoute አብነት ፈጽሞ አይወጡም

ሙሉ ማጣቀሻ፦ [CLOUD_AGENT.md](../frameworks/CLOUD_AGENT.md)።

---

## 🛠️ ፕሮግራማዊ አስተዳደር

**የ`manage` scope ያለውን Bearer key** በመጠቀም እያንዳንዱን የOmniRoute ሀብት (providers፣ combos፣ keys፣ settings) በHTTP ማስተዳደር ይችላሉ።

Keyውን በ**Dashboard → API Keys → New Key → Scope: manage** ውስጥ ይፍጠሩ፣ ከዚያ፦

```bash
# Providersን ዘርዝር
curl http://localhost:20128/api/providers \
  -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY"

# የ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" }'

# 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" }] }'

# API keysን ዘርዝር/ፍጠር
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"] }'
```

ሙሉውን የendpoint ካታሎግ እና የrequest/response schemas ለማየት [API_REFERENCE.md](../reference/API_REFERENCE.md)ን ይመልከቱ።

---

## 💻 ውስጣዊ CLI

OmniRoute ለማዋቀር፣ ለምርመራ እና ለሂደት ጊዜ ቁጥጥር የውስጥ CLI (`omniroute …`) ይዞ ይመጣል። ይህ የሶስተኛ ወገን CLIዎችን (Claude Code, Cursor, Codex, Cline, …) ከOmniRoute ጋር እንዲገናኙ ከሚያዋቅረው **በዳሽቦርዱ ውስጥ ካለው "CLI መሣሪያዎች" ገጽ የተለየ ነው**።

```bash
omniroute setup                    # መስተጋብራዊ ማዋቀሪያ (የይለፍ ቃል፣ አቅራቢዎች፣ ጥምረቶች)
omniroute setup --non-interactive  # ለCI ምቹ
omniroute doctor                   # የጤና ምርመራዎች (የውሂብ ማውጫ፣ DB፣ አቅራቢዎች፣ ወደቦች)
omniroute providers available      # የሚደገፉ አቅራቢዎችን ዘርዝር
omniroute providers list           # የተዋቀሩ ግንኙነቶችን ዘርዝር
omniroute providers test <id>      # የአቅራቢ ግንኙነትን በቀጥታ ፈትሽ
omniroute combos list              # ጥምረቶችን ዘርዝር
omniroute combos switch <name>     # ነባሪ ጥምረትን አዘጋጅ
omniroute models                   # የሚገኙ ሞዴሎችን ዘርዝር (--json, --search)
omniroute keys add | list | remove # የAPI ቁልፎችን ከተርሚናሉ አስተዳድር
omniroute backup                   # የውቅር + DB ቅጽበታዊ ቅጂ
omniroute restore [<timestamp>]    # ከቅጽበታዊ ቅጂ መልስ
omniroute health                   # ዝርዝር የጤና ሁኔታ (ሰባሪዎች፣ መሸጎጫ፣ ማህደረ ትውስታ)
omniroute quota                    # የአቅራቢ ኮታ አጠቃቀም
omniroute mcp status               # የMCP አገልጋይ ሁኔታ
omniroute a2a status               # የA2A አገልጋይ ሁኔታ
omniroute tunnel list|create|stop  # Cloudflare/Tailscale/ngrok ዋሻዎች
omniroute reset-password           # የአስተዳዳሪውን የይለፍ ቃል ዳግም አስጀምር
omniroute --mcp                    # የMCP አገልጋይን በstdio ላይ አስጀምር
omniroute --port 3000              # አገልጋዩን በብጁ ወደብ ላይ አስጀምር
```

ጠቃሚ ምክር፦ ጤናማ ያልሆኑ የአቅራቢ ግንኙነቶች ሲኖሩ ማንቂያ ለማግኘት `omniroute doctor --json`ን ከክትትል መሣሪያዎ ጋር ያጣምሩ።

---

## 🖥️ የዴስክቶፕ መተግበሪያ (Electron)

OmniRoute ለWindows፣ macOS እና Linux እንደ ቤተኛ የዴስክቶፕ መተግበሪያ ይገኛል።

### መጫን

```bash
# ከelectron ማውጫ፦
cd electron
npm install

# የልማት ሁነታ (በሂደት ላይ ካለ Next.js የልማት አገልጋይ ጋር ይገናኛል)፦
npm run dev

# የምርት ሁነታ (ራሱን የቻለ ግንባታን ይጠቀማል)፦
npm start
```

### ጫኚዎችን መገንባት

```bash
cd electron
npm run build          # የአሁኑ መድረክ
npm run build:win      # Windows (.exe NSIS)
npm run build:mac      # macOS (.dmg ሁለንተናዊ)
npm run build:linux    # Linux (.AppImage)
```

ውጤት → `electron/dist-electron/`

### ቁልፍ ባህሪያት

| ባህሪ                | መግለጫ                                                 |
| ------------------ | ---------------------------------------------------- |
| **የአገልጋይ ዝግጁነት**   | መስኮቱን ከማሳየቱ በፊት አገልጋዩን በተደጋጋሚ ይፈትሻል (ባዶ ማያ ገጽ አይኖርም) |
| **የስርዓት ትሪ**       | ወደ ትሪ አሳንስ፣ ወደብ ቀይር፣ ከትሪ ምናሌው ውጣ                     |
| **የወደብ አስተዳደር**    | የአገልጋዩን ወደብ ከትሪው ቀይር (አገልጋዩን በራስ-ሰር ዳግም ያስጀምራል)      |
| **የይዘት ደህንነት ፖሊሲ** | በክፍለ ጊዜ ራስጌዎች በኩል ጥብቅ CSP                            |
| **ነጠላ አብነት**       | በአንድ ጊዜ አንድ የመተግበሪያ አብነት ብቻ ሊሠራ ይችላል                 |
| **ከመስመር ውጭ ሁነታ**   | አብሮ የታሸገው Next.js አገልጋይ ያለበይነመረብ ይሠራል                |

### የአካባቢ ተለዋዋጮች

| ተለዋዋጭ                 | ነባሪ     | መግለጫ                          |
| --------------------- | ------- | ----------------------------- |
| `OMNIROUTE_PORT`      | `20128` | የአገልጋይ ወደብ                    |
| `OMNIROUTE_MEMORY_MB` | `512`   | የNode.js ሂፕ ገደብ (64–16384 MB) |

📖 ሙሉ ሰነድ፦ [`electron/README.md`](../../electron/README.md)