OmniRoute/docs/i18n/am/docs/guides/USER_GUIDE.md

User Guide (አማርኛ)

🌐 Languages: 🇺🇸 English · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇮🇳 hi · 🇭🇷 hr · 🇭🇺 hu · 🇦🇲 hy · 🇮🇩 id · 🇳🇬 ig · 🇮🇹 it · 🇯🇵 ja · 🇬🇪 ka · 🇰🇭 km · 🇮🇳 kn · 🇰🇷 ko · 🇱🇹 lt · 🇱🇻 lv · 🇮🇳 ml · 🇮🇳 mr · 🇲🇾 ms · 🇲🇹 mt · 🇲🇲 my · 🇳🇵 ne · 🇳🇱 nl · 🇳🇴 no · 🇮🇳 or · 🇮🇳 pa · 🇵🇭 phi · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇱🇰 si · 🇸🇰 sk · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW

---

🌐 Languages: 🇺🇸 English · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇮🇳 hi · 🇭🇷 hr · 🇭🇺 hu · 🇦🇲 hy · 🇮🇩 id · 🇳🇬 ig · 🇮🇹 it · 🇯🇵 ja · 🇬🇪 ka · 🇰🇭 km · 🇮🇳 kn · 🇰🇷 ko · 🇱🇹 lt · 🇱🇻 lv · 🇮🇳 ml · 🇮🇳 mr · 🇲🇾 ms · 🇲🇹 mt · 🇲🇲 my · 🇳🇵 ne · 🇳🇱 nl · 🇳🇴 no · 🇮🇳 or · 🇮🇳 pa · 🇵🇭 phi · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇱🇰 si · 🇸🇰 sk · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW

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

---

የይዘት ማውጫ

• የዋጋ አወጣጥ በአጭሩ
• የአጠቃቀም ሁኔታዎች
• የአቅራቢ ማዋቀር
• የCLI ውህደት
• ማሰማራት
• የሚገኙ ሞዴሎች
• የላቁ ባህሪያት
• ራስ-ሰር ማስተላለፍ (ያለ ውቅረት)
• የMCP እና A2A ውህደት
• የክህሎቶች ሥርዓት
• የማስታወሻ ሥርዓት
• Webhooks
• የደመና ወኪሎች
• ፕሮግራማዊ አስተዳደር
• ውስጣዊ CLI
• የዴስክቶፕ መተግበሪያ (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-key ግንኙነቶችን በአንድ ጊዜ ለማከል፣ ዳሽቦርድ → አቅራቢዎች → ከፋይል አስመጣን ይጠቀሙ። ዓምዶቹ በቦታ ቅደም ተከተል የሚወሰኑ ናቸው (provider,name,apiKey,baseUrl,priority)፤ provider አስቀድሞ እንደሚተዳደር አቅራቢ ወይም ተኳሃኝ ኖድ መኖር አለበት። አቅራቢዎችን ከCSV ወይም JSON ፋይል ማስመጣትን ይመልከቱ።

🔐 የደንበኝነት ምዝገባ አቅራቢዎች

Claude Code (Pro/Max)

ዳሽቦርድ → አቅራቢዎች → Claude Codeን አገናኝ
→ በOAuth ይግቡ → ራስ-ሰር የቶከን እድሳት
→ የ5-ሰዓት + ሳምንታዊ ኮታ ክትትል

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

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

ከClaude እና Claude Code ጋር ተኳሃኝ የሆኑ መስመሮች ለOpus እና Sonnet ሞዴሎች የmax የማሰብ ጥረትን እንዳለ ያቆያሉ። Haiku ሞዴሎች የmax የጥረት ደረጃን ስለማይቀበሉ፣ OmniRoute ጥያቄውን ወደ ላይኛው አቅራቢ ከመላኩ በፊት ወደ ከፍተኛ የማሰብ በጀት ዝቅ ያደርገዋል።

OpenAI Codex (Plus/Pro)

ዳሽቦርድ → አቅራቢዎች → Codexን አገናኝ
→ በOAuth ይግቡ (port 1455)
→ የ5-ሰዓት + ሳምንታዊ ዳግም ማስጀመር

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

GitHub Copilot

ዳሽቦርድ → አቅራቢዎች → 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

💰 ርካሽ አቅራቢዎች

GLM-4.7 (ዕለታዊ ዳግም ማስጀመር፣ $0.6/1M)

1. ይመዝገቡ፦ Zhipu AI
2. ከCoding Plan የAPI ቁልፍ ያግኙ
3. ዳሽቦርድ → የAPI ቁልፍ አክል፦ አቅራቢ፦ 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
2. የAPI ቁልፍ ያግኙ → ዳሽቦርድ → የAPI ቁልፍ አክል

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

Kimi K2 (በወር ቋሚ $9)

1. ደንበኛ ይሁኑ፦ Moonshot AI
2. የAPI ቁልፍ ያግኙ → ዳሽቦርድ → የAPI ቁልፍ አክል

አጠቃቀም: kimi/kimi-k2.5 — የባለሙያ ምክር: ለ10M ቶከኖች በወር ቋሚ $9 = ውጤታማ ወጪ $0.90/1M!

Baidu Qianfan / ERNIE

1. ይመዝገቡ፦ Baidu AI Cloud Qianfan
2. የQianfan API ቁልፍ ይፍጠሩ → ዳሽቦርድ → የAPI ቁልፍ አክል፦ አቅራቢ፦ qianfan

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

🆓 ነፃ አቅራቢዎች

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

Qoder (9 ነፃ ሞዴሎች)

ዳሽቦርድ → 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 ነፃ)

ዳሽቦርድ → 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ን ይመልከቱ።

Claude Code

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

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

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

Codex CLI

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

OpenClaw

~/.openclaw/openclaw.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 ጭነት (የሚመከር)

npm install -g omniroute

# የውቅር ማውጫ ይፍጠሩ
mkdir -p ~/.omniroute

# የ.env ፋይል ይፍጠሩ (.env.exampleን ይመልከቱ)
cp .env.example ~/.omniroute/.env

# አገልጋዩን ያስጀምሩ
omniroute
# ወይም ብጁ port በመጠቀም፦
omniroute --port 3000

CLIው .envን ከ~/.omniroute/.env ወይም ./.env በራስ-ሰር ይጭናል።

የማሳወቂያ ሳጥን ሁነታ

OmniRouteን በስርዓቱ የማሳወቂያ ሳጥን ውስጥ ያስጀምሩ፦

omniroute serve --tray

አገልጋዩና የማሳወቂያ ሳጥኑ ዝግጁ ከሆኑ በኋላ ትዕዛዙ ይጠናቀቃል።

አገልጋዩ ያለ terminal መስራቱን ይቀጥላል።

