# User Guide (Gaeilge)
🌐 **Languages:** 🇺🇸 [English](../../../../guides/USER_GUIDE.md) · 🇪🇹 [am](../../../am/docs/guides/USER_GUIDE.md) · 🇸🇦 [ar](../../../ar/docs/guides/USER_GUIDE.md) · 🇦🇿 [az](../../../az/docs/guides/USER_GUIDE.md) · 🇧🇬 [bg](../../../bg/docs/guides/USER_GUIDE.md) · 🇧🇩 [bn](../../../bn/docs/guides/USER_GUIDE.md) · 🇧🇦 [bs](../../../bs/docs/guides/USER_GUIDE.md) · 🇨🇿 [cs](../../../cs/docs/guides/USER_GUIDE.md) · 🇩🇰 [da](../../../da/docs/guides/USER_GUIDE.md) · 🇩🇪 [de](../../../de/docs/guides/USER_GUIDE.md) · 🇬🇷 [el](../../../el/docs/guides/USER_GUIDE.md) · 🇪🇸 [es](../../../es/docs/guides/USER_GUIDE.md) · 🇪🇪 [et](../../../et/docs/guides/USER_GUIDE.md) · 🇮🇷 [fa](../../../fa/docs/guides/USER_GUIDE.md) · 🇫🇮 [fi](../../../fi/docs/guides/USER_GUIDE.md) · 🇫🇷 [fr](../../../fr/docs/guides/USER_GUIDE.md) · 🇮🇳 [gu](../../../gu/docs/guides/USER_GUIDE.md) · 🇳🇬 [ha](../../../ha/docs/guides/USER_GUIDE.md) · 🇮🇱 [he](../../../he/docs/guides/USER_GUIDE.md) · 🇮🇳 [hi](../../../hi/docs/guides/USER_GUIDE.md) · 🇭🇷 [hr](../../../hr/docs/guides/USER_GUIDE.md) · 🇭🇺 [hu](../../../hu/docs/guides/USER_GUIDE.md) · 🇦🇲 [hy](../../../hy/docs/guides/USER_GUIDE.md) · 🇮🇩 [id](../../../id/docs/guides/USER_GUIDE.md) · 🇳🇬 [ig](../../../ig/docs/guides/USER_GUIDE.md) · 🇮🇹 [it](../../../it/docs/guides/USER_GUIDE.md) · 🇯🇵 [ja](../../../ja/docs/guides/USER_GUIDE.md) · 🇬🇪 [ka](../../../ka/docs/guides/USER_GUIDE.md) · 🇰🇭 [km](../../../km/docs/guides/USER_GUIDE.md) · 🇮🇳 [kn](../../../kn/docs/guides/USER_GUIDE.md) · 🇰🇷 [ko](../../../ko/docs/guides/USER_GUIDE.md) · 🇱🇹 [lt](../../../lt/docs/guides/USER_GUIDE.md) · 🇱🇻 [lv](../../../lv/docs/guides/USER_GUIDE.md) · 🇮🇳 [ml](../../../ml/docs/guides/USER_GUIDE.md) · 🇮🇳 [mr](../../../mr/docs/guides/USER_GUIDE.md) · 🇲🇾 [ms](../../../ms/docs/guides/USER_GUIDE.md) · 🇲🇹 [mt](../../../mt/docs/guides/USER_GUIDE.md) · 🇲🇲 [my](../../../my/docs/guides/USER_GUIDE.md) · 🇳🇵 [ne](../../../ne/docs/guides/USER_GUIDE.md) · 🇳🇱 [nl](../../../nl/docs/guides/USER_GUIDE.md) · 🇳🇴 [no](../../../no/docs/guides/USER_GUIDE.md) · 🇮🇳 [or](../../../or/docs/guides/USER_GUIDE.md) · 🇮🇳 [pa](../../../pa/docs/guides/USER_GUIDE.md) · 🇵🇭 [phi](../../../phi/docs/guides/USER_GUIDE.md) · 🇵🇱 [pl](../../../pl/docs/guides/USER_GUIDE.md) · 🇵🇹 [pt](../../../pt/docs/guides/USER_GUIDE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/guides/USER_GUIDE.md) · 🇷🇴 [ro](../../../ro/docs/guides/USER_GUIDE.md) · 🇷🇺 [ru](../../../ru/docs/guides/USER_GUIDE.md) · 🇱🇰 [si](../../../si/docs/guides/USER_GUIDE.md) · 🇸🇰 [sk](../../../sk/docs/guides/USER_GUIDE.md) · 🇸🇮 [sl](../../../sl/docs/guides/USER_GUIDE.md) · 🇷🇸 [sr](../../../sr/docs/guides/USER_GUIDE.md) · 🇸🇪 [sv](../../../sv/docs/guides/USER_GUIDE.md) · 🇰🇪 [sw](../../../sw/docs/guides/USER_GUIDE.md) · 🇮🇳 [ta](../../../ta/docs/guides/USER_GUIDE.md) · 🇮🇳 [te](../../../te/docs/guides/USER_GUIDE.md) · 🇹🇭 [th](../../../th/docs/guides/USER_GUIDE.md) · 🇹🇷 [tr](../../../tr/docs/guides/USER_GUIDE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/guides/USER_GUIDE.md) · 🇵🇰 [ur](../../../ur/docs/guides/USER_GUIDE.md) · 🇺🇿 [uz](../../../uz/docs/guides/USER_GUIDE.md) · 🇻🇳 [vi](../../../vi/docs/guides/USER_GUIDE.md) · 🇳🇬 [yo](../../../yo/docs/guides/USER_GUIDE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/guides/USER_GUIDE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/guides/USER_GUIDE.md)
---
🌐 **Languages:** 🇺🇸 [English](../../../../guides/USER_GUIDE.md) · 🇪🇹 [am](../../../am/docs/guides/USER_GUIDE.md) · 🇸🇦 [ar](../../../ar/docs/guides/USER_GUIDE.md) · 🇦🇿 [az](../../../az/docs/guides/USER_GUIDE.md) · 🇧🇬 [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) · 🇮🇳 [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)
Treoir iomlán maidir le soláthraithe a chumrú, teaglamaí a chruthú, uirlisí CLI a chomhtháthú, agus OmniRoute a imscaradh.
---
## Clár Ábhair
- [Praghsáil ar Shaol AG HAMHROG](#-praghsáil-ar-saol-ag-hamhrog)
- [Cásanna Úsáide](#cásanna-úsaide)
- [Socrú Soláthraí](#socrú-soláthraí)
- [Comhtháthú CLI](#comhtháthú-cli)
- [Imscartha](#imscartha)
- [Samhlacha ar Fáil](#samhlacha-ar-fáil)
- [Gnéithe Ards Price](#gnéithe-ard-pris)
- [Ródáil Uathoibríoch (Náid Chumraíocht)](#ródáil-uathoibríoch-náid-chumraíocht)
- [Comhtháthú MCP & A2A](#comhtháthú-mcp--a2a)
- [Córas Scileanna](#córas-scileanna)
- [Córas Cuimhne](#córas-cuimhne)
- [Gréasáin Hook](#gréasáin-hook)
- [Gníomhairí Scáileáin](#gníomhairí-scáileáin)
- [Bainisteoireacht Clárlathasach](#bainisteoireacht-clárlathasach)
- [CLI Inmheánach](#cli-inmheánach)
- [Feidhmchlár Deisce (Electron)](#feidhmchlár-deisce-electron)
## 💰 Praghsáil go Sracfhéachaint
| Leibhéal | Soláthraí | Costas | Athshocrú Cuóta | Is Fearr Do |
| -------------------- | ----------------- | ------------------ | ---------------------------------- | ------------------------- |
| **💳 SÍNTIÚS** | Claude Code (Pro) | $20/mí | 5h + seachtainiúil | Síntiús cheana féin |
| | Codex (Plus/Pro) | $20-200/mí | 5h + seachtainiúil | Úsáideoirí OpenAI |
| | GitHub Copilot | $10-19/mí | Míosúil | Úsáideoirí GitHub |
| **🔑 EOCRAÍ API** | DeepSeek | Íoc de réir úsáide | Níl aon cheann | Réasúnú saor |
| | Groq | Íoc de réir úsáide | Níl aon cheann | Tátal ultra-tapa |
| | xAI (Grok) | Íoc de réir úsáide | Níl aon cheann | Réasúnú Grok 4 |
| | Mistral | Íoc de réir úsáide | Níl aon cheann | Samhlacha óstáilte san AE |
| | Perplexity | Íoc de réir úsáide | Níl aon cheann | Cuardach-fheabhsaithe |
| | Together AI | Íoc de réir úsáide | Níl aon cheann | Samhlacha foinse oscailte |
| | Fireworks AI | Íoc de réir úsáide | Níl aon cheann | Íomhánna FLUX tapa |
| | Cerebras | Íoc de réir úsáide | Níl aon cheann | Luas scála-sliseanna |
| | Cohere | Íoc de réir úsáide | Níl aon cheann | Command R+ RAG |
| | NVIDIA NIM | Íoc de réir úsáide | Níl aon cheann | Samhlacha fiontair |
| | Baidu Qianfan | Íoc de réir úsáide | Níl aon cheann | Samhlacha ERNIE |
| **💰 SAOR** | GLM-4.7 | $0.6/1M | Laethúil 10AM | Cúltaca buiséid |
| | MiniMax M2.1 | $0.2/1M | 5 uair an chloig rollach | An rogha is saoire |
| | Kimi K2 | $9/mí comhréidh | 10M comharthaí/mí | Costas intuartha |
| **🆓 SAOR IN AISCE** | Qoder | $0 | Teorainneacha soláthraí i bhfeidhm | Deimhnigh catalóg reatha |
| | Kiro | $0 | ~50 creidmheas/mí | Claude saor in aisce |
---
## 🎯 Cásanna Úsáide
### Cás 1: "Tá síntiús Claude Pro agam"
**Fadhb:** Cailleann an cuóta gan úsáid, teorainneacha ráta le linn códú trom
```
Combo: "maximize-claude"
1. cc/claude-opus-4-7 (úsáid an síntiús go hiomlán)
2. glm/glm-4.7 (cúltaca saor nuair a bhíonn cuóta ídithe)
3. if/qwen3.8-max-preview (cúltaca éigeandála saor in aisce)
Costas míosúil: $20 (síntiús) + ~$5 (cúltaca) = $25 san iomlán
vs. $20 + teorainneacha a bhualadh = frustrachas
```
### Cás 2: "Teastaíonn uaim costas nialasach"
**Fadhb:** Ní féidir síntiúis a íoc, teastaíonn códú AI iontaofa
```
Combo: "zero-cost"
1. if/kimi-k2.7-code (rochtain saor in aisce liostaithe; d'fhéadfadh teorainneacha ráta a bheith i bhfeidhm)
2. kr/qwen3-coder-next (cúltaca saor in aisce Kiro)
Costas míosúil: $0
Cáilíocht: deimhnigh an tsamhail, na teorainneacha, príobháideacht, agus SLA do d'ualach oibre
```
### Cás 3: "Teastaíonn uaim códú 24/7, gan aon chur isteach"
**Fadhb:** Spriocdhátaí, ní féidir leo downtime a cheadú
```
Combo: "always-on"
1. cc/claude-opus-4-7 (an cháilíocht is fearr)
2. cx/gpt-5.5 (dara síntiús)
3. glm/glm-4.7 (saor, athshocraíonn laethúil)
4. minimax/MiniMax-M2.1 (is saoire, athshocraíonn 5h)
5. if/deepseek-v4-flash (rochtain saor in aisce liostaithe; d'fhéadfadh teorainneacha ráta a bheith i bhfeidhm)
Toradh: 5 shraith chúltaca a leathnaíonn athléimneacht; ní ráthaítear infhaighteacht an tsoláthraí
Costas míosúil: $20-200 (síntiúis) + $10-20 (cúltaca)
```
### Cás 4: "Teastaíonn uaim AI SAOR IN AISCE in OpenClaw"
**Fadhb:** Teastaíonn cúntóir AI in aipeanna teachtaireachta, go hiomlán saor in aisce
```
Combo: "openclaw-free"
1. if/qwen3.8-max-preview (rochtain saor in aisce liostaithe; d'fhéadfadh teorainneacha ráta a bheith i bhfeidhm)
2. if/deepseek-v4-flash (rochtain saor in aisce liostaithe; d'fhéadfadh teorainneacha ráta a bheith i bhfeidhm)
3. if/kimi-k2.7-code (rochtain saor in aisce liostaithe; d'fhéadfadh teorainneacha ráta a bheith i bhfeidhm)
Costas míosúil: $0
Rochtain trí: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
```
## 📖 Socrú Soláthraithe
Chun naisc eochracha API a chur leis ar an mórchóir ó chomhad CSV nó JSON, úsáid **Deais → Soláthraithe → Iompórtáil ó chomhad**. Tá na colúin suite de réir a suímh (`provider,name,apiKey,baseUrl,priority`); ní mór do `provider` a bheith ann cheana mar sholáthraí bainistithe nó mar nód comhoiriúnach. Féach [Iompórtáil soláthraithe ó chomhad CSV nó JSON](../providers/CSV-IMPORT.md).
### 🔐 Soláthraithe Síntiúis
#### Claude Code (Pro/Max)
```bash
Deais → Soláthraithe → Ceangail Claude Code
→ Logáil isteach le OAuth → Athnuachan uathoibríoch comhartha
→ Rianú cuóta 5 uair an chloig + seachtainiúil
Múnlaí:
cc/claude-opus-4-7
cc/claude-sonnet-4-6
cc/claude-haiku-4-5-20251001
```
**Leid Pro:** Úsáid Opus le haghaidh tascanna casta, agus Sonnet ar mhaithe le luas. Rianaíonn OmniRoute an cuóta de réir an mhúnla!
Níl brabhsálaí ar óstach OmniRoute? Rith `claude setup-token` áit ar bith ina bhfuil Claude Code logáilte isteach agus greamaigh an comhartha bliana amháin sa chluaisín **Comhartha Socraithe**. Féach [Claude Code le comhartha socraithe](../providers/CLAUDE_CODE_SETUP_TOKEN.md).
Caomhnaíonn bealaí atá comhoiriúnach le Claude agus Claude Code an iarracht smaointeoireachta `max` do mhúnlaí
Opus agus Sonnet. Ní ghlacann múnlaí Haiku leis an tsraith iarrachta `max`, mar sin íslíonn OmniRoute an
t-iarratas sin go buiséad ard smaointeoireachta sula seoltar ar aghaidh é.
#### OpenAI Codex (Plus/Pro)
```bash
Deais → Soláthraithe → Ceangail Codex
→ Logáil isteach le OAuth (port 1455)
→ Athshocrú 5 uair an chloig + seachtainiúil
Múnlaí:
cx/gpt-5.5
cx/gpt-5.4
cx/gpt-5.3-codex
cx/gpt-5.3-codex-spark
```
#### GitHub Copilot
```bash
Deais → Soláthraithe → Ceangail GitHub
→ OAuth trí GitHub
→ Athshocrú míosúil (an 1ú lá den mhí)
Múnlaí:
gh/gpt-5.5
gh/gpt-5.4
gh/claude-sonnet-4.6
gh/claude-opus-4.7
gh/gemini-3.1-pro-preview
```
**Creidmheasanna AI (billeáil bunaithe ar chomharthaí).** Nuair a thuairiscíonn GitHub `credits_used` don
chuntas, taispeánann an cárta Teorainneacha Soláthraí sraith **Creidmheasanna AI** leis na creidmheasanna
a úsáideadh sa tréimhse bhilleála reatha, lena n-áirítear ar phleananna eagraíochta neamhtheoranta.
**Teorainn áitiúil Creidmheasanna AI.** Cuir nasc GitHub in eagar agus socraigh **teorainn Creidmheasanna AI in aghaidh
na tréimhse billeála** (`providerSpecificData.githubCreditLimit`). Díchumasaíonn réimse folamh é; scipeálann `0`
an nasc i gcónaí. Nuair atá an léamh úsáide is déanaí cothrom leis an teorainn nó os a cionn, ní roghnaíonn
an cuntas an nasc sin agus filleann an ródú ar do naisc eile, ar an mbealach céanna le scoith bheartais
cuóta. Léann an tseiceáil an úsáid a bhailíonn an t-athnuachan thréimhsiúil cuóta cheana féin — ní ghlaonn
sé ar GitHub ar chosán na hiarrata riamh — agus fágann sé oscailte é i gcás teipe: ní chuireann léamh atá
ar iarraidh nó seanléamh (níos sine ná 15 nóiméad, nó ó thréimhse bhilleála a athshocraíodh cheana) bac ar
an nasc. Is cosaint áitiúil é seo, **ní uasteorainn chaiteachais ráthaithe**: d’fhéadfadh moilleanna i
dtuairisciú GitHub, an t-eatramh athnuachana, iarratais atá ar siúl agus úsáid lasmuigh de OmniRoute dul
thar an teorainn. Úsáid rialuithe caiteachais GitHub féin le haghaidh teorainn chrua.
### 💰 Soláthraithe Saora
#### GLM-4.7 (Athshocrú laethúil, $0.6/1M)
1. Cláraigh: [Zhipu AI](https://open.bigmodel.cn)
2. Faigh eochair API ón bPlean Códaithe
3. Deais → Cuir Eochair API leis: Soláthraí: `glm`, Eochair API: `your-key`
**Úsáid:** `glm/glm-4.7` — **Leid Pro:** Cuireann an Plean Códaithe cuóta 3× ar fáil ar 1/7 den chostas! Athshocraítear go laethúil é ag 10:00 AM.
#### MiniMax M2.1 (Athshocrú 5 uair an chloig, $0.20/1M)
1. Cláraigh: [MiniMax](https://www.minimax.io)
2. Faigh eochair API → Deais → Cuir Eochair API leis
**Úsáid:** `minimax/MiniMax-M2.1` — **Leid Pro:** An rogha is saoire le haghaidh comhthéacs fada (1M comhartha)!
#### Kimi K2 ($9/mí ar ráta comhréidh)
1. Liostáil: [Moonshot AI](https://platform.kimi.ai?aff=omniroute)
2. Faigh eochair API → Deais → Cuir Eochair API leis
**Úsáid:** `kimi/kimi-k2.5` — **Leid Pro:** $9/mí seasta le haghaidh 10M comhartha = costas éifeachtach $0.90/1M!
#### Baidu Qianfan / ERNIE
1. Cláraigh: [Baidu AI Cloud Qianfan](https://cloud.baidu.com/product/wenxinworkshop)
2. Cruthaigh eochair API Qianfan → Deais → Cuir Eochair API leis: Soláthraí: `qianfan`
**Úsáid:** `qianfan/ernie-5.1`, `qianfan/ernie-x1.1`, nó aitheantas samhla eile atá comhoiriúnach le OpenAI Qianfan.
### 🆓 Soláthraithe SAOR IN AISCE
Tá lasc in aice le **Níl fíordheimhniú riachtanach** ag soláthraithe saor in aisce gan fíordheimhniú ar a leathanach soláthraí.
Má mhúchtar é, díchumasaítear an soláthraí sin, baintear é de na hamhairc Soláthraithe cumraithe/dhlúth, agus
baintear a mhúnlaí de `/v1/models`.
#### Qoder (9 múnla SAOR IN AISCE)
```bash
Deais → Ceangail Qoder → Logáil isteach le OAuth → Tá rochtain faoi réir theorainneacha reatha an tsoláthraí
Múnlaí: 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 SAOR IN AISCE)
```bash
Deais → Ceangail Kiro → AWS Builder ID nó Google/GitHub → ~50 creidmheas/mí
Múnlaí: kr/claude-sonnet-4.5, kr/claude-haiku-4.5
```
---
## 🎨 Comhoiripeanna
Is féidir leat cártaí comhoiripe a athordú go díreach i **Dashboard → Combos** trí lámh gach cárta a tharraingt. Stóráiltear an t-ordú i SQLite agus athchóirítear é ar atosú.
### Sampla 1: Uasmhéadaigh Síntiús → Tacaíocht Saor
```
Dashboard → Combos → Create New
Name: premium-coding
Models:
1. cc/claude-opus-4-7 (Subscription primary)
2. glm/glm-4.7 (Cheap backup, $0.6/1M)
3. minimax/MiniMax-M2.7 (Cheapest fallback, $0.3/1M)
Use in CLI: premium-coding
```
### Sampla 2: Saor-Amháin (Costas Náid)
```
Name: free-combo
Models:
1. if/kimi-k2.7-code (listed free access; provider limits may apply)
2. kr/qwen3-coder-next (Kiro free fallback)
Cost: currently listed as $0; terms and availability may change
```
---
## 🔧 Comhtháthú CLI
### Cursor IDE
**Ag úsáid Cursor mar chliant OmniRoute** (route Cursor chat trí OmniRoute):
```
Socruithe → Samhlacha → Ardsocruithe:
URL Bonn API OpenAI: http://localhost:20128/v1
Eochair API OpenAI: [ón deais omniroute]
Samhail: cc/claude-opus-4-7
```
**Ag úsáid OmniRoute mar sholáthraí Cursor** (cuireann OmniRoute glao ar upstream Cursor): roghnaigh **Deais → Soláthraithe → Cursor → Logáil isteach le Cursor**. I Docker, féach [`docs/providers/CURSOR-DOCKER.md`](../providers/CURSOR-DOCKER.md).
### Claude Code
Cuir `~/.claude/settings.json` in eagar:
```json
{
"env": {
"ANTHROPIC_BASE_URL": "http://localhost:20128",
"ANTHROPIC_AUTH_TOKEN": "your-omniroute-api-key"
}
}
```
Bain úsáid as an pointe teagmhála fréamhochomaithe comhoiriúnach le Claude anseo. Ná cuir `/v1` le `ANTHROPIC_BASE_URL`.
### Codex CLI
```bash
export OPENAI_BASE_URL="http://localhost:20128"
export OPENAI_API_KEY="your-omniroute-api-key"
codex "your prompt"
```
### OpenClaw
Cuir `~/.openclaw/openclaw.json` in eagar:
```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" }]
}
}
}
}
```
**Nó bain úsáid as an Deais:** Uirlisí CLI → OpenClaw → Cumraíocht Uathoibríoch
### Cline / Continue / RooCode
```
Soláthraí: Comhoiriúnach le OpenAI
URL Bonn: http://localhost:20128/v1
Eochair API: [ón deais]
Samhail: cc/claude-opus-4-7
```
---
## 🚀 Imscaradh
### Suiteáil npm domhanda (Molta)
```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
```
Lódálann an CLI `.env` go huathoibríoch ó `~/.omniroute/.env` nó `./.env`. Ní féidir le `./.env` san eolaire oibre ach liosta ceadaithe gearr eochracha a shocrú (socruithe poirt, `REQUIRE_API_KEY`, locale agus dath); cuir gach rud eile i `~/.omniroute/.env`. Féach [conarthaí seolta CLI](CLI-LAUNCH-CONTRACTS.md#working-directory-env).
### Mód tráidire
Tosaigh OmniRoute sa tráidire córais:
```bash
omniroute serve --tray
```
Filleann an t-ordú nuair a bhíonn an freastalaí agus an tráidire réidh.
Leanann an freastalaí gan an teirminéal.
Tacaíonn modh tráidire le seisiúin macOS, Windows, agus Linux grafacha. Ní osclaíonn mód an tráidire an painéal go huathoibríoch.
Úsáid roghchlár an tráidire do na gníomhartha seo:
- Oscail an painéal.
- Oscail `/dashboard/logs`.
- Athraigh uath-tús.
- Stop OmniRoute.
Ná comhcheangail `--tray` leis na roghanna seo:
- `--daemon`
- `--log`
- `--no-recovery`
Éilíonn na modhanna seo úinéireacht próisis éagsúla.
Cumasaigh am tosaithe ag an gcéad logáil isteach meaisín eile:
```bash
omniroute autostart enable
```
Úsáideann Auto-tús mód tráidire ar sheisiúin macOS, Windows, agus Linux grafacha. Úsáideann Linux Headless an tseirbhís úsáideora systemd atá ann cheana féin.
Díchumasaigh am tosaithe ag logáil isteach:
```bash
omniroute autostart disable
```
### Díshuiteáil
Nuair nach bhfuil OmniRoute ag teastáil uait a thuilleadh, cuirimid dhá script thapa ar fáil chun é a bhaint glan:
| Ordú | Gníomh |
| ------------------------ | ------------------------------------------------------------------------------------------------- |
| `npm run uninstall` | Bain an app córais ach** Coinníonn do DB agus cumraíochtaí** i `~/.omniroute`. |
| `npm run uninstall:full` | Baintear an AND app go buan** scriosann sé gach cumraíocht, eochracha, agus bunachair shonraí** . |
> Nóta: Chun na horduithe seo a rith, déan nascleanúint chuig an bhfillteán tionscadail OmniRoute (má chlónáil tú é) agus rith iad. Nó, má tá tú suiteáilte go domhanda, is féidir leat `npm uninstall -g omniroute`.
### VPS Imscaradh
```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
```
### Imscaradh PM2 (Cuimhne Íseal)
Maidir le freastalaithe le RAM teoranta , úsáid an rogha teorainn chuimhne:
```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
```
Cruthaigh `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
```
Le haghaidh mód óstach-chomhtháite le binaries CLI, féach an roinn Docker sna príomhdhoiciméid.
### Folús Linux (xbps-src)
Is féidir le húsáideoirí neamhní Linux OmniRoute a phacáistiú agus a shuiteáil go dúchais ag baint úsáide as an gcreat tras-thiomsaithe `xbps-src`. Déanann sé seo an tógáil neamhspleách Node.js a uathoibriú mar aon leis na ceangail dhúchasacha `better-sqlite3` riachtanacha.
Féach ar an teimpléad xbps-src
```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 "
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
}
```
### Athróga Comhshaoil
| Athróg | Réamhshocrú | Cur síos |
| --------------------------------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `JWT_SECRET` | _(uathghinte)_ | JWT síniú rúnda — uathghinte ar an gcéad rith agus fós ag `server.env`; socraigh go sonrach é nuair atá an t-eolaire sonraí gearrthéarmach |
| `INITIAL_PASSWORD` | _(díshuiteáil)_ | An chéad phasfhocal logáil isteach. Tosaíonn npm/source installs le `CHANGEME`: cuir ina ionad. Unset: draoi bordála |
| `DATA_DIR` | `~/.omniroute` | Eolaire sonraí (db, úsáid, logaí) |
| `PORT` | réamhshocraithe creata | Port seirbhíse (`20128` i samplaí) |
| `HOSTNAME` | réamhshocraithe creata | Ceangail óstach (Docker réamhshocraithe le `0.0.0.0`) |
| `NODE_ENV` | réamhshocraithe am rite | Socraigh `production` le haghaidh imscaradh |
| `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128` | Dromchla poiblí URL ar an deais agus nochtaithe don fhreastalaí (a ionadaíonn oidhreacht `BASE_URL`) |
| `NEXT_PUBLIC_CLOUD_URL` | `https://omniroute.dev` | bonn críochphointe scamall sioncronaithe URL (a ionadaíonn oidhreacht `CLOUD_URL`) |
| `API_KEY_SECRET` | _(uathghinte)_ | rún HMAC le haghaidh eochracha API ginte — uathghinte ar an gcéad rith agus lean sé go `server.env` |
| `REQUIRE_API_KEY` | `false` | Íosluchtaigh eochair Iompróir API ar `/v1/*` |
| `ALLOW_API_KEY_REVEAL` | `false` | Ceadaigh d’úsáideoirí fíordheimhnithe ar an deais eochairluachanna API stóráilte iomlána a nochtadh ar éileamh |
| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Dúnta athnuachana ar thaobh an fhreastalaí le haghaidh sonraí i dtaisce maidir le Teorainneacha Soláthraí; Spreagann cnaipí athnuachana UI sioncronú láimhe fós |
| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Díchumasaigh seatanna uathoibríocha SQLite roimh writes/import/restore; cúltacaí láimhe fós ag obair |
| `APP_LOG_TO_FILE` | `true` | Cumasaíonn sé aschur logála feidhmchláir agus iniúchta chuig diosca |
| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth fianán (ar chúl seachfhreastalaí HTTPS ) |
| `CLOUDFLARED_BIN` | neamhshuite | Bain úsáid as dénártha `cloudflared` atá ann cheana féin in ionad íoslódáil bainistithe |
| `CLOUDFLARED_PROTOCOL` | `http2` | Iompar do Tholláin Mhearbhainistithe (`http2`, `quic`, nó `auto`) |
| `OMNIROUTE_MEMORY_MB` | `512` | teorainn carn Node.js i MB |
| `PROMPT_CACHE_MAX_SIZE` | `50` | Uasmhéid iontrálacha taisce pras |
| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Uasmhéid iontrálacha taisce shéimeantacha |
Le haghaidh tagartha iomlán an athróg timpeallachta, féach an [README](../README.md).
---
## 📊 Múnlaí atá ar fáil
Féach ar na múnlaí go léir atá ar fáil
> Tiomsaíodh an liosta thíos ó `open-sse/config/providerRegistry.ts` do v3.8.0. Déantar catalóga néil (Gemini, OpenRouter, srl.) a shioncronú go dinimiciúil — chun an catalóg bheo iomlán a fheiceáil, oscail **Deaischlár → Soláthraithe → [provider] → Múnlaí atá ar fáil** nó glaoigh ar `GET /api/models/catalog`.
>
> Má tá liosta ionsuite soláthraí imithe as sioncronú, úsáid **Iompórtáil ó /models** ar an leathanach sin (nó cumasaigh **Uath-Shioncronú**) chun catalóg bheo an fhoinseacháin réamhtheachtach a fháil. Fíoraíodh é seo i v3.8.50 le LLM7.io (`gemini-3.1-flash-lite`) agus UncloseAI (`solidrust/Hermes-3-Llama-3.1-8B-AWQ`); bhí rochtain anaithnid Pollinations teoranta ag an bhfoinseachán réamhtheachtach le linn an bhabhta tástála chéanna.
**Claude Code (`cc/`)** — OAuth Pro/Max: `cc/claude-opus-4-8`, `cc/claude-opus-4-7`, `cc/claude-opus-4-6`, `cc/claude-opus-4-5-20251101`, `cc/claude-sonnet-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
**Codex (`cx/`)** — OAuth Plus/Pro: `cx/gpt-5.5` (+ sraitheanna iarrachta: `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 SAOR IN AISCE: bain úsáid as an gcatalóg bheo a thaispeántar faoi **Deaischlár → Soláthraithe → Kiro → Múnlaí atá ar fáil**. Braitheann an infhaighteacht ar an gcuntas agus ar an bplean.
**Qoder (`if/`)** — OAuth SAOR IN AISCE: `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/mí cothrom nó de réir úsáide: `kimi/kimi-k2.6`, `kimi/kimi-k2.5`
**DeepSeek (`ds/`)** — Eochair API: `ds/deepseek-v4-pro`, `ds/deepseek-v4-flash`
**Groq (`groq/`)** — Sárthapa: `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 dúchasach: `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/`)** — Óstáilte san AE: `mistral/mistral-large-latest`, `mistral/mistral-medium-3-5`, `mistral/mistral-small-latest`, `mistral/codestral-latest`
**Perplexity (`pplx/`)** — Cuardach feabhsaithe: `pplx/sonar-deep-research`, `pplx/sonar-reasoning-pro`, `pplx/sonar-pro`, `pplx/sonar`
**Together AI (`together/`)** — Foinse oscailte: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo-Free` (saor in aisce), `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/`)** — Tátal tapa: `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/`)** — Ar scála sliseog: `cerebras/zai-glm-4.7`, `cerebras/gpt-oss-120b`
**Cohere (`cohere/`)** — Dírithe ar 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/`)** — Fiontraíoch: `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/`)**: Déantar é a shioncronú beo de réir eochair API ó Google — níl aon liosta statach ann. Ceangail eochair faoi **Deaischlár → Soláthraithe** agus ansin úsáid **Múnlaí atá ar fáil** chun an chatalóg reatha a iompórtáil (e.g. `gemini/gemini-3-pro`, `gemini/gemini-3-flash`).
**Soláthraithe comhoiriúnacha eile** (roghnaithe): `cohere`, `databricks`, `snowflake`, `together`, `vertex`, `alibaba`, `alibaba-cn`, `bedrock` (trí `aws-bedrock`), `azure-ai`, `openrouter` (catalóg passthrough), `siliconflow`, `hyperbolic`, `huggingface`, `featherless-ai`, `cloudflare-ai`, `scaleway`, `deepinfra`, `vercel-ai-gateway`, `bazaarlink`, `friendliai`, `nous-research`, `reka`, `volcengine`, `ai21`, `gigachat`. Coinníonn gach ceann acu a liosta múnlaí féin in `providerRegistry.ts` agus is féidir é a shioncronú go huathoibríoch nuair a chuireann an soláthraí críochphointe `/models` ar fáil.
**Nóta faoi aitheantóirí na múnlaí:** Úsáideann OmniRoute aitheantóirí dúchasacha soláthraithe (`claude-opus-4-8`, `gpt-5.5`, `glm-5.1`, `MiniMax-M2.7`, `kimi-k2.5`, `grok-4.20-0309-reasoning`). Tá leaganacha poncaithe i roinnt aitheantóirí toisc gurb é sin an fhormáid a bhfuil súil ag an API réamhtheachtach leis. Mura bhfuil múnla liostaithe thuas, rith `omniroute models --search ` nó buail `GET /api/models/catalog` chun a dheimhniú an bhfuil sé ar fáil.
---
## 🧩 Ardghnéithe
### Múnlaí Saincheaptha
Cuir aon mhúnla ID le haon soláthraí gan fanacht le nuashonrú aip:
```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"
```
Nó bain úsáid as an Deais:** Soláthraithe → [Soláthraí] → Múnlaí Saincheaptha** .
Nótaí:
- déantar soláthraithe OpenRouter agus OpenAI/Anthropic-compatible a bhainistiú ó** Múnlaí ar Fáil** amháin. Cuir leis, iompórtáil agus sioncronú uathoibríoch gach talamh sa liosta samhlacha céanna atá ar fáil, mar sin níl aon roinn ar leith ar Mhúnlaí Custaim do na soláthraithe sin.
- Tá an** Múnlaí Saincheaptha** Tá an rannán seo dírithe ar sholáthróirí nach nochtar allmhairí bainistithe de réir samhlacha.
### Soláthraithe Comhoiriúnacha OpenAI Saincheaptha
Is féidir aon gheata a labhraíonn an OpenAI API (seachfhreastalaí féin-óstach, vLLM, comhbhailitheoir tríú páirtí) a chur leis mar nód an tsoláthraí féin:
1. **Soláthraithe → Cuir OpenAI Comhoiriúnach** .
2. **Ainm** : lipéad taispeána don nód.
3. **Réimír** : an t-ainm ródaithe. Glaonn cliaint ar mhúnlaí mar `/`, mar sin feidhmíonn nód le réimír `mygw` `mygw/gpt-4o-mini`. Riachtanach; níl aon srian carachtar ann.
4. **API Cineál** : an teaghlach críochphointe a bhfreastalaíonn an geata air (Críochnaithe Comhrá, Freagraí, Leabaithe, fuaime, íomhánna).
5. **Bonn URL** : an fhréamh API, suas go dtí agus lena n-áirítear `/v1` (mar shampla `https://gateway.example.com/v1`), ní an cosán iomlán `/chat/completions`. Leagann geataí le cosáin neamhchaighdeánacha fúthu** Ardsocruithe** (cosán comhrá, cosán samhlacha).
6. Tá an** Eochair API (do Sheiceáil)** réimse amháin a dhéanann tástáil ar an nasc. Tar éis an nód a chruthú, é a oscailt agus a úsáid** Cuir Ceangal leis** chun an eochair a úsáidfidh iarratais a stóráil.
Faigheann an nód aitheantas inmheánach den fhoirm `openai-compatible--`; ní gá duit é a chlóscríobh riamh, is é an réimír an t-ainm poiblí.
#### Réimíreanna forchoimeádta
Ní féidir le haitheantas nó ailias soláthraí ionsuite a bheith i réimír (mar shampla `openai`, `cf`), ná id soláthraí scortha. Seiceálann an réititheoir múnla aitheantais agus ailiasanna ionsuite roimh nóid shaincheaptha, mar sin ní bhfaigheadh nód a úsáideann ceann de na réimírí sin trácht choíche: rachadh `/model` chuig an soláthraí ionsuite ina ionad sin, nó theipfeadh dúnta dá gcuirfí an soláthraí sin ar scor. Diúltaítear do chruthú nó d’eagarthóireacht nód le réimír dá leithéid le:
```text
prefix: "" is a reserved provider prefix — choose a different prefix (reserved ids/aliases cannot be used for custom nodes because requests like /model route to a built-in provider or fail closed when retired)
```
Roghnaigh réimír ar leith (`mygw`, `acme-proxy`). Má theipeann ar iarratais ar nód saincheaptha le hearráid a ainmníonn soláthraí ionsuite nó a dhintiúir, seiceáil an bhfuil réimír an nód in áirithe: tá nóid a sábháladh sula raibh an riail seo ann fós stóráilte, ach tá a mbealaí réimír chuig an soláthraí ionsuite fós. Cuir an nód in eagar agus tabhair réimír nua dó.
#### Roghanna geata in aghaidh an naisc
Téann na heochracha seo isteach i `providerSpecificData` naisc (mar shampla trí `PUT /api/providers/{id}`):
- `toolNameMaxLength` (slánuimhir, 1–1024) — le haghaidh naisc atá comhoiriúnach le formáid comhrá OpenAI a ndiúltaíonn a ngeata ainmneacha uirlisí fada. Seoltar ainmneacha níos faide mar ailiasanna gearra agus cuirtear ar ais iad sa fhreagra.
- `quotaEndpoint` — críochphointe quota/credits an gheata, léigh le haghaidh stiall cuóta an deais agus ródú atá feasach ar chuóta. Oibreacha ar naisc OpenAI-comhoiriúnacha agus Antraipeacha; tá an cruth iomlán doiciméadaithe i `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" }
}
}
}
```
### Slabhraing OmniRoute Peers
Is féidir geata OmniRoute eile a chur leis mar** Saincheaptha OpenAI-comhoiriúnach** soláthraí. Úsáid bonn `/v1` URL an chomhghleacaí agus eochair API tiomnaithe is lú pribhléid arna eisiúint ag an bpiaraí sin.
Le haghaidh slabhraí cómhalartacha nó il-hop, cumasaigh an garda lúb rogha an diúltaithe ar gach geata:
```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
```
Ní fhaigheann ach iarratais a sheoltar chuig piara URL atá liostaithe go sainráite an ceanntásc `X-OmniRoute-Peer-Trace`. Diúltaíonn geata do chás arís agus arís eile ID nó buiséad hop ídithe le HTTP `508 Loop Detected`; Ní fhaigheann gnáthsholáthraithe réamhtheachtacha aon mheiteashonraí piaraí.
Ní macasamhlú bunachar sonraí nó teip óstach é slabhraiú piaraí. Coinníonn gach geata stát SQLite neamhspleách, caches, cuntair rátaí, agus seisiúin. Bain úsáid as seachvótálaí droim ar ais atá seiceáilte ag an tsláinte nó teip tharchuir cliant le haghaidh infhaighteacht active/passive nó active/active, agus ná cuir aon bhunachar sonraí SQLite amháin isteach i gcásanna éagsúla OmniRoute reatha.
### Bealaí Soláthraí Tiomnaithe
Iarratais bealaigh go díreach chuig soláthraí sonrach le bailíochtú samhla:
```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
```
Cuirtear an réimír soláthraí leis go huathoibríoch má tá sé in easnamh. Tugann samhlacha mímheaitseála ar ais `400`.
### Cumraíocht Seachfhreastalaí Líonra
```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"}}'
```
**Tosaíocht:** Eochair-shonrach → Combo-shonrach → Soláthraí-shonrach → Comhshaol Domhanda →.
### Catalóg Múnla API
```bash
curl http://localhost:20128/api/models/catalog
```
Samhlacha tuairisceáin grúpáilte de réir soláthraí le cineálacha (`chat`, `embedding`, `image`).
### Cloud Sync
- Sioncronaigh soláthraithe, combos, agus socruithe thar gléasanna
- Sioncronú cúlra uathoibríoch le teorainn ama + teip-tapa
- Is fearr le freastalaí-taobh `NEXT_PUBLIC_BASE_URL`/`NEXT_PUBLIC_CLOUD_URL` i dtáirgeadh
### Cloudflare Tollán Tapa
- Ar fáil i** Deais → Críochphointí** le haghaidh Docker agus imscaradh féin-óstáilte eile
- Cruthaítear `https://*.trycloudflare.com` URL sealadach a chuireann ar aghaidh chuig do chríochphointe `/v1` reatha OpenAI-comhoiriúnach
- An Chéad chumas installs `cloudflared` ach amháin nuair is gá; athúsáidfidh restarts níos déanaí an dénártha bainistithe céanna
- Ní dhéantar Tolláin Mheara a athchóiriú go huathoibríoch tar éis do OmniRoute nó coimeádán a atosú; athchumasaigh iad ón deais nuair is gá
- Tollán Tá URLs gearrshaolach agus athraíonn siad gach uair a stop/start tú an tollán
- Réamhshocrú Tapa Bainistithe maidir le hiompar HTTP/2 chun rabhaidh maoláin QUIC UDP a sheachaint i gcoimeádáin srianta
- Socraigh `CLOUDFLARED_PROTOCOL=quic` nó `auto` más mian leat an rogha iompair bainistithe a shárú
- Socraigh `CLOUDFLARED_BIN` más fearr leat dénártha `cloudflared` réamhshuiteáilte a úsáid in ionad an íoslódála bainistithe
- Is féidir painéil Thapa Cloudflare, Tonnadóir Tailscale, agus ngrok Tollán a thaispeáint nó a chur i bhfolach i** Socruithe → Dealramh** . Ní stopann tollán reatha nuair a chuirtear painéal i bhfolach.
### LLM Gateway Intelligence (Céim 9)
- **Taisce Shéimeantach** — Neamhshruthú taisce uathoibríoch, freagairtí teocht = 0 (seachbhóthar le `X-OmniRoute-No-Cache: true`)
- **Neamhláithreacht Iarratas** — Déantar iarratais laistigh de 5s a dhúbláil trí cheanntásc `Idempotency-Key` nó `X-Request-Id`
- **Rianú Dul Chun Cinn** — Imeachtaí rogha an diúltaithe isteach SSE `event: progress` trí cheanntásc `X-OmniRoute-Progress: true`
---
### Clós Súgartha Aistritheoir
Rochtain trí** Aistritheoir → Deasc** . Dífhabhtaigh agus léirshamhlú conas a aistríonn OmniRoute iarratais API idir soláthraithe.
| Mód | Cuspóir |
| ------------------- | -------------------------------------------------------------------------------------------------------------- |
| **Clós Súgartha** | Roghnaigh formáidí source/target, greamaigh iarratas, agus féach ar an aschur aistrithe láithreach |
| **Tástálaí Comhrá** | Seol teachtaireachtaí comhrá beo tríd an seachfhreastalaí agus scrúdaigh an timthriall iomlán request/response |
| **Binse Tástála** | Rith baisc-thástálacha trasna comhcheangail ilfhormáide chun cruinneas an aistriúcháin a fhíorú |
| **Monatóir Beo** | Féach ar aistriúcháin fíor-ama de réir mar a shreabhann iarratais tríd an seachfhreastalaí |
**Cásanna úsáide:**
- Dífhabhtaigh cén fáth go mainneoidh teaglaim client/provider ar leith
- Fíoraigh go n-aistríonn clibeanna smaointeoireachta, glaonna uirlisí agus leideanna córais i gceart
- Déan comparáid idir na difríochtaí formáide idir formáidí OpenAI, Claude, Gemini, agus API
---
### Straitéisí Ródúcháin
Cumraigh via** Socruithe Painéal → → Ródú** . Nochtann an painéal na sé straitéis is mó a úsáidtear; Tacaíonn combos agus an ródaire uathoibríoch go hinmheánach le sraith níos leithne.
**Straitéisí atá le feiceáil ar an bpainéal (ródú ar leibhéal cuntais):**
| Straitéis | Cur síos |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| **Fill ar dtús** | Úsáideann sé cuntais in ord tosaíochta — láimhseálann an príomhchuntas gach iarratas go dtí nach mbíonn siad ar fáil |
| **Babhta Robin** | Rothaíonn sé trí gach cuntas a bhfuil teorainn ghreamaitheach inchumraithe aige (réamhshocraithe: 3 ghlao in aghaidh an chuntais) |
| **P2C (Cumhacht Dhá Rogha)** | Roghnaíonn sé 2 chuntas randamacha agus bealach chuig an gceann is sláintiúla — déantar an t-ualach a chothromú le feasacht ar shláinte |
| **randamach** | Roghnaíonn randamach cuntas do gach iarratas trí úsáid a bhaint as suaitheadh Fisher-Yates |
| **Is Lú Úsáidte** | Bealaí chuig an gcuntas leis an stampa ama `lastUsedAt` is sine, ag dáileadh an tráchta go cothrom |
| **Costas Optamaithe** | Bealaí chuig an gcuntas leis an luach tosaíochta is ísle, ag barrfheabhsú do sholáthraithe ar chostas is ísle |
**Ardstraitéisí teaglama agus uathoibríoch** (inchumraithe de réir teaglama nó trí réimíreanna `auto/*` — féach [AUTO-COMBO.md](../routing/AUTO-COMBO.md) ):
- `priority` — ordú dian, ní róbaí cruinn
- `weighted` — trácht comhréireach roinnte de réir meáchain in aghaidh an mhúnla
- `fill-first` - taosc an chéad mhúnla go dtí go mbuaileann teorainneacha
- `round-robin` / `strict-random` / `random`
- `p2c` (Cumhacht Dhá Rogha)
- `least-used` agus `cost-optimized`
- `auto` — scór-tiomáinte ar fud na n-iarrthóirí go léir
- `lkgp` (Soláthraí Dea-Aitheanta Deiridh) — bioráin don soláthraí deireanach ar éirigh leis, agus ansin tagann sé ar ais chuig na rialacha
- `context-optimized` - roghnaíonn sé an tsamhail leis an bhfuinneog comhthéacs saor in aisce is mó
- `context-relay` — slabhraí samhlacha comhthéacs fada le haghaidh casadh leantacha
#### Ceanntásc Seachtrach Seisiún Greamaitheach
Maidir le cleamhnas seisiún seachtrach (mar shampla, gníomhairí Claude Code/Codex taobh thiar de sheachvótálaithe droim ar ais), seol:
```http
X-Session-Id: your-session-key
```
Glacann OmniRoute le `x_session_id` freisin agus cuireann sé ar ais an eochair seisiúin éifeachtach i `X-OmniRoute-Session-Id`.
Má úsáideann tú Nginx agus má sheolann tú ceanntásca foscór-fhoirm, cumasaigh:
```nginx
underscores_in_headers on;
```
#### Ailiasanna Múnla saoróg
Cruthaigh patrúin saoróg chun ainmneacha samhlacha a athmhapáil:
```
Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-6
Pattern: gpt-* → Target: gh/gpt-5.3-codex
```
Tacaíonn saoróga le `*` (carachtair ar bith) agus `?` (carachtar aonair).
#### Slabhraí Fallback
Sainmhínigh slabhraí cúltaca domhanda a bhaineann le gach iarratas:
```
Chain: production-fallback
1. cc/claude-opus-4-7
2. gh/gpt-5.3-codex
3. glm/glm-4.7
```
---
### Comhcheangail Soláthraí Coitianta & Patrúin Ródú
Seo samplaí de phatrúin chun soláthraithe iolracha a chomhcheangal agus chun ródú eatarthu in OmniRoute:
#### 1. Teaglama Gníomhaire Códaithe: Réasúnaíocht Ard-Deireadh le Cost/Speed Fallback
Ideal do ghníomhairí códaithe (OpenCode, Claude Code , Cursor, Cline). Bealaí chuig samhlacha réasúnaíochta teorann ar dtús, ag titim siar go samhlacha mearchódaithe maidir le hídiú cuóta nó earráidí.
- **Deais** : Combos → Teaglama Nua → Ainm: `agent-coding` → : `Priority`
- **Múnlaí** :
1. `claude/claude-sonnet-4-6` (príomhghníomhaire códaithe)
2. `openai/gpt-4o` (tuilleamh tánaisteach ardchumais)
3. `deepseek/deepseek-v4-flash` (Aischur ardéifeachtúlachta, cost-éifeachtach)
```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. Saor-Sraith Auto Teip Teaglama
Slabhraí soláthraithe ilshraith saor in aisce agus gan eochair chun am aga fónaimh a uasmhéadú gan costais API.
- **Straitéis** : `Least Used` nó `Round Robin` (dáileann sé ualach thar chuótaí)
- **Múnlaí** :
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. Píblíne Ilmhódach / Fís & Téacs
Múnlaí físe speisialaithe a phéireáil le giniúint téacs ardluais le haghaidh sreafaí oibre a bhaineann le tuiscint íomhá agus giniúint cód.
- **Patrún** : Teaglama `Priority` a liostaíonn samhlacha fís-chumasacha ar dtús agus múnla ard-thréchuir text/code ar deireadh.
- **Múnlaí** :
1. `gemini/gemini-2.5-pro` (tuiscint láidir image/multimodal )
2. `openai/gpt-4o` (Fís Chothrom agus úsáid uirlisí)
3. `deepseek/deepseek-v4-flash` ( giniúint Text/code )
---
### Athléimneacht & Briste Cuarda
Cumraigh via** Socruithe Painéal → → Athléimneacht** .
Cuireann OmniRoute athléimneacht ar leibhéal an tsoláthraí i bhfeidhm le cúig chomhpháirt:
1. **Iarratas ar scuaine & luascadh** — Múnlú iarratais ar leibhéal an chórais:
- **Iarratais sa Nóiméad (RPM)** — Uasmhéid iarratais in aghaidh an nóiméid in aghaidh an chuntais
- **Am Íosta Idir Iarratais** — An bhearna íosta sna milleasoicindí idir iarratais
- **Iarratais Chomhthráthacha Uasta** — Uasmhéid iarratais chomhuaineacha in aghaidh an chuntais
2. **Ceangal Fuarú** — Cumraíocht in aghaidh an údaráis le haghaidh nasc aonair tar éis teipeanna in-triail:
- **Bonn Cooldown** — Fuinneog fuarú réamhshocraithe le haghaidh teipeanna in-athsholáthair in aghaidh an tsrutha
- **Úsáid Leideanna Atriail In aghaidh an tSrutha** — Onóracha `Retry-After` údarásach nó leideanna a athshocrú nuair a chuirtear ar fáil iad
- **Céimeanna Cúltaca Max** — Uasleibhéal aistarraingthe easpónantúil i gcás teipeanna arís agus arís eile
3. **Soláthraí Circuit Breaker** — Rianaíonn sé teipeanna soláthraithe ceann go ceann, marcáil soláthraí díghrádaithe ag an tairseach rabhaidh cumraithe, agus osclaíonn sé an scoradán nuair a shroichtear an tairseach teipe cumraithe:
- **Tairseach Díghrádaithe** — Teipeanna soláthraí as a chéile roimh dhul isteach `DEGRADED`
- **Tairseach Teip** — Teipeanna soláthraí as a chéile roimh dhul isteach `OPEN`
- **Athshocraigh Teorainn Ama** — Fuinneog ama sula ndéantar an soláthraí a thástáil arís
- **CLOSED** (Sláintiúil) — Sreabhann iarratais de ghnáth
- **DEGRADED** — Tá iarratais fós ar siúl agus teipeanna ardaithe á rianú
- **OPEN** — Cuirtear bac sealadach ar an soláthraí tar éis teipeanna arís agus arís eile
- **HALF_OPEN** — Tástáil an bhfuil téarnamh ag an soláthraí
Fanann teorainneacha ráta `429` nasctha le scóip nasctha i** Ceangal Fuarú** agus nach n-áirítear i dtreo an soláthróir breaker.
Taispeántar staid ama rite an bhriseora an tsoláthraí ar** Dashboard → Sláinte** amháin.
4. **Fan le haghaidh Cooldown** — Má tá gach nasc iarrthóra ag fuarú cheana féin, is féidir le OmniRoute fanacht leis an bhfionnuarú is luaithe agus an t-iarratas cliant céanna a dhéanamh arís go huathoibríoch.
5. **Uath-bhrath Teorainn Ráta** — Nuair a sheolann soláthraithe in aghaidh an tsrutha fuinneoga feithimh follasacha ar ais, sáraíonn na leideanna sin fuarú an naisc áitiúil nuair atá an socrú cumasaithe.
**Leid Pro:** Bain úsáid as an** Sláinte** leathanach chun scoradáin soláthraithe beo a iniúchadh agus a athshocrú tar éis briseadh amach. Ní athraíonn an leathanach Resilience ach cumraíocht.
---
### Easpórtáil / Iompórtáil Bunachar Sonraí
Bainistigh cúltacaí bunachar sonraí i** Socruithe Painéal → → & Stóráil** .
| Gníomh | Cur síos |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Bunachar Sonraí Easpórtála** | Íoslódáil bunachar sonraí SQLite mar chomhad `.sqlite` |
| **Easpórtáil Uile (.tar.gz)** | Íoslódálann sé cartlann chúltaca iomlán lena n-áirítear: bunachar sonraí, socruithe, teaglama, naisc soláthraithe (gan dintiúir), meiteashonraí eochair API |
| **Bunachar Sonraí Iompórtála** | Uaslódáil comhad `.sqlite` chun an bunachar sonraí reatha a athsholáthar. Cruthaítear cúltaca réamh-allmhairithe go huathoibríoch mura rud é go `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"
```
**Bailíochtú Iompórtála:** Tá an comhad iompórtáilte bailíochtaithe maidir le sláine ( seiceáil pragma SQLite ), táblaí riachtanacha (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), agus méid (uasmhéid 100MB).
**Cásanna Úsáide:**
- Imirce OmniRoute idir na meaisíní
- Cruthaigh cúltacaí seachtracha le haghaidh athshlánú tubaiste
- Comhroinn cumraíochtaí idir baill foirne (easpórtáil gach cartlann scaireanna → )
---
### Painéal na Socruithe
Eagraítear leathanach na socruithe isteach** 7 cluaisín** le haghaidh loingseoireachta éasca:
| Cluaisín | Clár ábhair |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Ginearálta** | Uirlisí stórála córais, iompar réamhshocraithe, Infheictheacht tollán Endpoint |
| **Dealramh** | Rialuithe téama (light/dark/system), infheictheacht an bharra taoibh, scoránaigh painéil le haghaidh cártaí tolláin Cloudflare/Tailscale/ngrok |
| **AI** | Buiséad smaointeoireachta (pas tríd / auto-stiall / saincheaptha / oiriúnaitheach — féach [THINKING_BUDGET.md](./THINKING_BUDGET.md) ), leid córais dhomhanda, stats taisce pras |
| **Slándáil** | socruithe Login/Password, Rialú Rochtana IP, API auth le haghaidh `/models`, Blocáil Soláthraí, garda pras-instealladh |
| **Ródú** | Straitéis ródaithe dhomhanda (Líon an Chéad Bhabhta / Babhta Robin / P2C / Randamach / Is Lú Úsáidte / Optamaithe Costas), ailiasanna samhail saoróg, slabhraí cúl-ais, mainneachtainí teaglama |
| **Athléimneacht** | Iarratas scuaine, fuarú nasc, cumraíocht an soláthróir breaker, agus fanacht-le-fuarú iompar |
| **Casta** | Sáraíonn cumraíocht seachfhreastalaí dhomhanda (HTTP/SOCKS5), seachfhreastalaí in aghaidh an tsoláthraí |
Ní dhúblaíonn Ginearálta logáil inléite amháin agus nótaí taisce a thuilleadh. Leantar le socruithe coinneála agus barrfheabhsú bunachar sonraí trí `/api/settings/database`; Úsáideann imréitigh taisce láimhe `DELETE /api/cache`. Is iad `CALL_LOGS_TABLE_MAX_ROWS` agus `PROXY_LOGS_TABLE_MAX_ROWS` a rialaíonn caipíní ró loga iarratais agus seachfhreastalaí.
---
### Costais & Bainistiú Buiséid
Rochtain trí** Costais Painéal → nIonstraimí** .
| Cluaisín | Cuspóir |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| **Buiséad** | Socraigh teorainneacha caiteachais in aghaidh an eochair API le buiséid daily/weekly/monthly agus rianú fíor-ama |
| **Praghsáil** | Féach ar agus cuir in eagar iontrálacha praghsála samhail — costas in aghaidh 1K input/output comharthaí in aghaidh an tsoláthraí |
```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
```
**Rianú Costas:** Déanann gach iarratas logáil ar úsáid chomharthaí agus ríomhtar costas ag baint úsáide as an tábla praghsála. Féach ar mhiondealuithe i** Úsáid Painéal na →** de réir soláthraí, múnla, agus eochair API.
---
### Trascríobh Fuaime
tacaíonn OmniRoute le trascríobh fuaime tríd an gcríochphointe atá comhoiriúnach le 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"
```
Is é `deepgram/nova-3` an bealach Deepgram dúchais agus tá eochair Deepgram API ag teastáil uaidh. Mura bhfuil ach OpenRouter cumraithe, úsáid `openrouter/deepgram/nova-3`.
**Óráid go Téacs (trascríobh)** soláthraithe:
- `openai/` (comhoiriúnach)
- `groq/` (Groq Whisper Turbo)
- `deepgram/` (teaghlach Nova)
- `assemblyai/`
- `nvidia/` (Parakeet, Canárach)
- `huggingface/` (leagan cogarna)
- `qwen/`
**Téacs-go-Caint (`POST /v1/audio/speech`)** soláthraithe:
- `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/`
Formáidí fuaime le tacaíocht le haghaidh trascríobh: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. Braitheann formáidí aschuir TTS ar an soláthraí (mp3, wav, opus, pcm, mulaw).
---
### Straitéisí Comhardaithe Teaglama
Cumraigh in aghaidh na teaglama cothromú i** Painéal na nIonstraimí → combos → Create/Edit →** .
| Straitéis | Cur síos |
| --------------------- | --------------------------------------------------------------------------------------------- |
| **Babhta-Robin** | Rothlaíonn sé trí mhúnlaí go seicheamhach |
| **Tosaíocht** | Déanann sé iarracht an chéad mhúnla i gcónaí; thiteann ar ais ach amháin trí earráid |
| **randamach** | Roghnaíonn sé samhail randamach as an teaglama do gach iarratas |
| **ualaithe** | Bealaí bunaithe go comhréireach ar mheáchan sannta in aghaidh na samhla |
| **Is Lú-Úsáidte** | Bealaí chuig an tsamhail leis an líon is lú iarratas le déanaí (úsáidtear méadracht teaglama) |
| **Costas-Optamaithe** | Bealaí chuig an tsamhail is saoire atá ar fáil (úsáidí tábla praghsála) |
Is féidir mainneachtainí teaglama domhanda a shocrú isteach** Socruithe Deais → → Routing → Teaglama Réamhshocruithe** . Faightear teorainn ama an iarratais reatha mar oidhreacht réamhshocraithe. Úsáid** Sprioc-am istigh (soicindí)** maidir le mainneachtainí teaglama nó teaglama aonair ach amháin nuair ba cheart go spreagfadh teorainn in aghaidh an sprice níos giorra cúlú níos tapúla.
Is rogha an diúltaithe iad optamaithe teaglama nialais-latency. Fág** Optimizations nialais-latency** díchumasaithe chun na gnéithe latency seo a chosc ó spriocanna aisghabhála rásaíochta, gan bacadh le spriocanna bunaithe ar stair TTFT, nó iarratais chúltaca a chomhbhrú; ag cur ar a chumas fálaithe cumraithe, scipeanna tuarthacha TTFT, agus comhbhrú réamhghníomhach aisiompaithe chun dílseacht routing/request a thrádáil le haghaidh latency eireaball níos ísle.
Díchumasaigh** Maolán comharthaí réasúnaíochta** nuair a éilíonn soláthraithe in aghaidh an tsrutha teorainneacha dochta `max_tokens` / `maxOutputTokens`. Nuair a bhíonn sé cumasaithe, ní chuireann ródú teaglama ach spás cúltaca réasúnaíochta do mhúnlaí a bhfuil caipín aschuir aitheanta acu agus fágann sé teorainn chomharthaí an chliaint gan athrú nuair a sháródh an luach maolánach sábháilte an teorainn sin. Má tá teorainn na gcliant os cionn na caidhpe atá ar eolas cheana féin, teannann OmniRoute síos go dtí an caipín sin é sula seoltar an t-iarratas in aghaidh an tsrutha.
---
### Painéal na Sláinte
Rochtain trí** Dashboard → Sláinte** . Forbhreathnú ar shláinte an chórais fíor-ama le 6 chárta:
| Cárta | Cad a thaispeánann sé |
| -------------------------- | -------------------------------------------------------------------- |
| **Stádas an Chórais** | Aga fónaimh, leagan, úsáid chuimhne, eolaire sonraí |
| **Sláinte Soláthraí** | Staid rite briseora ciorcaid soláthraí domhanda |
| **Teorainneacha Ráta** | Fuarú naisc ghníomhacha in aghaidh an chuntais leis an am atá fágtha |
| **Frithdhúnadh Gníomhach** | Frithdhúnadh gníomhach le scóip samhail agus eisiaimh shealadacha |
| **Taisce Síniú** | Staitisticí taisce dídhúbailt (eochracha gníomhacha, ráta buailte) |
| **Teiliméadracht Latency** | p50/p95/p99 comhiomlánú latency in aghaidh an tsoláthraí |
**Leid Pro:** Athnuachann an leathanach Sláinte go huathoibríoch gach 10 soicind. Úsáid an cárta scoradáin chiorcaid chun na soláthraithe a bhfuil fadhbanna acu a shainaithint.
---
## 🤑 Auto-Routing (Zero-config)
Seolann OmniRoute le **routálaí uathoibríoch scóráilte** a roghnaíonn an tsamhail is fearr do gach iarratas ar gach soláthraí ceangailte — gan aon combo a choimeád. Níl le déanamh ach an t-iarratas a sheoladh le ceann de na réamhshocruithe `auto/*` agus cuirfidh OmniRoute combo fíorúil le chéile ar an toirt, ag scóráil iarrthóirí ar moill, costas, ráta ratha, oiriúnacht comhthéacs, oiriúnacht samhail don tasc, teipeanna le déanaí, quota, agus stáid briseadh circuit.
| Réamhshocrú | Optamaíonn do |
| -------------- | --------------------------------------------------------------------------------------------------------------- |
| `auto` | Réamhshocrú cothrom (moill × costas × ráta ratha) |
| `auto/coding` | Tascanna ríomhchláraithe: roghnaíonn Claude, GPT-5, GLM, Kimi, Qwen Coder, DeepSeek coders |
| `auto/cheap` | Íseal $/token, glacadh le moill níos airde |
| `auto/fast` | Íseal moill, neamhshuim ar costas |
| `auto/offline` | Soláthraíte amháin áitiúil (Ollama, vLLM, llama.cpp) — úsáideach do shocrúcháin aer-ghlanta |
| `auto/smart` | Cáilíocht reasonála ar dtús (Opus, GPT-5 xhigh, R1, GLM 5.1 reasoning) |
| `auto/lkgp` | "Soláthraí Dea-Shannta Deireanach" — pionnáil leis an soláthraí rathúil deireanach, ansin tuilleadh ar rialacha |
Sampla:
```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
}'
```
Tá an t-uath-routálaí cur síos iomlán air i [AUTO-COMBO.md](../routing/AUTO-COMBO.md) — lena n-áirítear conas meáchain scórála a choigeartú, soláthraíte a thoirmeasc, agus cinntí routála a scrúdú i **Painéal → Auto Combo**.
---
## 🔌 Comhtháthú MCP & A2A
Is **freastalaí MCP** (Model Context Protocol) agus **freastalaí A2A** (Agent-to-Agent JSON-RPC 2.0) é OmniRoute araon. Is féidir le haon IDE nó óstach gníomhaíochta atá comhoiriúnach le MCP uirlisí OmniRoute a ghairm go díreach — gan aon choró sa bhreis ag teastáil.
### Aistrithe MCP
- **SSE**: `http://localhost:20128/api/mcp/sse`
- **HTTP In-shreafa**: `http://localhost:20128/api/mcp/stream`
- **stdio**: `omniroute --mcp` (do phlocáin IDE a roghnaíonn stdio)
### Ceangal le Claude Desktop
Cuir `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) nó an comhionann ar Windows/Linux in eagar:
```json
{
"mcpServers": {
"omniroute": {
"command": "omniroute",
"args": ["--mcp"]
}
}
}
```
### Ceangal le Cursor / Continue / VS Code MCP
Úsáid an URL SSE `http://localhost:20128/api/mcp/sse` agus eochair API Bearer a ghintear i **Painéal → Eochracha API**.
### Scóip
Sainmhíníonn MCP faoi láthair 32 scóip ainmnithe. Is féidir gach eochair Bearer a theorannú do scóip shonracha — féach [MCP-SERVER.md](../frameworks/MCP-SERVER.md) le haghaidh an iontrála údarásach scóip agus uirlisí agus [A2A-SERVER.md](../frameworks/A2A-SERVER.md) le haghaidh an scéim JSON-RPC.
---
## � Áiseanna Scileanna
Taispeánann OmniRoute **chreat scileanna in-infhiarmaithe** (`src/lib/skills/`) ionas go bhféadfaidh gníomhairí agus an críochfoirm A2A rithinne ábharshuímh (m.sh. `code-review`, `summarize`, `extract-facts`, `web-research`).
- **Comhéadan Margaidh** — Brabhsáil agus suiteáil scileanna ó **Dashboard → Skills**
- **Scóipeanna in aghaidh an eochracha** — Cuir teorainn le cén eochracha API a fhéadfaidh scileanna áirithe a thionscnamh
- **Scileanna saincheaptha** - Cuir comhad TypeScript i bhfilléan `src/lib/a2a/skills/`, cláraigh é, agus beidh sé ar fáil láithreach tríd an A2A
Lámhleabhar iomlán: [SKILLS.md](../frameworks/SKILLS.md).
---
## 💾 Córas Cuimhne
Coinníonn OmniRoute **cuimhne comhrá fadtéarmach** le tarrtháil hibrideach:
- **SQLite FTS5** le haghaidh cuardach focailbhoinne thar thréitheanna roimhe seo
- **Stóras veicteora Qdrant** (roghnach) le haghaidh cuimhneachtáil chiallmhara
- **Fáil amach fíricí go huathoibríoch** — Ainmneacha, roghanna, agus cinntí achoimeartar tar éis gach seisiún agus stóráiltear iad sa tábla `memory_facts`
- Tá cuimhneanna scóipithe in aghaidh an eochracha API agus in aghaidh an seisiúin
Bainistigh cuimhneanna i **Dashboard → Memory** (cuardach, eagar, easpórtáil, glan). Ligeann an dromchla HTTP (`/api/memory/*`) do ghníomhairí fíricí a bhrú agus a chuardach go clárlann — féach [MEMORY.md](../frameworks/MEMORY.md).
---
## 🔔 Webhooks
Liostáil le haghaidh teagmhais OmniRoute le haghaidh monatóireachta agus uathoibriú fíor-ama.
- Cruthaigh webhook i **Dashboard → Webhooks** le sprioc URL agus rún sínithe HMAC
- Teagmhais ar fáil: `request.completed`, `request.failed`, `provider.unavailable`, `budget.exceeded`, `combo.switched`, `circuit_breaker.opened`, `circuit_breaker.closed`
- Gach pacáiste sonraí cuireann `X-OmniRoute-Signature` (HMAC-SHA256) ar fáil le haghaidh fíorúcháin
- Atreiseanna: 3 iarracht le meitreach drochchúl, ansin scuabadh litreacha marbh
Scéimre iomlán i [WEBHOOKS.md](../frameworks/WEBHOOKS.md).
---
## ☁️ Gníomhairí Scáileáin
Comhtháthaíonn OmniRoute le gníomhairí códála scáileáin (**OpenAI Codex Cloud**, **Devin**, **Jules**, **Antigravity**) ionas gur féidir leat tascanna fadthéarmacha a sheoladh ón an chéanna dashboard a bhainistíonn do ródú áitiúil.
- Cruthaigh tascanna i **Dashboard → Cloud Agents** nó trí `POST /api/v1/agents/tasks`
- Rianaigh stádas, logaanna, agus airtealaí in aghaidh an tasc
- Eochracha API féin-iompairtha in aghaidh an soláthraí — ní fhágann ainmneacha teagmhasa instanciú OmniRoute choíche
Lámhleabhar iomlán: [CLOUD_AGENT.md](../frameworks/CLOUD_AGENT.md).
---
## 🛠️ Bainisteoireacht Clárlann
Is féidir leat gach acmhainn OmniRoute (soláthraithe, tiompáin, eochracha, socruithe) a bhainistiú thar HTTP ag baint úsáide as **eochair bearer leis an scóip `manage`**.
Gineadh an eochair i **Dashboard → API Keys → New Key → Scope: manage**, ansin:
```bash
# Liostaigh soláthraithe
curl http://localhost:20128/api/providers \
-H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY"
# Cuir nasc soláthraí leis
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" }'
# Cruthaigh tiompán
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" }] }'
# Liostáil/cruthaigh eochracha 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"] }'
```
Féach [API_REFERENCE.md](../reference/API_REFERENCE.md) le haghaidh an catalóg críochfoirm iomlán agus scéimeanna iarratas/freagra.
## 💧 CLI Inmheánach
Seolann OmniRoute CLI inmheánach (`omniroute …') le haghaidh socraithe, diagnóise agus rialaithe rith. Tá seo **leithleasc ón leathanach "Uirlisí CLI" sa deasc**, a chumraítear le haghaidh CLI tríú páirtí (Claude Code, Cursor, Codex, Cline, …) ionas gur féidir leo labhairt le OmniRoute.
```bash
omniroute setup # Treoraí idirghníomhach (pasfhocal, soláthraithe, combos)
omniroute setup --non-interactive # Oiriúnach do CI
omniroute doctor # Diagnóis sláinte (eolaire sonraí, DB, soláthraithe, poirt)
omniroute providers available # Liostáil soláthraithe tacaíochta
omniroute providers list # Liostáil naisc chumraithe
omniroute providers test # Tástáil beo ar nasc soláthraí
omniroute combos list # Liostáil combos
omniroute combos switch # Socraigh combo réamhshocraithe
omniroute models # Liostáil samhlacha ar fáil (--json, --search)
omniroute keys add | list | remove # Bainistigh eochracha API ón tteirminéal
omniroute backup # Grianghraf cumraíocht + DB
omniroute restore [] # Athchóirigh ó ghrianghraf
omniroute health # Sláinte mionsonraithe (briseoirí, taisce, cuimhne)
omniroute quota # Úsáid cuóta soláthraí
omniroute mcp status # Stádas freastalaí MCP
omniroute a2a status # Stádas freastalaí A2A
omniroute tunnel list|create|stop # Toilí Cloudflare/Tailscale/ngrok
omniroute reset-password # Athshocraigh pasfhocal an riaracháin
omniroute --mcp # Tosaigh freastalaí MCP thar stdio
omniroute --port 3000 # Tosaigh an freastalaí ar phort saincheaptha
```
Leid: páirigh `omniroute doctor --json` le d'fheirm monatóireachta chun a chur ar bun le haghaidh naisc soláthraí neamhshláintiúil.
---
## 💻 Feidhmchlár Deisce (Electron)
Tá OmniRoute ar fáil mar fheidhmchlár deisce dúchasach le haghaidh Windows, macOS, agus Linux.
### Suiteáil
```bash
# Ón eolaire electron:
cd electron
npm install
# Mód forbartha (ceangail le freastalaí forbartha Next.js ag rith):
npm run dev
# Mód táirgíochta (úsáideann tógáil neamhspleách):
npm start
```
### Tógáil Suiteálaithe
```bash
cd electron
npm run build # Ardán reatha
npm run build:win # Windows (.exe NSIS)
npm run build:mac # macOS (.dmg uilíoch)
npm run build:linux # Linux (.AppImage)
```
Aschur → `electron/dist-electron/`
### Príomhghnéithe
| Gné | Cur Síos |
| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| **Ullmhacht Freastalaí** | Polallú roimh an fhuinneog a thaispeáint (gan scáileán folamh) |
| **Trá idir na fóin** # Íoslaghdigh go dtí an trá, athraigh port, scoir ó roghchlár trá |
| **Bainistíocht Poirt** | Athraigh port an fhreastalaí ón trá (aththosaíonn sé an freastalaí go huathoibríoch) |
| **Beartas Slándála Ábhair** | CSP teann trí cheannteidil seisiún |
| **Inneamh Aonair** | Ní fhéadann ach aon instainc amháin den fheidhmchlár rith ag an am céanna |
| **Mód Aslíne** | Oibríonn freastalaí Next.js páisteáilte gan idirlíon |
### Athróganna Timpeallachta
| Athróg | Réamhshocrú | Cur Síos |
| --------------------- | ----------- | -------------------------------------- |
| `OMNIROUTE_PORT` | `20128` | Port an fhreastalaí |
| `OMNIROUTE_MEMORY_MB` | `512` | Teorainn cuimhne Node.js (64–16384 MB) |
📖 Doiciméadú iomlán: [`electron/README.md`](../../electron/README.md)