# 🚀 OmniRoute — Gateway AI Gratis (Bahasa Indonesia)

🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇸🇦 [ar](../ar/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇧🇩 [bn](../bn/README.md) · 🇨🇿 [cs](../cs/README.md) · 🇩🇰 [da](../da/README.md) · 🇩🇪 [de](../de/README.md) · 🇪🇸 [es](../es/README.md) · 🇮🇷 [fa](../fa/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇮🇳 [gu](../gu/README.md) · 🇮🇱 [he](../he/README.md) · 🇮🇳 [hi](../hi/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇮🇩 [id](../id/README.md) · 🇮🇹 [it](../it/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇮🇳 [mr](../mr/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇳🇴 [no](../no/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇰🇪 [sw](../sw/README.md) · 🇮🇳 [ta](../ta/README.md) · 🇮🇳 [te](../te/README.md) · 🇹🇭 [th](../th/README.md) · 🇹🇷 [tr](../tr/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇵🇰 [ur](../ur/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md)

---

### Jangan pernah berhenti ngoding. Routing cerdas ke **model AI GRATIS & berbiaya rendah** dengan fallback otomatis.

_Proxy API universal Anda — satu endpoint, 100+ penyedia, tanpa downtime. Kini dengan **MCP Server (25 alat)**, **Protokol A2A**, **Sistem Memori/Skill** & **Aplikasi Desktop Electron**._

**Chat Completions • Embeddings • Pembuatan Gambar • Video • Musik • Audio • Reranking • **Pencarian Web** • MCP Server • Protokol A2A • 100% TypeScript**

---

<div align="center">

[![npm version](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute)
[![Docker Hub](https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https://hub.docker.com/r/diegosouzapw/omniroute)

![NPM Downloads](https://img.shields.io/npm/dw/omniroute?label=npm%20down%20week&color=red)
![NPM Downloads](https://img.shields.io/npm/dm/omniroute?label=npm%20down%20month&color=red)

![NPM Downloads](https://img.shields.io/npm/d18m/omniroute?label=npm%20down%20year&color=red)
![Docker Pulls](https://img.shields.io/docker/pulls/diegosouzapw/omniroute)
![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/diegosouzapw/omniroute/total?style=flat&label=eletron%20donwloads&color=blue)

[![stars](https://custom-icon-badges.demolab.com/github/stars/diegosouzapw/OmniRoute?logo=star&style=flat)](https://github.com/diegosouzapw/OmniRoute/stargazers)
[![open issues](https://custom-icon-badges.demolab.com/github/issues-raw/diegosouzapw/OmniRoute?logo=issue)](https://github.com/diegosouzapw/OmniRoute/issues)
[![license](https://custom-icon-badges.demolab.com/github/license/diegosouzapw/OmniRoute?logo=law)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
[![last commit](https://custom-icon-badges.demolab.com/github/last-commit/diegosouzapw/OmniRoute?logo=history&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/commits/main)
[![total contributions](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=graph&logoColor=fff&color=blue&label=total%20contributions&query=%24.totalContributions&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)
[![code size](https://custom-icon-badges.demolab.com/github/languages/code-size/diegosouzapw/OmniRoute?logo=file-code&logoColor=white)](https://github.com/diegosouzapw/OmniRoute)
[![pr closed](https://custom-icon-badges.demolab.com/github/issues-pr-closed/diegosouzapw/OmniRoute?color=purple&logo=git-pull-request&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/pulls?q=is%3Apr+is%3Aclosed)
[![tag](https://custom-icon-badges.demolab.com/github/v/tag/diegosouzapw/OmniRoute?logo=tag&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/tags)
[![github streak](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=fire&logoColor=fff&color=orange&label=github%20streak&query=%24.currentStreak.length&suffix=%20days&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)
[![followers](https://custom-icon-badges.demolab.com/github/followers/diegosouzapw?logo=person-add)](https://github.com/diegosouzapw?tab=followers)
[![fork](https://custom-icon-badges.demolab.com/github/forks/diegosouzapw/OmniRoute?logo=fork)](https://github.com/diegosouzapw/OmniRoute/network/members)
[![watch](https://custom-icon-badges.demolab.com/github/watchers/diegosouzapw/OmniRoute?logo=eye)](https://github.com/diegosouzapw/OmniRoute/watchers)

[![License](https://img.shields.io/github/license/diegosouzapw/OmniRoute)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
[![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online)
[![WhatsApp](https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)

[🌐 Website](https://omniroute.online) • [🚀 Mulai Cepat](#-quick-start) • [💡 Fitur](#-key-features) • [📖 Dokumentasi](#-documentation) • [💰 Harga](#-pricing-at-a-glance) • [💬 WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)

</div>

🌐 **Available in:** 🇺🇸 [English](README.md) | 🇧🇷 [Português (Brasil)](docs/i18n/pt-BR/README.md) | 🇪🇸 [Español](docs/i18n/es/README.md) | 🇫🇷 [Français](docs/i18n/fr/README.md) | 🇮🇹 [Italiano](docs/i18n/it/README.md) | 🇷🇺 [Русский](docs/i18n/ru/README.md) | 🇨🇳 [中文 (简体)](docs/i18n/zh-CN/README.md) | 🇩🇪 [Deutsch](docs/i18n/de/README.md) | 🇮🇳 [हिन्दी](docs/i18n/in/README.md) | 🇹🇭 [ไทย](docs/i18n/th/README.md) | 🇺🇦 [Українська](docs/i18n/uk-UA/README.md) | 🇸🇦 [العربية](docs/i18n/ar/README.md) | 🇯🇵 [日本語](docs/i18n/ja/README.md) | 🇻🇳 [Tiếng Việt](docs/i18n/vi/README.md) | 🇧🇬 [Български](docs/i18n/bg/README.md) | 🇩🇰 [Dansk](docs/i18n/da/README.md) | 🇫🇮 [Suomi](docs/i18n/fi/README.md) | 🇮🇱 [עברית](docs/i18n/he/README.md) | 🇭🇺 [Magyar](docs/i18n/hu/README.md) | 🇮🇩 [Bahasa Indonesia](docs/i18n/id/README.md) | 🇰🇷 [한국어](docs/i18n/ko/README.md) | 🇲🇾 [Bahasa Melayu](docs/i18n/ms/README.md) | 🇳🇱 [Nederlands](docs/i18n/nl/README.md) | 🇳🇴 [Norsk](docs/i18n/no/README.md) | 🇵🇹 [Português (Portugal)](docs/i18n/pt/README.md) | 🇷🇴 [Română](docs/i18n/ro/README.md) | 🇵🇱 [Polski](docs/i18n/pl/README.md) | 🇸🇰 [Slovenčina](docs/i18n/sk/README.md) | 🇸🇪 [Svenska](docs/i18n/sv/README.md) | 🇵🇭 [Filipino](docs/i18n/phi/README.md) | 🇨🇿 [Čeština](docs/i18n/cs/README.md)

---

## 🖼️ Dashboard Utama

<div align="center">
  <img src="./docs/screenshots/MainOmniRoute.png" alt="OmniRoute Dashboard" width="800"/>
</div>

---

## 📸 Pratinjau Dashboard

<details>
<summary><b>Klik untuk melihat tangkapan layar dashboard</b></summary>

| Halaman        | Tangkapan Layar                                   |
| -------------- | ------------------------------------------------- |
| **Providers**  | ![Providers](docs/screenshots/01-providers.png)   |
| **Combos**     | ![Combos](docs/screenshots/02-combos.png)         |
| **Analytics**  | ![Analytics](docs/screenshots/03-analytics.png)   |
| **Health**     | ![Health](docs/screenshots/04-health.png)         |
| **Translator** | ![Translator](docs/screenshots/05-translator.png) |
| **Settings**   | ![Settings](docs/screenshots/06-settings.png)     |
| **CLI Tools**  | ![CLI Tools](docs/screenshots/07-cli-tools.png)   |
| **Usage Logs** | ![Usage](docs/screenshots/08-usage.png)           |
| **Endpoints**  | ![Endpoints](docs/screenshots/09-endpoint.png)    |

</details>

---

### 🤖 Penyedia AI Gratis untuk agen coding favorit Anda

_Hubungkan IDE atau alat CLI berbasis AI apa pun melalui OmniRoute — gateway API gratis untuk coding tanpa batas._

  <table>
    <tr>
      <td align="center" width="110">
        <a href="https://github.com/openclaw/openclaw">
          <img src="./public/providers/openclaw.png" alt="OpenClaw" width="48"/><br/>
          <b>OpenClaw</b>
        </a><br/>
        <sub>⭐ 205K</sub>
      </td>
      <td align="center" width="110">
        <a href="https://github.com/HKUDS/nanobot">
          <img src="./public/providers/nanobot.png" alt="NanoBot" width="48"/><br/>
          <b>NanoBot</b>
        </a><br/>
        <sub>⭐ 20.9K</sub>
      </td>
      <td align="center" width="110">
        <a href="https://github.com/sipeed/picoclaw">
          <img src="./public/providers/picoclaw.jpg" alt="PicoClaw" width="48"/><br/>
          <b>PicoClaw</b>
        </a><br/>
        <sub>⭐ 14.6K</sub>
      </td>
      <td align="center" width="110">
        <a href="https://github.com/zeroclaw-labs/zeroclaw">
          <img src="./public/providers/zeroclaw.png" alt="ZeroClaw" width="48"/><br/>
          <b>ZeroClaw</b>
        </a><br/>
        <sub>⭐ 9.9K</sub>
      </td>
      <td align="center" width="110">
        <a href="https://github.com/nearai/ironclaw">
          <img src="./public/providers/ironclaw.png" alt="IronClaw" width="48"/><br/>
          <b>IronClaw</b>
        </a><br/>
        <sub>⭐ 2.1K</sub>
      </td>
    </tr>
    <tr>
      <td align="center" width="110">
        <a href="https://github.com/anomalyco/opencode">
          <img src="./public/providers/opencode.svg" alt="OpenCode" width="48"/><br/>
          <b>OpenCode</b>
        </a><br/>
        <sub>⭐ 106K</sub>
      </td>
      <td align="center" width="110">
        <a href="https://github.com/openai/codex">
          <img src="./public/providers/codex.svg" alt="Codex CLI" width="48"/><br/>
          <b>Codex CLI</b>
        </a><br/>
        <sub>⭐ 60.8K</sub>
      </td>
      <td align="center" width="110">
        <a href="https://github.com/anthropics/claude-code">
          <img src="./public/providers/claude.svg" alt="Claude Code" width="48"/><br/>
          <b>Claude Code</b>
        </a><br/>
        <sub>⭐ 67.3K</sub>
      </td>
      <td align="center" width="110">
        <a href="https://github.com/google-gemini/gemini-cli">
          <img src="./public/providers/gemini-cli.svg" alt="Gemini CLI" width="48"/><br/>
          <b>Gemini CLI</b>
        </a><br/>
        <sub>⭐ 94.7K</sub>
      </td>
      <td align="center" width="110">
        <a href="https://github.com/Kilo-Org/kilocode">
          <img src="./public/providers/kilocode.svg" alt="Kilo Code" width="48"/><br/>
          <b>Kilo Code</b>
        </a><br/>
        <sub>⭐ 15.5K</sub>
      </td>
    </tr>
  </table>

<sub>📡 Semua agen terhubung melalui <code>http://localhost:20128/v1</code> atau <code>http://cloud.omniroute.online/v1</code> — satu konfigurasi, model dan kuota tak terbatas</sub>

---

## 🤔 Mengapa OmniRoute?

**Berhenti membuang uang dan terus mencapai batas:**

- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> Kuota langganan kedaluwarsa tanpa digunakan setiap bulan
- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> Batas rate menghentikan Anda di tengah sesi coding
- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> API mahal ($20-50/bulan per penyedia)
- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> Perpindahan manual antar penyedia

**OmniRoute mengatasi ini:**

- ✅ **Maksimalkan langganan** - Pantau kuota, gunakan setiap bit sebelum reset
- ✅ **Fallback otomatis** - Langganan → Kunci API → Murah → Gratis, tanpa downtime
- ✅ **Multi-akun** - Round-robin antar akun per penyedia
- ✅ **Universal** - Bekerja dengan Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, alat CLI apa pun

---

## 📧 Dukungan

> 💬 **Bergabunglah dengan komunitas kami!** [Grup WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Dapatkan bantuan, berbagi tips, dan tetap terupdate.

- **Website**: [omniroute.online](https://omniroute.online)
- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
- **WhatsApp**: [Grup Komunitas](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
- **Berkontribusi**: Lihat [CONTRIBUTING.md](CONTRIBUTING.md), buka PR, atau pilih `good first issue`

### 🐛 Melaporkan Bug?

Saat membuka issue, jalankan perintah system-info dan lampirkan file yang dihasilkan:

```bash
npm run system-info
```

Perintah ini menghasilkan `system-info.txt` berisi versi Node.js, versi OmniRoute, detail OS, alat CLI yang terpasang (qoder, gemini, claude, codex, antigravity, droid, dll.), status Docker/PM2, dan paket sistem — semua yang dibutuhkan untuk mereproduksi masalah Anda dengan cepat. Lampirkan file tersebut langsung ke GitHub issue Anda.

---

## 🔄 Cara Kerjanya

```
┌─────────────┐
│  CLI Anda   │  (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)
│   Tool      │
└──────┬──────┘
       │ http://localhost:20128/v1
       ↓
┌─────────────────────────────────────────┐
│           OmniRoute (Router Cerdas)       │
│  • Translasi format (OpenAI ↔ Claude)   │
│  • Pelacakan kuota + Embeddings + Gambar│
│  • Refresh token otomatis               │
└──────┬──────────────────────────────────┘
       │
       ├─→ [Tier 1: LANGGANAN] Claude Code, Codex, Gemini CLI
       │   ↓ kuota habis
       ├─→ [Tier 2: KUNCI API] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, dll.
       │   ↓ batas anggaran
       ├─→ [Tier 3: MURAH] GLM ($0.6/1M), MiniMax ($0.2/1M)
       │   ↓ batas anggaran
       └─→ [Tier 4: GRATIS] Qoder, Qwen, Kiro (tidak terbatas)

Hasil: Tidak pernah berhenti coding, biaya minimal
```

---

## 🎯 Apa yang Diselesaikan OmniRoute — 30 Masalah Nyata & Kasus Penggunaan

> **Setiap developer yang menggunakan alat AI menghadapi masalah ini setiap hari.** OmniRoute dibangun untuk menyelesaikannya semua — dari pembengkakan biaya hingga pemblokiran regional, dari alur OAuth yang rusak hingga operasi protokol dan observabilitas enterprise.

<details>
<summary><b>💸 1. "Saya membayar langganan mahal tapi masih terganggu oleh batas"</b></summary>

Developer membayar $20–200/bulan untuk Claude Pro, Codex Pro, atau GitHub Copilot. Meski sudah membayar, kuota memiliki batas — 5 jam penggunaan, batas mingguan, atau batas rate per menit. Di tengah sesi coding, penyedia berhenti merespons dan developer kehilangan fokus dan produktivitas.

**Cara OmniRoute menyelesaikannya:**

- **Fallback 4-Tier Cerdas** — Jika kuota langganan habis, secara otomatis mengarahkan ke Kunci API → Murah → Gratis tanpa intervensi manual
- **Pelacakan Batas Penyedia** — Snapshot kuota yang di-cache diperbarui sesuai jadwal sisi server (default `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES=70`) dengan pembaruan manual tersedia di UI
- **Dukungan Multi-Akun** — Beberapa akun per penyedia dengan round-robin otomatis — saat satu habis, beralih ke berikutnya
- **Combo Kustom** — Rantai fallback yang dapat dikustomisasi dengan 13 strategi penyeimbangan (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, **context-relay**)
- **Pembangun Combo Terstruktur** — Buat combo langkah demi langkah dengan pemilihan penyedia + model + akun yang eksplisit, termasuk penyedia berulang dan target akun tetap
- **P2C Berbasis Kuota** — Pemilihan akun power-of-two kini mempertimbangkan kapasitas kuota, backoff, kesalahan terkini, dan penggunaan berturut-turut
- **Kuota Bisnis Codex** — Pemantauan kuota workspace Business/Team langsung di dashboard

</details>

<details>
<summary><b>🔌 2. "Saya perlu menggunakan beberapa penyedia tetapi masing-masing memiliki API berbeda"</b></summary>

OpenAI menggunakan satu format, Claude (Anthropic) menggunakan format lain, Gemini pun berbeda lagi. Jika seorang developer ingin menguji model dari penyedia berbeda atau melakukan fallback di antara mereka, mereka perlu mengonfigurasi ulang SDK, mengganti endpoint, dan menangani format yang tidak kompatibel. Penyedia kustom (FriendLI, NIM) memiliki endpoint model non-standar.

**Cara OmniRoute menyelesaikannya:**

- **Endpoint Terpadu** — Satu `http://localhost:20128/v1` berfungsi sebagai proxy untuk semua 100+ penyedia
- **Translasi Format** — Otomatis dan transparan: OpenAI ↔ Claude ↔ Gemini ↔ Responses API
- **Sanitasi Respons** — Menghapus field non-standar (`x_groq`, `usage_breakdown`, `service_tier`) yang merusak OpenAI SDK v1.83+
- **Normalisasi Peran** — Mengonversi `developer` → `system` untuk penyedia non-OpenAI; `system` → `user` untuk GLM/ERNIE
- **Ekstraksi Tag Think** — Mengekstrak blok `<think>` dari model seperti DeepSeek R1 ke `reasoning_content` yang terstandarisasi
- **Output Terstruktur untuk Gemini** — Konversi otomatis `json_schema` → `responseMimeType`/`responseSchema`
- **`stream` default ke `false`** — Selaras dengan spesifikasi OpenAI, menghindari SSE tak terduga di SDK Python/Rust/Go

</details>

<details>
<summary><b>🌐 3. "Penyedia AI saya memblokir wilayah/negara saya"</b></summary>

Penyedia seperti OpenAI/Codex memblokir akses dari wilayah geografis tertentu. Pengguna mendapat kesalahan seperti `unsupported_country_region_territory` saat OAuth dan koneksi API. Ini sangat membuat frustasi para developer dari negara berkembang.

**Cara OmniRoute menyelesaikannya:**

- **Konfigurasi Proxy 3-Level** — Proxy yang dapat dikonfigurasi di 3 level: global (semua lalu lintas), per-penyedia (hanya satu penyedia), dan per-koneksi/kunci
- **Lencana Proxy Berkode Warna** — Indikator visual: 🟢 proxy global, 🟡 proxy penyedia, 🔵 proxy koneksi, selalu menampilkan IP
- **Pertukaran Token OAuth Melalui Proxy** — Alur OAuth juga melewati proxy, menyelesaikan masalah `unsupported_country_region_territory`
- **Uji Koneksi via Proxy** — Uji koneksi menggunakan proxy yang dikonfigurasi (tidak ada lagi bypass langsung)
- **Dukungan SOCKS5** — Dukungan proxy SOCKS5 penuh untuk routing keluar
- **Spoofing Sidik Jari TLS** — Sidik jari TLS seperti browser melalui `wreq-js` untuk melewati deteksi bot
- **🔏 Pencocokan Sidik Jari CLI** — Menyusun ulang header dan field body agar sesuai dengan tanda tangan biner CLI asli, sangat mengurangi risiko pemanduan akun. IP proxy tetap dipertahankan — Anda mendapatkan kesiluman **dan** penyamaran IP secara bersamaan

</details>

<details>
<summary><b>🆓 4. "Saya ingin menggunakan AI untuk coding tapi tidak punya uang"</b></summary>

Tidak semua orang bisa membayar $20–200/bulan untuk langganan AI. Pelajar, developer dari negara berkembang, penghobi, dan freelancer membutuhkan akses ke model berkualitas tanpa biaya sama sekali.

**Cara OmniRoute menyelesaikannya:**

- **Penyedia Tier Gratis Bawaan** — Dukungan asli untuk penyedia 100% gratis: Qoder (5 model tak terbatas via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 model tak terbatas: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID gratis), Gemini CLI (180K token/bulan gratis)
- **Ollama Cloud** — Model Ollama yang di-host di cloud pada `api.ollama.com` dengan tier "Light usage" gratis; gunakan prefix `ollamacloud/<model>`
- **Combo Hanya Gratis** — Rantai `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = $0/bulan tanpa downtime
- **Akses Gratis NVIDIA NIM** — ~40 RPM akses gratis selamanya untuk 70+ model di build.nvidia.com (beralih dari kredit ke batas rate murni)
- **Strategi Optimasi Biaya** — Strategi routing yang secara otomatis memilih penyedia termurah yang tersedia

</details>

<details>
<summary><b>🔒 5. "Saya perlu melindungi gateway AI saya dari akses tidak sah"</b></summary>

Saat mengekspos gateway AI ke jaringan (LAN, VPS, Docker), siapa pun yang memiliki alamat tersebut dapat mengonsumsi token/kuota developer. Tanpa perlindungan, API rentan terhadap penyalahgunaan, injeksi prompt, dan eksploitasi.

**Cara OmniRoute menyelesaikannya:**

- **Manajemen Kunci API** — Pembuatan, rotasi, dan pembatasan lingkup per penyedia dengan halaman `/dashboard/api-manager` yang didedikasikan
- **Izin Tingkat Model** — Batasi kunci API ke model tertentu (`openai/*`, pola wildcard), dengan toggle Izinkan Semua/Batasi
- **Perlindungan Endpoint API** — Wajibkan kunci untuk `/v1/models` dan blokir penyedia tertentu dari daftar
- **Auth Guard + Perlindungan CSRF** — Semua rute dashboard dilindungi dengan middleware `withAuth` + token CSRF
- **Pembatas Rate** — Pembatasan rate per-IP dengan jendela yang dapat dikonfigurasi
- **Penyaringan IP** — Allowlist/blocklist untuk kontrol akses
- **Penjaga Injeksi Prompt** — Sanitasi terhadap pola prompt berbahaya
- **Enkripsi AES-256-GCM** — Kredensial dienkripsi saat disimpan

</details>

<details>
<summary><b>🛑 6. "Penyedia saya mati dan saya kehilangan alur coding"</b></summary>

Penyedia AI bisa menjadi tidak stabil, mengembalikan kesalahan 5xx, atau mencapai batas rate sementara. Jika developer bergantung pada satu penyedia, mereka akan terganggu. Tanpa circuit breaker, percobaan ulang berulang dapat menyebabkan aplikasi crash.

**Cara OmniRoute menyelesaikannya:**

- **Antrian & Pacing Permintaan** — Bucket permintaan per-koneksi memperhalus lonjakan sebelum mencapai batas rate upstream
- **Pendinginan Koneksi** — Satu koneksi mendingin setelah kegagalan yang dapat dicoba ulang dengan petunjuk `Retry-After` upstream opsional dan backoff eksponensial
- **Circuit Breaker Penyedia** — Penyedia hanya trip setelah fallback habis dan permintaan penyedia masih gagal dengan kesalahan transien seluruh penyedia; batas rate `429` yang terikat koneksi tetap di Pendinginan Koneksi
- **Tunggu Pendinginan** — Server dapat menunggu pendinginan koneksi paling awal berakhir dan mencoba ulang permintaan klien yang sama secara otomatis
- **Anti-Thundering Herd** — Perlindungan mutex + semaphore terhadap badai percobaan ulang bersamaan
- **Rantai Fallback Combo** — Jika penyedia utama gagal, secara otomatis jatuh ke rantai berikutnya tanpa intervensi
- **Dashboard Kesehatan** — Pemantauan uptime, status circuit breaker penyedia, pendinginan, statistik cache, latensi p50/p95/p99

</details>

<details>
<summary><b>🔧 7. "Mengonfigurasi setiap alat AI membosankan dan berulang"</b></summary>

Developer menggunakan Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Setiap alat memerlukan konfigurasi berbeda (endpoint API, kunci, model). Mengonfigurasi ulang saat berganti penyedia atau model adalah pemborosan waktu.

**Cara OmniRoute menyelesaikannya:**

- **Dashboard Alat CLI** — Halaman khusus dengan pengaturan satu klik untuk Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline
- **Generator Konfigurasi GitHub Copilot** — Menghasilkan `chatLanguageModels.json` untuk VS Code dengan pemilihan model massal
- **Wizard Orientasi** — Pengaturan terpandu 4 langkah untuk pengguna pertama kali
- **Satu endpoint, semua model** — Konfigurasi `http://localhost:20128/v1` sekali, akses 100+ penyedia

</details>

<details>
<summary><b>🔑 8. "Mengelola token OAuth dari beberapa penyedia adalah mimpi buruk"</b></summary>

Claude Code, Codex, Gemini CLI, Copilot — semua menggunakan OAuth 2.0 dengan token yang kedaluwarsa. Developer perlu mengautentikasi ulang terus-menerus, menangani `client_secret is missing`, `redirect_uri_mismatch`, dan kegagalan di server jarak jauh. OAuth di LAN/VPS sangat bermasalah.

**Cara OmniRoute menyelesaikannya:**

- **Refresh Token Otomatis** — Token OAuth diperbarui di latar belakang sebelum kedaluwarsa
- **OAuth 2.0 (PKCE) Bawaan** — Alur otomatis untuk Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, Qoder
- **OAuth Multi-Akun** — Beberapa akun per penyedia melalui ekstraksi token JWT/ID
- **Perbaikan OAuth LAN/Jarak Jauh** — Deteksi IP privat untuk `redirect_uri` + mode URL manual untuk server jarak jauh
- **OAuth di Balik Nginx** — Menggunakan `window.location.origin` untuk kompatibilitas reverse proxy
- **Panduan OAuth Jarak Jauh** — Panduan langkah demi langkah untuk kredensial Google Cloud di VPS/Docker

</details>

<details>
<summary><b>📊 9. "Saya tidak tahu berapa banyak yang saya belanjakan atau di mana"</b></summary>

Developer menggunakan beberapa penyedia berbayar tetapi tidak memiliki tampilan pengeluaran yang terpadu. Setiap penyedia memiliki dashboard penagihan sendiri, tetapi tidak ada tampilan konsolidasi. Biaya tak terduga bisa menumpuk.

**Cara OmniRoute menyelesaikannya:**

- **Dashboard Analitik Biaya** — Pelacakan biaya per-token dan manajemen anggaran per penyedia
- **Batas Anggaran per Tier** — Batas pengeluaran per tier yang memicu fallback otomatis
- **Konfigurasi Harga Per-Model** — Harga yang dapat dikonfigurasi per model
- **Statistik Penggunaan Per Kunci API** — Jumlah permintaan dan cap waktu terakhir digunakan per kunci
- **Dashboard Analitik** — Kartu statistik, grafik penggunaan model, tabel penyedia dengan tingkat keberhasilan dan latensi

</details>

<details>
<summary><b>🐛 10. "Saya tidak dapat mendiagnosis kesalahan dan masalah dalam panggilan AI"</b></summary>

Saat panggilan gagal, pengembang tidak mengetahui apakah itu batas kecepatan, token kedaluwarsa, format salah, atau kesalahan penyedia. Log terfragmentasi di terminal yang berbeda. Tanpa observabilitas, debugging adalah trial-and-error.

**Bagaimana OmniRoute menyelesaikannya:**

- **Dasbor Log Terpadu** — 4 tab: Log Permintaan, Log Proksi, Log Audit, Konsol
- **Penampil Log Konsol** — Penampil gaya terminal real-time dengan level kode warna, gulir otomatis, pencarian, filter
- **Log Ringkasan SQLite** — Indeks log permintaan dan proksi tetap dapat dikueri saat restart tanpa memuat blob payload besar ke SQLite
- **Translator Playground** — 4 mode debugging: Playground (terjemahan format), Chat Tester (pulang pergi), Test Bench (batch), Live Monitor (real-time)
- **Telemetri Permintaan** — latensi p50/p95/p99 + penelusuran X-Request-Id
- **Artefak Detail Berbasis File** — Log aplikasi dirotasi berdasarkan ukuran, hari penyimpanan, dan jumlah arsip; payload permintaan/respons terperinci ada di `DATA_DIR/call_logs/` dan diputar secara independen dari ringkasan SQLite
- **Laporan Info Sistem** — `npm run system-info` menghasilkan `system-info.txt` dengan lingkungan lengkap Anda (versi Node, versi OmniRoute, OS, alat CLI, status Docker/PM2). Lampirkan saat melaporkan masalah untuk triase instan.

</details>

<details>
<summary><b>🏗️ 11. "Menyebarkan dan memelihara gateway itu rumit"</b></summary>

Menginstal, mengonfigurasi, dan memelihara proksi AI di berbagai lingkungan (lokal, VPS, Docker, cloud) membutuhkan banyak tenaga. Masalah seperti jalur hardcode, `EACCES` pada direktori, konflik port, dan pembangunan lintas platform menambah gesekan.

**Bagaimana OmniRoute menyelesaikannya:**

- **instal global npm** — `npm install -g omniroute && omniroute` — selesai
- **Docker Multi-Platform** — asli AMD64 + ARM64 (Apple Silicon, AWS Graviton, Raspberry Pi)
- **Docker Compose Profiles** — `base` (tanpa alat CLI) dan `cli` (dengan Claude Code, Codex, OpenClaw)
- **Aplikasi Desktop Electron** — Aplikasi asli untuk Windows/macOS/Linux dengan baki sistem, mulai otomatis, mode offline
- **Mode Port Terpisah** — API dan Dasbor pada port terpisah untuk skenario tingkat lanjut (proksi terbalik, jaringan kontainer)
- **Cloud Sync** — Konfigurasi sinkronisasi antar perangkat melalui Cloudflare Workers
- **DB Backups** — Pencadangan otomatis, pemulihan, ekspor dan impor semua pengaturan, dengan `DISABLE_SQLITE_AUTO_BACKUP` untuk pencadangan yang dikelola secara eksternal

</details>

<details>
<summary><b>🌍 12. "Antarmuka hanya berbahasa Inggris dan tim saya tidak bisa berbahasa Inggris"</b></summary>

Tim di negara-negara yang tidak berbahasa Inggris, khususnya di Amerika Latin, Asia, dan Eropa, kesulitan dengan antarmuka yang hanya berbahasa Inggris. Hambatan bahasa mengurangi adopsi dan meningkatkan kesalahan konfigurasi.

**Bagaimana OmniRoute menyelesaikannya:**

- **Dasbor i18n — 30 Bahasa** — 500+ tombol diterjemahkan termasuk Arab, Bulgaria, Denmark, Jerman, Spanyol, Finlandia, Prancis, Ibrani, Hindi, Hungaria, Indonesia, Italia, Jepang, Korea, Melayu, Belanda, Norwegia, Polandia, Portugis (PT/BR), Rumania, Rusia, Slovakia, Swedia, Thailand, Ukraina, Vietnam, China, Filipina, Inggris
- **Dukungan RTL** — Dukungan kanan ke kiri untuk bahasa Arab dan Ibrani
- **README Multi-Bahasa** — 30 terjemahan dokumentasi lengkap
- **Pemilih Bahasa** — Ikon bola dunia di header untuk peralihan waktu nyata

</details>

<details>
<summary><b>🔄 13. "Saya memerlukan lebih dari sekedar chat — saya memerlukan embeddings, gambar, audio"</b></summary>

AI bukan hanya penyelesaian obrolan. Pengembang perlu membuat gambar, mentranskripsikan audio, membuat penyematan untuk RAG, mengubah peringkat dokumen, dan memoderasi konten. Setiap API memiliki titik akhir dan format yang berbeda.

**Bagaimana OmniRoute menyelesaikannya:**

- **Sematan** — `/v1/embeddings` dengan 6 penyedia dan 9+ model
- **Pembuatan Gambar** — `/v1/images/generations` dengan 10 penyedia dan 20+ model (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)
- **Teks-ke-Video** — `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) dan SD WebUI
- **Teks-ke-Musik** — `/v1/music/generations` — ComfyUI (Audio Terbuka Stabil, MusicGen)
- **Transkripsi Audio** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3
- **Text-to-Speech** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld**, **Cartesia**, **PlayHT**, + penyedia yang ada
- **Moderasi** — `/v1/moderations` — Pemeriksaan keamanan konten
- **Pemeringkatan ulang** — `/v1/rerank` — Pemeringkatan ulang relevansi dokumen
- **Respon API** — Dukungan penuh `/v1/responses` untuk Codex

</details>

<details>
<summary><b>🧪 14. "Saya tidak punya cara untuk menguji dan membandingkan kualitas antar model"</b></summary>

Pengembang ingin mengetahui model mana yang terbaik untuk kasus penggunaan mereka — kode, terjemahan, penalaran — tetapi membandingkan secara manual itu lambat. Tidak ada alat evaluasi terintegrasi.

**Bagaimana OmniRoute menyelesaikannya:**

- **Evaluasi LLM** — Pengujian set emas dengan 10 kasus yang dimuat sebelumnya yang mencakup salam, matematika, geografi, pembuatan kode, kepatuhan JSON, terjemahan, penurunan harga, penolakan keamanan
- **4 Strategi Pertandingan** — `exact`, `contains`, `regex`, `custom` (fungsi JS)
- **Bangku Tes Taman Bermain Penerjemah** — Pengujian batch dengan banyak masukan dan keluaran yang diharapkan, perbandingan lintas penyedia
- **Penguji Obrolan** — Perjalanan bolak-balik penuh dengan rendering respons visual
- **Monitor Langsung** — Aliran real-time dari semua permintaan yang mengalir melalui proxy

</details>

<details>
<summary><b>📈 15. "Saya perlu meningkatkan skala tanpa kehilangan performa"</b></summary>

Seiring bertambahnya volume permintaan, tanpa menyimpan pertanyaan yang sama akan menghasilkan biaya duplikat. Tanpa idempotensi, permintaan duplikat akan membuang-buang pemrosesan. Batasan tarif per penyedia harus dipatuhi.

**Bagaimana OmniRoute menyelesaikannya:**

- **Cache Semantik** — Cache dua tingkat (tanda tangan + semantik) mengurangi biaya dan latensi
- **Request Idempoency** — Jendela deduplikasi 5 detik untuk permintaan yang identik
- **Deteksi Batas Tarif** — RPM per penyedia, selisih minimum, dan pelacakan serentak maks
- **Antrian & Kecepatan Permintaan** — Antrean, kecepatan, dan kecepatan konkurensi yang dapat dikonfigurasi secara default di Pengaturan → Ketahanan
- **Cache Validasi Kunci API** — cache 3 tingkat untuk kinerja produksi
- **Dasbor Kesehatan dengan Telemetri** — latensi p50/p95/p99, statistik cache, waktu aktif

</details>

<details>
<summary><b>🤖 16. "Saya ingin mengontrol perilaku model secara global"</b></summary>

Pengembang yang menginginkan semua respons dalam bahasa tertentu, dengan nada tertentu, atau ingin membatasi token penalaran. Mengonfigurasi ini di setiap alat/permintaan tidak praktis.

**Bagaimana OmniRoute menyelesaikannya:**

- **Injeksi Perintah Sistem** — Perintah global diterapkan ke semua permintaan
- **Validasi Anggaran Berpikir** — Kontrol alokasi token penalaran per permintaan (passthrough, otomatis, kustom, adaptif)
- **9 Strategi Perutean** — Strategi global yang menentukan cara permintaan didistribusikan
- **Wildcard Router** — pola `provider/*` merutekan secara dinamis ke penyedia mana pun
- **Combo Aktifkan/Nonaktifkan Toggle** — Beralih kombo langsung dari dasbor
- **Pengurutan Kombo Manual** — Seret kartu kombo berdasarkan pegangan dan pertahankan pesanan di SQLite
- **Toggle Penyedia** — Mengaktifkan/menonaktifkan semua koneksi untuk penyedia dengan satu klik
- **Penyedia yang Diblokir** — Kecualikan penyedia tertentu dari daftar `/v1/models`

</details>

<details>
<summary><b>🧰 17. "Saya membutuhkan alat MCP sebagai kemampuan produk kelas satu"</b></summary>

Many AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer.

**Bagaimana OmniRoute menyelesaikannya:**

- MCP muncul di navigasi dasbor dan tab protokol titik akhir
- Halaman manajemen MCP khusus dengan proses, alat, cakupan, dan audit
- Mulai cepat bawaan untuk `omniroute --mcp` dan orientasi klien

</details>

<details>
<summary><b>🧠 18. "Saya memerlukan orkestrasi A2A dengan jalur tugas sinkronisasi + streaming"</b></summary>

Alur kerja agen memerlukan balasan langsung dan eksekusi streaming jangka panjang dengan kontrol siklus hidup.

**Bagaimana OmniRoute menyelesaikannya:**

- Titik akhir A2A JSON-RPC (`POST /a2a`) dengan `message/send` dan `message/stream`
- Streaming SSE dengan propagasi status terminal
- API siklus hidup tugas untuk `tasks/get` dan `tasks/cancel`

</details>

<details>
<summary><b>🛰️ 19. "Saya membutuhkan kesehatan proses MCP yang nyata, bukan status yang dapat ditebak"</b></summary>

Tim operasional perlu mengetahui apakah MCP benar-benar aktif, bukan hanya apakah API dapat dijangkau.

**Bagaimana OmniRoute menyelesaikannya:**

- File detak jantung runtime dengan PID, stempel waktu, transportasi, jumlah alat, dan mode cakupan
- API status MCP menggabungkan detak jantung + aktivitas terkini
- Kartu status UI untuk kesegaran proses/waktu aktif/detak jantung

</details>

<details>
<summary><b>📋 20. "Saya memerlukan eksekusi alat MCP yang dapat diaudit"</b></summary>

Saat alat mengubah konfigurasi atau memicu tindakan operasi, tim memerlukan kemampuan penelusuran forensik.

**Bagaimana OmniRoute menyelesaikannya:**

- Pencatatan audit yang didukung SQLite untuk panggilan alat MCP
- Filter berdasarkan alat, keberhasilan/kegagalan, kunci API, dan penomoran halaman
- Tabel audit dasbor + titik akhir statistik untuk otomatisasi

</details>

<details>
<summary><b>🔐 21. "Saya memerlukan izin MCP terbatas per integrasi"</b></summary>

Different clients should have least-privilege access to tool categories.

**Bagaimana OmniRoute menyelesaikannya:**

- 10 cakupan MCP granular untuk akses alat terkontrol
- Penegakan cakupan dan visibilitas di UI manajemen MCP
- Postur default yang aman untuk perkakas operasional

</details>

<details>
<summary><b>⚙️ 22. "Saya memerlukan kontrol operasional tanpa memindahkan"</b></summary>

Tim memerlukan perubahan runtime yang cepat selama insiden atau peristiwa biaya.

**Bagaimana OmniRoute menyelesaikannya:**

- Beralih aktivasi kombo langsung dari dasbor MCP
- Sesuaikan pengaturan antrean, cooldown, pemutus, dan tunggu dari halaman Ketahanan khusus
- Tinjau status pemutus penyedia langsung dari dasbor Kesehatan

</details>

<details>
<summary><b>🔄 23. "Saya memerlukan visibilitas dan pembatalan siklus hidup tugas A2A langsung"</b></summary>

Without lifecycle visibility, task incidents become hard to triage.

**Bagaimana OmniRoute menyelesaikannya:**

- Daftar tugas/pemfilteran berdasarkan status/keterampilan dengan penomoran halaman
- Telusuri metadata tugas, peristiwa, dan artefak
- Titik akhir pembatalan tugas dan tindakan UI dengan konfirmasi

</details>

<details>
<summary><b>🌊 24. "Saya memerlukan metrik aliran aktif untuk memuat A2A"</b></summary>

Alur kerja streaming memerlukan wawasan operasional tentang konkurensi dan koneksi langsung.

**Bagaimana OmniRoute menyelesaikannya:**

- Penghitung aliran aktif terintegrasi ke dalam status A2A
- Stempel waktu tugas terakhir dan jumlah per negara bagian
- Kartu dasbor A2A untuk pemantauan operasi waktu nyata

</details>

<details>
<summary><b>🪪 25. "Saya memerlukan penemuan agen standar untuk klien"</b></summary>

Klien dan orkestra eksternal memerlukan metadata yang dapat dibaca mesin untuk orientasi.

**Bagaimana OmniRoute menyelesaikannya:**

- Kartu Agen terungkap di `/.well-known/agent.json`
- Kemampuan dan keterampilan yang ditunjukkan dalam manajemen UI
- API status A2A mencakup metadata penemuan untuk otomatisasi

</details>

<details>
<summary><b>🧭 26. "Saya memerlukan kemampuan protokol untuk ditemukan di UX produk"</b></summary>

If users cannot discover protocol surfaces, adoption and support quality drop.

**Bagaimana OmniRoute menyelesaikannya:**

- Halaman **Endpoint** terkonsolidasi dengan tab untuk Proxy, MCP, A2A, dan API Endpoints
- Pengalih status layanan inline (Online/Offline) untuk MCP dan A2A
- Tautan dari ikhtisar ke tab manajemen khusus

</details>

<details>
<summary><b>🧪 27. "Saya memerlukan validasi protokol end-to-end dengan klien nyata"</b></summary>

Mock tests are not enough to validate protocol compatibility before release.

**Bagaimana OmniRoute menyelesaikannya:**

- Suite E2E yang mem-boot aplikasi dan menggunakan transportasi klien MCP SDK yang sebenarnya
- Klien A2A menguji penemuan, pengiriman, streaming, dapatkan, dan pembatalan aliran
- Periksa silang pernyataan terhadap audit MCP dan API tugas A2A

</details>

<details>
<summary><b>📡 28. "Saya memerlukan observabilitas terpadu di semua antarmuka"</b></summary>

Splitting observability by protocol creates blind spots and longer MTTR.

**Bagaimana OmniRoute menyelesaikannya:**

- Dasbor/log/analitik terpadu dalam satu produk
- Kesehatan + audit + permintaan telemetri di seluruh lapisan OpenAI, MCP, dan A2A
- API Operasional untuk status dan otomatisasi

</details>

<details>
<summary><b>💼 29. "Saya memerlukan satu runtime untuk proxy + alat + orkestrasi agen"</b></summary>

Menjalankan banyak layanan terpisah akan meningkatkan biaya operasional dan mode kegagalan.

**Bagaimana OmniRoute menyelesaikannya:**

- Proksi yang kompatibel dengan OpenAI, server MCP, dan server A2A dalam satu tumpukan
- Otentikasi bersama, ketahanan, penyimpanan data, dan kemampuan observasi
- Model kebijakan yang konsisten di seluruh platform interaksi

</details>

<details>
<summary><b>🚀 30. "Saya perlu mengirim workflow agentic tanpa tumpukan glue code"</b></summary>

Tim kehilangan kecepatan saat menggabungkan beberapa layanan dan skrip ad-hoc.

**Bagaimana OmniRoute menyelesaikannya:**

- Strategi titik akhir terpadu untuk klien dan agen
- UI manajemen protokol bawaan dan jalur validasi asap
- Fondasi siap produksi (keamanan, logging, ketahanan, cadangan)

</details>

<details>
<summary><b>📚 31. "Sesi panjang saya crash karena batas 'context_length_exceeded'"</b></summary>

Selama proses debug mendalam, riwayat panjang dengan hasil alat dengan cepat melampaui jendela token penyedia, menyebabkan permintaan gagal dan konteks tidak ada lagi.

**Bagaimana OmniRoute menyelesaikannya:**

- **Kompresi Konteks Proaktif** — Mengevaluasi anggaran token sebelum permintaan mencapai hulu dan secara proaktif memangkas riwayat percakapan lama dengan mekanisme pencarian biner yang cerdas.
- **Pengaman Integritas Struktural** — Secara otomatis melacak definisi `tool_use` yang eksplisit dan memastikan bahwa jika masukan alat terpotong, `tool_result` yang terkait juga dihapus dengan aman, sehingga mencegah kesalahan validasi API.
- **Penghapusan Multi-Lapisan** — Secara progresif menghapus pesan sistem, pesan biasa, dan akhirnya menerapkan batas panjang yang ketat tanpa merusak logika percakapan.

</details>

### Contoh Playbook (Kasus Penggunaan Terintegrasi)

**Playbook A: Maximize paid subscription + cheap backup**

```txt
Combo: "maximize-claude"
  1. cc/claude-opus-4-7
  2. glm/glm-4.7
  3. if/kimi-k2-thinking

Monthly cost: $20 + small backup spend
Outcome: higher quality, near-zero interruption
```

**Playbook B: Tumpukan coding tanpa biaya**

```txt
Combo: "free-forever"
  1. gc/gemini-3-flash
  2. if/kimi-k2-thinking
  3. qw/qwen3-coder-plus

Monthly cost: $0
Outcome: stable free coding workflow
```

**Playbook C: Rantai fallback yang selalu aktif 24/7**

```txt
Combo: "always-on"
  1. cc/claude-opus-4-7
  2. cx/gpt-5.2-codex
  3. glm/glm-4.7
  4. minimax/MiniMax-M2.1
  5. if/kimi-k2-thinking

Outcome: deep fallback depth for deadline-critical workloads
```

**Playbook D: Operasi agen dengan MCP + A2A**

```txt
1) Start MCP transport (`omniroute --mcp`) for tool-driven operations
2) Run A2A tasks via `message/send` and `message/stream`
3) Observe via /dashboard/endpoint (MCP and A2A tabs)
4) Toggle services via inline status controls
```

---

## 🆓 Mulai Gratis — Tanpa Biaya Konfigurasi

> Siapkan pengkodean AI dalam hitungan menit di **$0/bulan**. Hubungkan akun gratis ini dan gunakan kombo **Free Stack** bawaan.

| Step | Action                                             | Providers Unlocked                                                 |
| ---- | -------------------------------------------------- | ------------------------------------------------------------------ |
| 1    | Connect **Kiro** (AWS Builder ID OAuth)            | Claude Sonnet 4.5, Haiku 4.5 — **unlimited**                       |
| 2    | Connect **Qoder** (Google OAuth)                   | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... — **unlimited** |
| 3    | Connect **Qwen** (Device Code)                     | qwen3-coder-plus, qwen3-coder-flash... — **unlimited**             |
| 4    | Connect **Gemini CLI** (Google OAuth)              | gemini-3-flash, gemini-2.5-pro — **Gratis 180K/bln**                  |
| 5    | `/dashboard/combos` → **Templat Tumpukan Gratis ($0)** | Round-robin semua penyedia gratis secara otomatis                       |

**Arahkan IDE/CLI apa pun ke:** `http://localhost:20128/v1` · Kunci API: `any-string` · Selesai.

> **Cakupan ekstra opsional (juga gratis):** Kunci API Groq (gratis 30 RPM), NVIDIA NIM (gratis 40 RPM, 70+ model), Cerebras (1 juta tok/hari), kunci API LongCat (50 juta token/hari!), Cloudflare Workers AI (10 ribu neuron/hari, 50+ model).

## Mulai Cepat

### 1) Instal dan jalankan

```bash
npm install -g omniroute
omniroute
```

> **pengguna pnpm:** Jalankan `pnpm approve-builds -g` setelah instalasi untuk mengaktifkan skrip build asli yang diperlukan oleh `better-sqlite3` dan `@swc/core`:
>
> ```bash
> pnpm install -g omniroute
> pnpm approve-builds -g   # Pilih semua paket → approve
> omniroute
> ```

Dasbor terbuka di `http://localhost:20128` dan URL dasar API adalah `http://localhost:20128/v1`.

#### Arch Linux (AUR)

Pengguna Arch Linux dapat menginstal [AUR package](https://aur.archlinux.org/packages/omniroute-bin), yang menginstal OmniRoute dan menyediakan layanan pengguna systemd:

```bash
yay -S omniroute-bin
systemctl --user enable --now omniroute.service
```

| Command                 | Description                                                 |
| ----------------------- | ----------------------------------------------------------- |
| `omniroute`             | Mulai server (`PORT=20128`, API dan dasbor pada port yang sama) |
| `omniroute --port 3000` | Set canonical/API port to 3000                              |
| `omniroute --mcp`       | Mulai server MCP (stdio transport)                          |
| `omniroute --no-open`   | Don't auto-open browser                                     |
| `omniroute --help`      | Show help                                                   |

Optional split-port mode:

```bash
PORT=20128 DASHBOARD_PORT=20129 omniroute
# API:       http://localhost:20128/v1
# Dashboard: http://localhost:20129
```

### 2) Menghapus Instalasi

Saat Anda tidak lagi memerlukan OmniRoute, kami menyediakan dua skrip cepat untuk penghapusan bersih:

| Command                  | Action                                                                              |
| ------------------------ | ----------------------------------------------------------------------------------- |
| `npm run uninstall`      | Menghapus aplikasi sistem tetapi **menyimpan DB dan konfigurasi Anda** di `~/.omniroute`.  |
| `npm run uninstall:full` | Menghapus aplikasi DAN secara permanen **menghapus semua konfigurasi, kunci, dan database**. |

> Catatan: Untuk menjalankan perintah ini, navigasikan ke folder proyek OmniRoute (jika Anda mengkloningnya) dan jalankan. Alternatifnya, jika diinstal secara global, Anda cukup menjalankan `npm uninstall -g omniroute`.

### Batas Waktu Streaming yang Berlangsung Lama

Untuk sebagian besar penerapan, Anda hanya memerlukan:

| Variable                 | Default                       | Purpose                                                                                                                                      |
| ------------------------ | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `REQUEST_TIMEOUT_MS`     | `600000`                      | Garis dasar bersama untuk batas waktu mulai respons upstream, batas waktu Undici yang tersembunyi, permintaan sidik jari TLS, dan batas waktu permintaan/proksi jembatan API |
| `STREAM_IDLE_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Kesenjangan maksimum antara potongan streaming sebelum OmniRoute membatalkan aliran SSE                                                                  |

Kompatibilitas mundur dipertahankan: `FETCH_TIMEOUT_MS`, `API_BRIDGE_PROXY_TIMEOUT_MS`, dan var batas waktu per lapisan lainnya yang ada masih berfungsi dan menggantikan garis dasar bersama.

Untuk upstream yang kompatibel dengan Kode Claude (`anthropic-compatible-cc-*`), OmniRoute juga memperoleh header `X-Stainless-Timeout` keluar dari batas waktu pengambilan yang diselesaikan sehingga batas waktu baca sisi penyedia tetap selaras dengan konfigurasi env Anda.

Untuk reverse proxy pihak ketiga yang kompatibel dengan Claude Code, OmniRoute tetap menggunakan default
`anthropic-beta` disetel konservatif dan, ketika `Client Cache Control` tersisa di `Auto`,
hanya meneruskan penanda `cache_control` yang disediakan klien. Jika permintaan tidak menyertakan
`cache_control`, OmniRoute tidak memasukkan penanda milik jembatan.

Penggantian tingkat lanjut tersedia jika Anda memerlukan kontrol yang lebih baik:

| Variable                                 | Default                                    | Purpose                                                              |
| ---------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------- |
| `FETCH_TIMEOUT_MS`                       | inherits `REQUEST_TIMEOUT_MS`              | Batas waktu mulai respons hulu digunakan hingga header respons tiba   |
| `FETCH_HEADERS_TIMEOUT_MS`               | inherits `FETCH_TIMEOUT_MS`                | Batas waktu Undici untuk menerima header respons upstream            |
| `FETCH_BODY_TIMEOUT_MS`                  | inherits `FETCH_TIMEOUT_MS`                | Undici time limit between upstream body chunks (`0` disables it)     |
| `FETCH_CONNECT_TIMEOUT_MS`               | `30000`                                    | Undici TCP connect timeout                                           |
| `FETCH_KEEPALIVE_TIMEOUT_MS`             | `4000`                                     | Undici idle keep-alive socket timeout                                |
| `TLS_CLIENT_TIMEOUT_MS`                  | inherits `FETCH_TIMEOUT_MS`                | Batas waktu untuk permintaan sidik jari TLS yang dilakukan melalui `wreq-js`          |
| `API_BRIDGE_PROXY_TIMEOUT_MS`            | inherits `REQUEST_TIMEOUT_MS` or `600000`  | Batas waktu untuk penerusan proxy `/v1` dari port API ke port dasbor   |
| `API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS`   | `max(API_BRIDGE_PROXY_TIMEOUT_MS, 300000)` | Batas waktu permintaan masuk di server jembatan API                    |
| `API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS`   | `60000`                                    | Batas waktu header masuk di server jembatan API                     |
| `API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS` | `5000`                                     | Batas waktu tetap hidup di server jembatan API|
| `API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS`    | `0`                                        |Batas waktu ketidakaktifan soket di server jembatan API (`0` menonaktifkannya) |

Untuk permintaan streaming, `FETCH_TIMEOUT_MS` hanya mencakup pengaturan koneksi/menunggu respons upstream pertama. Setelah aliran aktif, OmniRoute hanya akan dibatalkan pada keadaan terhenti sebenarnya (`STREAM_IDLE_TIMEOUT_MS`) atau tubuh Undici tidak aktif (`FETCH_BODY_TIMEOUT_MS`).

Jika Anda menjalankan OmniRoute di belakang Nginx, Caddy, Cloudflare, atau proksi terbalik lainnya, pastikan proksi tersebut
waktu tunggu juga lebih tinggi daripada waktu tunggu aliran/pengambilan OmniRoute Anda.

### 2) Hubungkan penyedia dan buat kunci API Anda

1. Buka Dasbor → `Providers` dan sambungkan setidaknya satu penyedia (OAuth atau kunci API).
2. Buka Dasbor → `Endpoints` dan buat kunci API.
3. (Opsional) Buka Dasbor → `Combos` dan atur rantai cadangan Anda.

### 3) Arahkan alat pengkodean Anda ke OmniRoute

```txt
Base URL: http://localhost:20128/v1
API Key:  [copy from Endpoint page]
Model:    if/kimi-k2-thinking (or any provider/model prefix)
```

Bekerja dengan Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, dan SDK yang kompatibel dengan OpenAI.

### 4) Mengaktifkan dan memvalidasi protokol (v2.0)

**MCP (untuk operasi yang digerakkan oleh alat):**

```bash
omniroute --mcp
```

Kemudian sambungkan klien MCP Anda melalui `stdio` dan uji alat seperti:

- `omniroute_get_health`
- `omniroute_list_combos`

**A2A (untuk alur kerja agen-ke-agen):**

```bash
curl http://localhost:20128/.well-known/agent.json
```

```bash
curl -X POST http://localhost:20128/a2a \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":"quickstart","method":"message/send","params":{"skill":"quota-management","messages":[{"role":"user","content":"Give me a short quota summary."}]}}'
```

### 5) Validasi semuanya end-to-end (direkomendasikan)

```bash
npm run test:protocols:e2e
```

Suite ini memvalidasi alur klien MCP dan A2A yang sebenarnya terhadap aplikasi yang sedang berjalan.

### Alternatif: dijalankan dari sumber

```bash
cp .env.example .env
npm install
PORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev
```

<details>
<summary><b>Void Linux (`xbps-src` template)</b></summary>

Untuk pengguna Void Linux, Anda dapat membuat paket asli menggunakan `xbps-src`. Simpan blok ini sebagai `srcpkgs/omniroute/template`:

```bash
# Template file for 'omniroute'
pkgname=omniroute
version=3.4.1
revision=1
hostmakedepends="nodejs python3 make"
depends="openssl"
short_desc="Universal AI gateway with smart routing for multiple LLM providers"
maintainer="zenobit <zenobit@disroot.org>"
license="MIT"
homepage="https://github.com/diegosouzapw/OmniRoute"
distfiles="https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz"
checksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b
system_accounts="_omniroute"
omniroute_homedir="/var/lib/omniroute"
export NODE_ENV=production
export npm_config_engine_strict=false
export npm_config_loglevel=error
export npm_config_fund=false
export npm_config_audit=false

do_build() {
	# Determine target CPU arch for node-gyp
	local _gyp_arch
	case "$XBPS_TARGET_MACHINE" in
		aarch64*) _gyp_arch=arm64 ;;
		armv7*|armv6*) _gyp_arch=arm ;;
		i686*) _gyp_arch=ia32 ;;
		*) _gyp_arch=x64 ;;
	esac

	# 1) Install all deps – skip scripts (no network in do_build, native modules
	#    compiled separately below; better-sqlite3 is serverExternalPackage so
	#    Next.js does not execute it during next build)
	NODE_ENV=development npm ci --ignore-scripts

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

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

	# 4) Compile better-sqlite3 native binding for the target architecture.
	#    Use node-gyp directly so CC/CXX from xbps-src cross-toolchain are used
	#    without npm altering them.
	local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
	(cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")

	# 5) Place the compiled binding into the standalone bundle
	local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
	mkdir -p "$_bs3_release"
	cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"

	# 6) Remove arch-specific sharp bundles – upstream sets images.unoptimized=true
	#    so sharp is not used at runtime; x64 .so files would break aarch64 strip
	rm -rf .next/standalone/node_modules/@img

	# 7) Copy pino runtime deps omitted by Next.js static analysis:
	#    pino-abstract-transport – required by pino's worker thread
	#    split2 – dep of pino-abstract-transport
	#    process-warning – dep of pino itself
	for _mod in pino-abstract-transport split2 process-warning; do
		cp -r "node_modules/$_mod" .next/standalone/node_modules/
	done
}

do_check() {
	npm run test:unit
}

do_install() {
	vmkdir usr/lib/omniroute/.next

	vcopy .next/standalone/. usr/lib/omniroute/.next/standalone

	# Prevent removal of empty Next.js app router dirs by the post-install hook
	for _d in \
		.next/standalone/.next/server/app/dashboard \
		.next/standalone/.next/server/app/dashboard/settings \
		.next/standalone/.next/server/app/dashboard/providers; do
		touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
	done

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

post_install() {
	vlicense LICENSE
}
```

</details>

---

## 🐳 Docker

OmniRoute tersedia sebagai image Docker publik di [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).

**Quick run:**

```bash
docker run -d \
  --name omniroute \
  --restart unless-stopped \
  --stop-timeout 40 \
  -p 20128:20128 \
  -v omniroute-data:/app/data \
  diegosouzapw/omniroute:latest
```

**Dengan file lingkungan:**

```bash
# Copy and edit .env first
cp .env.example .env

docker run -d \
  --name omniroute \
  --restart unless-stopped \
  --stop-timeout 40 \
  --env-file .env \
  -p 20128:20128 \
  -v omniroute-data:/app/data \
  diegosouzapw/omniroute:latest
```

**Menggunakan Docker Tulis:**

```bash
# Base profile (no CLI tools)
docker compose --profile base up -d

# CLI profile (Claude Code, Codex, OpenClaw built-in)
docker compose --profile cli up -d
```

Dukungan dasbor untuk penerapan Docker kini mencakup **Cloudflare Quick Tunnel** sekali klik di `Dashboard → Endpoints`. Yang pertama mengaktifkan pengunduhan `cloudflared` hanya bila diperlukan, memulai terowongan sementara ke titik akhir `/v1` Anda saat ini, dan menampilkan URL `https://*.trycloudflare.com/v1` yang dihasilkan langsung di bawah URL publik normal Anda.

Notes:

- URL Terowongan Cepat bersifat sementara dan berubah setelah setiap restart.
- Terowongan Cepat tidak dipulihkan secara otomatis setelah OmniRoute atau kontainer dimulai ulang. Aktifkan kembali dari dasbor bila diperlukan.
- Penginstalan terkelola saat ini mendukung Linux, macOS, dan Windows di `x64` / `arm64`.
- Terkelola Quick Tunnels default ke transportasi HTTP/2 untuk menghindari peringatan buffer UDP QUIC yang berisik di lingkungan kontainer yang terbatas. Setel `CLOUDFLARED_PROTOCOL=quic` atau `auto` jika Anda menginginkan transportasi lain.
- Gambar Docker menggabungkan akar CA sistem dan meneruskannya ke `cloudflared` yang dikelola, yang menghindari kegagalan kepercayaan TLS ketika terowongan melakukan bootstrap di dalam wadah.
- SQLite berjalan dalam mode WAL. `docker stop` harus dibiarkan selesai sehingga OmniRoute dapat memeriksa kembali perubahan terbaru ke `storage.sqlite`.
- File Compose yang dibundel sudah menetapkan masa tenggang penghentian 40 detik. Jika Anda menjalankan image secara langsung, pertahankan `--stop-timeout 40` (atau serupa) sehingga penghentian manual tidak menghentikan pembersihan pematian.
- Setel `CLOUDFLARED_BIN=/absolute/path/to/cloudflared` jika Anda ingin OmniRoute menggunakan biner yang sudah ada alih-alih mengunduhnya.

**Menggunakan Docker Compose dengan Caddy (HTTPS Auto-TLS):**

OmniRoute dapat diekspos dengan aman menggunakan penyediaan SSL otomatis Caddy. Pastikan data DNS A domain Anda mengarah ke IP server Anda.

```yaml
services:
  omniroute:
    image: diegosouzapw/omniroute:latest
    container_name: omniroute
    restart: unless-stopped
    volumes:
      - omniroute-data:/app/data
    environment:
      - PORT=20128
      - NEXT_PUBLIC_BASE_URL=https://your-domain.com

  caddy:
    image: caddy:latest
    container_name: caddy
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    command: caddy reverse-proxy --from https://your-domain.com --to http://omniroute:20128

volumes:
  omniroute-data:
```

| Image                    | Tag      | Size   | Description           |
| ------------------------ | -------- | ------ | --------------------- |
| `diegosouzapw/omniroute` | `latest` | ~250MB | Latest stable release |
| `diegosouzapw/omniroute` | `3.6.2`  | ~250MB | Current version       |

---

## 🖥️ Aplikasi Desktop — Offline & Selalu Aktif

> 🆕 **BARU!** OmniRoute kini tersedia sebagai **aplikasi desktop asli** untuk Windows, macOS, dan Linux.

Jalankan OmniRoute sebagai aplikasi desktop mandiri — tanpa terminal, tanpa browser, tanpa internet untuk model lokal. Aplikasi berbasis Electron meliputi:

- 🖥️ **Jendela Asli** — Jendela aplikasi khusus dengan integrasi baki sistem
- 🔄 **Mulai Otomatis** — Luncurkan OmniRoute saat login sistem
- 🔔 **Pemberitahuan Asli** — Dapatkan peringatan jika kuota habis atau masalah penyedia
- ⚡ **Instal Sekali Klik** — NSIS (Windows), DMG (macOS), AppImage (Linux)
- 🌐 **Mode Offline** — Bekerja sepenuhnya offline dengan server yang dibundel

### Mulai Cepat

```bash
# Development mode
npm run electron:dev

# Build for your platform
npm run electron:build         # Current platform
npm run electron:build:win     # Windows (.exe)
npm run electron:build:mac     # macOS (.dmg) — x64 & arm64
npm run electron:build:linux   # Linux (.AppImage)
```

### System Tray

Saat diminimalkan, OmniRoute ada di baki sistem Anda dengan tindakan cepat:

- Buka dasbor
- Ubah port server
- Keluar dari aplikasi

📖 Full documentation: [`electron/README.md`](electron/README.md)

---

## 💰 Harga Sekilas

| Tier                | Provider                    | Cost                      | Quota Reset      | Best For                          |
| ------------------- | --------------------------- | ------------------------- | ---------------- | --------------------------------- |
| **💳 SUBSCRIPTION** | Claude Code (Pro)           | $20/mo                    | 5h + weekly      | Already subscribed                |
|                     | Codex (Plus/Pro)            | $20-200/mo                | 5h + weekly      | OpenAI users                      |
|                     | Gemini CLI                  | **FREE**                  | 180K/mo + 1K/day | Everyone!                         |
|                     | GitHub Copilot              | $10-19/mo                 | Monthly          | GitHub users                      |
| **🔑 API KEY**      | NVIDIA NIM                  | **GRATIS** (pengembangan selamanya)    | ~40 RPM          | 70+ open models                   |
|                     | Cerebras                    | **FREE** (1M tok/day)     | 60K TPM / 30 RPM | World's fastest                   |
|                     | Groq                        | **FREE** (30 RPM)         | 14.4K RPD        | Ultra-fast Llama/Gemma            |
|                     | DeepSeek V3.2               | $0.27/$1.10 per 1M        | None             | Best price/quality reasoning      |
|                     | xAI Grok-4 Fast             | **$0.20/$0.50 per 1M** 🆕 | None             | Fastest + tool calling, ultralow  |
|                     | xAI Grok-4 (standard)       | $0.20/$1.50 per 1M 🆕     | None             | Penalaran andalan dari xAI       |
|                     | Mistral                     | Uji coba gratis + berbayar         | Rate limited     | European AI                       |
|                     | OpenRouter                  | Bayar per penggunaan               | None             | 100+ models aggr.                 |
| **💰 CHEAP**        | GLM-5 (via Z.AI) 🆕         | $0.5/1M                   | Daily 10AM       | 128K output, newest flagship      |
|                     | GLM-4.7                     | $0.6/1M                   | Daily 10AM       | Budget backup                     |
|                     | MiniMax M2.5 🆕             | $0.3/1M input             | 5-hour rolling   | Reasoning + agentic tasks         |
|                     | MiniMax M2.1                | $0.2/1M                   | 5-hour rolling   | Cheapest option                   |
|                     | Kimi K2.5 (Moonshot API) 🆕 | Bayar per penggunaan               | None             | Direct Moonshot API access        |
|                     | Kimi K2                     | $9/mo flat                | 10M tokens/mo    | Predictable cost                  |
| **🆓 FREE**         | Qoder                       | **$0**                    | Unlimited        | 5 models unlimited                |
|                     | Qwen                        | **$0**                    | Unlimited        | 4 models unlimited                |
|                     | Kiro                        | **$0**                    | Unlimited        | Claude Sonnet/Haiku (AWS Builder) |
|                     | LongCat Flash-Lite 🆕       | **$0** (50M tok/day 🔥)   | 1 RPS            | Kuota gratis terbesar di dunia       |
|                     | Pollinations AI 🆕          | **$0** (tidak perlu kunci)    | 1 req/15s        | GPT-5, Claude, DeepSeek, Llama 4  |
|                     | Cloudflare Workers AI 🆕    | **$0** (10K Neurons/day)  | ~150 resp/day    | 50+ model, keunggulan global           |
|                     | Scaleway AI 🆕              | **$0** (1M tokens total)  | Rate limited     | EU/GDPR, Qwen3 235B, Llama 70B    |

> 🆕 **Model baru ditambahkan (Mar 2026):** Keluarga Grok-4 Fast seharga $0,20/$0,50/M (dibandingkan pada 1143ms — 30% lebih cepat dibandingkan Gemini 2.5 Flash), GLM-5 melalui Z.AI dengan output 128K, penalaran MiniMax M2.5, harga DeepSeek V3.2 yang diperbarui, Kimi K2.5 melalui API langsung Moonshot.

**💡 Tumpukan Kombo $0 — Penyiapan Gratis Lengkap:**

```
# 🆓 Ultimate Free Stack 2026 — 11 Providers, $0 Forever
Kiro (kr/)             → Claude Sonnet/Haiku UNLIMITED
Qoder (if/)            → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED
LongCat Lite (lc/)     → LongCat-Flash-Lite — 50M tokens/day 🔥
Pollinations (pol/)    → GPT-5, Claude, DeepSeek, Llama 4 — no key needed
Qwen (qw/)             → qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED
Gemini (gemini/)       → Gemini 2.5 Flash — 1,500 req/day free API key
Cloudflare AI (cf/)    → Llama 70B, Gemma 3, Mistral — 10K Neurons/day
Scaleway (scw/)        → Qwen3 235B, Llama 70B — 1M free tokens (EU)
Groq (groq/)           → Llama/Gemma ultra-fast — 14.4K req/day
NVIDIA NIM (nvidia/)   → 70+ open models — 40 RPM forever
Cerebras (cerebras/)   → Llama/Qwen world-fastest — 1M tok/day
```

**Tanpa biaya. Jangan pernah berhenti melakukan pengkodean.** Konfigurasikan ini sebagai satu kombo OmniRoute dan semua fallback terjadi secara otomatis — tidak pernah ada peralihan manual.

---

---

## 🆓 Model Gratis — Apa yang Sebenarnya Anda Dapatkan

> Semua model di bawah **100% gratis tanpa memerlukan kartu kredit**. OmniRoute melakukan rute otomatis di antara keduanya ketika satu kuota habis — gabungkan semuanya untuk kombo $0 yang tidak dapat dipecahkan.

### 🔵 MODEL CLAUDE (melalui Kiro — ID AWS Builder)

| Model               | Prefix | Limit         | Rate Limit            |
| ------------------- | ------ | ------------- | --------------------- |
| `claude-sonnet-4.5` | `kr/`  | **Unlimited** | No reported daily cap |
| `claude-haiku-4.5`  | `kr/`  | **Unlimited** | No reported daily cap |
| `claude-opus-4.6`   | `kr/`  | **Unlimited** | Latest Opus via Kiro  |

### 🟢 MODEL QODER (PAT Gratis melalui qodercli)

| Model              | Prefix | Limit         | Rate Limit      |
| ------------------ | ------ | ------------- | --------------- |
| `kimi-k2-thinking` | `if/`  | **Unlimited** | No reported cap |
| `qwen3-coder-plus` | `if/`  | **Unlimited** | No reported cap |
| `deepseek-r1`      | `if/`  | **Unlimited** | No reported cap |
| `minimax-m2.1`     | `if/`  | **Unlimited** | No reported cap |
| `kimi-k2`          | `if/`  | **Unlimited** | No reported cap |

> Metode koneksi yang disarankan: **Token Akses Pribadi + `qodercli`**. Peramban OAuth adalah
> eksperimental dan dinonaktifkan secara default kecuali variabel lingkungan `QODER_OAUTH_*` dikonfigurasi.

### 🟡 MODEL QWEN (Otentikasi Kode Perangkat)

| Model               | Prefix | Limit         | Rate Limit          |
| ------------------- | ------ | ------------- | ------------------- |
| `qwen3-coder-plus`  | `qw/`  | **Unlimited** | No reported cap     |
| `qwen3-coder-flash` | `qw/`  | **Unlimited** | No reported cap     |
| `qwen3-coder-next`  | `qw/`  | **Unlimited** | No reported cap     |
| `vision-model`      | `qw/`  | **Unlimited** | Multimodal (images) |

### 🟣 GEMINI CLI (Google OAuth)

| Model                    | Prefix | Limit                       | Rate Limit    |
| ------------------------ | ------ | --------------------------- | ------------- |
| `gemini-3-flash-preview` | `gc/`  | **180K tok/month** + 1K/day | Monthly reset |
| `gemini-2.5-pro`         | `gc/`  | 180K/month (shared pool)    | High quality  |

### ⚫ NVIDIA NIM (Kunci API Gratis — build.nvidia.com)

| Tier       | Daily Limit  | Rate Limit  | Notes                                                  |
| ---------- | ------------ | ----------- | ------------------------------------------------------ |
| Free (Dev) | No token cap | **~40 RPM** | 70+ model; transisi ke batas tarif murni pada pertengahan tahun 2025 |

Model gratis populer: `moonshotai/kimi-k2.5` (Kimi K2.5), `z-ai/glm4.7` (GLM 4.7), `deepseek-ai/deepseek-v3.2` (DeepSeek V3.2), `nvidia/llama-3.3-70b-instruct`, `deepseek/deepseek-r1`

### ⚪ CEREBRAS (Kunci API Gratis — inference.cerebras.ai)

| Tier | Daily Limit       | Rate Limit       | Notes                                       |
| ---- | ----------------- | ---------------- | ------------------------------------------- |
| Free | **1M tokens/day** | 60K TPM / 30 RPM | World's fastest LLM inference; resets daily |

Available free: `llama-3.3-70b`, `llama-3.1-8b`, `deepseek-r1-distill-llama-70b`

### 🔴 GROQ (Kunci API Gratis — console.groq.com)

| Tier | Daily Limit   | Rate Limit       | Notes                                     |
| ---- | ------------- | ---------------- | ----------------------------------------- |
| Free | **14.4K RPD** | 30 RPM per model | No credit card; 429 on limit, not charged |

Available free: `llama-3.3-70b-versatile`, `gemma2-9b-it`, `mixtral-8x7b`, `whisper-large-v3`

### 🔴 LONGCAT AI (Kunci API Gratis — longcat.chat) 🆕

| Model                         | Prefix | Kuota Gratis Harian  | Notes                   |
| ----------------------------- | ------ | ----------------- | ----------------------- |
| `LongCat-Flash-Lite`          | `lc/`  | **50M tokens** 💥 | Kuota gratis terbesar yang pernah ada |
| `LongCat-Flash-Chat`          | `lc/`  | 500K tokens       | Multi-turn chat         |
| `LongCat-Flash-Thinking`      | `lc/`  | 500K tokens       | Reasoning / CoT         |
| `LongCat-Flash-Thinking-2601` | `lc/`  | 500K tokens       | Jan 2026 version        |
| `LongCat-Flash-Omni-2603`     | `lc/`  | 500K tokens       | Multimodal              |

> 100% gratis saat dalam versi beta publik. Daftar di [longcat.chat](https://longcat.chat) dengan email atau telepon. Reset setiap hari pukul 00:00 UTC.

### 🟢 POLLINASI AI (Tidak Perlu Kunci API) 🆕

| Model      | Prefix | Rate Limit | Provider Behind    |
| ---------- | ------ | ---------- | ------------------ |
| `openai`   | `pol/` | 1 req/15s  | GPT-5              |
| `claude`   | `pol/` | 1 req/15s  | Anthropic Claude   |
| `gemini`   | `pol/` | 1 req/15s  | Google Gemini      |
| `deepseek` | `pol/` | 1 req/15s  | DeepSeek V3        |
| `llama`    | `pol/` | 1 req/15s  | Meta Llama 4 Scout |
| `mistral`  | `pol/` | 1 req/15s  | Mistral AI         |

> ✨ **Tanpa gesekan:** Tanpa pendaftaran, tanpa kunci API. Tambahkan penyedia Penyerbukan dengan bidang kunci kosong dan itu langsung berfungsi.

### 🟠 AI CLOUDFLARE WORKERS (Kunci API Gratis — cloudflare.com) 🆕

| Tier | Daily Neurons | Equivalent Usage                        | Notes                   |
| ---- | ------------- | --------------------------------------- | ----------------------- |
| Free | **10,000**    | ~150 LLM resp / 500s audio / 15K embeds | Keunggulan global, 50+ model |

Model gratis populer: `@cf/meta/llama-3.3-70b-instruct`, `@cf/google/gemma-3-12b-it`, `@cf/openai/whisper-large-v3-turbo` (audio gratis!), `@cf/qwen/qwen2.5-coder-15b-instruct`

> Membutuhkan Token API + ID Akun dari [dash.cloudflare.com](https://dash.cloudflare.com). Simpan ID Akun di pengaturan penyedia.

### 🟣 SCALEWAY AI (1 Juta Token Gratis — scaleway.com) 🆕

| Tier | Free Quota    | Location     | Notes                               |
| ---- | ------------- | ------------ | ----------------------------------- |
| Free | **1M tokens** | 🇫🇷 Paris, EU | No credit card needed within limits |

Tersedia gratis: `qwen3-235b-a22b-instruct-2507` (Qwen3 235B!), `llama-3.1-70b-instruct`, `mistral-small-3.2-24b-instruct-2506`, `deepseek-v3-0324`

> Sesuai dengan UE/GDPR. Dapatkan kunci API di [console.scaleway.com](https://console.scaleway.com).

> **💡 Tumpukan Gratis Terbaik (11 Penyedia, $0 Selamanya):**
>
> ```
> Kiro (kr/)             → Claude Sonnet/Haiku TANPA BATAS
> Qoder (if/)            → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 TANPA BATAS
> LongCat Lite (lc/)     → LongCat-Flash-Lite — 50 juta token/hari 🔥
> Pollinations (pol/)    → GPT-5, Claude, DeepSeek, Llama 4 — tidak perlu kunci
> Qwen (qw/)             → model qwen3-coder TANPA BATAS
> Gemini (gemini/)       → Gemini 2.5 Flash — 1.500 req/hari gratis
> Cloudflare AI (cf/)    → 50+ model — 10 ribu Neurons/hari
> Scaleway (scw/)        → Qwen3 235B, Llama 70B — 1 juta token gratis (EU)
> Groq (groq/)           → Llama/Gemma — 14,4 ribu req/hari, sangat cepat
> NVIDIA NIM (nvidia/)   → 70+ model terbuka — 40 RPM selamanya
> Cerebras (cerebras/)   → Llama/Qwen tercepat di dunia — 1 juta tok/hari
> ```

## 🎙️ Kombo Transkripsi Gratis

> Transkripsikan audio/video apa pun seharga **$0** — Deepgram memimpin dengan $200 gratis, penggantian AssemblyAI $50, Groq Whisper sebagai cadangan darurat tanpa batas.

| Provider          | Free Credits           | Best Model                                   | Rate Limit                   |
| ----------------- | ---------------------- | -------------------------------------------- | ---------------------------- |
| 🟢 **Deepgram**   | **$200 free** (signup) | `nova-3` — best accuracy, 30+ languages      | Tidak ada batasan RPM pada kredit gratis |
| 🔵 **AssemblyAI** | **$50 free** (signup)  | `universal-3-pro` — chapters, sentiment, PII | Tidak ada batasan RPM pada kredit gratis |
| 🔴 **Groq**       | **Free forever**       | `whisper-large-v3` — OpenAI Whisper          | 30 RPM (rate limited)        |

**Suggested combo in `/dashboard/combos`:**

```
Name: free-transcription
Strategy: Priority
Nodes:
  [1] deepgram/nova-3          → uses $200 free first
  [2] assemblyai/universal-3-pro → fallback when Deepgram credits run out
  [3] groq/whisper-large-v3    → free forever, emergency fallback
```

Kemudian di tab `/dashboard/media` → **Transkripsi**: unggah file audio atau video apa pun → pilih titik akhir kombo Anda → dapatkan transkripsi dalam format yang didukung.

## 💡 Fitur Utama

OmniRoute v3.6 dibangun sebagai platform operasional, bukan hanya proxy relai.

### 🆕 Baru — Sorotan v3.6.x (Apr 2026)

| Feature                            | Apa Fungsinya                                                                                                                                      |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| 🌐 **V1 WebSocket Bridge**         | Lalu lintas WebSocket yang kompatibel dengan OpenAI ditingkatkan dan diproksi melalui `/v1/ws` — streaming penuh melalui WS dengan autentikasi sesi (kunci API atau cookie sesi)      |
| 🔑 **Sync Tokens & Config Bundle** | Menerbitkan/mencabut token sinkronisasi untuk titik akhir sinkronisasi konfigurasi. Paket konfigurasi diversi dengan ETag untuk polling hemat bandwidth                            |
| 🧠 **GLM Thinking (glmt) Preset**  | GLM Thinking registered first-class: 65 536 max tokens, 24 576 thinking budget, 900s timeout, usage sync & pricing — Claude-compatible API        |
| 🔢 **Hybrid Token Counting**       | Menggunakan `/messages/count_tokens` sisi penyedia jika tersedia; kembali ke perkiraan — pelacakan penggunaan yang akurat tanpa menebak-nebak|
|🌱 **Model Alias Benih Otomatis**       | 30+ cross-proxy dialect aliases normalised at startup — no more routing mismatches                                                                |
| 🛡️ **Safe Outbound Fetch**         | Semua validasi penyedia dan penemuan model melalui lapisan pengambilan yang dilindungi yang memblokir URL pribadi/lokal dengan percobaan ulang, batas waktu, dan perlindungan SSRF |
| ⏳ **Tunggu Masa Tenang**           | Percobaan ulang obrolan sisi server ketika setiap koneksi kandidat sedang dingin; dapat dikonfigurasi `enabled`, `maxRetries`, dan `maxRetryWaitSec`             |
| 🔍 **Validasi Env Runtime**      | Startup memvalidasi semua env vars dengan skema Zod - menghapus kesalahan untuk rahasia yang hilang, URL yang tidak valid, atau tipe yang salah                                  |
| 📋 **Compliance Audit Expansion**  | Log audit terstruktur dengan penomoran halaman, konteks permintaan, peristiwa autentikasi, peristiwa CRUD penyedia, dan pencatatan validasi yang diblokir SSRF                    |
| 🔐 **TPS Log Metric**              | Modal detail log menunjukkan Token Per Second (TPS) — sekilas kinerja cepat untuk setiap permintaan                                                 |
| 🗑️ **Uninstall / Full Uninstall**  | `npm run uninstall` menyimpan data, `npm run uninstall:full` menghapus semuanya — penghapusan bersih untuk semua metode instalasi                               |
| 🔧 **OAuth Env Repair**            | Tindakan "Perbaiki env" sekali klik untuk penyedia OAuth memulihkan vars env yang hilang dan memperbaiki status autentikasi yang rusak                                           |
| 🔒 **Pematian Elektron yang Anggun**  | Electron `before-quit` dimatikan Next.js dengan baik, mencegah penguncian database SQLite WAL pada penutupan desktop                                       |
| 👁️ **Pengalih Visibilitas Model**     | Pengalih visibilitas per model (ikon 👁) dengan filter pencarian dan lencana jumlah aktif (`N/M active`) di halaman penyedia                                  |
| 📧 **Email Privacy Masking**       | OAuth account emails masked (`di*****@g****.com`), full address visible on hover                                                                  |
| 🔗 **Context Relay Strategy**      | Strategi kombo menjaga kesinambungan sesi melalui ringkasan penyerahan terstruktur saat akun dirotasi di tengah percakapan                               |
| 🛡️ **Proxy Hardening**             | Pemeriksaan kesehatan token, validasi kunci API, dan operator undici semuanya menghormati konfigurasi proxy                                                              |
| ⚠️ **Node.js 24 Login Warning**    | Login page proactively detects incompatible Node.js versions and shows a clear warning banner                                                     |
| 📎 **Gemini PDF Attachments**      | PDF attachments correctly routed to Gemini via `inline_data` and generic base64 detection                                                         |
| 🔒 **Pengerasan Keamanan CodeQL**   | Resolved SSRF, insecure randomness, polynomial ReDoS, and incomplete URL sanitization alerts                                                      |

### 🆕 Baru — Peningkatan Terinspirasi ClawRouter (Mar 2026)

| Feature                              | Apa Fungsinya                                                                                |
| ------------------------------------ | ------------------------------------------------------------------------------------------- |
| ⚡ **Grok-4 Fast Family**            | xAI models at $0.20/$0.50/M — benchmarked 1143ms (30% faster than Gemini 2.5 Flash)         |
| 🧠 **GLM-5 via Z.AI**                | Konteks keluaran 128 ribu, $0,5/1 juta — andalan terbaru dari keluarga GLM                          |
| 🔮 **MiniMax M2.5**                  | Penalaran + tugas agen seharga $0,30/1 juta — peningkatan signifikan dari M2.1|
|🎯 **alat Memanggil Bendera per Model**    | Per model `toolCalling: true/false` di registri — AutoCombo melewatkan model yang tidak mendukung alat   |
| 🌍 **Multilingual Intent Detection** | Kata kunci PT/ZH/ES/AR dalam penilaian AutoCombo — pemilihan model yang lebih baik untuk konten non-Inggris  |
| 📊 **Benchmark-Driven Fallbacks**    | Latensi p95 nyata dari penilaian kombo umpan permintaan langsung — AutoCombo belajar dari data aktual |
| 🔁 **Request Deduplication**         | Content-hash based dedup window — multi-agent safe, prevents duplicate charges              |
| 🔌 **Pluggable RouterStrategy**      | Antarmuka `RouterStrategy` yang dapat diperluas — tambahkan logika perutean khusus sebagai plugin                 |

### 🚀 Sebelumnya v2.0.9+ — Playground, Fingerprint CLI & ACP

| Feature                                    | Apa Fungsinya                                                                                                                                                                                                                            |
| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 🎮 **Model Playground**                    | Halaman dasbor untuk menguji model apa pun secara langsung — pemilih penyedia/model/titik akhir, Editor Monaco, streaming, batalkan, pengaturan waktu                                                                                                                  |
| 🔏 **CLI Fingerprint Matching**            | Pengurutan header/isi per penyedia agar sesuai dengan tanda tangan CLI asli — alihkan per penyedia di Pengaturan > Keamanan. **IP proxy Anda dipertahankan**                                                                                           |
| 🤝 **Dukungan ACP (Protokol Klien Agen)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint                                                                                                                  |
| 🤖 **Dasbor Agen ACP**                | Debug › Halaman agen — kisi 14 agen dengan status pemasangan, versi, formulir agen khusus untuk alat CLI apa pun. Pengguna **OpenCode** mendapatkan tombol "Unduh opencode.json" yang secara otomatis menghasilkan konfigurasi siap pakai dengan semua model yang tersedia. |
| 🔧 **Custom Model `apiFormat` Routing**    | Model khusus dengan `apiFormat: "responses"` sekarang dirutekan dengan benar ke penerjemah Responses API                                                                                                                                         |
| 🏢 **Codex Workspace Isolation**           | Multiple Codex workspaces per email — OAuth correctly separates connections by workspace ID                                                                                                                                             |
| 🔄 **Pembaruan Otomatis Elektron**                | Aplikasi desktop memeriksa pembaruan + instal otomatis saat restart                                                                                                                                                                                |

### 🤖 Operasi Agen & Protokol (v2.0)

| Feature                               | Apa Fungsinya                                                                                                                           |
| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| 🔧 **Server MCP (25 alat)**          | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`). 18 core + 3 memory + 4 skill tools |
| 🤝 **Server A2A (JSON-RPC + SSE)**    | Eksekusi tugas agen-ke-agen dengan alur sinkronisasi dan streaming                                                                            |
| 🧭 **Halaman Titik Akhir Konsolidasi**    | Halaman manajemen bertab dengan tab Proksi Titik Akhir, MCP, A2A, dan Titik Akhir API|
| 🎚️ **Service Enable/Disable Toggles** |Sakelar ON/OFF untuk MCP dan A2A dengan pengaturan persistensi (default: OFF)                                                               |
| 🛰️ **Detak Jantung Waktu Proses MCP**          | Real process status (pid, uptime, heartbeat age, transport, scope mode)                                                                |
| 📋 **MCP Audit Trail**                | Log audit yang dapat difilter dengan keberhasilan/kegagalan dan atribusi kunci                                                                         |
| 🔐 **MCP Scope Enforcement**          | 10 izin cakupan terperinci untuk akses alat terkontrol                                                                               |
| 📡 **Manajemen Siklus Hidup Tugas A2A**  | List/filter tasks, inspect events/artifacts, cancel running tasks                                                                      |
| 📋 **Agent Card Discovery**           | `/.well-known/agent.json` untuk penemuan otomatis klien                                                                                    |
| 🧪 **Protocol E2E Test Harness**      | Klien MCP SDK + A2A asli mengalir di `test:protocols:e2e`                                                                                |
| ⚙️ **Operational Controls**           | Ganti kombo, sesuaikan pengaturan ketahanan, dan tinjau status pemutus dari permukaan Kesehatan dan Pengaturan khusus                          |

### 🧠 Routing & Kecerdasan

| Feature                            | Apa Fungsinya                                                             |
| ---------------------------------- | ------------------------------------------------------------------------ |
| 🎯 **Pengembalian 4 Tingkat Cerdas**       | Rute otomatis: Berlangganan → Kunci API → Murah → Gratis                        |
| 📊 **Pelacakan Kuota Waktu Nyata**    | Jumlah token langsung + setel ulang hitungan mundur per penyedia                          |
| 🔄 **Format Translation**          | OpenAI ↔ Claude ↔ Gemini ↔ Respons dengan konversi skema-aman        |
| 👥 **Dukungan Multi-Akun**       | Banyak akun per penyedia dengan pilihan cerdas                |
| 🔄 **Auto Token Refresh**          | Token OAuth disegarkan secara otomatis dengan percobaan ulang                            |
| 🎨 **Custom Combos**               | 13 strategi penyeimbangan + kontrol rantai mundur                         |
| 🔗 **Context Relay**               | Penyerahan kesinambungan sesi ketika rotasi akun terjadi di tengah sesi    |
| 🌐 **Wildcard Router**             | `provider/*` dynamic routing                                             |
| 🧠 **Thinking Budget Controls**    | Batas penalaran passthrough, otomatis, kustom, dan adaptif|
| 🔀 **Model Aliases**               |Alias ​​model khusus + bawaan dan keamanan migrasi                    |
| ⚡ **Background Degradation**      | Arahkan tugas latar belakang berprioritas rendah ke model yang lebih murah                    |
| 🧪 **Perutean Cerdas Sadar Tugas**    | Pilih model secara otomatis berdasarkan jenis konten (pengkodean/visi/analisis/ringkasan) |
| 🔄 **A2A Agent Workflows**         | Deterministic FSM orchestrator for stateful multi-step agent executions  |
| 🔀 **Adaptive Routing**            | Dynamic strategy override based on token volume and prompt complexity    |
| 🎲 **Provider Diversity**          | Shannon entropy scoring balancing auto-combo traffic distribution        |
| 💬 **System Prompt Injection**     | Global behavior controls applied consistently                            |
| 📄 **Kompatibilitas API Respons** | Dukungan penuh `/v1/responses` untuk Codex dan alur kerja agen tingkat lanjut    |

### 🎵 API Multi-Modal

| Feature                    | Apa Fungsinya                                                                                                                                                               |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 🖼️ **Image Generation**    | `/v1/images/generations` dengan cloud dan backend lokal                                                                                                                     |
| 📐 **Embeddings**          | `/v1/embeddings` untuk saluran pencarian dan RAG                                                                                                                              |
| 🎤 **Audio Transcription** | `/v1/audio/transcriptions` — 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |
| 🔊 **Text-to-Speech**      | `/v1/audio/speech` — 10 penyedia (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) dengan pesan kesalahan yang benar          |
| 🎬 **Video Generation**    | `/v1/videos/generations` (ComfyUI + SD WebUI workflows)                                                                                                                    |
| 🎵 **Music Generation**    | `/v1/music/generations` (ComfyUI workflows)                                                                                                                                |
| 🛡️ **Moderations**         | `/v1/moderations` safety checks                                                                                                                                            |
| 🔀 **Reranking**           | `/v1/rerank` untuk penilaian relevansi                                                                                                                                         |
| 🔍 **Web Search** 🆕       | `/v1/search` — 5 providers (Serper, Brave, Perplexity, Exa, Tavily), 6,500+ free/month, auto-failover, cache                                                               |

### 🛡️ Ketahanan, Keamanan & Tata Kelola

| Feature                             | Apa Fungsinya                                                                                            |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------- |
| 🔌 **Penyedia Pemutus Arus**    | Perjalanan/pemulihan di seluruh penyedia setelah kelelahan fallback dengan ambang batas yang dapat dikonfigurasi                       |
| 🔒 **Kunci Kuota Harian** 🆕          | Mendeteksi sinyal kelelahan dan mengunci perutean untuk model tertentu hingga tengah malam                      |
| 🎯 **Model Sadar Titik Akhir**        | Model khusus mendeklarasikan titik akhir + format API yang didukung                                                  |
| 🛡️ **Anti-Thundering Herd**         | Mutex + semaphore protections on retry/rate events                                                      |
| 🧠 **Semantic + Signature Cache**   | Pengurangan biaya/latensi dengan dua lapisan cache                                                            |
| ⚡ **Request Idempotency**          | Duplicate protection window                                                                             |
| 🔒 **TLS Fingerprint Spoofing**     | Sidik jari TLS seperti browser — **mengurangi deteksi bot dan penandaan akun**|
| 🔏 **CLI Fingerprint Matching**     | Matches native CLI request signatures — **reduces ban risk while preserving proxy IP**                  |
| 🌐 **IP Filtering**                 |Kontrol daftar yang diizinkan/daftar blokir untuk penerapan yang terbuka                                                     |
| 🚦 **Minta Antrian & Kecepatan**       | Bucket permintaan per koneksi yang dapat dikonfigurasi untuk RPM, spasi, konkurensi, dan waktu tunggu maksimal                 |
| 📉 **Graceful Degradation**         | Multi-layer capability fallbacks protecting core gateway operations                                     |
| 📜 **Config Audit Trail**           | Pelacakan perubahan berbasis diff mencegah penyimpangan operasional dengan rollback sederhana                           |
| ⏳ **Sinkronisasi Kesehatan Penyedia**         | Proactive token expiration monitoring triggering alerts before authorization failures                   |
| ❄️ **Connection Cooldown**          | Retryable 408/429/5xx failures cool down a single connection with optional upstream hints               |
| 🚪 **Nonaktifkan Otomatis Akun yang Diblokir** | Akun token yang diblokir secara permanen dapat dinonaktifkan secara otomatis                                        |
| 🔑 **Manajemen Kunci API + Pelingkupan** | Mengamankan penerbitan/rotasi kunci dan kontrol model/penyedia                                                |
| 👁️ **Pengungkapan Kunci API Cakupan** 🆕     | Ikut serta dalam pemulihan kunci API melalui `ALLOW_API_KEY_REVEAL`                                                  |
| 🛡️ **Protected `/models`**          | Gerbang autentikasi opsional dan penyembunyian penyedia untuk katalog model                                              |
| 🛡️ **Safe Outbound Fetch** 🆕       | Pengambilan yang dijaga untuk panggilan penyedia — memblokir URL pribadi/lokal, percobaan ulang, perlindungan SSRF                  |
| ⏳ **Tunggu Cooldown** 🆕         | Coba ulang obrolan secara otomatis setelah cooldown koneksi; dapat dikonfigurasi `enabled`, `maxRetries`, dan `maxRetryWaitSec` |
| 🔍 **Validasi Env Runtime** 🆕    | Zod-based env schema validation at startup with actionable error messages                               |
| 📋 **Compliance Audit v2** 🆕       | Penomoran halaman, konteks permintaan, peristiwa autentikasi, CRUD penyedia, dan logging yang diblokir SSRF                       |

### 📊 Observabilitas & Analitik

| Feature                          | Apa Fungsinya                                          |
| -------------------------------- | ----------------------------------------------------- |
| 📝 **Permintaan + Pencatatan Proksi**   | Permintaan/respons penuh dan pencatatan proksi|
| 📉 **Streamed Detailed Logs**    |Merekonstruksi aliran muatan SSE dengan rapi ke dalam UI  |
| 🏷️ **Lencana Model Real-Time** 🆕 | Status model langsung dan penghitung waktu mundur kuota harian    |
| 📋 **Dasbor Log Terpadu**    | Tampilan permintaan, proksi, audit, dan konsol dalam satu halaman  |
| 🔍 **Request Telemetry**         | latensi p50/p95/p99 dan penelusuran permintaan               |
| 🏥 **Health Dashboard**          | Uptime, breaker states, lockouts, cache stats         |
| 💰 **Cost Tracking**             | Kontrol anggaran dan visibilitas harga per model      |
| 📈 **Analytics Visualizations**  | Wawasan penggunaan model/penyedia dan tampilan tren         |
| 🧪 **Evaluation Framework**      | Pengujian set emas dengan strategi pencocokan yang dapat dikonfigurasi |
| 📡 **Live Diagnostics** 🆕       | Bypass cache semantik untuk pengujian langsung kombo yang akurat |
| 🔐 **TPS Log Metric** 🆕         | Tokens Per Second badge in log details modal          |

### ☁️ Deployment & Platform

| Feature                        | Apa Fungsinya                                                          |
| ------------------------------ | --------------------------------------------------------------------- |
| 🌐 **Deploy Anywhere**         | Localhost, VPS, Docker, Cloud environments                            |
| 🚇 **Cloudflare Tunnel** 🆕    | Integrasi Quick Tunnel sekali klik dari dasbor                 |
| 🔑 **Pemfilteran Model Kunci API** | Respons asli /v1/models difilter melalui peran konteks Pembawa yang ditetapkan |
| ⚡ **Smart Cache Bypass**      | Heuristik TTL yang dapat dikonfigurasi dan kontrol pengambilan ulang paksa               |
| 🔄 **Backup/Restore**          | Arus ekspor/impor dan pemulihan bencana                             |
| 🧙 **Onboarding Wizard**       | Penyiapan terpandu yang dijalankan pertama kali                                                |
| 🔧 **Dasbor Alat CLI**     | Pengaturan sekali klik untuk alat pengkodean populer                              |
| 🎮 **Model Playground**        | Uji penyedia/model/titik akhir apa pun dari dasbor|
| 🔏 **CLI Fingerprint Toggle**  |Pencocokan sidik jari per penyedia di Pengaturan > Keamanan              |
| 🌐 **i18n (30 languages)**     | Dasbor lengkap + dukungan bahasa dokumen dengan cakupan RTL              |
| 🧹 **Hapus Semua Model**        | Pembersihan daftar model sekali klik di detail penyedia                     |
| 👁️ **Sidebar Controls** 🆕     | Sembunyikan komponen dan integrasi dari Pengaturan Penampilan             |
| 📋 **Issue Templates**         | Templat GitHub standar untuk bug dan fitur                   |
| 📂 **Custom Data Directory**   | `DATA_DIR` penggantian untuk lokasi penyimpanan                              |
| 🌐 **V1 WebSocket Bridge** 🆕  | OpenAI-compatible WebSocket traffic proxied via `/v1/ws`              |
| 🔑 **Sync Tokens & Bundle** 🆕 | Konfigurasikan token sinkronisasi + titik akhir bundel berversi dengan dukungan ETag      |

### Fitur Penyelaman Mendalam

#### Penggantian cerdas dengan pengendalian biaya praktis

```txt
Combo: "my-coding-stack"
  1. cc/claude-opus-4-7
  2. nvidia/llama-3.3-70b
  3. glm/glm-4.7
  4. if/kimi-k2-thinking
```

Ketika kuota, tarif, atau kesehatan gagal, OmniRoute secara otomatis berpindah ke kandidat berikutnya tanpa peralihan manual.

#### Manajemen protokol yang terlihat dan dapat dioperasikan

- MCP + A2A dapat ditemukan di UI dan dokumen (tidak disembunyikan)
- API status protokol memaparkan data operasional langsung (`/api/mcp/*`, `/api/a2a/*`)
- Dasbor mencakup tindakan untuk operasi hari ke-2 (pengalihan kombo, pengaturan ulang pemutus, pembatalan tugas)

#### Workflow translator + validasi

Area Penerjemah meliputi:

- **Playground**: request transformation checks
- **Chat Tester**: full request/response round-trip
- **Test Bench**: multiple cases in one run
- **Live Monitor**: real-time traffic view

Ditambah validasi protokol dengan klien nyata melalui `npm run test:protocols:e2e`.

> 📖 **[MCP Server README](open-sse/mcp-server/README.md)** — Referensi alat, konfigurasi IDE, dan contoh klien
>
> 📖 **[A2A Server README](src/lib/a2a/README.md)** — Keterampilan, metode JSON-RPC, streaming, dan siklus hidup tugas

## 🧪 Evaluasi (Evals)

OmniRoute menyertakan kerangka evaluasi bawaan untuk menguji kualitas respons LLM terhadap rangkaian emas. Akses melalui **Analytics → Evals** di dasbor.

### Golden Set Bawaan

"OmniRoute Golden Set" yang dimuat sebelumnya berisi kasus uji untuk:

- Salam, matematika, geografi, pembuatan kode
- Kepatuhan format JSON, terjemahan, pembuatan penurunan harga
- Penolakan keamanan (konten berbahaya), penghitungan, logika boolean

### Strategi Evaluasi

| Strategy   | Description                                      | Example                          |
| ---------- | ------------------------------------------------ | -------------------------------- |
| `exact`    | Output must match exactly                        | `"4"`                            |
| `contains` | Output must contain substring (case-insensitive) | `"Paris"`                        |
| `regex`    | Output must match regex pattern                  | `"1.*2.*3"`                      |
| `custom`   | Custom JS function returns true/false            | `(output) => output.length > 10` |

---

## 📖 Panduan Setup

### Pengaturan Protokol (MCP + A2A)

<details>
<summary><b>🧩 Penyiapan MCP (Protokol Konteks Model)</b></summary>

Start MCP transport in stdio mode:

```bash
omniroute --mcp
```

Recommended validation flow:

1. Hubungkan klien MCP Anda melalui stdio.
2. Jalankan `omniroute_get_health`.
3. Jalankan `omniroute_list_combos`.
4. Buka `/dashboard/mcp` untuk mengonfirmasi detak jantung, aktivitas, dan audit.

API yang berguna untuk otomatisasi:

- `GET /api/mcp/status`
- `GET /api/mcp/tools`
- `GET /api/mcp/audit`
- `GET /api/mcp/audit/stats`

</details>

<details>
<summary><b>🤝 Pengaturan A2A (Agen2Agen)</b></summary>

Temukan agennya:

```bash
curl http://localhost:20128/.well-known/agent.json
```

Send a task:

```bash
curl -X POST http://localhost:20128/a2a \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":"setup-a2a","method":"message/send","params":{"skill":"quota-management","messages":[{"role":"user","content":"Summarize quota status."}]}}'
```

Manage lifecycle:

- `GET /api/a2a/status`
- `GET /api/a2a/tasks`
- `GET /api/a2a/tasks/:id`
- `POST /api/a2a/tasks/:id/cancel`

Operational UI:

- `/dashboard/a2a` untuk observasi tugas/status/aliran dan tindakan asap

</details>

<details>
<summary><b>🧪 Validasi protokol end-to-end</b></summary>

Validasi kedua protokol dengan klien nyata:

```bash
npm run test:protocols:e2e
```

This verifies:

- Koneksi/daftar/panggilan klien MCP SDK
- Penemuan A2A/kirim/aliran/dapatkan/batalkan
- Periksa silang data dalam audit MCP dan API manajemen tugas A2A

</details>

<details>
<summary><b>💳 Penyedia Berlangganan</b></summary>

### Claude Code (Pro/Max)

```bash
Dashboard → Providers → Connect Claude Code
→ OAuth login → Auto token refresh
→ 5-hour + weekly quota tracking

Models:
  cc/claude-opus-4-7
  cc/claude-sonnet-4-5-20250929
  cc/claude-haiku-4-5-20251001
```

**Kiat Pro:** Gunakan Opus untuk tugas kompleks, Soneta untuk kecepatan. OmniRoute melacak kuota per model!

### OpenAI Codex (Plus/Pro)

```bash
Dashboard → Providers → Connect Codex
→ OAuth login (port 1455)
→ 5-hour + weekly reset

Models:
  cx/gpt-5.2-codex
  cx/gpt-5.1-codex-max
```

#### Manajemen Batas Akun Codex (5 jam + Mingguan)

Setiap akun Codex kini memiliki kebijakan yang dapat diubah di `Dashboard -> Providers`:

- `5h` (ON/OFF): menerapkan kebijakan ambang jendela 5 jam.
- `Weekly` (ON/OFF): menerapkan kebijakan ambang jendela mingguan.
- Perilaku ambang batas: ketika jendela yang diaktifkan mencapai >=90% penggunaan, akun tersebut dilewati.
- Perilaku rotasi: OmniRoute merutekan ke akun Codex berikutnya yang memenuhi syarat secara otomatis.
- Perilaku reset: ketika waktu `resetAt` penyedia telah berlalu, akun akan memenuhi syarat lagi secara otomatis.

Scenarios:

- `5h ON` + `Weekly ON`: akun dilewati ketika salah satu jendela mencapai ambang batas.
- `5h OFF` + `Weekly ON`: hanya penggunaan mingguan yang dapat memblokir akun.
- `5h ON` + `Weekly OFF` : hanya penggunaan 5 jam yang dapat memblokir akun.
- `resetAt` lolos: akun masuk kembali ke rotasi secara otomatis (tidak ada pengaktifan ulang secara manual).

### Gemini CLI (GRATIS 180K/bulan!)

```bash
Dashboard → Providers → Connect Gemini CLI
→ Google OAuth
→ 180K completions/month + 1K/day

Models:
  gc/gemini-3-flash-preview
  gc/gemini-2.5-pro
```

**Nilai Terbaik:** Tingkat gratis yang sangat besar! Gunakan ini sebelum tingkatan berbayar.

### GitHub Copilot

```bash
Dashboard → Providers → Connect GitHub
→ OAuth via GitHub
→ Monthly reset (1st of month)

Models:
  gh/gpt-5
  gh/claude-4.5-sonnet
  gh/gemini-3.1-pro-preview
```

</details>

<details>
<summary><b>🔑 Penyedia Kunci API</b></summary>

### NVIDIA NIM (akses pengembang GRATIS — 70+ model)

1. Daftar: [build.nvidia.com](https://build.nvidia.com)
2. Dapatkan kunci API gratis (termasuk 1000 kredit inferensi)
3. Dasbor → Tambah Penyedia → NVIDIA NIM:
   - Kunci API: `nvapi-your-key`

**Model:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, dan 50+ lainnya

**Kiat Pro:** API yang kompatibel dengan OpenAI — bekerja secara lancar dengan terjemahan format OmniRoute!

### DeepSeek

1. Daftar: [platform.deepseek.com](https://platform.deepseek.com)
2. Dapatkan kunci API
3. Dasbor → Tambah Penyedia → DeepSeek

**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder`

### Groq (Tersedia Tingkat Gratis!)

1. Daftar: [console.groq.com](https://console.groq.com)
2. Dapatkan kunci API (termasuk tingkat gratis)
3. Dasbor → Tambah Penyedia → Groq

**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b`

**Pro Tip:** Ultra-fast inference — best for real-time coding!

### OpenRouter (100+ Model)

1. Daftar: [openrouter.ai](https://openrouter.ai)
2. Dapatkan kunci API
3. Dasbor → Tambah Penyedia → OpenRouter

**Model:** Akses 100+ model dari semua penyedia utama melalui satu kunci API.

**Perilaku dasbor:** Model OpenRouter dikelola dari **Model yang Tersedia**. Penambahan manual, impor, dan sinkronisasi otomatis semuanya memperbarui daftar yang sama.

</details>

<details>
<summary><b>💰 Penyedia Murah (Cadangan)</b></summary>

### GLM-4.7 (Reset harian, $0.6/1M)

1. Daftar: [Zhipu AI](https://open.bigmodel.cn/)
2. Dapatkan kunci API dari Coding Plan
3. Dasbor → Tambahkan Kunci API:
   - Penyedia: `glm`
   - Kunci API: `your-key`

**Use:** `glm/glm-4.7`

**Tips Pro:** Paket Coding menawarkan 3× kuota dengan biaya 1/7! Reset setiap hari pukul 10.00.

### MiniMax M2.1 (Reset 5 jam, $0.20/1M)

1. Daftar: [MiniMax](https://www.minimax.io/)
2. Dapatkan kunci API
3. Dasbor → Tambahkan Kunci API

**Use:** `minimax/MiniMax-M2.1`

**Kiat Pro:** Opsi termurah untuk konteks panjang (1 juta token)!

### Kimi K2 ($9/bulan flat)

1. Berlangganan: [Moonshot AI](https://platform.moonshot.ai/)
2. Dapatkan kunci API
3. Dasbor → Tambahkan Kunci API

**Use:** `kimi/kimi-latest`

**Kiat Pro:** Memperbaiki $9/bulan untuk 10 juta token = biaya efektif $0,90/1 juta!

</details>

<details>
<summary><b>🆓 Penyedia GRATIS (Cadangan Darurat)</b></summary>

### Qoder (5 model GRATIS melalui OAuth)

```bash
Dashboard → Connect Qoder
→ Qoder OAuth login
→ Unlimited usage

Models:
  if/kimi-k2-thinking
  if/qwen3-coder-plus
  if/glm-4.7
  if/minimax-m2
  if/deepseek-r1
```

### Qwen (4 model GRATIS melalui Kode Perangkat)

```bash
Dashboard → Connect Qwen
→ Device code authorization
→ Unlimited usage

Models:
  qw/qwen3-coder-plus
  qw/qwen3-coder-flash
```

### Kiro (Claude GRATIS)

```bash
Dashboard → Connect Kiro
→ AWS Builder ID or Google/GitHub
→ Unlimited usage

Models:
  kr/claude-sonnet-4.5
  kr/claude-haiku-4.5
```

</details>

<details>
<summary><b>🎨 Membuat Combo</b></summary>

### Contoh 1: Maksimalkan Langganan → Cadangan Murah

```
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.1 (Cheapest fallback, $0.20/1M)

Use in CLI: premium-coding
```

### Contoh 2: Gratis Saja (Tanpa Biaya)

```
Name: free-combo
Models:
  1. gc/gemini-3-flash-preview (180K free/month)
  2. if/kimi-k2-thinking (unlimited)
  3. qw/qwen3-coder-plus (unlimited)

Cost: $0 forever!
```

</details>

<details>
<summary><b>🔧 Integrasi CLI</b></summary>

### Cursor IDE

```
Settings → Models → Advanced:
  OpenAI API Base URL: http://localhost:20128/v1
  OpenAI API Key: [from OmniRoute dashboard]
  Model: cc/claude-opus-4-7
```

### Claude Code

Gunakan halaman **Alat CLI** di dasbor untuk konfigurasi sekali klik, atau edit `~/.claude/settings.json` secara manual.

### Codex CLI

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

codex "your prompt"
```

### OpenClaw

**Opsi 1 — Dasbor (disarankan):**

```
Dashboard → CLI Tools → OpenClaw → Select Model → Apply
```

**Option 2 — Manual:** Edit `~/.openclaw/openclaw.json`:

```json
{
  "models": {
    "providers": {
      "omniroute": {
        "baseUrl": "http://127.0.0.1:20128/v1",
        "apiKey": "sk_omniroute",
        "api": "openai-completions"
      }
    }
  }
}
```

> **Catatan:** OpenClaw hanya berfungsi dengan OmniRoute lokal. Gunakan `127.0.0.1` alih-alih `localhost` untuk menghindari masalah resolusi IPv6.

### Cline / Continue / RooCode

```
Settings → API Configuration:
  Provider: OpenAI Compatible
  Base URL: http://localhost:20128/v1
  API Key: [from OmniRoute dashboard]
  Model: if/kimi-k2-thinking
```

### OpenCode

**Langkah 1:** Tambahkan OmniRoute sebagai penyedia khusus:

```bash
opencode
/connect
# Select "Other" → Enter ID: "omniroute" → Enter your OmniRoute API key
```

**Langkah 2:** Buat/edit `opencode.json` di root proyek Anda:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "omniroute": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "OmniRoute",
      "options": {
        "baseURL": "http://localhost:20128/v1"
      },
      "models": {
        "cc/claude-sonnet-4-20250514": { "name": "Claude Sonnet 4" },
        "gg/gemini-2.5-pro": { "name": "Gemini 2.5 Pro" },
        "if/kimi-k2-thinking": { "name": "Kimi K2 (Free)" }
      }
    }
  }
}
```

**Langkah 3:** Pilih model di OpenCode:

```bash
/models
# Select any OmniRoute model from the list
```

> **Tips:** Tambahkan model apa pun yang tersedia di titik akhir OmniRoute `/v1/models` Anda ke bagian `models`. Gunakan format `provider/model-id` dari dasbor OmniRoute Anda.

</details>

---

## Pemecahan Masalah

<details>
<summary><b>Klik untuk memperluas panduan pemecahan masalah</b></summary>

**"Model bahasa tidak memberikan pesan"**

- Kuota penyedia habis → Periksa dashboard pelacak kuota
- Solusi: Gunakan combo fallback atau beralih ke tier yang lebih murah

**Rate limiting**

- Kuota berlangganan habis → Penggantian ke GLM/MiniMax
- Tambahkan kombo: `cc/claude-opus-4-7 → glm/glm-4.7 → if/kimi-k2-thinking`

**OAuth token expired**

- Disegarkan secara otomatis oleh OmniRoute
- Jika masalah terus berlanjut: Dasbor → Penyedia → Sambungkan kembali

**High costs**

- Periksa statistik penggunaan di Dashboard → Biaya
- Ganti model utama ke GLM/MiniMax
- Gunakan tingkat gratis (Gemini CLI, Qoder) untuk tugas-tugas yang tidak penting

**Port dasbor/API salah**

- `PORT` adalah port dasar kanonik (dan port API secara default)
- `API_PORT` hanya menimpa pendengar API yang kompatibel dengan OpenAI
- `DASHBOARD_PORT` hanya menimpa dashboard/pendengar Next.js
- Setel `NEXT_PUBLIC_BASE_URL` ke dasbor/URL publik Anda (untuk panggilan balik OAuth)

**Cloud sync errors**

- Verifikasi `BASE_URL` poin ke instance Anda yang sedang berjalan
- Verifikasi `CLOUD_URL` poin ke titik akhir cloud yang Anda harapkan
- Jaga agar nilai `NEXT_PUBLIC_*` selaras dengan nilai sisi server

**First login not working**

- Periksa `INITIAL_PASSWORD` di `.env`
- Jika tidak disetel, kata sandi cadangan adalah `123456`

**Tidak ada log permintaan**

- `call_logs` di SQLite menyimpan metadata ringkasan untuk tabel Log Permintaan dan tampilan analitik
- Muatan permintaan/respons terperinci ditulis ke `DATA_DIR/call_logs/` sebagai satu artefak JSON per permintaan
- Aktifkan pengambilan saluran pipa dari Dasbor → Log → Log Permintaan jika Anda memerlukan muatan per tahap yang terperinci
- `Export Logs` membaca file artefak sesuai permintaan, sementara `Export All` menyertakan direktori `call_logs/` bersama `storage.sqlite`
- Setel `APP_LOG_TO_FILE=true` jika Anda juga ingin log konsol aplikasi di `logs/application/app.log`
- Sesuaikan `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, dan `CALL_LOG_MAX_ENTRIES` sesuai kebutuhan

**Tes koneksi menunjukkan "Tidak Valid" untuk penyedia yang kompatibel dengan OpenAI**

- Banyak penyedia tidak mengekspos titik akhir `/models`
- OmniRoute v1.0.6+ menyertakan validasi fallback melalui penyelesaian obrolan
- Pastikan URL dasar menyertakan akhiran `/v1`

### 🔐 OAuth di Server Jarak Jauh

<a name="oauth-on-a-remote-server"></a>
<a name="oauth-em-servidor-remoto"></a>

> **⚠️ Penting bagi pengguna yang menjalankan OmniRoute di VPS, Docker, atau server jarak jauh mana pun**

#### Mengapa OAuth Antigravity / Gemini CLI gagal di server jarak jauh?

Penyedia **Antigravitasi** dan **Gemini CLI** menggunakan **Google OAuth 2.0**. Google mewajibkan `redirect_uri` dalam alur OAuth agar sama persis dengan salah satu URI yang telah didaftarkan sebelumnya di Google Cloud Console aplikasi.

Kredensial OAuth yang disertakan dalam OmniRoute didaftarkan **hanya untuk `localhost`**. Saat Anda mengakses OmniRoute di server jarak jauh (misalnya `https://omniroute.myserver.com`), Google menolak autentikasi dengan:

```
Error 400: redirect_uri_mismatch
```

#### Solusi: Konfigurasikan kredensial OAuth Anda sendiri

Anda perlu membuat **ID Klien OAuth 2.0** di Google Cloud Console dengan URI server Anda.

#### Langkah demi langkah

**1. Open Google Cloud Console**

Go to: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)

**2. Buat ID Klien OAuth 2.0 baru**

- Klik **"+ Buat Kredensial"** → **"ID klien OAuth"**
- Jenis aplikasi: **"Aplikasi web"**
- Nama: apa pun yang Anda suka (mis. `OmniRoute Remote`)

**3. Add Authorized Redirect URIs**

Di kolom **"URI pengalihan resmi"**, tambahkan:

```
https://your-server.com/callback
```

> Ganti `your-server.com` dengan domain atau IP server Anda (sertakan port jika diperlukan, misalnya `http://45.33.32.156:20128/callback`).

**4. Simpan dan salin kredensial**

Setelah pembuatan, Google akan menampilkan **ID Klien** dan **Rahasia Klien**.

**5. Tetapkan variabel lingkungan**

Di `.env` Anda (atau variabel lingkungan Docker):

```bash
# For Antigravity:
ANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com
ANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret

# For Gemini CLI:
GEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com
GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret
GEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret
```

**6. Restart OmniRoute**

```bash
# npm:
npm run dev

# Docker:
docker restart omniroute
```

**7. Try connecting again**

Dasbor → Penyedia → Antigravitasi (atau Gemini CLI) → OAuth

Google will now redirect correctly to `https://your-server.com/callback`.

---

#### Solusi sementara (tanpa kredensial kustom)

Jika Anda tidak ingin menyiapkan kredensial Anda sendiri saat ini, Anda masih dapat menggunakan **alur URL manual**:

1. OmniRoute membuka URL otorisasi Google
2. Setelah otorisasi, Google mencoba mengalihkan ke `localhost` (yang gagal di server jauh)
3. **Salin URL lengkap** dari bilah alamat browser Anda (meskipun halaman tidak dimuat)
4. Tempelkan URL tersebut ke bidang yang ditampilkan di modal koneksi OmniRoute
5. Klik **"Hubungkan"**

> Ini berfungsi karena kode otorisasi di URL valid terlepas dari apakah halaman pengalihan dimuat.

---

<details>
<summary><b>🇧🇷 Versão em Português</b></summary>

#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos?

Os provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticação. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs pré-cadastradas no Google Cloud Console do aplicativo.

As credenciais OAuth embutidas no OmniRoute estão cadastradas **apenas para `localhost`**. Quando você acessa o OmniRoute em um servidor remoto (ex: `https://omniroute.meuservidor.com`), o Google rejeita a autenticação com:

```
Error 400: redirect_uri_mismatch
```

#### Solução: Configure suas próprias credenciais OAuth

Você precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor.

#### Passo a passo

**1. Acesse o Google Cloud Console**

Abra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)

**2. Inilah ID Klien OAuth 2.0 yang baru**

- Klik pada **"+ Buat Kredensial"** → **"ID klien OAuth"**
- Tip aplikasi: **"Aplikasi web"**
- Nama: nama escolha qualquer (misal: `OmniRoute Remote`)

**3. Adicione as Authorized Redirect URIs**

No campo **"Authorized redirect URIs"**, adicione:

```
https://seu-servidor.com/callback
```

> Substitua `seu-servidor.com` pelo domínio ou IP do seu servidor (inclua a porta se necessário, ex: `http://45.33.32.156:20128/callback`).

**4. Salve e copie as credenciais**

Kemudian, Google menampilkan **ID Klien** dan **Rahasia Klien**.

**5. Configure as variáveis de ambiente**

No seu `.env` (ou nas variáveis de ambiente do Docker):

```bash
# Para Antigravity:
ANTIGRAVITY_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com
ANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret

# Para Gemini CLI:
GEMINI_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com
GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret
GEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret
```

**6. Reinicie o OmniRoute**

```bash
# Se usando npm:
npm run dev

# Se usando Docker:
docker restart omniroute
```

**7. Tente conectar novamente**

Dasbor → Penyedia → Antigravitasi (atau Gemini CLI) → OAuth

Agora o Google redirecionará corretamente para `https://seu-servidor.com/callback` e a autenticação funcionará.

---

#### Workaround temporário (sem configurar credenciais próprias)

Se não quiser criar credenciais próprias agora, ainda é possível usar o fluxo **manual de URL**:

1. O OmniRoute abrirá a URL de autorização do Google
2. Após você autorizar, o Google tentará redirecionar para `localhost` (que falha no servidor remoto)
3. **Copie a URL completa** da barra de endereço do seu browser (mesmo que a página não carregue)
4. Cole essa URL no campo que aparece no modal de conexão do OmniRoute
5. Clique em **"Connect"**

> Este workaround funciona porque o código de autorização na URL é válido independente do redirect ter carregado ou não.

</details>

---

</details>

## 🛠️ Stack Teknologi

<details>
<summary><b>Klik untuk membuka detail stack teknologi</b></summary>

- **Runtime**: Node.js 18–22 LTS (⚠️ Node.js 24+ **tidak didukung** — `better-sqlite3` biner asli tidak kompatibel)
- **Bahasa**: TypeScript 5.9 — **100% TypeScript** di `src/` dan `open-sse/` (nol `any` dalam modul inti sejak v2.0)
- **Kerangka Kerja**: Next.js 16 + React 19 + Tailwind CSS 4
- **Database**: lebih baik-sqlite3 (SQLite) + LowDB (JSON legacy) — status domain, log proksi, audit MCP, keputusan perutean, memori, keterampilan
- **Skema**: Zod (validasi I/O alat MCP, kontrak API)
- **Protokol**: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)
- **Streaming**: Peristiwa Terkirim Server (SSE)
- **Auth**: OAuth 2.0 (PKCE) + JWT + Kunci API + Otorisasi Cakupan MCP
- **Pengujian**: Pelari pengujian Node.js + Vitest (900+ pengujian termasuk unit, integrasi, E2E)
- **CI/CD**: Tindakan GitHub (publikasi npm otomatis + Docker Hub saat dirilis)
- **Situs Web**: [omniroute.online](https://omniroute.online)
- **Paket**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)
- **Pekerja Pelabuhan**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)
- **Ketahanan**: Pemutus arus, backoff eksponensial, kawanan anti-thundering, spoofing TLS, penyembuhan diri kombo otomatis

</details>

---

## Dokumentasi

| Document                                                              | Description                                         |
| --------------------------------------------------------------------- | --------------------------------------------------- |
| [User Guide](docs/guides/USER_GUIDE.md)                               | Penyedia, kombo, integrasi CLI, penerapan      |
| [API Reference](docs/reference/API_REFERENCE.md)                      | Semua titik akhir dengan contoh                         |
| [MCP Server](open-sse/mcp-server/README.md)                           | 25 alat MCP, konfigurasi IDE, klien Python/TS/Go     |
| [A2A Server](src/lib/a2a/README.md)                                   | Protokol JSON-RPC 2.0, keterampilan, streaming, manajemen tugas |
| [Auto-Combo Engine](docs/routing/AUTO-COMBO.md)                       | 6-factor scoring, mode packs, self-healing          |
| [Context Relay](docs/features/context-relay.md)                       | Strategi penyerahan sesi untuk rotasi akun       |
| [Troubleshooting](docs/guides/TROUBLESHOOTING.md)                     | Masalah umum dan solusinya                       |
| [Architecture](docs/architecture/ARCHITECTURE.md)                     | Arsitektur sistem dan internal|
| [Codebase Documentation](docs/architecture/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough              |
| [Uninstall Guide](docs/guides/UNINSTALL.md)                           |Penghapusan bersih untuk semua metode instalasi               |
| [Environment Config](docs/reference/ENVIRONMENT.md)                   | Lengkapi `.env` variabel dan referensi            |
| [Contributing](CONTRIBUTING.md)                                       | Pengaturan dan pedoman pengembangan                    |
| [OpenAPI Spec](docs/reference/openapi.yaml)                           | OpenAPI 3.0 specification                           |
| [Security Policy](SECURITY.md)                                        | Pelaporan kerentanan dan praktik keamanan      |
| [VM Deployment](docs/ops/VM_DEPLOYMENT_GUIDE.md)                      | Panduan lengkap: pengaturan VM + nginx + Cloudflare       |
| [Features Gallery](docs/guides/FEATURES.md)                           | Tur dasbor visual dengan tangkapan layar              |
| [Release Checklist](docs/ops/RELEASE_CHECKLIST.md)                    | Pre-release validation steps                        |

---

## 🗺️ Roadmap

OmniRoute memiliki **218+ fitur yang direncanakan** di berbagai fase pengembangan. Berikut adalah bidang-bidang utamanya:

| Category                      | Planned Features | Highlights                                                                                            |
| ----------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------- |
| 🧠 **Routing & Intelligence** | 25+              | Perutean latensi terendah, perutean berbasis tag, preflight kuota, P2C sadar kuota, perutean kombo berbasis langkah |
| 🔒 **Security & Compliance**  | 20+              | Pengerasan SSRF, penyelubungan kredensial, batas tarif per titik akhir, pelingkupan kunci manajemen                  |
| 📊 **Observability**          | 15+              | Integrasi OpenTelemetry, pemantauan kuota waktu nyata, kesehatan target kombo, pelacakan biaya per model   |
| 🔄 **Provider Integrations**  | 20+              | Registri model dinamis, cooldown koneksi, Codex multi-akun, penguraian kuota Salinan              |
| ⚡ **Performance**            | 15+              | Lapisan cache ganda, cache cepat, cache respons, streaming keepalive, API batch|
| 🌐 **Ecosystem**              | 10+              | WebSocket API, config hot-reload, distributed config store, commercial mode                           |

### 🔜 Segera Hadir

- 🔗 **Integrasi OpenCode** — Dukungan penyedia asli untuk IDE pengkodean AI OpenCode
- 🔗 **Integrasi TRAE** — Dukungan penuh untuk kerangka pengembangan AI TRAE
- 📦 **Batch API** — Pemrosesan batch asinkron untuk permintaan massal
- 🎯 **Perutean Berbasis Tag** — Merutekan permintaan berdasarkan tag dan metadata khusus
- 💰 **Strategi Biaya Terendah** — Secara otomatis memilih penyedia termurah yang tersedia

> 📝 Spesifikasi fitur lengkap tersedia di [docs/new-features/](docs/new-features/) (217 spesifikasi detail)

---

## 👥 Kontributor

[![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)

### Cara Berkontribusi

1. Cabangkan repositori
2. Buat cabang fitur Anda (`git checkout -b feature/amazing-feature`)
3. Komit perubahan Anda (`git commit -m 'Add amazing feature'`)
4. Dorong ke cabang (`git push origin feature/amazing-feature`)
5. Buka Permintaan Tarik

Lihat [CONTRIBUTING.md](CONTRIBUTING.md) untuk panduan detailnya.

### Merilis Versi Baru

```bash
# Create a release — npm publish happens automatically
gh release create v2.0.0 --title "v2.0.0" --generate-notes
```

---

## 📊 Riwayat Star

<a href="https://www.star-history.com/?repos=diegosouzapw%2Fomniroute&type=date&legend=top-left">
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=diegosouzapw/omniroute&type=date&theme=dark&legend=top-left" />
   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=diegosouzapw/omniroute&type=date&legend=top-left" />
   <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=diegosouzapw/omniroute&type=date&legend=top-left" />
 </picture>
</a>

## 🌍 StarMapper

<a href="https://starmapper.bruniaux.com/diegosouzapw/omniroute">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute?theme=dark" />
    <source media="(prefers-color-scheme: light)" srcset="https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute?theme=light" />
    <img alt="StarMapper" src="https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute" />
  </picture>
</a>

## 🙏 Ucapan Terima Kasih

Terima kasih khusus kepada **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — implementasi Go asli yang menginspirasi port JavaScript ini.

---

## Lisensi

Lisensi MIT - lihat [LICENSE](LICENSE) untuk detailnya.

---

<div align="center">
  <sub>Built with ❤️ for developers who code 24/7</sub>
  <br/>
  <sub><a href="https://omniroute.online">omniroute.online</a></sub>
</div>
<!-- GitHub Discussions enabled for community Q&A -->