የማሳወቂያ ሳጥን ሁነታ macOSን፣ Windowsን እና ግራፊክሳዊ የLinux ክፍለ-ጊዜዎችን ይደግፋል። የማሳወቂያ ሳጥን ሁነታ ዳሽቦርዱን በራስ-ሰር አይከፍትም።

ለእነዚህ ድርጊቶች የማሳወቂያ ሳጥን ምናሌውን ይጠቀሙ፦

• ዳሽቦርዱን ይክፈቱ።
• /dashboard/logsን ይክፈቱ።
• ራስ-ሰር ማስጀመርን ይቀይሩ።
• OmniRouteን ያቁሙ።

--trayን ከእነዚህ አማራጮች ጋር አያጣምሩ፦

• --daemon
• --log
• --no-recovery

እነዚህ ሁነታዎች የተለየ የሂደት ባለቤትነት ይፈልጋሉ።

በሚቀጥለው የማሽን መግቢያ ጊዜ ማስጀመርን ያንቁ፦

omniroute autostart enable

ራስ-ሰር ማስጀመር በmacOS፣ Windows እና ግራፊክሳዊ የLinux ክፍለ-ጊዜዎች ላይ የማሳወቂያ ሳጥን ሁነታን ይጠቀማል። ማሳያ የሌለው Linux ነባሩን የsystemd ተጠቃሚ አገልግሎት ይጠቀማል።

በመግቢያ ጊዜ ማስጀመርን ያሰናክሉ፦

omniroute autostart disable

ማራገፍ

ከአሁን በኋላ OmniRoute በማያስፈልግዎት ጊዜ፣ ሙሉ በሙሉ ለማስወገድ ሁለት ፈጣን ስክሪፕቶችን አቅርበናል፦

ትዕዛዝ	ድርጊት
npm run uninstall	የስርዓት መተግበሪያውን ያስወግዳል፣ ነገር ግን በ~/.omniroute ውስጥ የውሂብ ጎታዎንና ውቅሮችዎን ያቆያል።
npm run uninstall:full	መተግበሪያውን ያስወግዳል፣ እንዲሁም ሁሉንም ውቅሮች፣ ቁልፎች እና የውሂብ ጎታዎች እስከመጨረሻው ይሰርዛል።

ማስታወሻ፦ እነዚህን ትዕዛዞች ለማስኬድ፣ ወደ OmniRoute ፕሮጀክት አቃፊ ይሂዱ (clone ካደረጉት) እና ያስኪዷቸው። እንደ አማራጭ፣ በአጠቃላይ የተጫነ ከሆነ፣ npm uninstall -g omnirouteን ብቻ ማስኬድ ይችላሉ።

በVPS ላይ ማሰማራት

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

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

npm run start
# ወይም፦ pm2 start npm --name omniroute -- start

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

የRAM አቅማቸው ውስን ለሆኑ አገልጋዮች፣ የማህደረ ትውስታ ገደብ አማራጩን ይጠቀሙ፦

# በ512MB ገደብ (ነባሪ)
pm2 start npm --name omniroute -- start

# ወይም ብጁ የማህደረ ትውስታ ገደብ በመጠቀም
OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start

# ወይም ecosystem.config.jsን በመጠቀም
pm2 start ecosystem.config.js

ecosystem.config.jsን ይፍጠሩ፦

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

# Image ይገንቡ (ነባሪ = codex/claude/droid አስቀድሞ የተጫነበት runner-cli)
docker build -t omniroute:cli .

# ተንቀሳቃሽ ሁነታ (የሚመከር)
docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli

ከCLI binaries ጋር ለhost-የተዋሃደ ሁነታ፣ በዋናዎቹ ሰነዶች ውስጥ ያለውን የDocker ክፍል ይመልከቱ።

Void Linux (xbps-src)

Void Linux ተጠቃሚዎች xbps-src የመስቀለኛ-ማጠናቀር ማዕቀፍን በመጠቀም OmniRouteን በስርዓቱ ቤተኛ መንገድ ማሸግ እና መጫን ይችላሉ። ይህም የNode.js ራሱን የቻለ ግንባታን ከሚያስፈልጉት better-sqlite3 ቤተኛ bindings ጋር በራስ-ሰር ያከናውናል።

የxbps-src አብነትን ይመልከቱ

# የ'omniroute' አብነት ፋይል
pkgname=omniroute
version=3.8.0
revision=1
hostmakedepends="nodejs python3 make"
depends="openssl"
short_desc="ብዙ LLM አቅራቢዎችን በብልህ ማዘዋወር የሚያስተዳድር ሁለንተናዊ AI መግቢያ"
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() {
	# ለnode-gyp የዒላማውን CPU መዋቅር ይወስኑ
	local _gyp_arch
	case "$XBPS_TARGET_MACHINE" in
		aarch64*) _gyp_arch=arm64 ;;
		armv7*|armv6*) _gyp_arch=arm ;;
		i686*) _gyp_arch=ia32 ;;
		*) _gyp_arch=x64 ;;
	esac

	# 1) ሁሉንም ጥገኛዎች ይጫኑ – ስክሪፕቶችን ይዝለሉ
	NODE_ENV=development npm ci --ignore-scripts

	# 2) ራሱን የቻለውን የNext.js ጥቅል ይገንቡ
	npm run build

	# 3) የማይንቀሳቀሱ ሀብቶችን ወደ ራሱን የቻለው ጥቅል ይቅዱ
	cp -r .next/static .next/standalone/.next/static
	[ -d public ] && cp -r public .next/standalone/public || true

	# 4) የbetter-sqlite3 ቤተኛ 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) የተጠናቀረውን binding በራሱን የቻለው ጥቅል ውስጥ ያስቀምጡ
	local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
	mkdir -p "$_bs3_release"
	cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"

	# 6) ለተወሰነ መዋቅር የተዘጋጁ sharp ጥቅሎችን ያስወግዱ
	rm -rf .next/standalone/node_modules/@img

	# 7) በNext.js የማይንቀሳቀስ ትንተና የተዘለሉትን የpino runtime ጥገኛዎች ይቅዱ፦
	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

	# ከመጫን በኋላ ባለው hook ባዶ የNext.js መተግበሪያ router ማውጫዎች እንዳይወገዱ ይከላከሉ
	for _d in \
		.next/standalone/.next/server/app/dashboard \
		.next/standalone/.next/server/app/dashboard/settings \
		.next/standalone/.next/server/app/dashboard/providers; do
		touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
	done

	cat > "${WRKDIR}/omniroute" <<'EOF'
#!/bin/sh
export PORT="${PORT:-20128}"
export DATA_DIR="${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}"
export APP_LOG_TO_FILE="${APP_LOG_TO_FILE:-false}"
mkdir -p "${DATA_DIR}"
exec node /usr/lib/omniroute/.next/standalone/server.js "$@"
EOF
	vbin "${WRKDIR}/omniroute"
}

post_install() {
	vlicense LICENSE
}

የአካባቢ ተለዋዋጮች

