# 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 de réir 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 [Soláthraithe a iompórtáil ó 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 OAuth → Athnuachan uathoibríoch comhartha
→ Rianú cuóta 5 huaire + seachtainiúil
Samhlacha:
cc/claude-opus-4-7
cc/claude-sonnet-4-6
cc/claude-haiku-4-5-20251001
```
**Leid Ghairmiúil:** Úsáid Opus le haghaidh tascanna casta, agus Sonnet le haghaidh luais. Rianaíonn OmniRoute an cuóta de réir samhla!
Nach bhfuil brabhsálaí ar óstach OmniRoute? Rith `claude setup-token` áit ar bith a bhfuil Claude Code logáilte isteach agus greamaigh an comhartha bliana 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 shamhlacha Opus agus Sonnet.
Ní ghlacann samhlacha 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 OAuth (port 1455)
→ Athshocrú 5 huaire + seachtainiúil
Samhlacha:
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 (1ú lá den mhí)
Samhlacha:
gh/gpt-5.5
gh/gpt-5.4
gh/claude-sonnet-4.6
gh/claude-opus-4.7
gh/gemini-3.1-pro-preview
```
### 💰 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 ó Coding Plan
3. Deais → Cuir Eochair API Leis: Soláthraí: `glm`, Eochair API: `your-key`
**Úsáid:** `glm/glm-4.7` — **Leid Ghairmiúil:** Cuireann Coding Plan 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, $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 Ghairmiúil:** An rogha is saoire do chomhthéacs fada (1M comhartha)!
#### Kimi K2 ($9/mí ar ráta seasta)
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 Ghairmiúil:** $9/mí seasta ar 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ó ID samhla eile Qianfan atá comhoiriúnach le OpenAI.
### 🆓 Soláthraithe SAOR IN AISCE
Tá lasc taobh le **Ní theastaíonn fíordheimhniú** ag soláthraithe saor in aisce nach dteastaíonn fíordheimhniú uathu ar leathanach a soláthraí.
Má mhúchtar é, díchumasaítear an soláthraí sin, baintear é de na hamhairc chumraithe/dhlútha Soláthraithe, agus
baintear a shamhlacha ó `/v1/models`.
#### Qoder (9 samhail SAOR IN AISCE)
```bash
Deais → Ceangail Qoder → Logáil isteach OAuth → Tá rochtain faoi réir theorainneacha reatha an tsoláthraí
Samhlacha: 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 creidiúint/mí
Samhlacha: 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
### npm suiteáil domhain (Molta)
```bash
npm install -g omniroute
# Cruthaigh eolaire cumraíochta
mkdir -p ~/.omniroute
# Cruthaigh comhad .env (féach .env.example)
cp .env.example ~/.omniroute/.env
# Tosaigh an freastalaí
omniroute
# Nó le port saincheaptha:
omniroute --port 3000
```
Lódann an CLI `.env` go huathoibríoch ó `~/.omniroute/.env` nó `./.env`.
### Mód trá
Tosaigh OmniRoute sa tray córais:
```bash
omniroute serve --tray
```
Filleann an t-ordú tar éis don fhreastalaí agus don tray a bheith réidh.
Leanann an freastalaí ar aghaidh gan an teirminéal.
Tacaíonn an mód tray le macOS, Windows, agus seisiúin Linux grafaiciúla. Ní oscailtear an deais go huathoibríoch i mód tray.
Bain úsáid as an roghchlár tray le haghaidh na ngníomhartha seo:
- Oscail an deais.
- Oscail `/dashboard/logs`.
- Athraigh tosú uathoibríoch.
- Stop OmniRoute.
Ná cuir `--tray` leis na roghanna seo:
- `--daemon`
- `--log`
- `--no-recovery`
Tá na modhanna seo ag teastáil ó sheilbh éagsúla próiseálaí.
Cumas tosú ag an chéad logáil isteach ar an meaisín eile:
```bash
omniroute autostart enable
```
Úsáideann an tosú uathoibríoch mód tray ar macOS, Windows, agus seisiúin Linux grafaiciúla. Úsáideann Linux ceanntaisc an tseirbhís úsáideora systemd atá ann cheana féin.
Díchumasigh tosú ag logáil isteach:
```bash
omniroute autostart disable
```
### Díshuiteáil
Nuair nach bhfuil OmniRoute de dhíth ort a thuilleadh, cuirimid dhá script tapa ar fáil le haghaidh baint ghlan:
| Ordú | Gníomh |
| ------------------------ | --------------------------------------------------------------------------------------------------- |
| `npm run uninstall` | Baineann an app córais ach **coinníonn sé do bhunachar sonraí agus cumraíochtaí** i `~/.omniroute`. |
| `npm run uninstall:full` | Baineann an app AGUS scriostar go buan **gach cumraíocht, eochracha, agus bunachar sonraí**. |
> Nóta: Le haghaidh na n-orduithe seo, téigh go dtí an fillteán tionscadail OmniRoute (más ghearraigh tú é) agus rith iad. Ar an mbealach eile, má tá sé suiteáilte go domhain, is féidir leat `npm uninstall -g omniroute` a rith go simplí.
### Imscaradh VPS
```bash
git clone https://github.com/diegosouzapw/OmniRoute.git
cd OmniRoute && npm install && npm run build
export JWT_SECRET="your-secure-secret-change-this"
export INITIAL_PASSWORD="your-password"
export DATA_DIR="/var/lib/omniroute"
export PORT="20128"
export HOSTNAME="0.0.0.0"
export NODE_ENV="production"
export NEXT_PUBLIC_BASE_URL="http://localhost:20128"
export API_KEY_SECRET="endpoint-proxy-api-key-secret"
npm run start
# Nó: pm2 start npm --name omniroute -- start
```
### Imscaradh PM2 (Cuimhne Íseal)
Do fhreastalaithe le RAM teoranta, bain úsáid as an rogha teorainn cuimhne:
```bash
# Le teorainn 512MB (réamhshocrú)
pm2 start npm --name omniroute -- start
# Nó le teorainn cuimhne saincheaptha
OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start
# Nó ag úsáid 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
# Tóg íomhá (réamhshocrú = runner-cli le codex/claude/droid suiteáilte roimh ré)
docker build -t omniroute:cli .
# Mód iniompartha (molta)
docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli
```
Le haghaidh mód comhtháthaithe óstach le binréidh CLI, féach an rannán Docker sa phríomhcháipéisíocht.
### Void Linux (xbps-src)
Is féidir le húsáideoirí Void Linux OmniRoute a phacáistiú agus a shuiteáil go dúchasach ag baint úsáide as an chreat traschomhshóite `xbps-src`. Léiríonn sé seo an t-ábhar stand-alone Node.js in éineacht le ceangail dhúchasacha `better-sqlite3" atá de dhíth.
Féach samhail xbps-src
```bash
# Comhad samhail le haghaidh '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() {
# DéanCumh anailís ar cuspóir CPU le haghaidh 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) Suiteáil gach spleáchadh – scipeáil scripteanna
NODE_ENV=development npm ci --ignore-scripts
# 2) Tóg an bunchlár Next.js stand-alone
npm run build
# 3) Cóipeáil sócmhainní statacha isteach sa stand-alone
cp -r .next/static .next/standalone/.next/static
[ -d public ] && cp -r public .next/standalone/public || true
# 4) Tiomsaigh ceangal dúchasach better-sqlite3
local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
(cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
# 5) Cuir an ceangal tiomsaithe sa bhundíol stand-alone
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) Bain pacáistí sharp ar aon chuspóir
rm -rf .next/steamline/node_modules/@img
# 7) Cóipeáil spleáchanna rithime pino nach bhfuil san anailís statach Next.js:
for _mod in pino-abstract-transport split2 process-warning; do
cp -r "node_modules/$_mod" .next/standalone/node_modules/
done
}
do_check() {
npm run test:unit
}
do_install() {
vmkdir usr/lib/omniroute/.next
vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
# Cosc ar bhaint folaíteacha eolaire rautaire app Next.js ag an hook post-suiteáil
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 Timpeallachta
| Athróg | Réamhshocrú | Cur Síos |
| --------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `JWT_SECRET` | `omniroute-default-secret-change-me` | Rúndacht síniú JWT (**athrú i bhforbairt**) |
| `INITIAL_PASSWORD` | `CHANGEME` | Pasfhocal logála isteach den chéad uair |
| `DATA_DIR` | `~/.omniroute` | Eolaire sonraí (bunachar sonraí, úsáid, logaí) |
| `PORT` | réamhshocrú fréamhchórais | Port seirbhíse (`20128` san fholláin |
| `HOSTNAME` | réamhshocrú fréamhchórais | Ceangal óstach (réamhshocrú Docker `0.0.0.0`) |
| `NODE_ENV` | réamhshocrú rithime | Socraigh `production` le haghaidh imscartha |
| `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128` | URL bonn poiblí a thaispeántar don deais agus a nochtar don fhreastalaí (athraíonn `BASE_URL` seanmhod) |
| `NEXT_PUBLIC_CLOUD_URL` | `https://omniroute.dev` | URL bonn críochphointe sioncronú scamall (athraíonn `CLOUD_URL` seanmhod) |
| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | Rúndacht HMAC le haghaidh eochracha API ginte |
| `REQUIRE_API_KEY` | `false` | Éileamh eochair API Bearer ar `/v1/*` |
| `ALLOW_API_KEY_REVEAL` | `false` | Ceadaigh d'úsáideoirí deise deimhnithe na luachanna iomlán eochair API stóráilte a nochtadh ar éileamh |
| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Rith tuisceana freastalaí le haghaidh sonraí Teorainneacha Soláthraí stóráilte; cuirfidh cnaipí athnuachana an deais fós sioncronú láimhe ar siúl |
| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Díchumasigh ceapacha SQLite uathoibríoch roimh scríbh/Iompórtáil/athchóiriú; oibríonn cóipeanna cúltaca láimhe fós |
| `APP_LOG_TO_FILE` | `true` | Cumasaigh aschur logaí iarratais agus iniúchta ar diosca |
| `AUTH_COOKIE_SECURE` | `false` | Fórsaigh fíorordú `Secure` (taobh thiar de seirbhíse frithbheochana HTTPS) |
| `CLOUDFLARED_BIN` | gan socraigh | Úsáid bineár `cloudflared` atá ann cheana in ionad íoslódáil bhainistithe |
| `CLOUDFLARED_PROTOCOL` | `http2` | Iompar le haghaidh Tunnealla Tapa Bainistithe (`http2`, `quic`, nó `auto`) |
| `OMNIROUTE_MEMORY_MB` | `512` | Teorainn cuimhne Node.js i MB |
| `PROMPT_CACHE_MAX_SIZE` | `50` | Méid uasta iontrálacha taisce luaslaíochta |
| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Méid uasta iontrálacha taisce séimeantacha |
Le haghaidh an tagarmharc iomlán athróga timpeallachta, féach an [README](../README.md).
---
## 📊 Samhlacha ar Fáil
Féach ar gach samhail ar fáil
> Tá an liosta thíos curtha le chéile ó `open-sse/config/providerRegistry.ts` le haghaidh v3.8.0. Sioncronaítear catalóga scamall (Gemini, OpenRouter, etc.) go dinimiciúil — chun an catalóg beo iomlán a oscailt, téigh go **Dashboard → Providers → [provider] → Available Models** nó glac `GET /api/models/catalog`.
>
> Má bhí an liosta ionsuite de sholáthraí áirithe imithe as alt, úsáid **Import from /models** ar an leathanach sin (nó cumasaigh **Auto-Sync**) chun an catalóg upstream beo a tharraingt. Rinneadh é seo a fhíorú i v3.8.50 le haghaidh LLM7.io (`gemini-3.1-flash-lite`) agus UncloseAI (`solidrust/Hermes-3-Llama-3.1-8B-AWQ`) — bhí rochtain anaithnid Pollinasions fós teoranta ag upstream le linn an tástála chéanna.
**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` (+ leibhéil 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/`)** — SAOR IN AISCE OAuth: úsáid an catalóg beo a thaispeántar faoi **Dashboard → Providers → Kiro → Available Models**. Bíonn an infhaighteacht ag brath ar an gcuntas agus an plean.
**Qoder (`if/`)** — SAOR IN AISCE 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/míosa síos nó in aghaidh an úsáide: `kimi/kimi-k2.6`, `kimi/kimi-k2.5`
**DeepSeek (`ds/`)** — Eochair API: `ds/deepseek-v4-pro`, `ds/deepseek-v4-flash`
**Groq (`groq/`)** — Ultra-tapa: `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áil san AE: `mistral/mistral-large-latest`, `mistral/mistral-medium-3-5`, `mistral/mistral-small-latest`, `mistral/devstral-latest`, `mistral/codestral-latest`
**Perplexity (`pplx/`)** — curtha le cuardach: `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/`)** — inferences 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/`)** - scála vafeaire: `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/`)** — gnó: `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/`)**: Sioncronaithe beo in aghaidh na heochrach API ó Google — gan liosta statach. Ceangail eochair i **Dashboard → Providers** ansin úsáid **Available Models** chun an catalóg reatha a iompórtáil (m.sh. `gemini/gemini-3-pro`, `gemini/gemini-3-flash`).
**Soláthraithe comhoiriúnacha eile** (roghnaithe): `cohere`, `databricks`, `snowflake`, `together`, `vertex`, `alibaba`, `alibaba-cn`, `bedrock` (tríd an `aws-bedrock`), `azure-ai`, `openrouter` (catalóg pas-tríd), `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 samhlacha féin i `providerRegistry.ts` agus is féidir é a shioncronú go huathoibríoch nuair a nochtlann an soláthraí pointe deiridh `/models`.
**Nóta ar aitheantais samhlacha:** Úsáideann OmniRoute aitheantais nádúrtha soláthraí (`claude-opus-4-8`, `gpt-5.5`, `glm-5.1`, `MiniMax-M2.7`, `kimi-k2.5`, `grok-4.20-0309-reasoning`). Tá leaganacha ponctuála i roinnt aitheantais toisc go dteastaíonn siad mar sin ón API upstream. Mura bhfuil samhail ar an liosta thuas, rith `omniroute models --search ` nó glac `GET /api/models/catalog` chun infhaighteacht a dheimhniú.
---
## 🧩 Ardghnéithe
### Samhlacha Saincheaptha
Cuir aon ID samhla le haon soláthraí gan fanacht le nuashonrú ar an aip:
```bash
# Tríd an 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"}'
# Liosta: curl http://localhost:20128/api/provider-models?provider=openai
# Bain: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-5.2"
```
Nó úsáid an Painéal: **Soláthraithe → [Soláthraí] → Samhlacha Saincheaptha**.
Nótaí:
- Déantar soláthraithe OpenRouter agus soláthraithe atá comhoiriúnach le OpenAI/Anthropic a bhainistiú ó **Samhlacha atá ar Fáil** amháin. Cuirtear samhlacha a chuirtear leis de láimh, a iompórtáiltear nó a shioncronaítear go huathoibríoch ar an liosta céanna de shamhlacha atá ar fáil, mar sin níl rannán ar leith Samhlacha Saincheaptha ann do na soláthraithe sin.
- Tá an rannán **Samhlacha Saincheaptha** beartaithe do sholáthraithe nach gcuireann iompórtálacha bainistithe de shamhlacha atá ar fáil ar fáil.
### Soláthraithe Saincheaptha atá Comhoiriúnach le OpenAI
Is féidir aon gheata a úsáideann API OpenAI (seachfhreastalaí féinóstáilte, vLLM, comhbhailitheoir tríú páirtí)
a chur leis mar nód soláthraí dá chuid féin:
1. **Soláthraithe → Cuir Soláthraí Comhoiriúnach le OpenAI Leis**.
2. **Ainm**: lipéad taispeána don nód.
3. **Réimír**: an t-ainm ródúcháin. Glaonn cliaint ar shamhlacha mar `/`, mar sin freastalaíonn nód leis an
réimír `mygw` ar `mygw/gpt-4o-mini`. Riachtanach; níl aon srian ar charachtair.
4. **Cineál API**: an teaghlach críochphointí a bhfreastalaíonn an geata air (Comhlánuithe Comhrá, Freagraí,
Leabuithe, fuaim, íomhánna).
5. **Bun-URL**: fréamh an API, suas go dtí `/v1` agus é sin san áireamh (mar shampla
`https://gateway.example.com/v1`), seachas an chonair iomlán `/chat/completions`. Socraíonn geataí a bhfuil
conairí neamhchaighdeánacha acu iad faoi **Ardsocruithe** (conair chomhrá, conair samhlacha).
6. Ní dhéanann an réimse **Eochair API (le Seiceáil)** ach an nasc a thástáil. Tar éis duit an nód a chruthú,
oscail é agus úsáid **Cuir Nasc Leis** chun an eochair a úsáidfidh iarratais a stóráil.
Faigheann an nód ID inmheánach den fhoirm `openai-compatible--`; ní gá duit é a
chlóscríobh choíche, mar is í an réimír an t-ainm poiblí.
#### Réimíreanna forchoimeádta
Ní féidir le réimír a bheith mar ID ná mar ailias de sholáthraí ionsuite (mar shampla `openai`, `cf`), ná
mar ID de sholáthraí scortha. Seiceálann réiteoir na samhlacha IDanna agus ailiasanna ionsuite roimh
nóid shaincheaptha, mar sin ní bhfaigheadh nód a úsáideann ceann de na réimíreanna sin trácht choíche:
rachadh `/model` chuig an soláthraí ionsuite ina ionad sin, nó theipfeadh sé go dúnta dá mbeadh an soláthraí sin
scortha. Diúltaítear do chruthú nó d'eagarthóireacht nóid lena leithéid de réimír leis seo:
```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 chuig 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óid
forchoimeádta: tá nóid a sábháladh sula raibh an riail seo ann fós stóráilte, ach ródálann a réimír chuig
an soláthraí ionsuite. Cuir an nód in eagar agus tabhair réimír nua dó.
### Piaraí OmniRoute a Shlabhrú
Is féidir geata OmniRoute eile a chur leis mar sholáthraí **Saincheaptha atá comhoiriúnach le OpenAI**. Úsáid
bun-URL `/v1` an phiara agus eochair API thiomnaithe leis na pribhléidí is lú, arna heisiúint ag an bpiara sin.
I gcás slabhraí cómhalartacha nó ilchéime, cumasaigh an chosaint roghnach ar lúba 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 URL piara atá ar an liosta ceada go sainráite an ceanntásc
`X-OmniRoute-Peer-Trace`. Diúltaíonn geata d'ID ásc a tharla arís nó do bhuiséad léimeanna atá ídithe
le HTTP `508 Loop Detected`; ní fhaigheann gnáthsholáthraithe réamhtheachtacha aon mheiteashonraí piara.
Ní macasamhlú bunachair sonraí ná teipaistriú óstaigh é slabhriú piaraí. Coinníonn gach geata a staid
SQLite, a thaiscí, a áiritheoirí ráta agus a sheisiúin féin. Úsáid seachfhreastalaí droim ar ais le seiceálacha sláinte nó
teipaistriú cliaint le haghaidh infhaighteachta gníomhaí/éighníomhaí nó gníomhaí/gníomhaí, agus ná gléas aon bhunachar sonraí SQLite amháin
riamh i roinnt ásc OmniRoute atá ag rith.
### Bealaí Tiomnaithe Soláthraí
Ródáil iarratais 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 réimír an tsoláthraí leis go huathoibríoch má tá sí ar iarraidh. Tugann samhlacha nach bhfuil ag teacht le chéile `400` ar ais.
### Cumraíocht Seachfhreastalaí Líonra
```bash
# Socraigh an seachfhreastalaí domhanda
curl -X PUT http://localhost:20128/api/settings/proxy \
-d '{"global": {"type":"http","host":"proxy.example.com","port":"8080"}}'
# Seachfhreastalaí de réir soláthraí
curl -X PUT http://localhost:20128/api/settings/proxy \
-d '{"providers": {"openai": {"type":"socks5","host":"proxy.example.com","port":"1080"}}}'
# Tástáil an seachfhreastalaí
curl -X POST http://localhost:20128/api/settings/proxy/test \
-d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}'
```
**Tosaíocht:** Sonrach don eochair → Sonrach don teaglaim → Sonrach don soláthraí → Domhanda → Timpeallacht.
### API Chatalóg na Samhlacha
```bash
curl http://localhost:20128/api/models/catalog
```
Tugann sé samhlacha ar ais atá grúpáilte de réir soláthraí agus cineálacha acu (`chat`, `embedding`, `image`).
### Sioncronú Néalbhunaithe
- Sioncronaigh soláthraithe, teaglamaí agus socruithe thar ghléasanna
- Sioncronú uathoibríoch sa chúlra le teorainn ama + teip thapa
- Tabhair tús áite do `NEXT_PUBLIC_BASE_URL`/`NEXT_PUBLIC_CLOUD_URL` ar thaobh an fhreastalaí i dtáirgeadh
### Tollán Tapa Cloudflare
- Ar fáil in **Deais → Críochphointí** le haghaidh Docker agus imscaradh féinóstáilte eile
- Cruthaíonn sé URL sealadach `https://*.trycloudflare.com` a chuireann ar aghaidh chuig do chríochphointe reatha `/v1` atá comhoiriúnach le OpenAI
- Suiteálann an chéad chumasú `cloudflared` nuair is gá amháin; úsáideann atosuití ina dhiaidh sin an dénártha bainistithe céanna arís
- Ní athchóirítear Tolláin Thapa go huathoibríoch tar éis atosú OmniRoute nó coimeádáin; cumasaigh arís iad ón deais nuair is gá
- Tá URLanna tolláin gearrshaolach agus athraíonn siad gach uair a stopann nó a thosaíonn tú an tollán
- Úsáideann Tolláin Thapa bhainistithe iompar HTTP/2 de réir réamhshocraithe chun rabhaidh fhothramacha faoi mhaolán UDP QUIC a sheachaint i gcoimeádáin shrianta
- Socraigh `CLOUDFLARED_PROTOCOL=quic` nó `auto` más mian leat rogha an iompair bhainistithe 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 bhainistithe
- Is féidir painéil Tollán Tapa Cloudflare, Tonnadóir Tailscale, agus Tollán ngrok a thaispeáint nó a cheilt in **Socruithe → Cuma**. Ní stopann painéal a cheilt tollán atá ag rith.
### Faisnéis Gheata LLM (Céim 9)
- **Taisce Shéimeantach** — Cuireann sé freagraí neamhshruthaithe le temperature=0 sa taisce go huathoibríoch (seachain é le `X-OmniRoute-No-Cache: true`)
- **Idéimpitéinseacht Iarratais** — Dí-dhúblaíonn sé iarratais laistigh de 5s trí cheanntásc `Idempotency-Key` nó `X-Request-Id`
- **Rianú Dul Chun Cinn** — Imeachtaí roghnacha SSE `event: progress` trí cheanntásc `X-OmniRoute-Progress: true`
---
### Clós Súgartha an Aistritheora
Faigh rochtain air trí **Deais → Aistritheoir**. Dífhabhtaigh agus léirshamhlaigh an chaoi a n-aistríonn OmniRoute iarratais API idir soláthraithe.
| Mód | Cuspóir |
| ------------------- | ---------------------------------------------------------------------------------------------------------------- |
| **Clós Súgartha** | Roghnaigh formáidí foinse/sprice, greamaigh iarratas, agus féach an t-aschur aistrithe láithreach |
| **Tástálaí Comhrá** | Seol teachtaireachtaí beo comhrá tríd an seachfhreastalaí agus scrúdaigh timthriall iomlán an iarratais/fhreagra |
| **Binse Tástála** | Rith baiscthástálacha thar iliomad teaglamaí formáide chun cruinneas an aistriúcháin a dheimhniú |
| **Monatóir Beo** | Breathnaigh ar aistriúcháin fíor-ama de réir mar a shreabhann iarratais tríd an seachfhreastalaí |
**Cásanna úsáide:**
- Dífhabhtaigh an fáth a dteipeann ar theaglaim shonrach cliaint/soláthraí
- Deimhnigh go n-aistrítear clibeanna smaointeoireachta, glaonna uirlise, agus leid chórais i gceart
- Déan comparáid idir na difríochtaí formáide i bhformáidí OpenAI, Claude, Gemini, agus Responses API
---
### Straitéisí Ródaithe
Cumraigh trí **Deais → Socruithe → Ródú**. Taispeánann an deais na sé straitéis is mó úsáid; tacaíonn teaglamaí agus an t-uath-ródaire le tacar níos leithne go hinmheánach.
**Straitéisí atá le feiceáil ar an deais (ródú ar leibhéal an chuntais):**
| Straitéis | Cur síos |
| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| **Líon an Chéad Cheann** | Úsáideann sé cuntais in ord tosaíochta — láimhseálann an príomhchuntas gach iarratas go dtí nach mbíonn sé ar fáil |
| **Spól-Ródaíocht** | Rothlaíonn sé trí gach cuntas le teorainn ghreamaitheach inchumraithe (réamhshocrú: 3 ghlao in aghaidh an chuntais) |
| **P2C (Cumhacht Dhá Rogha)** | Roghnaíonn sé 2 chuntas randamacha agus ródaíonn chuig an gceann is sláintiúla — cothromaíonn sé ualach agus sláinte á cur san áireamh |
| **Randamach** | Roghnaíonn sé cuntas go randamach do gach iarratas trí shuaitheadh Fisher-Yates |
| **Is Lú Úsáidte** | Ródaíonn sé chuig an gcuntas leis an stampa ama `lastUsedAt` is sine, agus dáileann sé trácht go cothrom |
| **Optamaithe ó thaobh Costais de** | Ródaíonn sé chuig an gcuntas leis an luach tosaíochta is ísle, ag optamú do na soláthraithe is saoire |
**Ardteaglamaí agus uathstraitéisí** (inchumraithe de réir teaglama nó trí réimíreanna `auto/*` — féach [AUTO-COMBO.md](../routing/AUTO-COMBO.md)):
- `priority` — ord docht, ní úsáideann sé spól-ródaíocht riamh
- `weighted` — scoilt chomhréireach tráchta de réir meáchain gach samhla
- `fill-first` — ídigh an chéad samhail go dtí go mbaintear teorainneacha amach
- `round-robin` / `strict-random` / `random`
- `p2c` (Cumhacht Dhá Rogha)
- `least-used` agus `cost-optimized`
- `auto` — bunaithe ar scóir thar gach iarrthóir
- `lkgp` (An Soláthraí Deireanach ar Eol a Bheith Maith) — ceanglaíonn sé leis an soláthraí rathúil deireanach, ansin téann sé siar chuig rialacha
- `context-optimized` — roghnaíonn sé an tsamhail leis an bhfuinneog chomhthéacs shaor is mó
- `context-relay` — nascann sé samhlacha fad-chomhthéacs le chéile do shealanna leantacha
#### Ceanntásc Seisiúin Ghreamaithigh Sheachtraigh
Le haghaidh cleamhnas seisiúin seachtrach (mar shampla, gníomhairí Claude Code/Codex taobh thiar de sheachfhreastalaithe droim ar ais), seol:
```http
X-Session-Id: your-session-key
```
Glacann OmniRoute le `x_session_id` freisin agus seolann sé eochair éifeachtach an tseisiúin ar ais in `X-OmniRoute-Session-Id`.
Má úsáideann tú Nginx agus má sheolann tú ceanntásca ina bhfuil fostríoca, cumasaigh:
```nginx
underscores_in_headers on;
```
#### Ailiasanna Samhla le Saoróg
Cruthaigh patrúin saoróige chun ainmneacha samhlacha a athmhapáil:
```
Patrún: claude-sonnet-* → Sprioc: cc/claude-sonnet-4-6
Patrún: gpt-* → Sprioc: gh/gpt-5.3-codex
```
Tacaíonn saoróga le `*` (carachtair ar bith) agus `?` (carachtar aonair).
#### Slabhraí Cúltaca
Sainigh slabhraí cúltaca domhanda a bhaineann le gach iarratas:
```
Slabhra: production-fallback
1. cc/claude-opus-4-7
2. gh/gpt-5.3-codex
3. glm/glm-4.7
```
---
### Teaglamaí Coitianta Soláthraithe & Patrúin Ródaithe
Seo patrúin shamplacha chun iliomad soláthraithe a chomhcheangal agus ródú eatarthu in OmniRoute:
#### 1. Teaglaim Gníomhaire Códúcháin: Réasúnaíocht Ardleibhéil le Cúltaca Costais/Luais
Oiriúnach do ghníomhairí códúcháin (OpenCode, Claude Code, Cursor, Cline). Ródaíonn sé ar dtús chuig samhlacha réasúnaíochta ceannródaíocha, agus téann sé siar chuig samhlacha tapa códúcháin nuair a ídítear cuóta nó nuair a tharlaíonn earráidí.
- **Deais**: Teaglamaí → Teaglaim Nua → Ainm: `agent-coding` → Straitéis: `Priority`
- **Samhlacha**:
1. `claude/claude-sonnet-4-6` (Príomhghníomhaire códúcháin)
2. `openai/gpt-4o` (Cúltaca tánaisteach ardacmhainne)
3. `deepseek/deepseek-v4-flash` (Cúltaca ardéifeachtúlachta, cost-éifeachtach)
```bash
# Sampla tríd an 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. Teaglaim Uath-Theipaistrithe Saorchise
Slabhraíonn sé soláthraithe saorchise agus soláthraithe gan eochair chun an t-aga fónaimh a uasmhéadú gan costais API.
- **Straitéis**: `Least Used` nó `Round Robin` (dáiltear an t-ualach ar fud cuótaí)
- **Samhlacha**:
1. `groq/llama-3.3-70b-versatile`
2. `gemini/gemini-2.5-flash`
3. `cerebras/gpt-oss-120b`
```bash
# Sampla tríd an 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 / Amhairc & Téacs
Samhlacha speisialaithe amhairc a phéireáil le giniúint téacs ardluais le haghaidh sreafaí oibre ina mbíonn tuiscint íomhánna agus giniúint cóid i gceist.
- **Patrún**: Teaglaim `Priority` ina liostaítear samhlacha atá in ann fís a phróiseáil ar dtús agus samhail téacs/cóid ardtréchuir ar deireadh.
- **Samhlacha**:
1. `gemini/gemini-2.5-pro` (Tuiscint láidir ar íomhánna/ar ábhar ilmhódach)
2. `openai/gpt-4o` (Úsáid chothromaithe físe agus uirlisí)
3. `deepseek/deepseek-v4-flash` (Giniúint téacs/cóid)
---
### Athléimneacht & Scoradáin Chiorcaid
Cumraigh trí **Painéal → Socruithe → Athléimneacht**.
Cuireann OmniRoute athléimneacht ar leibhéal an tsoláthraí i bhfeidhm le cúig chomhpháirt:
1. **Ciú Iarratas & Rialú Luais** — Múnlú iarratas ar leibhéal an chórais:
- **Iarratais sa Nóiméad (RPM)** — Uasmhéid iarratas sa nóiméad in aghaidh an chuntais
- **Íosmhéid Ama Idir Iarratais** — An bhearna íosta i milleasoicindí idir iarratais
- **Uasmhéid Iarratas Comhreathach** — Uasmhéid iarratas comhuaineach in aghaidh an chuntais
2. **Tréimhse Shuaimhnithe Naisc** — Cumraíocht de réir cineáil fíordheimhnithe do nasc aonair tar éis teipeanna ar féidir atriail a dhéanamh orthu:
- **Buntréimhse Shuaimhnithe** — An tréimhse shuaimhnithe réamhshocraithe le haghaidh teipeanna in aghaidh srutha ar féidir atriail a dhéanamh orthu
- **Úsáid Leideanna Atrialach In Aghaidh Srutha** — Cloítear le leideanna údarásacha `Retry-After` nó athshocraithe nuair a chuirtear ar fáil iad
- **Uasmhéid Céimeanna Cúlaithe** — An t-uasleibhéal cúlaithe easpónantúil le haghaidh teipeanna arís agus arís eile
3. **Scoradán Ciorcaid Soláthraí** — Rianaíonn sé teipeanna soláthraí ó cheann ceann, marcálann sé soláthraí mar dhíghrádaithe ag an tairseach rabhaidh chumraithe, agus osclaíonn sé an scoradán nuair a shroichtear an tairseach teipe cumraithe:
- **Tairseach Díghrádaithe** — Líon na dteipeanna soláthraí as a chéile sula dtéitear isteach i `DEGRADED`
- **Tairseach Teipe** — Líon na dteipeanna soláthraí as a chéile sula dtéitear isteach i `OPEN`
- **Teorainn Ama Athshocraithe** — An tréimhse ama sula ndéantar an soláthraí a thástáil arís
- **CLOSED** (Sláintiúil) — Sreabhann iarratais mar is gnách
- **DEGRADED** — Leanann iarratais ag sreabhadh agus teipeanna méadaithe á rianú
- **OPEN** — Cuirtear bac sealadach ar an soláthraí tar éis teipeanna arís agus arís eile
- **HALF_OPEN** — Ag tástáil an bhfuil an soláthraí téarnaithe
Fanann teorainneacha ráta `429` atá sonrach do nasc sa **Tréimhse Shuaimhnithe Naisc** agus ní áirítear iad i dtreo scoradán an tsoláthraí.
Ní thaispeántar staid reatha scoradán an tsoláthraí ach ar **Painéal → Sláinte**.
4. **Fan leis an Tréimhse Shuaimhnithe** — Má tá gach nasc iarrthach i dtréimhse shuaimhnithe cheana féin, is féidir le OmniRoute fanacht go dtí an tréimhse shuaimhnithe is túisce agus an t-iarratas cliaint céanna a atriail go huathoibríoch.
5. **Uathbhraite Teorann Ráta** — Nuair a sheolann soláthraithe in aghaidh srutha tréimhsí feithimh sainráite ar ais, sáraíonn na leideanna sin tréimhse shuaimhnithe áitiúil an naisc nuair atá an socrú cumasaithe.
**Leid Ghairmiúil:** Úsáid an leathanach **Sláinte** chun scoradáin bheo soláthraithe a iniúchadh agus a athshocrú tar éis briste. Ní athraíonn an leathanach Athléimneachta ach an chumraíocht.
---
### Easpórtáil / Iompórtáil Bunachair Sonraí
Bainistigh cúltacaí bunachair sonraí in **Painéal → Socruithe → Córas & Stóras**.
| Gníomh | Cur Síos |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Easpórtáil Bunachar Sonraí** | Íoslódálann sé bunachar sonraí reatha SQLite mar chomhad `.sqlite` |
| **Easpórtáil Gach Rud (.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í eochracha API |
| **Iompórtáil Bunachar Sonraí** | Uaslódálann sé comhad `.sqlite` chun an bunachar sonraí reatha a ionadú. Cruthaítear cúltaca réamhiompórtála go huathoibríoch mura bhfuil `DISABLE_SQLITE_AUTO_BACKUP=true` |
```bash
# API: Easpórtáil bunachar sonraí
curl -o backup.sqlite http://localhost:20128/api/db-backups/export
# API: Easpórtáil gach rud (cartlann iomlán)
curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll
# API: Iompórtáil bunachar sonraí
curl -X POST http://localhost:20128/api/db-backups/import \
-F "file=@backup.sqlite"
```
**Bailíochtú Iompórtála:** Déantar sláine an chomhaid iompórtáilte (seiceáil pragma SQLite), na táblaí riachtanacha (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), agus a mhéid (uasmhéid 100MB) a bhailíochtú.
**Cásanna Úsáide:**
- OmniRoute a aistriú idir ríomhairí
- Cúltacaí seachtracha a chruthú le haghaidh athshlánú ó thubaiste
- Cumraíochtaí a chomhroinnt idir baill foirne (easpórtáil gach rud → comhroinn an chartlann)
---
### Painéal Socruithe
Tá an leathanach socruithe eagraithe ina **7 gcluaisín** chun nascleanúint éasca a dhéanamh:
| Cluaisín | Ábhar |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Ginearálta** | Uirlisí stórála córais, iompar réamhshocraithe, infheictheacht tolláin Críochphointe |
| **Cuma** | Rialuithe téama (geal/dorcha/córas), infheictheacht an taobhbharra, scoráin painéil do chártaí tolláin Cloudflare/Tailscale/ngrok |
| **AI** | Buiséad smaointeoireachta (pas tríd / baint uathoibríoch / saincheaptha / oiriúnaitheach — féach [THINKING_BUDGET.md](./THINKING_BUDGET.md)), leid chórais dhomhanda, staitisticí taisce leid |
| **Slándáil** | Socruithe Logála Isteach/Focail Faire, Rialú Rochtana IP, fíordheimhniú API do `/models`, Soláthraithe a Bhlocáil, cosaint ar ionsá leid |
| **Ródú** | Straitéis ródaithe dhomhanda (Líon an Chéad Cheann / Spideog-Róbhabhta / P2C / Randamach / Is Lú Úsáid / Optamaithe de réir Costais), ailiasanna samhlacha le saoróg, slabhraí cúltaca, réamhshocruithe teaglama |
| **Athléimneacht** | Ciú iarratas, tréimhse shuaimhnithe naisc, cumraíocht scoradáin soláthraí, agus iompar feithimh ar an tréimhse shuaimhnithe |
| **Ardsocruithe** | Cumraíocht seachfhreastalaí dhomhanda (HTTP/SOCKS5), sáruithe seachfhreastalaí de réir soláthraí |
Ní dhéanann Ginearálta nótaí inléite amháin maidir le logáil agus taisce a dhúbláil a thuilleadh. Déantar socruithe coinneála agus
optamaithe an bhunachair sonraí a bhuanú trí `/api/settings/database`; úsáidtear
`DELETE /api/cache` chun an taisce a ghlanadh de láimh. Rialaítear uasteorainneacha rónna na logaí iarratas agus seachfhreastalaí le
`CALL_LOGS_TABLE_MAX_ROWS` agus `PROXY_LOGS_TABLE_MAX_ROWS`.
---
### Bainistíocht Costas & Buiséid
Faigh rochtain air trí **Deais → Costais**.
| Cluaisín | Cuspóir |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| **Buiséad** | Socraigh teorainneacha caiteachais de réir eochair API le buiséid laethúla/seachtainiúla/míosúla agus rianú fíor-ama |
| **Praghsáil** | Féach ar iontrálacha praghsála samhlacha agus cuir in eagar iad — costas in aghaidh 1K comhartha ionchuir/aschuir de réir soláthraí |
```bash
# API: Socraigh buiséad
curl -X POST http://localhost:20128/api/usage/budget \
-H "Content-Type: application/json" \
-d '{"keyId": "key-123", "limit": 50.00, "period": "monthly"}'
# API: Faigh stádas reatha an bhuiséid
curl http://localhost:20128/api/usage/budget
```
**Rianú Costais:** Logálann gach iarratas úsáid comharthaí agus ríomhann sé an costas de réir an tábla praghsála. Féach ar mhiondealuithe in **Deais → Úsáid** de réir soláthraí, samhla agus eochrach API.
---
### Tras-scríobh Fuaime
Tacaíonn OmniRoute le tras-scrí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
# Sampla le 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 dúchasach Deepgram agus teastaíonn eochair API Deepgram uaidh.
Mura bhfuil ach OpenRouter cumraithe, úsáid `openrouter/deepgram/nova-3`.
Soláthraithe **Urlabhra-go-Téacs (tras-scríobh)**:
- `openai/` (comhoiriúnach le whisper)
- `groq/` (Groq Whisper Turbo)
- `deepgram/` (teaghlach Nova)
- `assemblyai/`
- `nvidia/` (Parakeet, Canary)
- `huggingface/` (leaganacha whisper)
- `qwen/`
Soláthraithe **Téacs-go-hUrlabhra (`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/`
Formáidí fuaime a dtacaítear leo le haghaidh tras-scríofa: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. Braitheann formáidí aschuir TTS ar an soláthraí (mp3, wav, opus, pcm, mulaw).
---
### Straitéisí Cothromaithe Teaglama
Cumraigh cothromú de réir teaglama in **Deais → Teaglamaí → Cruthaigh/Cuir in Eagar → Straitéis**.
| Straitéis | Cur Síos |
| ------------------------------ | ------------------------------------------------------------------------------------------------- |
| **Spideog-Róbhabhta** | Rothlaíonn trí na samhlacha go seicheamhach |
| **Tosaíocht** | Baineann triail as an gcéad samhail i gcónaí; ní théann sé chuig cúltaca ach amháin ar earráid |
| **Randamach** | Roghnaíonn samhail randamach ón teaglama le haghaidh gach iarratais |
| **Ualaithe** | Ródálann go comhréireach bunaithe ar mheáchain a shanntar de réir samhla |
| **Is Lú Úsáid** | Ródálann chuig an tsamhail leis an líon is lú iarratas le déanaí (úsáideann méadrachtaí teaglama) |
| **Optamaithe de réir Costais** | Ródálann chuig an tsamhail is saoire atá ar fáil (úsáideann an tábla praghsála) |
Is féidir réamhshocruithe teaglama domhanda a shocrú in **Deais → Socruithe → Ródú → Réamhshocruithe Teaglama**.
Faigheann teorainneacha ama spriocanna teaglama an teorainn ama iarratais reatha le hoidhreacht de réir réamhshocraithe. Ná húsáid **Teorainn ama sprice
(soicindí)** sna réamhshocruithe teaglama nó i dteaglama aonair ach amháin nuair ba cheart do theorainn níos giorra in aghaidh na sprice
cúltaca níos tapúla a spreagadh.
Ní mór optamuithe teaglama gan mhoill a roghnú go sainráite. Fág **Optamuithe gan mhoill** díchumasaithe chun
cosc a chur ar na gnéithe moille seo spriocanna cúltaca a rásáil, spriocanna a scipeáil bunaithe ar stair TTFT,
nó iarratais chúltaca a chomhbhrú; má chumasaítear é, ceadaítear fálú cumraithe, scipeanna réamh-mheastacha TTFT,
agus comhbhrú réamhghníomhach cúltaca chun dílseacht ródaithe/iarratais a mhalartú ar mhoill eireabaill níos ísle.
Díchumasaigh an **maolán comharthaí réasúnaíochta** nuair a éilíonn soláthraithe réamhtheachtacha teorainneacha dochta
`max_tokens` / `maxOutputTokens`. Nuair a bhíonn sé cumasaithe, ní chuireann ródú teaglama spás breise
do shamhlacha réasúnaíochta ach le haghaidh samhlacha a bhfuil uasteorainn aschuir aitheanta acu agus fágann sé teorainn chomharthaí an chliaint gan athrú nuair a
sháródh an luach sábháilte maolánaithe an uasteorainn sin. Má tá teorainn an chliaint os cionn uasteorann aitheanta cheana féin,
laghdaíonn OmniRoute í go dtí an uasteorainn sin sula seoltar an t-iarratas réamhtheachtach.
---
### Deais Sláinte
Faigh rochtain uirthi trí **Deais → Sláinte**. Forbhreathnú fíor-ama ar shláinte an chórais ina bhfuil 6 chárta:
| Cárta | An Méid a Thaispeánann Sé |
| -------------------------- | ------------------------------------------------------------------------------ |
| **Stádas an Chórais** | Aga fónaimh, leagan, úsáid cuimhne, eolaire sonraí |
| **Sláinte Soláthraithe** | Staid ama rite dhomhanda scoradán ciorcaid na soláthraithe |
| **Teorainneacha Ráta** | Tréimhsí fuaraithe gníomhacha ceangail de réir cuntais agus an t-am atá fágtha |
| **Frithdhúnadh Gníomhach** | Frithdhúnadh gníomhach atá scóipithe de réir samhla agus eisiaimh shealadacha |
| **Taisce Sínithe** | Staitisticí na taisce dí-dhúblála (eochracha gníomhacha, ráta amas) |
| **Teiliméadracht Folaigh** | Comhiomlánú folaigh p50/p95/p99 de réir soláthraí |
**Leid Ghairmiúil:** Athnuachan an leathanach Sláinte é féin gach 10 soicind. Úsáid cárta an scoradáin chiorcaid chun na soláthraithe a bhfuil fadhbanna acu a aithint.
---
## 🤑 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)