# User Guide (Suomi)
🌐 **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) · 🇫🇷 [fr](../../../fr/docs/guides/USER_GUIDE.md) · 🇮🇪 [ga](../../../ga/docs/guides/USER_GUIDE.md) · 🇮🇳 [gu](../../../gu/docs/guides/USER_GUIDE.md) · 🇳🇬 [ha](../../../ha/docs/guides/USER_GUIDE.md) · 🇮🇱 [he](../../../he/docs/guides/USER_GUIDE.md) · 🇮🇳 [hi](../../../hi/docs/guides/USER_GUIDE.md) · 🇭🇷 [hr](../../../hr/docs/guides/USER_GUIDE.md) · 🇭🇺 [hu](../../../hu/docs/guides/USER_GUIDE.md) · 🇦🇲 [hy](../../../hy/docs/guides/USER_GUIDE.md) · 🇮🇩 [id](../../../id/docs/guides/USER_GUIDE.md) · 🇳🇬 [ig](../../../ig/docs/guides/USER_GUIDE.md) · 🇮🇹 [it](../../../it/docs/guides/USER_GUIDE.md) · 🇯🇵 [ja](../../../ja/docs/guides/USER_GUIDE.md) · 🇬🇪 [ka](../../../ka/docs/guides/USER_GUIDE.md) · 🇰🇭 [km](../../../km/docs/guides/USER_GUIDE.md) · 🇮🇳 [kn](../../../kn/docs/guides/USER_GUIDE.md) · 🇰🇷 [ko](../../../ko/docs/guides/USER_GUIDE.md) · 🇱🇹 [lt](../../../lt/docs/guides/USER_GUIDE.md) · 🇱🇻 [lv](../../../lv/docs/guides/USER_GUIDE.md) · 🇮🇳 [ml](../../../ml/docs/guides/USER_GUIDE.md) · 🇮🇳 [mr](../../../mr/docs/guides/USER_GUIDE.md) · 🇲🇾 [ms](../../../ms/docs/guides/USER_GUIDE.md) · 🇲🇹 [mt](../../../mt/docs/guides/USER_GUIDE.md) · 🇲🇲 [my](../../../my/docs/guides/USER_GUIDE.md) · 🇳🇵 [ne](../../../ne/docs/guides/USER_GUIDE.md) · 🇳🇱 [nl](../../../nl/docs/guides/USER_GUIDE.md) · 🇳🇴 [no](../../../no/docs/guides/USER_GUIDE.md) · 🇮🇳 [or](../../../or/docs/guides/USER_GUIDE.md) · 🇮🇳 [pa](../../../pa/docs/guides/USER_GUIDE.md) · 🇵🇭 [phi](../../../phi/docs/guides/USER_GUIDE.md) · 🇵🇱 [pl](../../../pl/docs/guides/USER_GUIDE.md) · 🇵🇹 [pt](../../../pt/docs/guides/USER_GUIDE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/guides/USER_GUIDE.md) · 🇷🇴 [ro](../../../ro/docs/guides/USER_GUIDE.md) · 🇷🇺 [ru](../../../ru/docs/guides/USER_GUIDE.md) · 🇱🇰 [si](../../../si/docs/guides/USER_GUIDE.md) · 🇸🇰 [sk](../../../sk/docs/guides/USER_GUIDE.md) · 🇸🇮 [sl](../../../sl/docs/guides/USER_GUIDE.md) · 🇷🇸 [sr](../../../sr/docs/guides/USER_GUIDE.md) · 🇸🇪 [sv](../../../sv/docs/guides/USER_GUIDE.md) · 🇰🇪 [sw](../../../sw/docs/guides/USER_GUIDE.md) · 🇮🇳 [ta](../../../ta/docs/guides/USER_GUIDE.md) · 🇮🇳 [te](../../../te/docs/guides/USER_GUIDE.md) · 🇹🇭 [th](../../../th/docs/guides/USER_GUIDE.md) · 🇹🇷 [tr](../../../tr/docs/guides/USER_GUIDE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/guides/USER_GUIDE.md) · 🇵🇰 [ur](../../../ur/docs/guides/USER_GUIDE.md) · 🇺🇿 [uz](../../../uz/docs/guides/USER_GUIDE.md) · 🇻🇳 [vi](../../../vi/docs/guides/USER_GUIDE.md) · 🇳🇬 [yo](../../../yo/docs/guides/USER_GUIDE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/guides/USER_GUIDE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/guides/USER_GUIDE.md)
---
🌐 **Languages:** 🇺🇸 [English](../../../../guides/USER_GUIDE.md) · 🇪🇹 [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) · 🇫🇷 [fr](../../../fr/docs/guides/USER_GUIDE.md) · 🇮🇪 [ga](../../../ga/docs/guides/USER_GUIDE.md) · 🇮🇳 [gu](../../../gu/docs/guides/USER_GUIDE.md) · 🇳🇬 [ha](../../../ha/docs/guides/USER_GUIDE.md) · 🇮🇱 [he](../../../he/docs/guides/USER_GUIDE.md) · 🇮🇳 [hi](../../../hi/docs/guides/USER_GUIDE.md) · 🇭🇷 [hr](../../../hr/docs/guides/USER_GUIDE.md) · 🇭🇺 [hu](../../../hu/docs/guides/USER_GUIDE.md) · 🇦🇲 [hy](../../../hy/docs/guides/USER_GUIDE.md) · 🇮🇩 [id](../../../id/docs/guides/USER_GUIDE.md) · 🇳🇬 [ig](../../../ig/docs/guides/USER_GUIDE.md) · 🇮🇹 [it](../../../it/docs/guides/USER_GUIDE.md) · 🇯🇵 [ja](../../../ja/docs/guides/USER_GUIDE.md) · 🇬🇪 [ka](../../../ka/docs/guides/USER_GUIDE.md) · 🇰🇭 [km](../../../km/docs/guides/USER_GUIDE.md) · 🇮🇳 [kn](../../../kn/docs/guides/USER_GUIDE.md) · 🇰🇷 [ko](../../../ko/docs/guides/USER_GUIDE.md) · 🇱🇹 [lt](../../../lt/docs/guides/USER_GUIDE.md) · 🇱🇻 [lv](../../../lv/docs/guides/USER_GUIDE.md) · 🇮🇳 [ml](../../../ml/docs/guides/USER_GUIDE.md) · 🇮🇳 [mr](../../../mr/docs/guides/USER_GUIDE.md) · 🇲🇾 [ms](../../../ms/docs/guides/USER_GUIDE.md) · 🇲🇹 [mt](../../../mt/docs/guides/USER_GUIDE.md) · 🇲🇲 [my](../../../my/docs/guides/USER_GUIDE.md) · 🇳🇵 [ne](../../../ne/docs/guides/USER_GUIDE.md) · 🇳🇱 [nl](../../../nl/docs/guides/USER_GUIDE.md) · 🇳🇴 [no](../../../no/docs/guides/USER_GUIDE.md) · 🇮🇳 [or](../../../or/docs/guides/USER_GUIDE.md) · 🇮🇳 [pa](../../../pa/docs/guides/USER_GUIDE.md) · 🇵🇭 [phi](../../../phi/docs/guides/USER_GUIDE.md) · 🇵🇱 [pl](../../../pl/docs/guides/USER_GUIDE.md) · 🇵🇹 [pt](../../../pt/docs/guides/USER_GUIDE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/guides/USER_GUIDE.md) · 🇷🇴 [ro](../../../ro/docs/guides/USER_GUIDE.md) · 🇷🇺 [ru](../../../ru/docs/guides/USER_GUIDE.md) · 🇱🇰 [si](../../../si/docs/guides/USER_GUIDE.md) · 🇸🇰 [sk](../../../sk/docs/guides/USER_GUIDE.md) · 🇸🇮 [sl](../../../sl/docs/guides/USER_GUIDE.md) · 🇷🇸 [sr](../../../sr/docs/guides/USER_GUIDE.md) · 🇸🇪 [sv](../../../sv/docs/guides/USER_GUIDE.md) · 🇰🇪 [sw](../../../sw/docs/guides/USER_GUIDE.md) · 🇮🇳 [ta](../../../ta/docs/guides/USER_GUIDE.md) · 🇮🇳 [te](../../../te/docs/guides/USER_GUIDE.md) · 🇹🇭 [th](../../../th/docs/guides/USER_GUIDE.md) · 🇹🇷 [tr](../../../tr/docs/guides/USER_GUIDE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/guides/USER_GUIDE.md) · 🇵🇰 [ur](../../../ur/docs/guides/USER_GUIDE.md) · 🇺🇿 [uz](../../../uz/docs/guides/USER_GUIDE.md) · 🇻🇳 [vi](../../../vi/docs/guides/USER_GUIDE.md) · 🇳🇬 [yo](../../../yo/docs/guides/USER_GUIDE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/guides/USER_GUIDE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/guides/USER_GUIDE.md)
Kattava opas palveluntarjoajien määrittämiseen, yhdistelmien luomiseen, CLI-työkalujen integrointiin ja OmniRouten käyttöönottoon.
---
## Sisällysluettelo
- [Hinnoittelu yhdellä silmäyksellä](#-pricing-at-a-glance)
- [Käyttötapaukset](#-use-cases)
- [Palveluntarjoajan määritys](#-provider-setup)
- [CLI-integraatio](#-cli-integration)
- [Käyttöönotto](#-deployment)
- [Saatavilla olevat mallit](#-available-models)
- [Edistyneet ominaisuudet](#-advanced-features)
- [Automaattinen reititys (ei määrityksiä)](#-auto-routing-zero-config)
- [MCP- ja A2A-integraatio](#-mcp--a2a-integration)
- [Taitojärjestelmä](#-skills-system)
- [Muistijärjestelmä](#-memory-system)
- [Webhookit](#-webhooks)
- [Pilviagentit](#-cloud-agents)
- [Ohjelmallinen hallinta](#-programmatic-management)
- [Sisäinen CLI](#-internal-cli)
- [Työpöytäsovellus (Electron)](#-desktop-application-electron)
---
## 💰 Hinnoittelu yhdellä silmäyksellä
| Taso | Palveluntarjoaja | Hinta | Kiintiön nollaus | Sopii parhaiten |
| ---------------- | ----------------- | ------------- | ---------------------------------------- | -------------------------------- |
| **💳 TILAUS** | Claude Code (Pro) | $20/kk | 5 h + viikoittain | Nykyisille tilaajille |
| | Codex (Plus/Pro) | $20–200/kk | 5 h + viikoittain | OpenAI-käyttäjille |
| | GitHub Copilot | $10–19/kk | Kuukausittain | GitHub-käyttäjille |
| **🔑 API-AVAIN** | DeepSeek | Käytön mukaan | Ei nollausta | Edulliseen päättelyyn |
| | Groq | Käytön mukaan | Ei nollausta | Erittäin nopeaan inferenssiin |
| | xAI (Grok) | Käytön mukaan | Ei nollausta | Grok 4 -päättelyyn |
| | Mistral | Käytön mukaan | Ei nollausta | EU:ssa isännöityihin malleihin |
| | Perplexity | Käytön mukaan | Ei nollausta | Hakua hyödyntäviin tehtäviin |
| | Together AI | Käytön mukaan | Ei nollausta | Avoimen lähdekoodin malleihin |
| | Fireworks AI | Käytön mukaan | Ei nollausta | Nopeaan FLUX-kuvien luontiin |
| | Cerebras | Käytön mukaan | Ei nollausta | Piikiekkotason nopeuteen |
| | Cohere | Käytön mukaan | Ei nollausta | Command R+ RAG -käyttöön |
| | NVIDIA NIM | Käytön mukaan | Ei nollausta | Yritysmalleihin |
| | Baidu Qianfan | Käytön mukaan | Ei nollausta | ERNIE-malleihin |
| **💰 EDULLINEN** | GLM-4.7 | $0.6/1M | Päivittäin klo 10 | Edulliseksi varavaihtoehdoksi |
| | MiniMax M2.1 | $0.2/1M | Liukuva 5 tunnin jakso | Halvimmaksi vaihtoehdoksi |
| | Kimi K2 | Kiinteä $9/kk | 10M tokenia/kk | Ennakoitaviin kustannuksiin |
| **🆓 ILMAINEN** | Qoder | $0 | Palveluntarjoajan rajoitusten mukaisesti | Tarkista nykyinen mallivalikoima |
| | Kiro | $0 | ~50 krediittiä/kk | Ilmaiseen Claude-käyttöön |
---
## 🎯 Käyttötapaukset
### Tapaus 1: "Minulla on Claude Pro -tilaus"
**Ongelma:** Kiintiö vanhenee käyttämättömänä, ja käyttörajoitukset tulevat vastaan intensiivisen ohjelmoinnin aikana
```
Yhdistelmä: "maximize-claude"
1. cc/claude-opus-4-7 (hyödynnä tilaus kokonaan)
2. glm/glm-4.7 (edullinen varavaihtoehto kiintiön loputtua)
3. if/qwen3.8-max-preview (ilmainen varavaihtoehto hätätilanteisiin)
Kuukausikustannus: $20 (tilaus) + ~$5 (varavaihtoehto) = yhteensä $25
verrattuna $20 + käyttörajoitusten saavuttamisen aiheuttama turhautuminen
```
### Tapaus 2: "En halua lainkaan kustannuksia"
**Ongelma:** Tilauksiin ei ole varaa, mutta tarvitsen luotettavaa tekoälyä ohjelmointiin
```
Yhdistelmä: "zero-cost"
1. if/kimi-k2.7-code (ilmoitettu ilmainen käyttö; käyttörajoituksia saatetaan soveltaa)
2. kr/qwen3-coder-next (ilmainen Kiro-varavaihtoehto)
Kuukausikustannus: $0
Laatu: varmista mallin soveltuvuus, rajoitukset, tietosuoja ja SLA omalle työkuormallesi
```
### Tapaus 3: "Tarvitsen ohjelmointiapua ympäri vuorokauden ilman keskeytyksiä"
**Ongelma:** Määräajat painavat päälle, eikä käyttökatkoihin ole varaa
```
Yhdistelmä: "always-on"
1. cc/claude-opus-4-7 (paras laatu)
2. cx/gpt-5.5 (toinen tilaus)
3. glm/glm-4.7 (edullinen, nollautuu päivittäin)
4. minimax/MiniMax-M2.1 (halvin, nollautuu 5 tunnin välein)
5. if/deepseek-v4-flash (ilmoitettu ilmainen käyttö; käyttörajoituksia saatetaan soveltaa)
Tulos: 5 varajärjestelmätasoa parantaa vikasietoisuutta; taustapalvelujen saatavuutta ei taata
Kuukausikustannus: $20–200 (tilaukset) + $10–20 (varavaihtoehto)
```
### Tapaus 4: "Haluan ILMAISEN tekoälyn OpenClaw'ssa"
**Ongelma:** Tarvitsen tekoälyavustajan viestisovelluksiin täysin ilmaiseksi
```
Yhdistelmä: "openclaw-free"
1. if/qwen3.8-max-preview (ilmoitettu ilmainen käyttö; käyttörajoituksia saatetaan soveltaa)
2. if/deepseek-v4-flash (ilmoitettu ilmainen käyttö; käyttörajoituksia saatetaan soveltaa)
3. if/kimi-k2.7-code (ilmoitettu ilmainen käyttö; käyttörajoituksia saatetaan soveltaa)
Kuukausikustannus: $0
Käyttö seuraavien kautta: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
```
---
## 📖 Palveluntarjoajien määritys
Voit lisätä API-avainyhteyksiä joukkona CSV- tai JSON-tiedostosta valitsemalla **Hallintapaneeli → Palveluntarjoajat → Tuo tiedostosta**. Sarakkeet ovat paikkasidonnaisia (`provider,name,apiKey,baseUrl,priority`); `provider`-arvon on jo oltava hallittu palveluntarjoaja tai yhteensopiva solmu. Katso [Palveluntarjoajien tuominen CSV- tai JSON-tiedostosta](../providers/CSV-IMPORT.md).
### 🔐 Tilauspohjaiset palveluntarjoajat
#### Claude Code (Pro/Max)
```bash
Hallintapaneeli → Palveluntarjoajat → Yhdistä Claude Code
→ OAuth-kirjautuminen → Tunnuksen automaattinen päivitys
→ 5 tunnin ja viikoittaisen kiintiön seuranta
Mallit:
cc/claude-opus-4-7
cc/claude-sonnet-4-6
cc/claude-haiku-4-5-20251001
```
**Ammattilaisen vinkki:** Käytä Opusta monimutkaisiin tehtäviin ja Sonnetia nopeutta vaativiin tehtäviin. OmniRoute seuraa kunkin mallin kiintiötä!
Eikö OmniRoute-isännällä ole selainta? Suorita `claude setup-token` missä tahansa, missä Claude Codeen on kirjauduttu, ja liitä vuoden voimassa oleva tunnus **Setup Token** -välilehdelle. Katso [Claude Coden käyttäminen asetustunnuksella](../providers/CLAUDE_CODE_SETUP_TOKEN.md).
Claude- ja Claude Code -yhteensopivat reitit säilyttävät Opus- ja Sonnet-mallien `max`-päättelytason. Haiku-mallit eivät hyväksy `max`-tasoa, joten OmniRoute alentaa pyynnön korkeaan päättelybudjettiin ennen sen lähettämistä ylävirran palveluun.
#### OpenAI Codex (Plus/Pro)
```bash
Hallintapaneeli → Palveluntarjoajat → Yhdistä Codex
→ OAuth-kirjautuminen (portti 1455)
→ Nollaus 5 tunnin välein ja viikoittain
Mallit:
cx/gpt-5.5
cx/gpt-5.4
cx/gpt-5.3-codex
cx/gpt-5.3-codex-spark
```
#### GitHub Copilot
```bash
Hallintapaneeli → Palveluntarjoajat → Yhdistä GitHub
→ OAuth GitHubin kautta
→ Kuukausittainen nollaus (kuukauden 1. päivänä)
Mallit:
gh/gpt-5.5
gh/gpt-5.4
gh/claude-sonnet-4.6
gh/claude-opus-4.7
gh/gemini-3.1-pro-preview
```
### 💰 Edulliset palveluntarjoajat
#### GLM-4.7 (Päivittäinen nollaus, $0.6/1M)
1. Rekisteröidy: [Zhipu AI](https://open.bigmodel.cn)
2. Hanki API-avain Coding Plan -tilauksesta
3. Hallintapaneeli → Lisää API-avain: Palveluntarjoaja: `glm`, API-avain: `your-key`
**Käyttö:** `glm/glm-4.7` — **Ammattilaisen vinkki:** Coding Plan tarjoaa kolminkertaisen kiintiön seitsemäsosalla hinnasta! Nollaus päivittäin klo 10.00.
#### MiniMax M2.1 (Nollaus 5 tunnin välein, $0.20/1M)
1. Rekisteröidy: [MiniMax](https://www.minimax.io)
2. Hanki API-avain → Hallintapaneeli → Lisää API-avain
**Käyttö:** `minimax/MiniMax-M2.1` — **Ammattilaisen vinkki:** Edullisin vaihtoehto pitkälle kontekstille (1M tunnistetta)!
#### Kimi K2 (Kiinteästi $9/kuukausi)
1. Tilaa: [Moonshot AI](https://platform.kimi.ai?aff=omniroute)
2. Hanki API-avain → Hallintapaneeli → Lisää API-avain
**Käyttö:** `kimi/kimi-k2.5` — **Ammattilaisen vinkki:** Kiinteä $9/kuukausi 10 miljoonasta tunnisteesta = todellinen kustannus $0.90/1M!
#### Baidu Qianfan / ERNIE
1. Rekisteröidy: [Baidu AI Cloud Qianfan](https://cloud.baidu.com/product/wenxinworkshop)
2. Luo Qianfan API-avain → Hallintapaneeli → Lisää API-avain: Palveluntarjoaja: `qianfan`
**Käyttö:** `qianfan/ernie-5.1`, `qianfan/ernie-x1.1` tai jokin muu Qianfanin OpenAI-yhteensopiva mallitunnus.
### 🆓 ILMAISET palveluntarjoajat
Todennusta edellyttämättömillä ilmaisilla palveluntarjoajilla on kytkin **Todennusta ei vaadita** -kohdan vieressä niiden palveluntarjoajasivulla.
Sen poistaminen käytöstä poistaa kyseisen palveluntarjoajan käytöstä ja Palveluntarjoajien määritetyistä ja tiiviistä näkymistä sekä
poistaa sen mallit `/v1/models`-luettelosta.
#### Qoder (9 ILMAISTA mallia)
```bash
Hallintapaneeli → Yhdistä Qoder → OAuth-kirjautuminen → Käyttöön sovelletaan palveluntarjoajan nykyisiä rajoituksia
Mallit: 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 ILMAISEKSI)
```bash
Hallintapaneeli → Yhdistä Kiro → AWS Builder ID tai Google/GitHub → ~50 krediittiä kuukaudessa
Mallit: kr/claude-sonnet-4.5, kr/claude-haiku-4.5
```
---
## 🎨 Yhdistelmät
Voit järjestää yhdistelmäkortit uudelleen suoraan kohdassa **Hallintapaneeli → Yhdistelmät** vetämällä kunkin kortin kahvasta. Järjestys tallennetaan SQLite-tietokantaan ja palautetaan uudelleenlatauksen yhteydessä.
### Esimerkki 1: Maksimoi tilauksen käyttö → Edullinen varamalli
```
Hallintapaneeli → Yhdistelmät → Luo uusi
Nimi: premium-coding
Mallit:
1. cc/claude-opus-4-7 (Ensisijainen tilausmalli)
2. glm/glm-4.7 (Edullinen varamalli, $0.6/1M)
3. minimax/MiniMax-M2.7 (Halvin varavaihtoehto, $0.3/1M)
Käyttö CLI:ssä: premium-coding
```
### Esimerkki 2: Vain ilmaiset (ei kustannuksia)
```
Nimi: free-combo
Mallit:
1. if/kimi-k2.7-code (ilmoitettu maksuton käyttöoikeus; palveluntarjoajan rajoituksia voidaan soveltaa)
2. kr/qwen3-coder-next (Kiron maksuton varavaihtoehto)
Kustannus: ilmoitettu tällä hetkellä arvoksi $0; ehdot ja saatavuus voivat muuttua
```
---
## 🔧 CLI-integraatio
### Cursor IDE
**Cursorin käyttäminen OmniRoute-asiakasohjelmana** (reititä Cursor-keskustelut OmniRouten kautta):
```
Asetukset → Mallit → Lisäasetukset:
OpenAI API:n perus-URL: http://localhost:20128/v1
OpenAI API -avain: [OmniRoute-hallintapaneelista]
Malli: cc/claude-opus-4-7
```
**OmniRouten käyttäminen Cursor-palveluntarjoajana** (OmniRoute kutsuu Cursor-ylävirtaa): suosi vaihtoehtoa
**Hallintapaneeli → Palveluntarjoajat → Cursor → Kirjaudu Cursorilla**. Katso Dockerissa
[`docs/providers/CURSOR-DOCKER.md`](../providers/CURSOR-DOCKER.md).
### Claude Code
Muokkaa tiedostoa `~/.claude/settings.json`:
```json
{
"env": {
"ANTHROPIC_BASE_URL": "http://localhost:20128",
"ANTHROPIC_AUTH_TOKEN": "your-omniroute-api-key"
}
}
```
Käytä tässä Claude-yhteensopivaa juuripäätepistettä. Älä lisää polkua `/v1` muuttujaan `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
Muokkaa tiedostoa `~/.openclaw/openclaw.json`:
```json
{
"agents": {
"defaults": {
"model": { "primary": "omniroute/if/kimi-k2.7-code" }
}
},
"models": {
"providers": {
"omniroute": {
"baseUrl": "http://localhost:20128/v1",
"apiKey": "your-omniroute-api-key",
"api": "openai-completions",
"models": [{ "id": "if/kimi-k2.7-code", "name": "Kimi K2.7 Code" }]
}
}
}
}
```
**Tai käytä hallintapaneelia:** CLI-työkalut → OpenClaw → Automaattinen määritys
### Cline / Continue / RooCode
```
Palveluntarjoaja: OpenAI-yhteensopiva
Perus-URL: http://localhost:20128/v1
API-avain: [hallintapaneelista]
Malli: cc/claude-opus-4-7
```
---
## 🚀 Käyttöönotto
### Globaali npm-asennus (suositus)
```bash
npm install -g omniroute
# Luo määrityshakemisto
mkdir -p ~/.omniroute
# Luo .env-tiedosto (katso .env.example)
cp .env.example ~/.omniroute/.env
# Käynnistä palvelin
omniroute
# Tai mukautetulla portilla:
omniroute --port 3000
```
CLI lataa `.env`-tiedoston automaattisesti sijainnista `~/.omniroute/.env` tai `./.env`.
### Ilmoitusaluetila
Käynnistä OmniRoute järjestelmän ilmoitusalueella:
```bash
omniroute serve --tray
```
Komento päättyy, kun palvelin ja ilmoitusaluekuvake ovat valmiina.
Palvelin jatkaa toimintaansa ilman päätettä.
Ilmoitusaluetilaa tuetaan macOS:ssä, Windowsissa ja graafisissa Linux-istunnoissa. Ilmoitusaluetila ei avaa hallintapaneelia automaattisesti.
Käytä ilmoitusaluevalikkoa seuraaviin toimintoihin:
- Avaa hallintapaneeli.
- Avaa `/dashboard/logs`.
- Muuta automaattisen käynnistyksen asetusta.
- Pysäytä OmniRoute.
Älä käytä valitsinta `--tray` yhdessä seuraavien valitsimien kanssa:
- `--daemon`
- `--log`
- `--no-recovery`
Nämä tilat edellyttävät erilaista prosessin omistajuutta.
Ota käynnistys käyttöön koneen seuraavan sisäänkirjautumisen yhteydessä:
```bash
omniroute autostart enable
```
Automaattinen käynnistys käyttää ilmoitusaluetilaa macOS:ssä, Windowsissa ja graafisissa Linux-istunnoissa. Graafista käyttöliittymää vailla oleva Linux käyttää olemassa olevaa systemd-käyttäjäpalvelua.
Poista sisäänkirjautumisen yhteydessä tapahtuva käynnistys käytöstä:
```bash
omniroute autostart disable
```
### Asennuksen poistaminen
Kun et enää tarvitse OmniRoutea, tarjoamme kaksi nopeaa komentosarjaa siistiä poistamista varten:
| Komento | Toiminto |
| ------------------------ | ------------------------------------------------------------------------------------------------------------- |
| `npm run uninstall` | Poistaa järjestelmäsovelluksen, mutta **säilyttää tietokantasi ja määrityksesi** hakemistossa `~/.omniroute`. |
| `npm run uninstall:full` | Poistaa sovelluksen JA **hävittää kaikki määritykset, avaimet ja tietokannat pysyvästi**. |
> Huomautus: Suorita nämä komennot siirtymällä OmniRoute-projektikansioon (jos kloonasit sen) ja suorittamalla ne siellä. Jos asensit sen globaalisti, voit vaihtoehtoisesti suorittaa komennon `npm uninstall -g omniroute`.
### VPS-käyttöönotto
```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
# Tai: pm2 start npm --name omniroute -- start
```
### PM2-käyttöönotto (vähäinen muistinkäyttö)
Käytä muistirajoitusvalintaa palvelimilla, joilla on rajallisesti RAM-muistia:
```bash
# 512MB:n rajoituksella (oletus)
pm2 start npm --name omniroute -- start
# Tai mukautetulla muistirajoituksella
OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start
# Tai käyttämällä tiedostoa ecosystem.config.js
pm2 start ecosystem.config.js
```
Luo `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
# Koosta levykuva (oletus = runner-cli, jossa codex/claude/droid on esiasennettu)
docker build -t omniroute:cli .
# Siirrettävä tila (suositus)
docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli
```
Katso CLI-binäärit sisältävää isäntäjärjestelmään integroitua tilaa koskevat tiedot päädokumentaation Docker-osiosta.
### Void Linux (xbps-src)
Void Linuxin käyttäjät voivat paketoida ja asentaa OmniRouten natiivisti käyttämällä `xbps-src`-ristiinkäännöskehystä. Tämä automatisoi itsenäisen Node.js-koontiversion luomisen sekä tarvittavat natiivit `better-sqlite3`-sidokset.
Näytä xbps-src-mallipohja
```bash
# Mallipohjatiedosto paketille 'omniroute'
pkgname=omniroute
version=3.8.0
revision=1
hostmakedepends="nodejs python3 make"
depends="openssl"
short_desc="Yleiskäyttöinen tekoäly-yhdyskäytävä älykkäällä reitityksellä useille LLM-palveluntarjoajille"
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() {
# Määritä node-gypin kohdesuoritinarkkitehtuuri
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) Asenna kaikki riippuvuudet – ohita komentosarjat
NODE_ENV=development npm ci --ignore-scripts
# 2) Kokoa itsenäinen Next.js-paketti
npm run build
# 3) Kopioi staattiset resurssit itsenäiseen pakettiin
cp -r .next/static .next/standalone/.next/static
[ -d public ] && cp -r public .next/standalone/public || true
# 4) Käännä better-sqlite3:n natiivi sidos
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) Sijoita käännetty sidos itsenäiseen pakettiin
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) Poista arkkitehtuurikohtaiset sharp-paketit
rm -rf .next/standalone/node_modules/@img
# 7) Kopioi Next.js:n staattisen analyysin ohittamat pinon suorituksenaikaiset riippuvuudet:
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
# Estä asennuksen jälkeistä käsittelijää poistamasta tyhjiä Next.js-sovellusreitittimen hakemistoja
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
}
```
### Ympäristömuuttujat
| Muuttuja | Oletusarvo | Kuvaus |
| --------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT-allekirjoituksen salaisuus (**vaihda tuotantoympäristössä**) |
| `INITIAL_PASSWORD` | `CHANGEME` | Ensimmäisen kirjautumisen salasana |
| `DATA_DIR` | `~/.omniroute` | Datahakemisto (tietokanta, käyttötilastot, lokit) |
| `PORT` | kehyksen oletusarvo | Palvelun portti (esimerkeissä `20128`) |
| `HOSTNAME` | kehyksen oletusarvo | Kuunteluosoite (Dockerin oletusarvo on `0.0.0.0`) |
| `NODE_ENV` | ajonaikainen oletusarvo | Aseta käyttöönottoa varten arvoksi `production` |
| `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128` | Koontinäytössä näkyvä ja palvelimelle välitettävä julkinen perus-URL (korvaa vanhan `BASE_URL`-muuttujan) |
| `NEXT_PUBLIC_CLOUD_URL` | `https://omniroute.dev` | Pilvisynkronoinnin päätepisteen perus-URL (korvaa vanhan `CLOUD_URL`-muuttujan) |
| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | Luotujen API-avainten HMAC-salaisuus |
| `REQUIRE_API_KEY` | `false` | Vaadi Bearer API -avain reitillä `/v1/*` |
| `ALLOW_API_KEY_REVEAL` | `false` | Salli todennettujen koontinäytön käyttäjien näyttää tallennettujen API-avainten täydet arvot pyynnöstä |
| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Välimuistiin tallennettujen palveluntarjoajarajojen palvelinpuolen päivitysväli; käyttöliittymän päivityspainikkeet käynnistävät edelleen manuaalisen synkronoinnin |
| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Poista automaattiset SQLite-tilannevedokset käytöstä ennen kirjoitusta, tuontia tai palautusta; manuaaliset varmuuskopiot toimivat edelleen |
| `APP_LOG_TO_FILE` | `true` | Ottaa käyttöön sovellus- ja auditointilokien kirjoittamisen levylle |
| `AUTH_COOKIE_SECURE` | `false` | Pakota todennusevästeen `Secure`-asetus (HTTPS-käänteisvälityspalvelimen takana) |
| `CLOUDFLARED_BIN` | ei asetettu | Käytä olemassa olevaa `cloudflared`-binääriä hallitun latauksen sijaan |
| `CLOUDFLARED_PROTOCOL` | `http2` | Hallittujen Quick Tunnels -tunneleiden siirtoprotokolla (`http2`, `quic` tai `auto`) |
| `OMNIROUTE_MEMORY_MB` | `512` | Node.js-keon enimmäiskoko megatavuina |
| `PROMPT_CACHE_MAX_SIZE` | `50` | Kehotevälimuistin merkintöjen enimmäismäärä |
| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Semanttisen välimuistin merkintöjen enimmäismäärä |
Täydellinen ympäristömuuttujien luettelo on [README-tiedostossa](../README.md).
---
## 📊 Saatavilla olevat mallit
Näytä kaikki saatavilla olevat mallit
> Alla oleva luettelo on koottu tiedostosta `open-sse/config/providerRegistry.ts` versiolle v3.8.0. Pilvipalvelujen malliluettelot (Gemini, OpenRouter jne.) synkronoidaan dynaamisesti — saat koko ajantasaisen luettelon avaamalla **Hallintapaneeli → Palveluntarjoajat → [palveluntarjoaja] → Saatavilla olevat mallit** tai kutsumalla päätepistettä `GET /api/models/catalog`.
>
> Jos palveluntarjoajan sisäinen luettelo ei ole enää ajan tasalla, nouda ajantasainen luettelo ylävirrasta käyttämällä kyseisellä sivulla toimintoa **Tuo kohteesta /models** (tai ottamalla käyttöön **Automaattinen synkronointi**). Tämä vahvistettiin versiossa v3.8.50 palveluille LLM7.io (`gemini-3.1-flash-lite`) ja UncloseAI (`solidrust/Hermes-3-Llama-3.1-8B-AWQ`); Pollinations-palvelun anonyymi käyttö pysyi ylävirran rajoittamana saman testikierroksen aikana.
**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` (+ päättelytasot: `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/`)** — ILMAINEN OAuth: käytä ajantasaista luetteloa kohdassa **Hallintapaneeli → Palveluntarjoajat → Kiro → Saatavilla olevat mallit**. Saatavuus riippuu tilistä ja tilauksesta.
**Qoder (`if/`)** — ILMAINEN 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 $ / 1 milj.: `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 $ / 1 milj.: `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/`)** — kiinteä 9 $/kk tai käytön mukaan: `kimi/kimi-k2.6`, `kimi/kimi-k2.5`
**DeepSeek (`ds/`)** — API-avain: `ds/deepseek-v4-pro`, `ds/deepseek-v4-flash`
**Groq (`groq/`)** — Erittäin nopea: `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/`)** — Natiivi Grok: `xai/grok-4.3`, `xai/grok-4.20-multi-agent-0309`, `xai/grok-4.20-0309-reasoning`, `xai/grok-4.20-0309-non-reasoning`
**Mistral (`mistral/`)** — Isännöity EU:ssa: `mistral/mistral-large-latest`, `mistral/mistral-medium-3-5`, `mistral/mistral-small-latest`, `mistral/devstral-latest`, `mistral/codestral-latest`
**Perplexity (`pplx/`)** — Hakutoiminnoilla täydennetty: `pplx/sonar-deep-research`, `pplx/sonar-reasoning-pro`, `pplx/sonar-pro`, `pplx/sonar`
**Together AI (`together/`)** — Avoin lähdekoodi: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo-Free` (ilmainen), `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/`)** — Nopea inferenssi: `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/`)** — Kiekkomittakaava: `cerebras/zai-glm-4.7`, `cerebras/gpt-oss-120b`
**Cohere (`cohere/`)** — RAG-painotteinen: `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/`)** — Yrityskäyttöön: `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/`)**: Synkronoidaan ajantasaisesti Googlelta API-avaimen perusteella — ei staattista luetteloa. Yhdistä avain kohdassa **Hallintapaneeli → Palveluntarjoajat** ja tuo sitten nykyinen luettelo käyttämällä toimintoa **Saatavilla olevat mallit** (esim. `gemini/gemini-3-pro`, `gemini/gemini-3-flash`).
**Muut yhteensopivat palveluntarjoajat** (valikoima): `cohere`, `databricks`, `snowflake`, `together`, `vertex`, `alibaba`, `alibaba-cn`, `bedrock` (`aws-bedrock`-palvelun kautta), `azure-ai`, `openrouter` (luettelon läpivienti), `siliconflow`, `hyperbolic`, `huggingface`, `featherless-ai`, `cloudflare-ai`, `scaleway`, `deepinfra`, `vercel-ai-gateway`, `bazaarlink`, `friendliai`, `nous-research`, `reka`, `volcengine`, `ai21`, `gigachat`. Kukin ylläpitää omaa malliluetteloaan tiedostossa `providerRegistry.ts`, ja luettelo voidaan synkronoida automaattisesti, kun palveluntarjoaja tarjoaa `/models`-päätepisteen.
**Huomautus mallitunnuksista:** OmniRoute käyttää palveluntarjoajien natiiveja tunnuksia (`claude-opus-4-8`, `gpt-5.5`, `glm-5.1`, `MiniMax-M2.7`, `kimi-k2.5`, `grok-4.20-0309-reasoning`). Jotkin tunnukset sisältävät pisteillä erotettuja versioita, koska ylävirran API odottaa niitä tässä muodossa. Jos mallia ei ole lueteltu yllä, vahvista sen saatavuus suorittamalla `omniroute models --search ` tai kutsumalla päätepistettä `GET /api/models/catalog`.
---
## 🧩 Edistyneet ominaisuudet
### Mukautetut mallit
Lisää mikä tahansa mallitunnus mille tahansa palveluntarjoajalle odottamatta sovelluspäivitystä:
```bash
# API:n kautta
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"}'
# Listaa: curl http://localhost:20128/api/provider-models?provider=openai
# Poista: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-5.2"
```
Voit myös käyttää hallintapaneelia: **Palveluntarjoajat → [Palveluntarjoaja] → Mukautetut mallit**.
Huomautuksia:
- OpenRouter- sekä OpenAI-/Anthropic-yhteensopivia palveluntarjoajia hallitaan vain **Saatavilla olevat mallit** -kohdassa. Manuaalisesti lisätyt, tuodut ja automaattisesti synkronoidut mallit päätyvät kaikki samaan saatavilla olevien mallien luetteloon, joten näille palveluntarjoajille ei ole erillistä Mukautetut mallit -osiota.
- **Mukautetut mallit** -osio on tarkoitettu palveluntarjoajille, jotka eivät tarjoa hallittua saatavilla olevien mallien tuontia.
### Mukautetut OpenAI-yhteensopivat palveluntarjoajat
Mikä tahansa OpenAI API:a käyttävä yhdyskäytävä (itse isännöity välityspalvelin, vLLM tai kolmannen osapuolen koontipalvelu)
voidaan lisätä omaksi palveluntarjoajasolmukseen:
1. **Palveluntarjoajat → Lisää OpenAI-yhteensopiva**.
2. **Nimi**: solmun näyttönimi.
3. **Etuliite**: reititysnimi. Asiakkaat kutsuvat malleja muodossa `/`, joten solmu, jonka
etuliite on `mygw`, tarjoaa mallin `mygw/gpt-4o-mini`. Pakollinen; merkkejä ei ole rajoitettu.
4. **API-tyyppi**: yhdyskäytävän tarjoama päätepisteperhe (Chat Completions, Responses,
Embeddings, ääni, kuvat).
5. **Perus-URL**: API:n juuriosoite `/v1` mukaan lukien (esimerkiksi
`https://gateway.example.com/v1`), ei koko `/chat/completions`-polku. Yhdyskäytävien
epästandardit polut määritetään kohdassa **Lisäasetukset** (keskustelupolku, mallipolku).
6. **API-avain (tarkistusta varten)** -kenttä vain testaa yhteyden. Kun solmu on luotu,
avaa se ja tallenna pyyntöjen käyttämä avain valitsemalla **Lisää yhteys**.
Solmu saa sisäisen tunnuksen muodossa `openai-compatible--`; sitä ei tarvitse
koskaan kirjoittaa, sillä etuliite on julkinen nimi.
#### Varatut etuliitteet
Etuliite ei voi olla sisäänrakennetun palveluntarjoajan tunnus tai alias (esimerkiksi `openai`, `cf`) eikä
käytöstä poistetun palveluntarjoajan tunnus. Mallin ratkaisutoiminto tarkistaa sisäänrakennetut tunnukset ja aliakset ennen
mukautettuja solmuja, joten tällaista etuliitettä käyttävä solmu ei koskaan vastaanottaisi liikennettä:
`/model` ohjattaisiin sen sijaan sisäänrakennetulle palveluntarjoajalle tai pyyntö hylättäisiin, jos kyseinen palveluntarjoaja
olisi poistettu käytöstä. Tällaisen etuliitteen sisältävän solmun luonti tai muokkaus hylätään seuraavalla viestillä:
```text
prefix: "" on varattu palveluntarjoajan etuliite — valitse toinen etuliite (varattuja tunnuksia/aliaksia ei voi käyttää mukautetuissa solmuissa, koska pyynnöt, kuten /model, reititetään sisäänrakennetulle palveluntarjoajalle tai hylätään, kun palveluntarjoaja on poistettu käytöstä)
```
Valitse yksilöllinen etuliite (`mygw`, `acme-proxy`). Jos pyynnöt mukautetulle solmulle epäonnistuvat ja
virheessä mainitaan sisäänrakennettu palveluntarjoaja tai sen tunnistetiedot, tarkista, onko solmun etuliite
varattu: ennen tämän säännön käyttöönottoa tallennetut solmut ovat edelleen tallessa, mutta niiden etuliite reitittää pyynnöt
sisäänrakennetulle palveluntarjoajalle. Muokkaa solmua ja anna sille uusi etuliite.
### OmniRoute-vertaisyhdyskäytävien ketjuttaminen
Toinen OmniRoute-yhdyskäytävä voidaan lisätä **mukautetuksi OpenAI-yhteensopivaksi** palveluntarjoajaksi. Käytä
vertaisyhdyskäytävän `/v1`-perus-URL-osoitetta ja sen myöntämää erillistä, vähimpien oikeuksien periaatteen mukaista API-avainta.
Ota vastavuoroisissa tai monen hypyn ketjuissa valinnainen silmukkasuojaus käyttöön jokaisessa yhdyskäytävässä:
```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
```
Vain nimenomaisesti sallittujen vertaissolmujen URL-osoitteisiin lähetetyt pyynnöt saavat
`X-OmniRoute-Peer-Trace`-otsakkeen. Yhdyskäytävä hylkää toistuvan instanssitunnuksen tai loppuun käytetyn hyppykiintiön
HTTP-virheellä `508 Loop Detected`; tavalliset ylävirran palveluntarjoajat eivät saa vertaissolmujen metatietoja.
Vertaissolmujen ketjutus ei ole tietokannan replikointia eikä isännän vikasietoisuutta. Jokainen yhdyskäytävä ylläpitää itsenäisiä
SQLite-tiloja, välimuisteja, nopeusrajoituslaskureita ja istuntoja. Käytä terveystarkistettua käänteistä välityspalvelinta tai asiakkaan
vikasietoisuutta aktiivi/passiivi- tai aktiivi/aktiivi-saatavuuteen, äläkä koskaan liitä yhtä SQLite-tietokantaa
useisiin käynnissä oleviin OmniRoute-instansseihin.
### Erilliset palveluntarjoajareitit
Reititä pyynnöt suoraan tietylle palveluntarjoajalle mallin validoinnin kanssa:
```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
```
Palveluntarjoajan etuliite lisätään automaattisesti, jos se puuttuu. Yhteensopimattomat mallit palauttavat arvon `400`.
### Verkkovälityspalvelimen määritys
```bash
# Määritä yleinen välityspalvelin
curl -X PUT http://localhost:20128/api/settings/proxy \
-d '{"global": {"type":"http","host":"proxy.example.com","port":"8080"}}'
# Palveluntarjoajakohtainen välityspalvelin
curl -X PUT http://localhost:20128/api/settings/proxy \
-d '{"providers": {"openai": {"type":"socks5","host":"proxy.example.com","port":"1080"}}}'
# Testaa välityspalvelin
curl -X POST http://localhost:20128/api/settings/proxy/test \
-d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}'
```
**Prioriteettijärjestys:** Avainkohtainen → Yhdistelmäkohtainen → Palveluntarjoajakohtainen → Yleinen → Ympäristö.
### Malliluettelon API
```bash
curl http://localhost:20128/api/models/catalog
```
Palauttaa palveluntarjoajan mukaan ryhmitellyt mallit tyyppeineen (`chat`, `embedding`, `image`).
### Pilvisynkronointi
- Synkronoi palveluntarjoajat, yhdistelmät ja asetukset laitteiden välillä
- Automaattinen taustasynkronointi aikakatkaisulla ja nopealla keskeytyksellä
- Suosi tuotannossa palvelinpuolen `NEXT_PUBLIC_BASE_URL`-/`NEXT_PUBLIC_CLOUD_URL`-muuttujia
### Cloudflare Quick Tunnel
- Käytettävissä kohdassa **Dashboard → Endpoints** Dockerille ja muille itse ylläpidetyille käyttöönottoympäristöille
- Luo väliaikaisen `https://*.trycloudflare.com`-URL-osoitteen, joka välittää pyynnöt nykyiseen OpenAI-yhteensopivaan `/v1`-päätepisteeseesi
- Ensimmäinen käyttöönotto asentaa `cloudflared`-ohjelman vain tarvittaessa; myöhemmät uudelleenkäynnistykset käyttävät samaa hallinnoitua binääritiedostoa
- Quick Tunnels -tunneleita ei palauteta automaattisesti OmniRouten tai säilön uudelleenkäynnistyksen jälkeen; ota ne tarvittaessa uudelleen käyttöön hallintapaneelista
- Tunnelien URL-osoitteet ovat väliaikaisia ja vaihtuvat aina, kun pysäytät tai käynnistät tunnelin
- Hallinnoidut Quick Tunnels -tunnelit käyttävät oletuksena HTTP/2-siirtoprotokollaa, jotta rajoitetuissa säilöissä vältetään QUICin UDP-puskuria koskevat tarpeettomat varoitukset
- Aseta `CLOUDFLARED_PROTOCOL=quic` tai `auto`, jos haluat ohittaa hallinnoidun siirtoprotokollan valinnan
- Aseta `CLOUDFLARED_BIN`, jos haluat käyttää esiasennettua `cloudflared`-binääritiedostoa hallinnoidun latauksen sijaan
- Cloudflare Quick Tunnel-, Tailscale Funnel- ja ngrok Tunnel -paneelit voidaan näyttää tai piilottaa kohdassa **Settings → Appearance**. Paneelin piilottaminen ei pysäytä käynnissä olevaa tunnelia.
### LLM-yhdyskäytävän älykkyys (vaihe 9)
- **Semanttinen välimuisti** — Tallentaa automaattisesti välimuistiin suoratoistamattomat vastaukset, joiden lämpötila on 0 (ohita käyttämällä otsaketta `X-OmniRoute-No-Cache: true`)
- **Pyyntöjen idempotenssi** — Poistaa päällekkäiset pyynnöt 5 sekunnin ajalta `Idempotency-Key`- tai `X-Request-Id`-otsakkeen avulla
- **Edistymisen seuranta** — Valinnaiset SSE:n `event: progress` -tapahtumat `X-OmniRoute-Progress: true`-otsakkeen avulla
---
### Kääntäjän kokeiluympäristö
Avaa kohdasta **Dashboard → Translator**. Selvitä ja visualisoi, miten OmniRoute muuntaa API-pyyntöjä palveluntarjoajien välillä.
| Tila | Tarkoitus |
| --------------------------- | --------------------------------------------------------------------------------------------------------- |
| **Kokeiluympäristö** | Valitse lähde- ja kohdemuodot, liitä pyyntö ja näe muunnettu tulos välittömästi |
| **Keskustelutestaaja** | Lähetä reaaliaikaisia keskusteluviestejä välityspalvelimen kautta ja tarkastele koko pyyntö-vastaussykliä |
| **Testipenkki** | Suorita erätestejä useilla muotoyhdistelmillä muunnosten oikeellisuuden varmistamiseksi |
| **Reaaliaikainen seuranta** | Seuraa muunnoksia reaaliajassa pyyntöjen kulkiessa välityspalvelimen kautta |
**Käyttötapaukset:**
- Selvitä, miksi tietty asiakas- ja palveluntarjoajayhdistelmä epäonnistuu
- Varmista, että ajattelutunnisteet, työkalukutsut ja järjestelmäkehotteet muunnetaan oikein
- Vertaa OpenAI-, Claude-, Gemini- ja Responses API -muotojen välisiä eroja
---
### Reititysstrategiat
Määritä kohdassa **Dashboard → Settings → Routing**. Hallintapaneelissa ovat käytettävissä kuusi eniten käytettyä strategiaa; yhdistelmät ja automaattinen reititin tukevat sisäisesti laajempaa valikoimaa.
**Hallintapaneelissa näkyvät strategiat (tilitason reititys):**
| Strategia | Kuvaus |
| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| **Täytä ensimmäinen** | Käyttää tilejä prioriteettijärjestyksessä — ensisijainen tili käsittelee kaikki pyynnöt, kunnes se ei ole käytettävissä |
| **Kiertävä vuorottelu** | Kiertää kaikkien tilien välillä määritettävällä pysyvyysrajalla (oletus: 3 kutsua tiliä kohden) |
| **P2C (kahden vaihtoehdon teho)** | Valitsee 2 satunnaista tiliä ja reitittää terveempään — tasapainottaa kuormaa huomioiden palvelun kunnon |
| **Satunnainen** | Valitsee jokaiselle pyynnölle satunnaisen tilin Fisher–Yates-sekoituksella |
| **Vähiten käytetty** | Reitittää tilille, jolla on vanhin `lastUsedAt`-aikaleima, jakaen liikenteen tasaisesti |
| **Kustannusoptimoitu** | Reitittää tilille, jolla on pienin prioriteettiarvo, optimoiden edullisimpien palveluntarjoajien käyttöä |
**Edistyneet yhdistelmä- ja automaattiset strategiat** (määritettävissä yhdistelmäkohtaisesti tai `auto/*`-etuliitteillä — katso [AUTO-COMBO.md](../routing/AUTO-COMBO.md)):
- `priority` — tiukka järjestys, ei koskaan kiertävää vuorottelua
- `weighted` — liikenteen suhteellinen jako mallikohtaisten painotusten perusteella
- `fill-first` — käyttää ensimmäistä mallia, kunnes rajat saavutetaan
- `round-robin` / `strict-random` / `random`
- `p2c` (kahden vaihtoehdon teho)
- `least-used` ja `cost-optimized`
- `auto` — pisteytykseen perustuva valinta kaikkien ehdokkaiden välillä
- `lkgp` (viimeisin toimivaksi tunnettu palveluntarjoaja) — käyttää viimeisintä onnistunutta palveluntarjoajaa ja siirtyy sitten varasääntöihin
- `context-optimized` — valitsee mallin, jolla on suurin vapaa konteksti-ikkuna
- `context-relay` — ketjuttaa pitkän kontekstin malleja jatkovuoroja varten
#### Ulkoinen pysyvän istunnon otsake
Jos tarvitset ulkoista istuntokohtaista kohdistusta (esimerkiksi Claude Code- tai Codex-agentteja käänteisten välityspalvelinten takana), lähetä:
```http
X-Session-Id: istuntoavaimesi
```
OmniRoute hyväksyy myös `x_session_id`-otsakkeen ja palauttaa käytössä olevan istuntoavaimen `X-OmniRoute-Session-Id`-otsakkeessa.
Jos käytät Nginxiä ja lähetät alaviivoja sisältäviä otsakkeita, ota käyttöön:
```nginx
underscores_in_headers on;
```
#### Jokerimerkkejä sisältävät mallialiakset
Luo jokerimerkkimalleja mallien nimien uudelleenmääritystä varten:
```
Malli: claude-sonnet-* → Kohde: cc/claude-sonnet-4-6
Malli: gpt-* → Kohde: gh/gpt-5.3-codex
```
Jokerimerkit tukevat merkkejä `*` (mitkä tahansa merkit) ja `?` (yksi merkki).
#### Varaketjut
Määritä yleisiä varaketjuja, joita sovelletaan kaikkiin pyyntöihin:
```
Ketju: production-fallback
1. cc/claude-opus-4-7
2. gh/gpt-5.3-codex
3. glm/glm-4.7
```
---
### Yleiset palveluntarjoajayhdistelmät ja reititysmallit
Seuraavassa on esimerkkimalleja useiden palveluntarjoajien yhdistämiseen ja niiden väliseen reititykseen OmniRoutessa:
#### 1. Ohjelmointiagenttiyhdistelmä: edistynyt päättely sekä kustannus- ja nopeuspohjainen varavaihtoehto
Sopii erinomaisesti ohjelmointiagenteille (OpenCode, Claude Code, Cursor, Cline). Reitittää pyynnöt aluksi edistyneille päättelymalleille ja siirtyy nopeisiin ohjelmointimalleihin kiintiön loppuessa tai virhetilanteissa.
- **Hallintapaneeli**: Combos → New Combo → Name: `agent-coding` → Strategy: `Priority`
- **Mallit**:
1. `claude/claude-sonnet-4-6` (ensisijainen ohjelmointiagentti)
2. `openai/gpt-4o` (toissijainen suuren kapasiteetin varavaihtoehto)
3. `deepseek/deepseek-v4-flash` (erittäin tehokas ja kustannustehokas varavaihtoehto)
```bash
# Esimerkki API:n kautta
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. Ilmaistason automaattinen varmistusyhdistelmä
Ketjuttaa useita ilmaistason ja ilman avainta toimivia palveluntarjoajia käytettävyyden maksimoimiseksi ilman API-kustannuksia.
- **Strategia**: `Least Used` tai `Round Robin` (jakaa kuorman kiintiöiden kesken)
- **Mallit**:
1. `groq/llama-3.3-70b-versatile`
2. `gemini/gemini-2.5-flash`
3. `cerebras/gpt-oss-120b`
```bash
# Esimerkki CLI:n kautta
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. Multimodaalinen / kuva- ja tekstiputki
Erikoistuneiden konenäkömallien yhdistäminen nopeaan tekstintuotantoon työnkuluissa, joihin kuuluu kuvien ymmärtäminen ja koodin generointi.
- **Malli**: `Priority`-yhdistelmä, jossa konenäköä tukevat mallit luetellaan ensin ja suuren suorituskyvyn teksti-/koodimalli viimeisenä.
- **Mallit**:
1. `gemini/gemini-2.5-pro` (Vahva kuvien ja multimodaalisen sisällön ymmärtäminen)
2. `openai/gpt-4o` (Tasapainoinen konenäkö ja työkalujen käyttö)
3. `deepseek/deepseek-v4-flash` (Tekstin/koodin generointi)
---
### Vikasietoisuus ja katkaisijat
Määritä kohdassa **Hallintapaneeli → Asetukset → Vikasietoisuus**.
OmniRoute toteuttaa palveluntarjoajatason vikasietoisuuden viidellä komponentilla:
1. **Pyyntöjono ja tahdistus** — Järjestelmätason pyyntöjen hallinta:
- **Pyyntöjä minuutissa (RPM)** — Pyyntöjen enimmäismäärä minuutissa tiliä kohden
- **Pyyntöjen välinen vähimmäisaika** — Pyyntöjen välinen vähimmäisväli millisekunteina
- **Samanaikaisten pyyntöjen enimmäismäärä** — Samanaikaisten pyyntöjen enimmäismäärä tiliä kohden
2. **Yhteyden jäähdytysaika** — Todennustyyppikohtainen määritys yksittäiselle yhteydelle uudelleenyrityksen sallivien virheiden jälkeen:
- **Perusjäähdytysaika** — Oletusarvoinen jäähdytysjakso ylävirran virheille, joiden jälkeen voidaan yrittää uudelleen
- **Käytä ylävirran uudelleenyritysvihjeitä** — Noudattaa ensisijaista `Retry-After`-arvoa tai nollausvihjeitä, kun ne ovat saatavilla
- **Takaisinkytkentävaiheiden enimmäismäärä** — Eksponentiaalisen takaisinkytkennän enimmäistaso toistuville virheille
3. **Palveluntarjoajan katkaisija** — Seuraa palveluntarjoajan päästä päähän -virheitä, merkitsee palveluntarjoajan heikentyneeksi määritetyn varoituskynnyksen kohdalla ja avaa katkaisijan, kun määritetty virhekynnys saavutetaan:
- **Heikentymiskynnys** — Peräkkäisten palveluntarjoajavirheiden määrä ennen `DEGRADED`-tilaan siirtymistä
- **Virhekynnys** — Peräkkäisten palveluntarjoajavirheiden määrä ennen `OPEN`-tilaan siirtymistä
- **Nollauksen aikakatkaisu** — Aikaikkuna ennen palveluntarjoajan testaamista uudelleen
- **CLOSED** (Toimintakuntoinen) — Pyynnöt kulkevat normaalisti
- **DEGRADED** — Pyynnöt kulkevat edelleen samalla, kun kohonnutta virhemäärää seurataan
- **OPEN** — Palveluntarjoaja estetään väliaikaisesti toistuvien virheiden jälkeen
- **HALF_OPEN** — Testataan, onko palveluntarjoaja palautunut
Yhteyskohtaiset `429`-nopeusrajoitukset pysyvät **Yhteyden jäähdytysajassa**, eikä niitä lasketa mukaan palveluntarjoajan katkaisijaan.
Palveluntarjoajan katkaisijan suorituksenaikainen tila näytetään vain kohdassa **Hallintapaneeli → Terveys**.
4. **Odota jäähdytysajan päättymistä** — Jos kaikki mahdolliset yhteydet ovat jo jäähdytystilassa, OmniRoute voi odottaa aikaisimman jäähdytysajan päättymistä ja yrittää samaa asiakaspyyntöä automaattisesti uudelleen.
5. **Nopeusrajoituksen automaattinen tunnistus** — Kun ylävirran palveluntarjoajat palauttavat nimenomaiset odotusajat, nämä vihjeet ohittavat paikallisen yhteyden jäähdytysajan, jos asetus on käytössä.
**Ammattilaisen vinkki:** Tarkastele ja nollaa aktiiviset palveluntarjoajien katkaisijat käyttökatkon jälkeen **Terveys**-sivulla. Vikasietoisuus-sivu muuttaa vain määrityksiä.
---
### Tietokannan vienti/tuonti
Hallitse tietokannan varmuuskopioita kohdassa **Hallintapaneeli → Asetukset → Järjestelmä ja tallennustila**.
| Toiminto | Kuvaus |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Vie tietokanta** | Lataa nykyisen SQLite-tietokannan `.sqlite`-tiedostona |
| **Vie kaikki (.tar.gz)** | Lataa täydellisen varmuuskopioarkiston, joka sisältää tietokannan, asetukset, yhdistelmät, palveluntarjoajayhteydet (ei tunnistetietoja) ja API-avainten metatiedot |
| **Tuo tietokanta** | Lataa palvelimeen `.sqlite`-tiedoston nykyisen tietokannan korvaamiseksi. Tuontia edeltävä varmuuskopio luodaan automaattisesti, ellei `DISABLE_SQLITE_AUTO_BACKUP=true` |
```bash
# API: Vie tietokanta
curl -o backup.sqlite http://localhost:20128/api/db-backups/export
# API: Vie kaikki (täydellinen arkisto)
curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll
# API: Tuo tietokanta
curl -X POST http://localhost:20128/api/db-backups/import \
-F "file=@backup.sqlite"
```
**Tuonnin validointi:** Tuodun tiedoston eheys (SQLite pragma -tarkistus), vaaditut taulut (`provider_connections`, `provider_nodes`, `combos`, `api_keys`) ja koko (enintään 100 Mt) validoidaan.
**Käyttötapaukset:**
- Siirrä OmniRoute koneesta toiseen
- Luo ulkoisia varmuuskopioita katastrofipalautusta varten
- Jaa määrityksiä tiimin jäsenten kesken (vie kaikki → jaa arkisto)
---
### Asetusten hallintapaneeli
Asetussivu on järjestetty **7 välilehteen** helppoa siirtymistä varten:
| Välilehti | Sisältö |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Yleiset** | Järjestelmän tallennustyökalut, oletustoiminta, Endpoint-tunnelin näkyvyys |
| **Ulkoasu** | Teeman asetukset (vaalea/tumma/järjestelmä), sivupalkin näkyvyys, Cloudflare-/Tailscale-/ngrok-tunnelikorttien paneelivalinnat |
| **Tekoäly** | Ajattelubudjetti (läpivienti / automaattinen poisto / mukautettu / adaptiivinen — katso [THINKING_BUDGET.md](./THINKING_BUDGET.md)), yleinen järjestelmäkehote, kehotteiden välimuistitilastot |
| **Suojaus** | Kirjautumis- ja salasana-asetukset, IP-pääsynhallinta, `/models`-rajapinnan API-todennus, palveluntarjoajien esto, kehotesyötteiden suojaus |
| **Reititys** | Yleinen reititysstrategia (täytä ensin / vuorottelu / P2C / satunnainen / vähiten käytetty / kustannusoptimoitu), jokerimerkilliset mallialiakset, varaketjut, yhdistelmien oletusasetukset |
| **Vikasietoisuus** | Pyyntöjono, yhteyksien jäähdytysaika, palveluntarjoajan katkaisijan määritykset ja jäähdytysajan odotustoiminta |
| **Lisäasetukset** | Yleiset välityspalvelinasetukset (HTTP/SOCKS5), palveluntarjoajakohtaiset välityspalvelinasetusten ohitukset |
Yleiset-välilehti ei enää toista vain luku -muotoisia loki- ja välimuisti-ilmoituksia. Tietokannan säilytys- ja
optimointiasetukset tallennetaan `/api/settings/database`-rajapinnan kautta; välimuisti tyhjennetään manuaalisesti
komennolla `DELETE /api/cache`. Pyyntö- ja välityspalvelinlokien rivien enimmäismääriä hallitaan muuttujilla
`CALL_LOGS_TABLE_MAX_ROWS` ja `PROXY_LOGS_TABLE_MAX_ROWS`.
---
### Kustannusten ja budjettien hallinta
Avaa kohdasta **Hallintapaneeli → Kustannukset**.
| Välilehti | Tarkoitus |
| --------------- | ------------------------------------------------------------------------------------------------------------------ |
| **Budjetti** | Aseta API-avainkohtaiset kulutusrajat päivä-, viikko- tai kuukausibudjetteina ja seuraa niitä reaaliajassa |
| **Hinnoittelu** | Tarkastele ja muokkaa mallien hinnoittelutietoja — hinta 1 000 syöte-/tulostetunnusta kohden palveluntarjoajittain |
```bash
# API: Aseta budjetti
curl -X POST http://localhost:20128/api/usage/budget \
-H "Content-Type: application/json" \
-d '{"keyId": "key-123", "limit": 50.00, "period": "monthly"}'
# API: Hae budjetin nykyinen tila
curl http://localhost:20128/api/usage/budget
```
**Kustannusten seuranta:** Jokaisesta pyynnöstä kirjataan tunnusten käyttö ja lasketaan kustannus hinnoittelutaulukon perusteella. Tarkastele palveluntarjoaja-, malli- ja API-avainkohtaisia erittelyjä kohdassa **Hallintapaneeli → Käyttö**.
---
### Äänen litterointi
OmniRoute tukee äänen litterointia OpenAI-yhteensopivan päätepisteen kautta:
```bash
POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data
# Esimerkki curl-komennolla
curl -X POST http://localhost:20128/v1/audio/transcriptions \
-H "Authorization: Bearer your-api-key" \
-F "file=@audio.mp3" \
-F "model=openai/whisper-1"
```
`deepgram/nova-3` on Deepgramin natiivi reitti ja vaatii Deepgramin API-avaimen.
Jos vain OpenRouter on määritetty, käytä mallia `openrouter/deepgram/nova-3`.
**Puheesta tekstiksi (litterointi)** -palveluntarjoajat:
- `openai/` (Whisper-yhteensopiva)
- `groq/` (Groq Whisper Turbo)
- `deepgram/` (Nova-tuoteperhe)
- `assemblyai/`
- `nvidia/` (Parakeet, Canary)
- `huggingface/` (Whisper-muunnelmat)
- `qwen/`
**Tekstistä puheeksi (`POST /v1/audio/speech`)** -palveluntarjoajat:
- `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/`
Litteroinnin tukemat äänimuodot: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. TTS-tulostemuodot riippuvat palveluntarjoajasta (mp3, wav, opus, pcm, mulaw).
---
### Yhdistelmien tasapainotusstrategiat
Määritä yhdistelmäkohtainen tasapainotus kohdassa **Hallintapaneeli → Yhdistelmät → Luo/Muokkaa → Strategia**.
| Strategia | Kuvaus |
| ---------------------- | ------------------------------------------------------------------------------------------- |
| **Vuorottelu** | Käy mallit läpi järjestyksessä |
| **Prioriteetti** | Kokeilee aina ensimmäistä mallia; siirtyy varamalliin vain virheen ilmetessä |
| **Satunnainen** | Valitsee jokaiselle pyynnölle satunnaisen mallin yhdistelmästä |
| **Painotettu** | Reitittää suhteellisesti kullekin mallille määritettyjen painotusten perusteella |
| **Vähiten käytetty** | Reitittää malliin, jolla on vähiten viimeaikaisia pyyntöjä (käyttää yhdistelmän mittareita) |
| **Kustannusoptimoitu** | Reitittää halvimpaan saatavilla olevaan malliin (käyttää hinnoittelutaulukkoa) |
Yhdistelmien yleiset oletusasetukset voidaan määrittää kohdassa **Hallintapaneeli → Asetukset → Reititys → Yhdistelmien oletusasetukset**.
Yhdistelmän kohteiden aikakatkaisut perivät oletusarvoisesti nykyisen pyynnön aikakatkaisun. Käytä yhdistelmien oletusasetusten tai yksittäisen yhdistelmän **Kohteen aikakatkaisu
(sekunteina)** -asetusta vain silloin, kun lyhyemmän kohdekohtaisen rajan tulee
käynnistää nopeampi varareititys.
Viiveettömät yhdistelmäoptimoinnit on otettava erikseen käyttöön. Jätä **Viiveettömät optimoinnit** pois käytöstä,
jotta nämä viiveominaisuudet eivät kilpailuta varakohteita, ohita kohteita TTFT-historian
perusteella tai pakkaa varapyyntöjä; käyttöönotto sallii määritetyn rinnakkaisvarmistuksen, ennakoivat TTFT-
ohitukset ja ennakoivan varapyyntöjen pakkauksen, jolloin reitityksen ja pyyntöjen tarkkuudesta voidaan tinkiä pienemmän
pitkän hännän viiveen saavuttamiseksi.
Poista **päättelytokenien puskuri** käytöstä, kun upstream-palveluntarjoajat edellyttävät tiukkoja
`max_tokens`- / `maxOutputTokens`-rajoja. Kun se on käytössä, yhdistelmäreititys lisää päättelymallien
lisävaran vain malleille, joiden tulostusraja tunnetaan, ja jättää asiakkaan token-rajan ennalleen, jos
turvallinen puskuroitu arvo ylittäisi kyseisen rajan. Jos asiakkaan raja ylittää jo tunnetun rajan,
OmniRoute pienentää sen kyseiseen rajaan ennen upstream-pyynnön lähettämistä.
---
### Kunnon koontinäyttö
Avaa valitsemalla **Koontinäyttö → Kunto**. Reaaliaikainen järjestelmän kunnon yleiskatsaus, jossa on 6 korttia:
| Kortti | Mitä se näyttää |
| ---------------------------- | ------------------------------------------------------------------------ |
| **Järjestelmän tila** | Käyttöaika, versio, muistin käyttö, datahakemisto |
| **Palveluntarjoajien kunto** | Palveluntarjoajien globaalin katkaisijan ajonaikainen tila |
| **Nopeusrajoitukset** | Tilikohtaiset aktiiviset yhteyksien jäähdytysajat ja jäljellä oleva aika |
| **Aktiiviset estot** | Aktiiviset mallikohtaiset estot ja tilapäiset poissulkemiset |
| **Allekirjoitusvälimuisti** | Deduplikointivälimuistin tilastot (aktiiviset avaimet, osumaprosentti) |
| **Latenssitelemetria** | Palveluntarjoajakohtainen p50-/p95-/p99-latenssien aggregointi |
**Ammattilaisen vinkki:** Kunto-sivu päivittyy automaattisesti 10 sekunnin välein. Katkaisijakortin avulla voit tunnistaa, millä palveluntarjoajilla on ongelmia.
---
## 🤖 Automaattinen reititys (ei määrityksiä)
OmniRoute sisältää **pisteytykseen perustuvan automaattisen reitittimen**, joka valitsee kullekin pyynnölle parhaan mallin kaikista yhdistetyistä palveluntarjoajista — ylläpidettävää yhdistelmää ei tarvita. Lähetä pyyntö jollakin `auto/*`-etuliitteellä, niin OmniRoute kokoaa virtuaalisen yhdistelmän lennossa ja pisteyttää ehdokkaat viiveen, kustannusten, onnistumisprosentin, kontekstiin sopivuuden, mallin tehtäväkohtaisen soveltuvuuden, viimeaikaisten virheiden, kiintiön ja katkaisijan tilan perusteella.
| Etuliite | Optimointikohde |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `auto` | Tasapainotettu oletus (viive × kustannukset × onnistumisprosentti) |
| `auto/coding` | Ohjelmointitehtävät: suosii Claudea, GPT-5:tä, GLM:ää, Kimiä, Qwen Coderia ja DeepSeek-koodausmalleja |
| `auto/cheap` | Pienin $/token, hyväksyy suuremman viiveen |
| `auto/fast` | Pienin viive, jättää kustannukset huomiotta |
| `auto/offline` | Vain paikalliset palveluntarjoajat (Ollama, vLLM, llama.cpp) — hyödyllinen eristetyissä ympäristöissä |
| `auto/smart` | Päättelyn laatu etusijalla (Opus, GPT-5 xhigh, R1, GLM 5.1 reasoning) |
| `auto/lkgp` | "Viimeksi toimivaksi todettu palveluntarjoaja" — käyttää viimeksi onnistunutta palveluntarjoajaa ja turvautuu sitten sääntöihin |
Esimerkki:
```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
}'
```
Automaattinen reititin kuvataan kattavasti tiedostossa [AUTO-COMBO.md](../routing/AUTO-COMBO.md) — mukaan lukien pisteytyspainojen säätäminen, palveluntarjoajien lisääminen estolistalle ja reitityspäätösten tarkastelu kohdassa **Koontinäyttö → Auto Combo**.
---
## 🔌 MCP- ja A2A-integraatio
OmniRoute toimii sekä **MCP-palvelimena** (Model Context Protocol) että **A2A-palvelimena** (agenttien välinen JSON-RPC 2.0). Mikä tahansa MCP-yhteensopiva IDE tai agentti-isäntä voi kutsua OmniRouten työkaluja suoraan — ylimääräistä sovitinta ei tarvita.
### MCP-siirtotavat
- **SSE**: `http://localhost:20128/api/mcp/sse`
- **Suoratoistettava HTTP**: `http://localhost:20128/api/mcp/stream`
- **stdio**: `omniroute --mcp` (stdio-siirtotapaa suosiville IDE-laajennuksille)
### Claude Desktopin yhdistäminen
Muokkaa tiedostoa `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) tai vastaavaa tiedostoa Windowsissa/Linuxissa:
```json
{
"mcpServers": {
"omniroute": {
"command": "omniroute",
"args": ["--mcp"]
}
}
}
```
### Cursorin / Continuen / VS Code MCP:n yhdistäminen
Käytä SSE-URL-osoitetta `http://localhost:20128/api/mcp/sse` ja Bearer-API-avainta, joka on luotu kohdassa **Koontinäyttö → API-avaimet**.
### Käyttöoikeusalueet
MCP määrittelee tällä hetkellä 32 nimettyä käyttöoikeusaluetta. Kukin Bearer-avain voidaan rajata tiettyihin käyttöoikeusalueisiin — kattava käyttöoikeusalueiden ja työkalujen luettelo on tiedostossa [MCP-SERVER.md](../frameworks/MCP-SERVER.md), ja JSON-RPC-skeema on tiedostossa [A2A-SERVER.md](../frameworks/A2A-SERVER.md).
---
## 🧠 Taitojärjestelmä
OmniRoute tarjoaa laajennettavan **taitokehyksen** (`src/lib/skills/`), jonka avulla agentit ja A2A-päätepiste voivat suorittaa toimialuekohtaisia rutiineja (esim. `code-review`, `summarize`, `extract-facts`, `web-research`).
- **Markkinapaikan käyttöliittymä** — Selaa ja asenna taitoja kohdassa **Hallintapaneeli → Taidot**
- **Avainkohtaiset käyttöoikeudet** — Rajoita, mitkä API-avaimet voivat kutsua mitäkin taitoja
- **Mukautetut taidot** — Lisää TypeScript-tiedosto hakemistoon `src/lib/a2a/skills/`, rekisteröi se, minkä jälkeen sitä voidaan kutsua välittömästi A2A:n kautta
Täydellinen viite: [SKILLS.md](../frameworks/SKILLS.md).
---
## 💾 Muistijärjestelmä
OmniRoute säilyttää **pitkäkestoisen keskustelumuistin** hybridihakua käyttäen:
- **SQLite FTS5** avainsanahakuihin aiemmista keskusteluvuoroista
- **Qdrant-vektoritietokanta** (valinnainen) semanttiseen palautukseen
- **Automaattinen faktojen poiminta** — entiteetit, mieltymykset ja päätökset tiivistetään jokaisen istunnon jälkeen ja tallennetaan `memory_facts`-tauluun
- Muistit rajataan API-avaimen ja istunnon mukaan
Hallitse muisteja kohdassa **Hallintapaneeli → Muisti** (haku, muokkaus, vienti ja tyhjennys). HTTP-rajapinnan (`/api/memory/*`) avulla agentit voivat lähettää ja hakea faktoja ohjelmallisesti — katso [MEMORY.md](../frameworks/MEMORY.md).
---
## 🔔 Webhookit
Tilaa OmniRoute-tapahtumia reaaliaikaista valvontaa ja automaatiota varten.
- Luo webhook kohdassa **Hallintapaneeli → Webhookit** määrittämällä kohde-URL ja HMAC-allekirjoitussalaisuus
- Saatavilla olevat tapahtumat: `request.completed`, `request.failed`, `provider.unavailable`, `budget.exceeded`, `combo.switched`, `circuit_breaker.opened`, `circuit_breaker.closed`
- Jokainen hyötykuorma sisältää `X-OmniRoute-Signature`-otsakkeen (HMAC-SHA256) tarkistusta varten
- Uudelleenyritykset: 3 yritystä eksponentiaalisella viiveellä, minkä jälkeen tapahtuma siirretään käsittelemättömien viestien jonoon
Täydellinen skeema on tiedostossa [WEBHOOKS.md](../frameworks/WEBHOOKS.md).
---
## ☁️ Pilviagentit
OmniRoute integroituu pilvipohjaisiin koodausagentteihin (**OpenAI Codex Cloud**, **Devin**, **Jules**, **Antigravity**), joten voit lähettää pitkäkestoisia tehtäviä samasta hallintapaneelista, jolla hallitset paikallista reititystä.
- Luo tehtäviä kohdassa **Hallintapaneeli → Pilviagentit** tai käyttäen `POST /api/v1/agents/tasks`
- Seuraa kunkin tehtävän tilaa, lokeja ja artefakteja
- Käytä omaa API-avaintasi kullekin palveluntarjoajalle — tunnistetiedot eivät koskaan poistu OmniRoute-instanssista
Täydellinen viite: [CLOUD_AGENT.md](../frameworks/CLOUD_AGENT.md).
---
## 🛠️ Ohjelmallinen hallinta
Voit hallita kaikkia OmniRoute-resursseja (palveluntarjoajia, yhdistelmiä, avaimia ja asetuksia) HTTP:n kautta käyttämällä **Bearer-avainta, jolla on `manage`-käyttöoikeus**.
Luo avain kohdassa **Hallintapaneeli → API-avaimet → Uusi avain → Käyttöoikeus: manage** ja suorita sitten:
```bash
# Listaa palveluntarjoajat
curl http://localhost:20128/api/providers \
-H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY"
# Lisää palveluntarjoajayhteys
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" }'
# Luo yhdistelmä
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" }] }'
# Listaa/luo API-avaimia
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"] }'
```
Täydellinen päätepisteluettelo sekä pyyntö- ja vastausskeemat ovat tiedostossa [API_REFERENCE.md](../reference/API_REFERENCE.md).
---
## 💻 Sisäinen CLI
OmniRoute sisältää sisäisen CLI:n (`omniroute …`) määritystä, diagnostiikkaa ja suorituksenaikaista hallintaa varten. Tämä on **erillinen hallintapaneelin CLI-työkalut-sivusta**, jolla määritetään kolmansien osapuolten CLI-työkaluja (Claude Code, Cursor, Codex, Cline, …), jotta ne voivat viestiä OmniRouten kanssa.
```bash
omniroute setup # Ohjattu interaktiivinen määritys (salasana, palveluntarjoajat, yhdistelmät)
omniroute setup --non-interactive # Soveltuu CI-ympäristöihin
omniroute doctor # Kuntodiagnostiikka (datahakemisto, tietokanta, palveluntarjoajat, portit)
omniroute providers available # Luettele tuetut palveluntarjoajat
omniroute providers list # Luettele määritetyt yhteydet
omniroute providers test # Testaa palveluntarjoajayhteys reaaliaikaisesti
omniroute combos list # Luettele yhdistelmät
omniroute combos switch # Aseta oletusyhdistelmä
omniroute models # Luettele käytettävissä olevat mallit (--json, --search)
omniroute keys add | list | remove # Hallitse API-avaimia päätteestä
omniroute backup # Luo tilannevedos määrityksistä ja tietokannasta
omniroute restore [] # Palauta tilannevedoksesta
omniroute health # Yksityiskohtaiset kuntotiedot (katkaisimet, välimuisti, muisti)
omniroute quota # Palveluntarjoajien kiintiöiden käyttö
omniroute mcp status # MCP-palvelimen tila
omniroute a2a status # A2A-palvelimen tila
omniroute tunnel list|create|stop # Cloudflare-/Tailscale-/ngrok-tunnelit
omniroute reset-password # Nollaa järjestelmänvalvojan salasana
omniroute --mcp # Käynnistä MCP-palvelin stdio-yhteydellä
omniroute --port 3000 # Käynnistä palvelin mukautetussa portissa
```
Vinkki: yhdistä `omniroute doctor --json` valvontatyökaluusi, jotta saat hälytyksen epäkuntoisista palveluntarjoajayhteyksistä.
---
## 🖥️ Työpöytäsovellus (Electron)
OmniRoute on saatavilla natiivina työpöytäsovelluksena Windowsille, macOS:lle ja Linuxille.
### Asennus
```bash
# electron-hakemistosta:
cd electron
npm install
# Kehitystila (muodostaa yhteyden käynnissä olevaan Next.js-kehityspalvelimeen):
npm run dev
# Tuotantotila (käyttää itsenäistä koontiversiota):
npm start
```
### Asennuspakettien koostaminen
```bash
cd electron
npm run build # Nykyinen alusta
npm run build:win # Windows (.exe NSIS)
npm run build:mac # macOS (.dmg, universaali)
npm run build:linux # Linux (.AppImage)
```
Tuloste → `electron/dist-electron/`
### Keskeiset ominaisuudet
| Ominaisuus | Kuvaus |
| ---------------------------- | -------------------------------------------------------------------------------------------- |
| **Palvelimen valmius** | Tarkistaa palvelimen ennen ikkunan näyttämistä (ei tyhjää näyttöä) |
| **Ilmaisinalue** | Pienennä ilmaisinalueelle, vaihda porttia tai sulje ilmaisinalueen valikosta |
| **Porttien hallinta** | Vaihda palvelimen porttia ilmaisinalueelta (käynnistää palvelimen automaattisesti uudelleen) |
| **Sisällön suojauskäytäntö** | Rajoittava CSP istunto-otsakkeiden kautta |
| **Yksi instanssi** | Vain yksi sovellusinstanssi voi olla käynnissä kerrallaan |
| **Offline-tila** | Pakettiin sisältyvä Next.js-palvelin toimii ilman internetyhteyttä |
### Ympäristömuuttujat
| Muuttuja | Oletusarvo | Kuvaus |
| --------------------- | ---------- | ------------------------------- |
| `OMNIROUTE_PORT` | `20128` | Palvelimen portti |
| `OMNIROUTE_MEMORY_MB` | `512` | Node.js-keon raja (64–16384 Mt) |
📖 Täydellinen dokumentaatio: [`electron/README.md`](../../electron/README.md)