ተለዋዋጭ	ነባሪ	መግለጫ
JWT_SECRET	omniroute-default-secret-change-me	JWT መፈረሚያ ሚስጥር (በምርት አካባቢ ይቀይሩት)
INITIAL_PASSWORD	CHANGEME	የመጀመሪያ መግቢያ የይለፍ ቃል
DATA_DIR	~/.omniroute	የውሂብ ማውጫ (የውሂብ ጎታ፣ አጠቃቀም፣ ምዝግቦች)
PORT	የፍሬምወርኩ ነባሪ	የአገልግሎት ወደብ (በምሳሌዎች ውስጥ 20128)
HOSTNAME	የፍሬምወርኩ ነባሪ	የማስተሳሰሪያ አስተናጋጅ (የDocker ነባሪ 0.0.0.0 ነው)
NODE_ENV	የአሂድ ጊዜ ነባሪ	ለማሰማራት production ያዘጋጁ
NEXT_PUBLIC_BASE_URL	http://localhost:20128	ለዳሽቦርዱ የሚታይ እና ለአገልጋዩ የሚጋለጥ ይፋዊ መሠረታዊ URL (የቀድሞውን BASE_URL ይተካል)
NEXT_PUBLIC_CLOUD_URL	https://omniroute.dev	የደመና ማመሳሰያ መጨረሻ ነጥብ መሠረታዊ URL (የቀድሞውን CLOUD_URL ይተካል)
API_KEY_SECRET	endpoint-proxy-api-key-secret	ለሚፈጠሩ API ቁልፎች የHMAC ሚስጥር
REQUIRE_API_KEY	false	በ/v1/* ላይ የBearer API ቁልፍን ያስገድዱ
ALLOW_API_KEY_REVEAL	false	ማንነታቸው የተረጋገጠ የዳሽቦርድ ተጠቃሚዎች ሲጠይቁ ሙሉ የተከማቹ API ቁልፍ እሴቶችን እንዲመለከቱ ይፍቀዱ
PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES	70	ለተሸጎጠ የአቅራቢ ገደቦች ውሂብ የአገልጋይ-ወገን ማደሻ ድግግሞሽ፤ የUI ማደሻ አዝራሮች አሁንም በእጅ ማመሳሰልን ያስነሳሉ
DISABLE_SQLITE_AUTO_BACKUP	false	ከመጻፍ/ማስመጣት/መመለስ በፊት ራስ-ሰር የSQLite ቅጽበተ ቅጂዎችን ያሰናክሉ፤ በእጅ የሚደረጉ ምትኬዎች አሁንም ይሠራሉ
APP_LOG_TO_FILE	true	የመተግበሪያ እና የኦዲት ምዝግብ ውጤትን ወደ ዲስክ ማስቀመጥን ያነቃል
AUTH_COOKIE_SECURE	false	Secure የማረጋገጫ ኩኪን ያስገድዱ (ከHTTPS ተገላቢጦሽ ፕሮክሲ በስተጀርባ)
CLOUDFLARED_BIN	አልተዋቀረም	በሚተዳደር ማውረድ ፈንታ ነባር cloudflared ባይነሪን ይጠቀሙ
CLOUDFLARED_PROTOCOL	http2	በሚተዳደሩ Quick Tunnels የሚጠቀመው ማጓጓዣ (http2፣ quic፣ ወይም auto)
OMNIROUTE_MEMORY_MB	512	የNode.js ሂፕ ገደብ በMB
PROMPT_CACHE_MAX_SIZE	50	ከፍተኛው የጥያቄ መሸጎጫ ግቤቶች ብዛት
SEMANTIC_CACHE_MAX_SIZE	100	ከፍተኛው የፍቺ መሸጎጫ ግቤቶች ብዛት

የአካባቢ ተለዋዋጮችን ሙሉ ማጣቀሻ ለማየት READMEን ይመልከቱ።

---

📊 የሚገኙ ሞዴሎች

የሚገኙትን ሞዴሎች በሙሉ ይመልከቱ

ከታች ያለው ዝርዝር ለv3.8.0 ከopen-sse/config/providerRegistry.ts የተመረጠ ነው። የደመና ካታሎጎች (Gemini፣ OpenRouter፣ ወዘተ) በተለዋዋጭ ሁኔታ ይመሳሰላሉ — ሙሉውን የቀጥታ ካታሎግ ለማየት Dashboard → Providers → [provider] → Available Models ይክፈቱ ወይም GET /api/models/catalog ይጠቀሙ።

የአቅራቢው አብሮገነብ ዝርዝር ከአሁኑ ሁኔታ ከተለየ፣ የቀጥታውን የላይኛው ምንጭ ካታሎግ ለማምጣት በዚያ ገጽ ላይ Import from /models ይጠቀሙ (ወይም Auto-Syncን ያንቁ)። ይህ በv3.8.50 ለLLM7.io (gemini-3.1-flash-lite) እና UncloseAI (solidrust/Hermes-3-Llama-3.1-8B-AWQ) ተረጋግጧል፤ በዚያው የሙከራ ዙር የPollinations ስም-አልባ መዳረሻ በላይኛው ምንጭ ገደብ ውስጥ ቀርቷል።

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

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

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

Kiro (kr/) — ነፃ OAuth፦ በDashboard → Providers → Kiro → Available Models ስር የሚታየውን የቀጥታ ካታሎግ ይጠቀሙ። ተገኝነቱ በመለያው እና በዕቅዱ ላይ ይመሰረታል።

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

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

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

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

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

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

xAI (xai/) — ቤተኛ Grok፦ xai/grok-4.3, xai/grok-4.20-multi-agent-0309, xai/grok-4.20-0309-reasoning, xai/grok-4.20-0309-non-reasoning

Mistral (mistral/) — በአውሮፓ ህብረት የተስተናገደ፦ mistral/mistral-large-latest, mistral/mistral-medium-3-5, mistral/mistral-small-latest, mistral/devstral-latest, mistral/codestral-latest

Perplexity (pplx/) — በፍለጋ የተጠናከረ፦ pplx/sonar-deep-research, pplx/sonar-reasoning-pro, pplx/sonar-pro, pplx/sonar

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

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

Cerebras (cerebras/) — በዌፈር ልኬት፦ cerebras/zai-glm-4.7, cerebras/gpt-oss-120b

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

NVIDIA NIM (nvidia/) — ለድርጅቶች፦ nvidia/z-ai/glm-5.1, nvidia/minimaxai/minimax-m2.7, nvidia/google/gemma-4-31b-it, nvidia/mistralai/mistral-small-4-119b-2603, nvidia/mistralai/mistral-large-3-675b-instruct-2512, nvidia/qwen/qwen3.5-397b-a17b, nvidia/deepseek-ai/deepseek-v4-pro, nvidia/openai/gpt-oss-120b, nvidia/nvidia/nemotron-3-super-120b-a12b

Baidu Qianfan (qianfan/) — ERNIE: qianfan/ernie-5.1, qianfan/ernie-5.0-thinking-latest, qianfan/ernie-x1.1

Ollama Cloud (ollama-cloud/): ollama-cloud/deepseek-v4-pro, ollama-cloud/deepseek-v4-flash, ollama-cloud/kimi-k2.6, ollama-cloud/glm-5.1, ollama-cloud/minimax-m2.7, ollama-cloud/gemma4:31b, ollama-cloud/qwen3.5:397b

Gemini (Google Cloud gemini/)፦ ከGoogle በእያንዳንዱ API ቁልፍ መሠረት በቀጥታ ይመሳሰላል — የማይለወጥ ዝርዝር የለም። በDashboard → Providers ውስጥ ቁልፍ ያገናኙ፣ ከዚያም የአሁኑን ካታሎግ ለማስመጣት Available Modelsን ይጠቀሙ (ለምሳሌ፦ gemini/gemini-3-pro, gemini/gemini-3-flash)።

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

ስለ ሞዴል መለያዎች ማስታወሻ፦ OmniRoute የአቅራቢውን ቤተኛ መለያዎች (claude-opus-4-8, gpt-5.5, glm-5.1, MiniMax-M2.7, kimi-k2.5, grok-4.20-0309-reasoning) ይጠቀማል። የላይኛው ምንጭ API የሚጠብቃቸው በዚህ መልኩ ስለሆነ፣ አንዳንድ መለያዎች ነጥብ ያላቸውን ስሪቶች ያካትታሉ። አንድ ሞዴል ከላይ ካልተዘረዘረ፣ ተገኝነቱን ለማረጋገጥ omniroute models --search <term>ን ያሂዱ ወይም GET /api/models/catalogን ይጠቀሙ።

---

🧩 የላቁ ባህሪያት

ብጁ ሞዴሎች

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

# በAPI በኩል
curl -X POST http://localhost:20128/api/provider-models \
  -H "Content-Type: application/json" \
  -d '{"provider": "openai", "modelId": "gpt-5.2", "modelName": "GPT-5.2"}'

# ዝርዝር፦ curl http://localhost:20128/api/provider-models?provider=openai
# ማስወገድ፦ curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-5.2"

ወይም Dashboardን ይጠቀሙ፦ Providers → [Provider] → Custom Models።

ማስታወሻዎች፦

• OpenRouter እና OpenAI/Anthropic-ተኳኋኝ አቅራቢዎች ከAvailable Models ብቻ ይተዳደራሉ። በእጅ ማከል፣ ማስመጣት እና ራስ-ሰር ማመሳሰል ሁሉም በተመሳሳዩ የሚገኙ ሞዴሎች ዝርዝር ውስጥ ይቀመጣሉ፤ ስለዚህ ለእነዚህ አቅራቢዎች የተለየ Custom Models ክፍል የለም።
• የCustom Models ክፍል የሚተዳደሩ የሞዴል ማስመጣቶችን ለማያቀርቡ አቅራቢዎች የታሰበ ነው።

የOmniRoute አቻዎችን ማገናኘት

ሌላ OmniRoute ጌትዌይ እንደ Custom OpenAI-compatible አቅራቢ ሊታከል ይችላል። የአቻውን /v1 መሠረታዊ URL እና በዚያ አቻ የተሰጠ ራሱን የቻለ፣ ዝቅተኛ ፈቃድ ያለው API ቁልፍ ይጠቀሙ።

ለተገላቢጦሽ ወይም ባለብዙ-ዝላይ ሰንሰለቶች፣ በእያንዳንዱ ጌትዌይ ላይ በፍላጎት የሚነቃውን የሉፕ መከላከያ ያንቁ፦

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

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

በግልጽ ወደተፈቀደ የአቻ URL የተላኩ ጥያቄዎች ብቻ የX-OmniRoute-Peer-Trace ራስጌን ይቀበላሉ። አንድ ጌትዌይ የተደገመ የኢንስታንስ ID ወይም ያለቀ የዝላይ ገደብን በHTTP 508 Loop Detected ውድቅ ያደርጋል፤ መደበኛ የላይኛው ዥረት አቅራቢዎች ምንም የአቻ ሜታዳታ አይቀበሉም።

የአቻ ማገናኘት የዳታቤዝ ማባዛት ወይም የአስተናጋጅ መተካካት አይደለም። እያንዳንዱ ጌትዌይ ራሱን የቻለ የSQLite ሁኔታ፣ መሸጎጫዎች፣ የፍጥነት ቆጣሪዎች እና ክፍለ-ጊዜዎች ይኖሩታል። ለንቁ/ተጠባባቂ ወይም ንቁ/ንቁ ተገኝነት ጤንነቱ የሚፈተሽ የተገላቢጦሽ ፕሮክሲ ወይም የደንበኛ መተካካትን ይጠቀሙ፤ እንዲሁም አንድን SQLite ዳታቤዝ በበርካታ እየሰሩ ያሉ OmniRoute ኢንስታንሶች ላይ ፈጽሞ አይጫኑ።

ለአቅራቢዎች የተወሰኑ መስመሮች

ከሞዴል ማረጋገጫ ጋር ጥያቄዎችን በቀጥታ ወደተወሰነ አቅራቢ ያስተላልፉ፦

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 ይመልሳሉ።

የኔትወርክ ፕሮክሲ ውቅር

# ዓለም አቀፍ ፕሮክሲ ያዘጋጁ
curl -X PUT http://localhost:20128/api/settings/proxy \
  -d '{"global": {"type":"http","host":"proxy.example.com","port":"8080"}}'

# ለእያንዳንዱ አቅራቢ ፕሮክሲ
curl -X PUT http://localhost:20128/api/settings/proxy \
  -d '{"providers": {"openai": {"type":"socks5","host":"proxy.example.com","port":"1080"}}}'

# ፕሮክሲን ይፈትሹ
curl -X POST http://localhost:20128/api/settings/proxy/test \
  -d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}'

ቅድሚያ፦ ለቁልፍ-የተወሰነ → ለጥምረት-የተወሰነ → ለአቅራቢ-የተወሰነ → ዓለም አቀፍ → አካባቢ።

የሞዴል ካታሎግ API

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

በአቅራቢ የተመደቡ ሞዴሎችን ከአይነቶቻቸው (chat፣ embedding፣ image) ጋር ይመልሳል።

የደመና ማመሳሰል

• አቅራቢዎችን፣ ጥምረቶችን እና ቅንብሮችን በመሣሪያዎች መካከል ያመሳስሉ
• ከጊዜ ማብቂያ + ፈጣን ማቋረጥ ጋር ራስ-ሰር የጀርባ ማመሳሰል
• በምርት አካባቢ የአገልጋይ-ወገን NEXT_PUBLIC_BASE_URL/NEXT_PUBLIC_CLOUD_URLን ይምረጡ

Cloudflare ፈጣን ቱነል

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

የLLM ጌትዌይ ብልህነት (ደረጃ 9)

• የፍቺ መሸጎጫ — ዥረት-አልባ፣ temperature=0 ምላሾችን በራስ-ሰር ይሸጎጣል (በX-OmniRoute-No-Cache: true ይለፉት)
• የጥያቄ አንድ-ጊዜነት — በIdempotency-Key ወይም X-Request-Id ራስጌ አማካኝነት በ5 ሰከንድ ውስጥ የሚቀርቡ ጥያቄዎችን ከመደጋገም ይከላከላል
• የሂደት ክትትል — በX-OmniRoute-Progress: true ራስጌ በፍላጎት የሚነቁ SSE event: progress ክስተቶች

---

የተርጓሚ የሙከራ ቦታ

በDashboard → Translator በኩል ይድረሱበት። OmniRoute በአቅራቢዎች መካከል የAPI ጥያቄዎችን እንዴት እንደሚተረጉም ስህተቶችን ያርሙ እና በምስል ይመልከቱ።

ሁነታ	ዓላማ
Playground	የምንጭ/ዒላማ ቅርጸቶችን ይምረጡ፣ ጥያቄን ይለጥፉ እና የተተረጎመውን ውጤት ወዲያውኑ ይመልከቱ
Chat Tester	በፕሮክሲው በኩል የቀጥታ ውይይት መልዕክቶችን ይላኩ እና ሙሉውን የጥያቄ/ምላሽ ዑደት ይመርምሩ
Test Bench	የትርጉም ትክክለኛነትን ለማረጋገጥ በበርካታ የቅርጸት ጥምረቶች ላይ የጅምላ ፈተናዎችን ያሂዱ
Live Monitor	ጥያቄዎች በፕሮክሲው ውስጥ ሲያልፉ የእውነተኛ-ጊዜ ትርጉሞችን ይመልከቱ

የአጠቃቀም ሁኔታዎች፦

• አንድ የተወሰነ የደንበኛ/አቅራቢ ጥምረት ለምን እንደሚሳነው ስህተቱን ያርሙ
• የአስተሳሰብ መለያዎች፣ የመሣሪያ ጥሪዎች እና የስርዓት መጠየቂያዎች በትክክል መተርጎማቸውን ያረጋግጡ
• በOpenAI፣ Claude፣ Gemini እና Responses API ቅርጸቶች መካከል ያሉ የቅርጸት ልዩነቶችን ያወዳድሩ

---

የማስተላለፊያ ስልቶች

በDashboard → Settings → Routing በኩል ያዋቅሩ። Dashboard በብዛት ጥቅም ላይ የሚውሉትን ስድስት ስትራቴጂዎች ያሳያል፤ combos እና auto-router በውስጣዊ አሠራራቸው የበለጠ ሰፊ ስብስብን ይደግፋሉ።

በDashboard ላይ የሚታዩ ስትራቴጂዎች (በመለያ ደረጃ የሚደረግ ማዘዋወር):

ስትራቴጂ	መግለጫ
መጀመሪያውን ሙላ	መለያዎችን በቅድሚያ ቅደም ተከተል ይጠቀማል — ዋናው መለያ እስኪገኝ እስከማይችል ድረስ ሁሉንም ጥያቄዎች ያስተናግዳል
ተራ በተራ	ሊዋቀር በሚችል የቋሚነት ገደብ ሁሉንም መለያዎች በተራ ይጠቀማል (ነባሪ፦ በአንድ መለያ 3 ጥሪዎች)
P2C (ከሁለት አማራጮች የተሻለው)	2 የዘፈቀደ መለያዎችን መርጦ ጤናማ ወደሆነው ያዘዋውራል — የጤና ሁኔታን ከግምት በማስገባት ጭነትን ያመጣጥናል
የዘፈቀደ	Fisher-Yates shuffleን በመጠቀም ለእያንዳንዱ ጥያቄ አንድ መለያ በዘፈቀደ ይመርጣል
በትንሹ ጥቅም ላይ የዋለ	እጅግ የቆየው lastUsedAt timestamp ወዳለው መለያ ያዘዋውራል፣ ትራፊክንም በእኩል ያሰራጫል
ለወጪ የተመቻቸ	ዝቅተኛው የቅድሚያ እሴት ወዳለው መለያ ያዘዋውራል፣ ዝቅተኛ ወጪ ላላቸው አቅራቢዎች ያመቻቻል

የላቁ combo እና auto ስትራቴጂዎች (ለእያንዳንዱ combo ወይም በauto/* prefixes በኩል ሊዋቀሩ የሚችሉ — AUTO-COMBO.mdን ይመልከቱ)፦

• priority — ጥብቅ ቅደም ተከተል፣ round-robinን ፈጽሞ አይጠቀምም
• weighted — በእያንዳንዱ model ክብደት መሠረት የተመጣጠነ የትራፊክ ክፍፍል
• fill-first — ገደቦች እስኪደረሱ ድረስ የመጀመሪያውን model ሙሉ በሙሉ ይጠቀማል
• round-robin / strict-random / random
• p2c (ከሁለት አማራጮች የተሻለው)
• least-used እና cost-optimized
• auto — በሁሉም እጩዎች ላይ በውጤት ነጥብ የሚመራ
• lkgp (በመጨረሻ ጥሩ እንደሆነ የታወቀ አቅራቢ) — በመጨረሻ ስኬታማ ወደነበረው አቅራቢ ያቆያል፣ ከዚያም ወደ ደንቦች ይመለሳል
• context-optimized — ትልቁ ነፃ context window ያለውን model ይመርጣል
• context-relay — ለቀጣይ ዙሮች ረጅም-context modelsን በሰንሰለት ያገናኛል

ውጫዊ ቋሚ Session Header

ለውጫዊ session affinity (ለምሳሌ፣ ከreverse proxies ጀርባ ላሉ Claude Code/Codex agents)፣ የሚከተለውን ይላኩ፦

X-Session-Id: your-session-key

OmniRoute x_session_idንም ይቀበላል፣ ተግባራዊውን session keyም በX-OmniRoute-Session-Id ይመልሳል።

Nginxን የሚጠቀሙ እና underscore-form headersን የሚልኩ ከሆነ፣ ይህን ያንቁ፦

underscores_in_headers on;

Wildcard Model Aliases

የmodel ስሞችን ዳግም ለመመደብ wildcard patternsን ይፍጠሩ፦

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

Wildcards *ን (ማንኛውም ቁምፊዎች) እና ?ን (አንድ ቁምፊ) ይደግፋሉ።

Fallback Chains

በሁሉም ጥያቄዎች ላይ ተግባራዊ የሚሆኑ global fallback chainsን ይግለጹ፦

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

---

የመቋቋም አቅም እና Circuit Breakers

በDashboard → Settings → Resilience በኩል ያዋቅሩ።

OmniRoute በአቅራቢ ደረጃ የመቋቋም አቅምን በአምስት ክፍሎች ይተገብራል፦

1. የጥያቄ ወረፋ እና ፍጥነት መቆጣጠር — በስርዓት ደረጃ የጥያቄ ፍሰት ማስተካከያ፦

   • ጥያቄዎች በደቂቃ (RPM) — ለእያንዳንዱ መለያ በደቂቃ የሚፈቀደው ከፍተኛ የጥያቄዎች ብዛት
   • በጥያቄዎች መካከል ዝቅተኛው ጊዜ — በጥያቄዎች መካከል በmilliseconds የሚለካ ዝቅተኛው ክፍተት
   • ከፍተኛው በአንድ ጊዜ የሚካሄዱ ጥያቄዎች — ለእያንዳንዱ መለያ በአንድ ጊዜ የሚካሄዱ ከፍተኛው የጥያቄዎች ብዛት

2. የግንኙነት ማቀዝቀዣ ጊዜ — ዳግም ሊሞከሩ ከሚችሉ ውድቀቶች በኋላ ለአንድ ግንኙነት፣ በእያንዳንዱ auth type የሚደረግ ውቅር፦

   • መሠረታዊ ማቀዝቀዣ ጊዜ — ዳግም ሊሞከሩ ለሚችሉ upstream ውድቀቶች ነባሪ የማቀዝቀዣ ጊዜ
   • የUpstream ዳግም ሙከራ ፍንጮችን ተጠቀም — ሲቀርቡ ባለሥልጣን የሆኑ Retry-After ወይም reset ፍንጮችን ያከብራል
   • ከፍተኛው የBackoff ደረጃዎች — ለተደጋጋሚ ውድቀቶች ከፍተኛው የexponential backoff ደረጃ

3. የአቅራቢ Circuit Breaker — ከጫፍ እስከ ጫፍ የሚከሰቱ የአቅራቢ ውድቀቶችን ይከታተላል፣ በተዋቀረው የማስጠንቀቂያ ገደብ ላይ አቅራቢውን የተዳከመ ብሎ ምልክት ያደርጋል፣ እና የተዋቀረው የውድቀት ገደብ ሲደረስ breakerን ይከፍታል፦

   • የመዳከም ገደብ — ወደ DEGRADED ከመግባቱ በፊት የሚከሰቱ ተከታታይ የአቅራቢ ውድቀቶች
   • የውድቀት ገደብ — ወደ OPEN ከመግባቱ በፊት የሚከሰቱ ተከታታይ የአቅራቢ ውድቀቶች
   • የዳግም ማስጀመሪያ ጊዜ — አቅራቢው እንደገና ከመፈተኑ በፊት ያለው የጊዜ መስኮት
   • CLOSED (ጤናማ) — ጥያቄዎች በመደበኛነት ይፈሳሉ
   • DEGRADED — ከፍ ያሉ ውድቀቶች እየተከታተሉ ጥያቄዎች አሁንም ይፈሳሉ
   • OPEN — ከተደጋጋሚ ውድቀቶች በኋላ አቅራቢው ለጊዜው ይታገዳል
   • HALF_OPEN — አቅራቢው ማገገሙን በመፈተሽ ላይ

   በግንኙነት ወሰን ያሉ 429 የፍጥነት ገደቦች በየግንኙነት ማቀዝቀዣ ጊዜ ውስጥ ይቆያሉ፣ በአቅራቢ breaker ላይም አይቆጠሩም።

   የአቅራቢ breaker runtime state የሚታየው በDashboard → Health ላይ ብቻ ነው።

4. ማቀዝቀዣውን ጠብቅ — እያንዳንዱ እጩ ግንኙነት አስቀድሞ በማቀዝቀዣ ጊዜ ላይ ከሆነ፣ OmniRoute ቀድሞ የሚያበቃውን የማቀዝቀዣ ጊዜ ጠብቆ ያንኑ የclient ጥያቄ በራስ-ሰር እንደገና ሊሞክር ይችላል።

5. የፍጥነት ገደብ ራስ-ሰር ማወቂያ — upstream አቅራቢዎች ግልጽ የመጠበቂያ ጊዜዎችን ሲመልሱ፣ ቅንብሩ ከነቃ እነዚያ ፍንጮች ከአካባቢያዊው የግንኙነት ማቀዝቀዣ ጊዜ ይልቅ ቅድሚያ ያገኛሉ።

የባለሙያ ምክር፦ ከአገልግሎት መቋረጥ በኋላ ንቁ የአቅራቢ breakersን ለመመርመር እና ዳግም ለማስጀመር የHealth ገጽን ይጠቀሙ። Resilience ገጹ የሚቀይረው ውቅረትን ብቻ ነው።

---

የDatabase ወደ ውጭ መላክ / ወደ ውስጥ ማስገባት

የdatabase backupsን በDashboard → Settings → System & Storage ያስተዳድሩ።

ድርጊት	መግለጫ
የውሂብ ጎታ ወደ ውጭ ላክ	የአሁኑን SQLite የውሂብ ጎታ እንደ .sqlite ፋይል ያወርዳል
ሁሉንም ወደ ውጭ ላክ (.tar.gz)	የሚከተሉትን ያካተተ ሙሉ የምትኬ ማህደር ያወርዳል፦ የውሂብ ጎታ፣ ቅንብሮች፣ ጥምረቶች፣ የአቅራቢ ግንኙነቶች (ማረጋገጫዎችን ሳያካትት)፣ የAPI ቁልፍ ሜታዳታ
የውሂብ ጎታ አስመጣ	የአሁኑን የውሂብ ጎታ ለመተካት .sqlite ፋይል ይሰቅላል። DISABLE_SQLITE_AUTO_BACKUP=true ካልሆነ በቀር፣ ከማስመጣት በፊት ምትኬ በራስ-ሰር ይፈጠራል

# API፦ የውሂብ ጎታን ወደ ውጭ ላክ
curl -o backup.sqlite http://localhost:20128/api/db-backups/export

# API፦ ሁሉንም ወደ ውጭ ላክ (ሙሉ ማህደር)
curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll

# API፦ የውሂብ ጎታን አስመጣ
curl -X POST http://localhost:20128/api/db-backups/import \
  -F "file=@backup.sqlite"

የማስመጣት ማረጋገጫ፦ የመጣው ፋይል ለትክክለኛነት (የSQLite pragma ምርመራ)፣ ለሚያስፈልጉ ሰንጠረዦች (provider_connections፣ provider_nodes፣ combos፣ api_keys) እና ለመጠን (ከፍተኛው 100MB) ይረጋገጣል።

የአጠቃቀም ሁኔታዎች፦

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

---

የቅንብሮች ዳሽቦርድ

ለቀላል አሰሳ፣ የቅንብሮች ገጹ በ7 ትሮች ተደራጅቷል፦

ትር	ይዘቶች
አጠቃላይ	የስርዓት ማከማቻ መሣሪያዎች፣ ነባሪ ባህሪ፣ የEndpoint ቱነል ታይነት
ገጽታ	የገጽታ መቆጣጠሪያዎች (ብርሃን/ጨለማ/ስርዓት)፣ የጎን አሞሌ ታይነት፣ ለCloudflare/Tailscale/ngrok ቱነል ካርዶች የፓነል መቀያየሪያዎች
AI	የአስተሳሰብ በጀት (እንዳለ ማሳለፍ / በራስ-ሰር ማስወገድ / ብጁ / ተስማሚ — THINKING_BUDGET.mdን ይመልከቱ)፣ ዓለም አቀፍ የስርዓት መመሪያ፣ የመመሪያ መሸጎጫ ስታቲስቲክስ
ደህንነት	የመግቢያ/የይለፍ ቃል ቅንብሮች፣ የIP መዳረሻ ቁጥጥር፣ ለ/models የAPI ማረጋገጫ፣ የአቅራቢ እገዳ፣ ከመመሪያ-መርፌ ጥቃት መከላከያ
ማስተላለፊያ	ዓለም አቀፍ የማስተላለፊያ ስልት (መጀመሪያ ሙላ / ተራ በተራ / P2C / የዘፈቀደ / በትንሹ ጥቅም ላይ የዋለ / ወጪ-የተመቻቸ)፣ የዋይልድካርድ ሞዴል ተለዋጭ ስሞች፣ የመጠባበቂያ ሰንሰለቶች፣ የጥምረት ነባሪዎች
ጽናት	የጥያቄ ወረፋ፣ የግንኙነት ማቀዝቀዣ ጊዜ፣ የአቅራቢ ወረዳ መቋረጫ ውቅር እና ማቀዝቀዣውን የመጠበቅ ባህሪ
የላቀ	ዓለም አቀፍ የፕሮክሲ ውቅር (HTTP/SOCKS5)፣ ለእያንዳንዱ አቅራቢ የፕሮክሲ መሻሮች

አጠቃላይ ከአሁን በኋላ ተደጋጋሚ የሆኑ ተነባቢ-ብቻ የምዝግብ እና የመሸጎጫ ማስታወሻዎችን አያካትትም። የውሂብ ጎታ ማቆያ እና ማመቻቻ ቅንብሮች በ/api/settings/database በኩል በቋሚነት ይቀመጣሉ፤ መሸጎጫን በእጅ ማጽዳት DELETE /api/cacheን ይጠቀማል። የጥያቄ እና የፕሮክሲ ምዝግብ ረድፍ ገደቦች በ CALL_LOGS_TABLE_MAX_ROWS እና PROXY_LOGS_TABLE_MAX_ROWS ይቆጣጠራሉ።

---

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

በዳሽቦርድ → ወጪዎች በኩል ይድረሱበት።

ትር	ዓላማ
በጀት	ለእያንዳንዱ API ቁልፍ ዕለታዊ/ሳምንታዊ/ወርሃዊ በጀቶች እና የቅጽበታዊ ክትትል ያላቸው የወጪ ገደቦችን ያዘጋጁ
ዋጋ አሰጣጥ	የሞዴል ዋጋ አሰጣጥ ግቤቶችን ይመልከቱ እና ያርትዑ — ለእያንዳንዱ አቅራቢ በ1K የግብዓት/የውጤት ቶከኖች የሚከፈል ወጪ

# API፦ በጀት አዘጋጅ
curl -X POST http://localhost:20128/api/usage/budget \
  -H "Content-Type: application/json" \
  -d '{"keyId": "key-123", "limit": 50.00, "period": "monthly"}'

# API፦ የአሁኑን የበጀት ሁኔታ አግኝ
curl http://localhost:20128/api/usage/budget

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

---

የድምፅ ወደ ጽሑፍ ቅጂ

OmniRoute OpenAI-ተኳሃኝ በሆነው Endpoint በኩል የድምፅ ወደ ጽሑፍ ቅጂን ይደግፋል፦

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

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

deepgram/nova-3 ቤተኛው የDeepgram መስመር ሲሆን፣ የDeepgram API ቁልፍ ያስፈልገዋል። OpenRouter ብቻ ከተዋቀረ፣ openrouter/deepgram/nova-3ን ይጠቀሙ።

ድምፅ-ወደ-ጽሑፍ (ቅጂ) አቅራቢዎች፦

• openai/ (ከwhisper ጋር ተኳሃኝ)
• groq/ (Groq Whisper Turbo)
• deepgram/ (Nova ቤተሰብ)
• assemblyai/
• nvidia/ (Parakeet፣ Canary)
• huggingface/ (የwhisper ተለዋጮች)
• qwen/

ጽሑፍ-ወደ-ድምፅ (POST /v1/audio/speech) አቅራቢዎች፦

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

ለድምፅ ወደ ጽሑፍ ቅጂ የሚደገፉ የድምፅ ቅርጸቶች፦ mp3፣ wav፣ m4a፣ flac፣ ogg፣ webm። የTTS ውጤት ቅርጸቶች በአቅራቢው ላይ ይመሰረታሉ (mp3፣ wav፣ opus፣ pcm፣ mulaw)።

---

የጥምረት ማመጣጠኛ ስልቶች

የእያንዳንዱን ጥምረት ማመጣጠኛ በዳሽቦርድ → ጥምረቶች → ፍጠር/አርትዕ → ስልት ውስጥ ያዋቅሩ።

ስትራቴጂ	መግለጫ
ተራ-በተራ	በሞዴሎች መካከል በቅደም ተከተል ይዘዋወራል
ቅድሚያ	ሁልጊዜ የመጀመሪያውን ሞዴል ይሞክራል፤ ስህተት ሲኖር ብቻ ወደ ተተኪው ይመለሳል
የዘፈቀደ	ለእያንዳንዱ ጥያቄ ከጥምሩ ውስጥ አንድ ሞዴል በዘፈቀደ ይመርጣል
ክብደት-ተኮር	ለእያንዳንዱ ሞዴል በተመደቡ ክብደቶች መሠረት ጥያቄዎችን በተመጣጣኝ ሁኔታ ይመራል
በትንሹ-ጥቅም-ላይ-የዋለ	በቅርብ ጊዜ ከሁሉም ያነሱ ጥያቄዎች ወደነበሩት ሞዴል ይመራል (የጥምር መለኪያዎችን ይጠቀማል)
ወጪ-የተመቻቸ	ካሉት ሞዴሎች ወደ ርካሹ ይመራል (የዋጋ ሰንጠረዡን ይጠቀማል)

ዓለም አቀፍ የጥምር ነባሪዎችን በዳሽቦርድ → ቅንብሮች → ማዘዋወር → የጥምር ነባሪዎች ውስጥ ማዋቀር ይቻላል። የጥምር ዒላማ የጊዜ ገደቦች በነባሪነት የአሁኑን የጥያቄ ጊዜ ገደብ ይወርሳሉ። አጭር የየዒላማው ገደብ ፈጣን ወደ ተተኪ መመለስን ማስጀመር ሲኖርበት ብቻ በጥምር ነባሪዎች ወይም በግለሰብ ጥምር ላይ **የዒላማ ጊዜ ገደብ (ሰከንዶች)**ን ይጠቀሙ።

ዜሮ-መዘግየት ያላቸው የጥምር ማመቻቻዎች በፈቃደኝነት የሚነቁ ናቸው። እነዚህ የመዘግየት ባህሪያት ከተተኪ ዒላማዎች ጋር እንዳይሽቀዳደሙ፣ በTTFT ታሪክ መሠረት ዒላማዎችን እንዳይዘሉ ወይም የተተኪ ጥያቄዎችን እንዳያመቁ ዜሮ-መዘግየት ማመቻቻዎችን እንደተሰናከሉ ይተዉ፤ ማንቃት የተዋቀረ ትይዩ ጥያቄ መላክን፣ ትንበያዊ የTTFT ዝለላዎችን እና ንቁ የተተኪ ጥያቄ ማመቅን በመፍቀድ የማዘዋወር/የጥያቄ ታማኝነትን ለዝቅተኛ የመጨረሻ-ጅራት መዘግየት ይለውጣል።

የላይኛው አቅራቢዎች ጥብቅ የ max_tokens / maxOutputTokens ገደቦችን ሲጠይቁ የምክንያታዊነት ቶከን ቋትን ያሰናክሉ። ሲነቃ፣ የጥምር ማዘዋወር የምክንያታዊነት ሞዴል ተጨማሪ ቦታን የሚጨምረው የሚታወቅ የውጤት ጣሪያ ላላቸው ሞዴሎች ብቻ ሲሆን፣ ደህንነቱ የተጠበቀው በቋት የተጨመረ እሴት ያንን ጣሪያ የሚያልፍ ከሆነ የደንበኛውን የቶከን ገደብ ሳይቀይር ይተዋል። የደንበኛው ገደብ ከታወቀ ጣሪያ በላይ ከሆነ፣ OmniRoute ጥያቄውን ወደ ላይኛው አቅራቢ ከመላኩ በፊት እስከዚያ ጣሪያ ድረስ ይቀንሰዋል።

---

የጤና ዳሽቦርድ

በዳሽቦርድ → ጤና በኩል ይድረሱበት። 6 ካርዶች ያሉት የእውነተኛ ጊዜ የስርዓት ጤና አጠቃላይ እይታ፦

ካርድ	የሚያሳየው
የስርዓት ሁኔታ	የሥራ ጊዜ፣ ስሪት፣ የማህደረ ትውስታ አጠቃቀም፣ የውሂብ ማውጫ
የአቅራቢ ጤና	የዓለም አቀፍ አቅራቢ ሰርኪት መቆራረጫ የአሂድ ጊዜ ሁኔታ
የፍጥነት ገደቦች	በእያንዳንዱ መለያ ላይ ያሉ ንቁ የግንኙነት የማቀዝቀዣ ጊዜያት ከቀሪ ጊዜ ጋር
ንቁ መቆለፎች	ንቁ ሞዴል-ወሰን ያላቸው መቆለፎች እና ጊዜያዊ ማግለሎች
የፊርማ መሸጎጫ	የብዜት ማስወገጃ መሸጎጫ ስታቲስቲክስ (ንቁ ቁልፎች፣ የስኬት መጠን)
የመዘግየት ቴሌሜትሪ	ለእያንዳንዱ አቅራቢ የp50/p95/p99 መዘግየት ድምር

የባለሙያ ምክር፦ የጤና ገጹ በየ10 ሰከንዱ በራስ-ሰር ይታደሳል። የትኞቹ አቅራቢዎች ችግር እያጋጠማቸው እንደሆነ ለመለየት የሰርኪት መቆራረጫ ካርዱን ይጠቀሙ።

---

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

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

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

ምሳሌ፦

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 ውስጥ ሙሉ በሙሉ ተገልጿል — ይህም የውጤት-ነጥብ ክብደቶችን እንዴት ማስተካከል፣ አቅራቢዎችን በጥቁር ዝርዝር ማስገባት እና በዳሽቦርድ → ራስ-ሰር ጥምረት ውስጥ የማዘዋወር ውሳኔዎችን መመርመርን ያካትታል።

---

🔌 የ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 ላይ ተመጣጣኙን ፋይል ያርትዑ፦

{
  "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ን፣ ለJSON-RPC መርሐግብር ደግሞ 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።

---

💾 የማስታወሻ ስርዓት

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

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

ማስታወሻዎችን በDashboard → Memory ውስጥ ያስተዳድሩ (ይፈልጉ፣ ያርትዑ፣ ወደ ውጭ ይላኩ፣ ያጽዱ)። የHTTP በይነገጽ (/api/memory/*) ኤጀንቶች እውነታዎችን በፕሮግራም እንዲጨምሩ እና እንዲጠይቁ ያስችላቸዋል — 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 ውስጥ ይገኛል።

---

☁️ የደመና ኤጀንቶች

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

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

ሙሉ ማጣቀሻ፦ CLOUD_AGENT.md።

---

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

የmanage ወሰን ያለውን Bearer ቁልፍ በመጠቀም ሁሉንም የOmniRoute ሀብቶች (አቅራቢዎች፣ combos፣ ቁልፎች፣ ቅንብሮች) በHTTP በኩል ማስተዳደር ይችላሉ።

ቁልፉን በDashboard → API Keys → New Key → Scope: manage ውስጥ ያመንጩ፣ ከዚያም፦

# አቅራቢዎችን ዘርዝር
curl http://localhost:20128/api/providers \
  -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY"

# የአቅራቢ ግንኙነት ጨምር
curl -X POST http://localhost:20128/api/providers \
  -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "provider": "openai", "apiKey": "sk-...", "name": "main" }'

# 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 ቁልፎችን ዘርዝር/ፍጠር
curl http://localhost:20128/api/keys -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY"
curl -X POST http://localhost:20128/api/keys -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY" \
  -d '{ "name": "ci-bot", "scopes": ["chat"] }'

ሙሉውን የመገናኛ ነጥቦች ዝርዝር እና የጥያቄ/ምላሽ እቅዶች ለማየት API_REFERENCE.md ይመልከቱ።

---

💻 ውስጣዊ CLI

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

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 እንደ ቤተኛ የዴስክቶፕ መተግበሪያ ይገኛል።

መጫን

# ከelectron ማውጫ፦
cd electron
npm install

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

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

ጫኚዎችን መገንባት

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