<div align="center">
  <img src="./docs/screenshots/MainOmniRoute.png" alt="OmniRoute Dashboard" width="800"/>
  
  # 🚀 OmniRoute — Cổng AI miễn phí

### Không bao giờ ngừng viết mã. Định tuyến thông minh tới **Mô hình AI MIỄN PHÍ và chi phí thấp** với tính năng dự phòng tự động.

_Proxy API phổ quát của bạn — một điểm cuối, hơn 36 nhà cung cấp, không có thời gian ngừng hoạt động._

**Hoàn thành cuộc trò chuyện • Nhúng • Tạo hình ảnh • Âm thanh • Sắp xếp lại • 100% TypeScript**

---

### 🤖 Nhà cung cấp AI miễn phí cho các tác nhân mã hóa yêu thích của bạn

_Kết nối mọi công cụ IDE hoặc CLI được hỗ trợ bởi AI thông qua OmniRoute — cổng API miễn phí để mã hóa không giới hạn._

  <table>
    <tr>
      <td align="center" width="110">
        <a href="https://github.com/cline/cline">
          <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.png" 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.png" 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.png" 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.png" alt="Kilo Code" width="48"/><br/>
          <b>Kilo Code</b>
        </a><br/>
        <sub>⭐ 15.5K</sub>
      </td>
    </tr>
  </table>

<sub>📡 Tất cả đại lý kết nối qua <code>http://localhost:20128/v1</code> hoặc <code>http://cloud.omniroute.online/v1</code> — một cấu hình, số mô hình và hạn ngạch không giới hạn</sub>

---

[![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)
[![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) • [🚀 Quick Start](#-quick-start) • [💡 Features](#-key-features) • [📖 Docs](#-documentation) • [💰 Pricing](#-pricing-at-a-glance) • [💬 WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)

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

</div>

---

## 🤔 Tại sao lại là OmniRoute?

**Ngưng lãng phí tiền và đạt đến giới hạn:**

- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> Hạn mức đăng ký hết hạn không được sử dụng hàng tháng
- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> Giới hạn tốc độ khiến bạn không thể viết mã giữa chừng
- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> API đắt tiền ($20-50/tháng cho mỗi nhà cung cấp)
- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> Chuyển đổi thủ công giữa các nhà cung cấp

**OmniRoute giải quyết vấn đề này:**

- ✅ **Tối đa hóa số lượt đăng ký** - Theo dõi hạn ngạch, sử dụng từng bit trước khi đặt lại
- ✅ **Tự động dự phòng** - Đăng ký → Khóa API → Giá rẻ → Miễn phí, không có thời gian ngừng hoạt động
- ✅ **Nhiều tài khoản** - Luân chuyển giữa các tài khoản cho mỗi nhà cung cấp
- ✅ **Universal** - Hoạt động với Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, mọi công cụ CLI

---

## 🔄 Nó hoạt động như thế nào

```
┌─────────────┐
│  Your CLI   │  (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)
│   Tool      │
└──────┬──────┘
       │ http://localhost:20128/v1
       ↓
┌─────────────────────────────────────────┐
│           OmniRoute (Smart Router)        │
│  • Format translation (OpenAI ↔ Claude) │
│  • Quota tracking + Embeddings + Images │
│  • Auto token refresh                   │
└──────┬──────────────────────────────────┘
       │
       ├─→ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI
       │   ↓ quota exhausted
       ├─→ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.
       │   ↓ budget limit
       ├─→ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)
       │   ↓ budget limit
       └─→ [Tier 4: FREE] iFlow, Qwen, Kiro (unlimited)

Result: Never stop coding, minimal cost
```

---

## 🎯 What OmniRoute Solves — 16 Real Pain Points

> **Every developer using AI tools faces these problems daily.** OmniRoute was built to solve them all — from cost overruns to regional blocks, from broken OAuth flows to zero observability.

<details>
<summary><b>💸 1. "I pay for an expensive subscription but still get interrupted by limits"</b></summary>

Developers pay $20–200/month for Claude Pro, Codex Pro, or GitHub Copilot. Even paying, quota has a ceiling — 5h of usage, weekly limits, or per-minute rate limits. Mid-coding session, the provider stops responding and the developer loses flow and productivity.

**How OmniRoute solves it:**

- **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention
- **Real-Time Quota Tracking** — Shows token consumption in real-time with reset countdown (5h, daily, weekly)
- **Multi-Account Support** — Multiple accounts per provider with auto round-robin — when one runs out, switches to the next
- **Custom Combos** — Customizable fallback chains with 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized)
- **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard

</details>

<details>
<summary><b>🔌 2. "I need to use multiple providers but each has a different API"</b></summary>

OpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If a dev wants to test models from different providers or fallback between them, they need to reconfigure SDKs, change endpoints, deal with incompatible formats. Custom providers (FriendLI, NIM) have non-standard model endpoints.

**How OmniRoute solves it:**

- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 36+ providers
- **Format Translation** — Automatic and transparent: OpenAI ↔ Claude ↔ Gemini ↔ Responses API
- **Response Sanitization** — Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+
- **Role Normalization** — Converts `developer` → `system` for non-OpenAI providers; `system` → `user` for GLM/ERNIE
- **Think Tag Extraction** — Extracts `<think>` blocks from models like DeepSeek R1 into standardized `reasoning_content`
- **Structured Output for Gemini** — `json_schema` → `responseMimeType`/`responseSchema` automatic conversion
- **`stream` defaults to `false`** — Aligns with OpenAI spec, avoiding unexpected SSE in Python/Rust/Go SDKs

</details>

<details>
<summary><b>🌐 3. "My AI provider blocks my region/country"</b></summary>

Providers like OpenAI/Codex block access from certain geographic regions. Users get errors like `unsupported_country_region_territory` during OAuth and API connections. This is especially frustrating for developers from developing countries.

**How OmniRoute solves it:**

- **3-Level Proxy Config** — Configurable proxy at 3 levels: global (all traffic), per-provider (one provider only), and per-connection/key
- **Color-Coded Proxy Badges** — Visual indicators: 🟢 global proxy, 🟡 provider proxy, 🔵 connection proxy, always showing the IP
- **OAuth Token Exchange Through Proxy** — OAuth flow also goes through the proxy, solving `unsupported_country_region_territory`
- **Connection Tests via Proxy** — Connection tests use the configured proxy (no more direct bypass)
- **SOCKS5 Support** — Full SOCKS5 proxy support for outbound routing
- **TLS Fingerprint Spoofing** — Browser-like TLS fingerprint via `wreq-js` to bypass bot detection

</details>

<details>
<summary><b>🆓 4. "I want to use AI for coding but I have no money"</b></summary>

Not everyone can pay $20–200/month for AI subscriptions. Students, devs from emerging countries, hobbyists, and freelancers need access to quality models at zero cost.

**How OmniRoute solves it:**

- **Free Tier Providers Built-in** — Native support for 100% free providers: iFlow (8 unlimited models), Qwen (3 unlimited models), Kiro (Claude for free), Gemini CLI (180K/month free)
- **Free-Only Combos** — Chain `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = $0/month with zero downtime
- **NVIDIA NIM Free Credits** — 1000 free credits integrated
- **Cost Optimized Strategy** — Routing strategy that automatically chooses the cheapest available provider

</details>

<details>
<summary><b>🔒 5. "I need to protect my AI gateway from unauthorized access"</b></summary>

When exposing an AI gateway to the network (LAN, VPS, Docker), anyone with the address can consume the developer's tokens/quota. Without protection, APIs are vulnerable to misuse, prompt injection, and abuse.

**How OmniRoute solves it:**

- **API Key Management** — Generation, rotation, and scoping per provider with a dedicated `/dashboard/api-manager` page
- **Model-Level Permissions** — Restrict API keys to specific models (`openai/*`, wildcard patterns), with Allow All/Restrict toggle
- **API Endpoint Protection** — Require a key for `/v1/models` and block specific providers from the listing
- **Auth Guard + CSRF Protection** — All dashboard routes protected with `withAuth` middleware + CSRF tokens
- **Rate Limiter** — Per-IP rate limiting with configurable windows
- **IP Filtering** — Allowlist/blocklist for access control
- **Prompt Injection Guard** — Sanitization against malicious prompt patterns
- **AES-256-GCM Encryption** — Credentials encrypted at rest

</details>

<details>
<summary><b>🛑 6. "My provider went down and I lost my coding flow"</b></summary>

AI providers can become unstable, return 5xx errors, or hit temporary rate limits. If a dev depends on a single provider, they're interrupted. Without circuit breakers, repeated retries can crash the application.

**How OmniRoute solves it:**

- **Circuit Breaker per-provider** — Auto-open/close with configurable thresholds and cooldown (Closed/Open/Half-Open)
- **Exponential Backoff** — Progressive retry delays
- **Anti-Thundering Herd** — Mutex + semaphore protection against concurrent retry storms
- **Combo Fallback Chains** — If the primary provider fails, automatically falls through the chain with no intervention
- **Combo Circuit Breaker** — Auto-disables failing providers within a combo chain
- **Health Dashboard** — Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency

</details>

<details>
<summary><b>🔧 7. "Configuring each AI tool is tedious and repetitive"</b></summary>

Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time.

**How OmniRoute solves it:**

- **CLI Tools Dashboard** — Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline
- **GitHub Copilot Config Generator** — Generates `chatLanguageModels.json` for VS Code with bulk model selection
- **Onboarding Wizard** — Guided 4-step setup for first-time users
- **One endpoint, all models** — Configure `http://localhost:20128/v1` once, access 36+ providers

</details>

<details>
<summary><b>🔑 8. "Managing OAuth tokens from multiple providers is hell"</b></summary>

Claude Code, Codex, Gemini CLI, Copilot — all use OAuth 2.0 with expiring tokens. Developers need to re-authenticate constantly, deal with `client_secret is missing`, `redirect_uri_mismatch`, and failures on remote servers. OAuth on LAN/VPS is particularly problematic.

**How OmniRoute solves it:**

- **Auto Token Refresh** — OAuth tokens refresh in background before expiration
- **OAuth 2.0 (PKCE) Built-in** — Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow
- **Multi-Account OAuth** — Multiple accounts per provider via JWT/ID token extraction
- **OAuth LAN/Remote Fix** — Private IP detection for `redirect_uri` + manual URL mode for remote servers
- **OAuth Behind Nginx** — Uses `window.location.origin` for reverse proxy compatibility
- **Remote OAuth Guide** — Step-by-step guide for Google Cloud credentials on VPS/Docker

</details>

<details>
<summary><b>📊 9. "I don't know how much I'm spending or where"</b></summary>

Developers use multiple paid providers but have no unified view of spending. Each provider has its own billing dashboard, but there's no consolidated view. Unexpected costs can pile up.

**How OmniRoute solves it:**

- **Cost Analytics Dashboard** — Per-token cost tracking and budget management per provider
- **Budget Limits per Tier** — Spending ceiling per tier that triggers automatic fallback
- **Per-Model Pricing Configuration** — Configurable prices per model
- **Usage Statistics Per API Key** — Request count and last-used timestamp per key
- **Analytics Dashboard** — Stat cards, model usage chart, provider table with success rates and latency

</details>

<details>
<summary><b>🐛 10. "I can't diagnose errors and problems in AI calls"</b></summary>

When a call fails, the dev doesn't know if it was a rate limit, expired token, wrong format, or provider error. Fragmented logs across different terminals. Without observability, debugging is trial-and-error.

**How OmniRoute solves it:**

- **Unified Logs Dashboard** — 4 tabs: Request Logs, Proxy Logs, Audit Logs, Console
- **Console Log Viewer** — Real-time terminal-style viewer with color-coded levels, auto-scroll, search, filter
- **SQLite Proxy Logs** — Persistent logs that survive server restarts
- **Translator Playground** — 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time)
- **Request Telemetry** — p50/p95/p99 latency + X-Request-Id tracing
- **File-Based Logging with Rotation** — Console interceptor captures everything to JSON log with size-based rotation

</details>

<details>
<summary><b>🏗️ 11. "Deploying and maintaining the gateway is complex"</b></summary>

Installing, configuring, and maintaining an AI proxy across different environments (local, VPS, Docker, cloud) is labor-intensive. Problems like hardcoded paths, `EACCES` on directories, port conflicts, and cross-platform builds add friction.

**How OmniRoute solves it:**

- **npm global install** — `npm install -g omniroute && omniroute` — done
- **Docker Multi-Platform** — AMD64 + ARM64 native (Apple Silicon, AWS Graviton, Raspberry Pi)
- **Docker Compose Profiles** — `base` (no CLI tools) and `cli` (with Claude Code, Codex, OpenClaw)
- **Electron Desktop App** — Native app for Windows/macOS/Linux with system tray, auto-start, offline mode
- **Split-Port Mode** — API and Dashboard on separate ports for advanced scenarios (reverse proxy, container networking)
- **Cloud Sync** — Config synchronization across devices via Cloudflare Workers
- **DB Backups** — Automatic backup, restore, export and import of all settings

</details>

<details>
<summary><b>🌍 12. "The interface is English-only and my team doesn't speak English"</b></summary>

Teams in non-English-speaking countries, especially in Latin America, Asia, and Europe, struggle with English-only interfaces. Language barriers reduce adoption and increase configuration errors.

**How OmniRoute solves it:**

- **Dashboard i18n — 30 Languages** — All 500+ keys translated including Arabic, Bulgarian, Danish, German, Spanish, Finnish, French, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Dutch, Norwegian, Polish, Portuguese (PT/BR), Romanian, Russian, Slovak, Swedish, Thai, Ukrainian, Vietnamese, Chinese, Filipino, English
- **RTL Support** — Right-to-left support for Arabic and Hebrew
- **Multi-Language READMEs** — 30 complete documentation translations
- **Language Selector** — Globe icon in header for real-time switching

</details>

<details>
<summary><b>🔄 13. "I need more than chat — I need embeddings, images, audio"</b></summary>

AI isn't just chat completion. Devs need to generate images, transcribe audio, create embeddings for RAG, rerank documents, and moderate content. Each API has a different endpoint and format.

**How OmniRoute solves it:**

- **Embeddings** — `/v1/embeddings` with 6 providers and 9+ models
- **Image Generation** — `/v1/images/generations` with 4 providers and 9+ models
- **Audio Transcription** — `/v1/audio/transcriptions` — Whisper-compatible
- **Text-to-Speech** — `/v1/audio/speech` — Multi-provider audio synthesis
- **Moderations** — `/v1/moderations` — Content safety checks
- **Reranking** — `/v1/rerank` — Document relevance reranking
- **Responses API** — Full `/v1/responses` support for Codex

</details>

<details>
<summary><b>🧪 14. "I have no way to test and compare quality across models"</b></summary>

Developers want to know which model is best for their use case — code, translation, reasoning — but comparing manually is slow. No integrated eval tools exist.

**How OmniRoute solves it:**

- **LLM Evaluations** — Golden set testing with 10 pre-loaded cases covering greetings, math, geography, code generation, JSON compliance, translation, markdown, safety refusal
- **4 Match Strategies** — `exact`, `contains`, `regex`, `custom` (JS function)
- **Translator Playground Test Bench** — Batch testing with multiple inputs and expected outputs, cross-provider comparison
- **Chat Tester** — Full round-trip with visual response rendering
- **Live Monitor** — Real-time stream of all requests flowing through the proxy

</details>

<details>
<summary><b>📈 15. "I need to scale without losing performance"</b></summary>

As request volume grows, without caching the same questions generate duplicate costs. Without idempotency, duplicate requests waste processing. Per-provider rate limits must be respected.

**How OmniRoute solves it:**

- **Semantic Cache** — Two-tier cache (signature + semantic) reduces cost and latency
- **Request Idempotency** — 5s deduplication window for identical requests
- **Rate Limit Detection** — Per-provider RPM, min gap, and max concurrent tracking
- **Editable Rate Limits** — Configurable defaults in Settings → Resilience with persistence
- **API Key Validation Cache** — 3-tier cache for production performance
- **Health Dashboard with Telemetry** — p50/p95/p99 latency, cache stats, uptime

</details>

<details>
<summary><b>🤖 16. "I want to control model behavior globally"</b></summary>

Developers who want all responses in a specific language, with a specific tone, or want to limit reasoning tokens. Configuring this in every tool/request is impractical.

**How OmniRoute solves it:**

- **System Prompt Injection** — Global prompt applied to all requests
- **Thinking Budget Validation** — Reasoning token allocation control per request (passthrough, auto, custom, adaptive)
- **6 Routing Strategies** — Global strategies that determine how requests are distributed
- **Wildcard Router** — `provider/*` patterns route dynamically to any provider
- **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard
- **Provider Toggle** — Enable/disable all connections for a provider with one click
- **Blocked Providers** — Exclude specific providers from `/v1/models` listing

</details>

## ⚡ Bắt đầu nhanh

**1. Cài đặt trên toàn cầu:**

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

🎉 Trang tổng quan mở lúc `http://localhost:20128`

| Lệnh                    | Mô tả                                   |
| ----------------------- | --------------------------------------- |
| `omniroute`             | Máy chủ khởi động (cổng mặc định 20128) |
| `omniroute --port 3000` | Sử dụng cổng tùy chỉnh                  |
| `omniroute --no-open`   | Không tự động mở trình duyệt            |
| `omniroute --help`      | Hiển thị trợ giúp                       |

**2. Kết nối nhà cung cấp MIỄN PHÍ:**

Bảng điều khiển → Nhà cung cấp → Kết nối **Mã Claude** hoặc **AntiGravity** → Đăng nhập OAuth → Xong!

**3. Sử dụng trong công cụ CLI của bạn:**

```
Claude Code/Codex/Gemini CLI/OpenClaw/Cursor/Cline Settings:
  Endpoint: http://localhost:20128/v1
  API Key: [copy from dashboard]
  Model: if/kimi-k2-thinking
```

**Chỉ vậy thôi!** Bắt đầu viết mã với các mô hình AI MIỄN PHÍ.

**Thay thế - chạy từ nguồn:**

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

---

## 🐳 Docker

OmniRoute có sẵn dưới dạng hình ảnh Docker công khai trên [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).

**Chạy nhanh:**

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

**Với tệp môi trường:**

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

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

**Sử dụng Docker Compose:**

```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
```

| Hình ảnh                 | Gắn thẻ  | Kích thước | Mô tả                          |
| ------------------------ | -------- | ---------- | ------------------------------ |
| `diegosouzapw/omniroute` | `latest` | ~250MB     | Bản phát hành ổn định mới nhất |
| `diegosouzapw/omniroute` | `1.0.3`  | ~250MB     | Phiên bản hiện tại             |

---

---

## 🖥️ Desktop App — Offline & Always-On

> 🆕 **NEW!** OmniRoute is now available as a **native desktop application** for Windows, macOS, and Linux.

- 🖥️ **Native Window** — Dedicated app window with system tray integration
- 🔄 **Auto-Start** — Launch OmniRoute on system login
- 🔔 **Native Notifications** — Get alerts for quota exhaustion or provider issues
- ⚡ **One-Click Install** — NSIS (Windows), DMG (macOS), AppImage (Linux)
- 🌐 **Offline Mode** — Works fully offline with bundled server

```bash
npm run electron:dev           # Development mode
npm run electron:build         # Current platform
npm run electron:build:win     # Windows (.exe)
npm run electron:build:mac     # macOS (.dmg)
npm run electron:build:linux   # Linux (.AppImage)
```

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

---

## 💰 Sơ lược về giá

| Bậc             | Nhà cung cấp        | Chi phí                      | Đặt lại hạn ngạch     | Tốt nhất cho            |
| --------------- | ------------------- | ---------------------------- | --------------------- | ----------------------- |
| **💳 ĐĂNG KÝ**  | Mã Claude (Pro)     | $20/tháng                    | 5h + hàng tuần        | Đã đăng ký              |
|                 | Codex (Plus/Pro)    | $20-200/tháng                | 5h + hàng tuần        | Người dùng OpenAI       |
|                 | Song Tử CLI         | **MIỄN PHÍ**                 | 180K/tháng + 1K/ngày  | Mọi người!              |
|                 | Phi công phụ GitHub | $10-19/tháng                 | Hàng tháng            | Người dùng GitHub       |
| **🔑 KHÓA API** | NVIDIA NIM          | **MIỄN PHÍ** (1000 tín dụng) | Một lần               | Kiểm tra bậc miễn phí   |
|                 | DeepSeek            | Trả tiền cho mỗi lần sử dụng | Không có              | Giá/chất lượng tốt nhất |
|                 | Groq                | Cấp miễn phí + trả phí       | Tỷ lệ giới hạn        | Suy luận cực nhanh      |
|                 | xAI (Grok)          | Trả tiền cho mỗi lần sử dụng | Không có              | Mô hình Grok            |
|                 | Mistral             | Cấp miễn phí + trả phí       | Tỷ lệ giới hạn        | AI Châu Âu              |
|                 | OpenRouter          | Trả tiền cho mỗi lần sử dụng | Không có              | Hơn 100 mẫu             |
| **💰 RẺ**       | GLM-4.7             | 0,6 USD/1 triệu USD          | 10 giờ sáng hàng ngày | Dự phòng ngân sách      |
|                 | MiniMax M2.1        | 0,2 USD/1 triệu USD          | lăn 5 giờ             | Lựa chọn rẻ nhất        |
|                 | Kimi K2             | $9/tháng căn hộ              | 10 triệu token/tháng  | Chi phí dự đoán         |
| **🆓 MIỄN PHÍ** | iFlow               | $0                           | Không giới hạn        | 8 mẫu miễn phí          |
|                 | Qwen                | $0                           | Không giới hạn        | 3 mẫu miễn phí          |
|                 | Kiro                | $0                           | Không giới hạn        | Claude miễn phí         |

**💡 Mẹo chuyên nghiệp:** Bắt đầu với Gemini CLI (180K miễn phí/tháng) + combo iFlow (miễn phí không giới hạn) = chi phí $0!

---

## 💡 Tính năng chính

### 🧠 Định tuyến lõi & thông minh

| Tính năng                                     | Nó làm gì                                                                                 |
| --------------------------------------------- | ----------------------------------------------------------------------------------------- |
| 🎯 **Dự phòng 4 tầng thông minh**             | Tự động định tuyến: Đăng ký → Khóa API → Giá rẻ → Miễn phí                                |
| 📊 **Theo dõi hạn ngạch theo thời gian thực** | Số lượng mã thông báo trực tiếp + đếm ngược đặt lại cho mỗi nhà cung cấp                  |
| 🔄 **Dịch định dạng**                         | OpenAI ↔ Claude ↔ Gemini ↔ Con trỏ ↔ Kiro liền mạch + vệ sinh phản hồi                    |
| 👥 **Hỗ trợ nhiều tài khoản**                 | Nhiều tài khoản cho mỗi nhà cung cấp với lựa chọn thông minh                              |
| 🔄 **Tự động làm mới mã thông báo**           | Mã thông báo OAuth tự động làm mới bằng thử lại                                           |
| 🎨 **Combo tùy chỉnh**                        | 6 chiến lược: điền trước, quay vòng, p2c, ngẫu nhiên, ít sử dụng nhất, tối ưu hóa chi phí |
| 🧩 **Mẫu tùy chỉnh**                          | Thêm bất kỳ ID mẫu nào vào bất kỳ nhà cung cấp nào                                        |
| 🌐 **Bộ định tuyến ký tự đại diện**           | Định tuyến động các mẫu `provider/*` tới bất kỳ nhà cung cấp nào                          |
| 🧠 **Ngân sách suy nghĩ**                     | Các chế độ truyền qua, tự động, tùy chỉnh và thích ứng cho các mô hình lý luận            |
| 💬 **Tiêm nhắc nhở hệ thống**                 | Lời nhắc hệ thống toàn cầu được áp dụng cho tất cả các yêu cầu                            |
| 📄 **API phản hồi**                           | Hỗ trợ đầy đủ API phản hồi OpenAI (`/v1/responses`) cho Codex                             |

### 🎵 API đa phương thức

| Tính năng                             | Nó làm gì                                                    |
| ------------------------------------- | ------------------------------------------------------------ |
| 🖼️ **Tạo hình ảnh**                   | `/v1/images/generations` — 4 nhà cung cấp, hơn 9 mô hình     |
| 📐 **Nhúng**                          | `/v1/embeddings` — 6 nhà cung cấp, hơn 9 mô hình             |
| 🎤 **Phiên âm âm thanh**              | `/v1/audio/transcriptions` — Tương thích với lời thì thầm    |
| 🔊 **Chuyển văn bản thành giọng nói** | `/v1/audio/speech` — Tổng hợp âm thanh từ nhiều nhà cung cấp |
| 🛡️ **Kiểm duyệt**                     | `/v1/moderations` — Kiểm tra an toàn nội dung                |
| 🔀 **Sắp xếp lại**                    | `/v1/rerank` — Sắp xếp lại mức độ liên quan của tài liệu     |

### 🛡️ Khả năng phục hồi và bảo mật

| Tính năng                              | Nó làm gì                                                                              |
| -------------------------------------- | -------------------------------------------------------------------------------------- |
| 🔌 **Ngắt mạch**                       | Tự động mở/đóng theo từng nhà cung cấp với các ngưỡng có thể định cấu hình             |
| 🛡️ **Bầy chống sấm sét**               | Mutex + giới hạn tốc độ semaphore cho nhà cung cấp khóa API                            |
| 🧠 **Bộ đệm ngữ nghĩa**                | Bộ đệm hai lớp (chữ ký + ngữ nghĩa) giảm chi phí và độ trễ                             |
| ⚡ **Yêu cầu quyền bình đẳng**         | Khoảng thời gian loại trừ 5 giây đối với các yêu cầu trùng lặp                         |
| 🔒 **Giả mạo vân tay TLS**             | Bỏ qua việc phát hiện bot dựa trên TLS thông qua wreq-js                               |
| 🌐 **Lọc IP**                          | Danh sách cho phép/danh sách chặn để kiểm soát truy cập API                            |
| 📊 **Giới hạn tỷ lệ có thể chỉnh sửa** | RPM có thể định cấu hình, khoảng cách tối thiểu và đồng thời tối đa ở cấp hệ thống     |
| 🛡 **Bảo vệ điểm cuối API**            | Kiểm soát xác thực + chặn nhà cung cấp cho điểm cuối `/models`                         |
| 🔒 **Khả năng hiển thị proxy**         | Huy hiệu được mã hóa màu: 🟢 toàn cầu, 🟡 nhà cung cấp, 🔵 mỗi kết nối với màn hình IP |
| 🌐 **Cấu hình proxy 3 cấp**            | Định cấu hình proxy ở cấp độ toàn cầu, theo nhà cung cấp hoặc theo từng kết nối        |

### 📊 Khả năng quan sát & phân tích

| Tính năng                                | Nó làm gì                                                                                     |
| ---------------------------------------- | --------------------------------------------------------------------------------------------- |
| 📝 **Yêu cầu ghi nhật ký**               | Chế độ gỡ lỗi với nhật ký yêu cầu/phản hồi đầy đủ                                             |
| 💾 **Nhật ký proxy SQLite**              | Nhật ký proxy liên tục vẫn tồn tại khi khởi động lại máy chủ                                  |
| 📊 **Bảng thông tin phân tích**          | Recharts-Powered: thẻ thống kê, biểu đồ sử dụng mô hình, bảng nhà cung cấp                    |
| 📈 **Theo dõi tiến độ**                  | Chọn tham gia các sự kiện tiến trình SSE để phát trực tuyến                                   |
| 🧪 **Đánh giá LLM**                      | Thử nghiệm set vàng với 4 chiến thuật trận đấu                                                |
| 🔍 **Yêu cầu đo từ xa**                  | tổng hợp độ trễ p50/p95/p99 + theo dõi X-Request-Id                                           |
| 📋 **Bảng điều khiển nhật ký**           | Trang 4 tab hợp nhất: Nhật ký yêu cầu, Nhật ký proxy, Nhật ký kiểm tra, Bảng điều khiển       |
| 🖥️ **Trình xem nhật ký bảng điều khiển** | Trình xem kiểu thiết bị đầu cuối thời gian thực với bộ lọc cấp độ, tìm kiếm, tự động cuộn     |
| 📑 **Ghi nhật ký dựa trên tệp**          | Trình chặn chặn của bảng điều khiển ghi lại tất cả đầu ra vào tệp nhật ký JSON bằng cách xoay |
| 🏥 **Bảng thông tin sức khỏe**           | Thời gian hoạt động của hệ thống, trạng thái ngắt mạch, khóa, số liệu thống kê bộ đệm         |
| 💰 **Theo dõi chi phí**                  | Quản lý ngân sách + cấu hình giá theo từng mô hình                                            |

### ☁️ Triển khai & đồng bộ

| Tính năng                          | Nó làm gì                                                                               |
| ---------------------------------- | --------------------------------------------------------------------------------------- |
| 💾 **Đồng bộ đám mây**             | Đồng bộ hóa cấu hình trên các thiết bị thông qua Cloudflare Workers                     |
| 🌐 **Triển khai mọi nơi**          | Localhost, VPS, Docker, Công nhân Cloudflare                                            |
| 🔑 **Quản lý khóa API**            | Tạo, xoay vòng và phạm vi khóa API cho mỗi nhà cung cấp                                 |
| 🧙 **Trình hướng dẫn giới thiệu**  | Thiết lập có hướng dẫn 4 bước cho người dùng lần đầu                                    |
| 🔧 **Bảng điều khiển công cụ CLI** | Định cấu hình bằng một cú nhấp chuột Claude, Codex, Cline, OpenClaw, Kilo, AntiGravity  |
| 🔄 **Sao lưu DB**                  | Tự động sao lưu, khôi phục, xuất và nhập cho tất cả cài đặt                             |
| 🌐 **Quốc tế hóa**                 | I18n đầy đủ với hỗ trợ next-intl — Tiếng Anh + Tiếng Bồ Đào Nha (Brazil)                |
| 🌍 **Bộ chọn ngôn ngữ**            | Biểu tượng quả địa cầu trong tiêu đề để chuyển đổi ngôn ngữ theo thời gian thực (🇺🇸/🇧🇷) |
| 📂 **Thư mục dữ liệu tùy chỉnh**   | `DATA_DIR` env var để ghi đè đường dẫn lưu trữ `~/.omniroute` mặc định                  |

<details>
<summary><b>📖 Chi tiết tính năng</b></summary>

### 🎯 Dự phòng 4 tầng thông minh

Tạo combo với dự phòng tự động:

```
Combo: "my-coding-stack"
  1. cc/claude-opus-4-6        (your subscription)
  2. nvidia/llama-3.3-70b      (free NVIDIA API)
  3. glm/glm-4.7               (cheap backup, $0.6/1M)
  4. if/kimi-k2-thinking       (free fallback)

→ Auto switches when quota runs out or errors occur
```

### 📊 Theo dõi hạn ngạch theo thời gian thực

- Tiêu thụ mã thông báo trên mỗi nhà cung cấp
- Đặt lại đếm ngược (5 giờ, hàng ngày, hàng tuần)
- Ước tính chi phí cho các bậc trả phí
- Báo cáo chi tiêu hàng tháng

### 🔄 Dịch định dạng

Dịch liền mạch giữa các định dạng:

- **OpenAI** ↔ **Claude** ↔ **Gemini** ↔ **Phản hồi của OpenAI**
- Công cụ CLI của bạn gửi định dạng OpenAI → OmniRoute dịch → Nhà cung cấp nhận định dạng gốc
- Hoạt động với mọi công cụ hỗ trợ điểm cuối OpenAI tùy chỉnh
- **Sạch hóa phản hồi** — Loại bỏ các trường không chuẩn để tương thích nghiêm ngặt với OpenAI SDK
- **Chuẩn hóa vai trò** — `developer` → `system` đối với non-OpenAI; `system` → `user` dành cho kiểu máy GLM/ERNIE
- **Trích xuất thẻ suy nghĩ** — `<think>` khối → `reasoning_content` cho các mô hình tư duy
- **Đầu ra có cấu trúc** — `json_schema` → `responseMimeType`/`responseSchema` của Gemini

### 👥 Hỗ trợ nhiều tài khoản

- Thêm nhiều tài khoản cho mỗi nhà cung cấp
- Tự động định tuyến vòng tròn hoặc dựa trên mức độ ưu tiên
- Dự phòng tài khoản tiếp theo khi đạt hạn ngạch

### 🔄 Tự động làm mới mã thông báo

- Mã thông báo OAuth tự động làm mới trước khi hết hạn
- Không cần xác thực lại thủ công
- Trải nghiệm liền mạch trên tất cả các nhà cung cấp

### 🎨 Combo tùy chỉnh

- Tạo kết hợp mô hình không giới hạn
- 6 chiến lược: điền trước, quay vòng, sức mạnh của hai lựa chọn, ngẫu nhiên, ít sử dụng nhất, tối ưu hóa chi phí
- Chia sẻ combo trên các thiết bị với Cloud Sync

### 🏥 Bảng thông tin sức khỏe

- Trạng thái hệ thống (thời gian hoạt động, phiên bản, mức sử dụng bộ nhớ)
- Trạng thái ngắt mạch của mỗi nhà cung cấp (Đóng/Mở/Nửa mở)
- Trạng thái giới hạn tỷ lệ và khóa hoạt động
- Thống kê bộ đệm chữ ký
- Đo từ xa độ trễ (p50/p95/p99) + bộ đệm nhắc nhở
- Đặt lại tình trạng sức khỏe chỉ bằng một cú nhấp chuột

### 🔧 Sân chơi dịch thuật

OmniRoute bao gồm Sân chơi dịch thuật tích hợp mạnh mẽ với **4 chế độ** để gỡ lỗi, kiểm tra và giám sát các bản dịch API:

| Chế độ                           | Mô tả                                                                                                                                                                                                                              |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **💻Sân chơi**                   | Dịch định dạng trực tiếp - dán bất kỳ nội dung yêu cầu API nào và xem ngay cách OmniRoute dịch nó giữa các định dạng nhà cung cấp (OpenAI ↔ Claude ↔ Gemini ↔ API phản hồi). Bao gồm các mẫu ví dụ và tự động phát hiện định dạng. |
| **💬 Trình kiểm tra trò chuyện** | Gửi các yêu cầu trò chuyện thực tế thông qua OmniRoute và xem toàn bộ hành trình: thông tin đầu vào của bạn, yêu cầu được dịch, phản hồi của nhà cung cấp và phản hồi được dịch lại. Vô giá để xác nhận định tuyến kết hợp.        |
| **🧪 Ghế thử nghiệm**            | Chế độ thử nghiệm hàng loạt - xác định nhiều trường hợp thử nghiệm với đầu vào và đầu ra dự kiến ​​khác nhau, chạy tất cả chúng cùng một lúc và so sánh kết quả giữa các nhà cung cấp và mô hình.                                  |
| **📱 Giám sát trực tiếp**        | Giám sát yêu cầu theo thời gian thực — xem các yêu cầu đến khi chúng truyền qua OmniRoute, xem các bản dịch định dạng đang diễn ra trực tiếp và xác định các vấn đề ngay lập tức.                                                  |

**Truy cập:** Bảng điều khiển → Trình dịch (thanh bên)

### 💾 Đồng bộ đám mây

- Đồng bộ hóa nhà cung cấp, combo và cài đặt trên các thiết bị
- Đồng bộ nền tự động
- Lưu trữ được mã hóa an toàn

</details>

---

## 🎯 Trường hợp sử dụng

### Trường hợp 1: "Tôi có đăng ký Claude Pro"

**Vấn đề:** Hạn ngạch hết hạn không được sử dụng, giới hạn tốc độ trong quá trình mã hóa nặng

```
Combo: "maximize-claude"
  1. cc/claude-opus-4-6        (use subscription fully)
  2. glm/glm-4.7               (cheap backup when quota out)
  3. if/kimi-k2-thinking       (free emergency fallback)

Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total
vs. $20 + hitting limits = frustration
```

### Trường hợp 2: "Tôi muốn chi phí bằng 0"

**Vấn đề:** Không đủ khả năng đăng ký, cần mã hóa AI đáng tin cậy

```
Combo: "free-forever"
  1. gc/gemini-3-flash         (180K free/month)
  2. if/kimi-k2-thinking       (unlimited free)
  3. qw/qwen3-coder-plus       (unlimited free)

Monthly cost: $0
Quality: Production-ready models
```

### Trường hợp 3: "Tôi cần code 24/7, không bị gián đoạn"

**Vấn đề:** Thời hạn, không đủ khả năng cho thời gian ngừng hoạt động

```
Combo: "always-on"
  1. cc/claude-opus-4-6        (best quality)
  2. cx/gpt-5.2-codex          (second subscription)
  3. glm/glm-4.7               (cheap, resets daily)
  4. minimax/MiniMax-M2.1      (cheapest, 5h reset)
  5. if/kimi-k2-thinking       (free unlimited)

Result: 5 layers of fallback = zero downtime
```

### Trường hợp 4: "Tôi muốn AI MIỄN PHÍ trong OpenClaw"

**Vấn đề:** Cần trợ lý AI trong ứng dụng nhắn tin, hoàn toàn miễn phí

```
Combo: "openclaw-free"
  1. if/glm-4.7                (unlimited free)
  2. if/minimax-m2.1           (unlimited free)
  3. if/kimi-k2-thinking       (unlimited free)

Monthly cost: $0
Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
```

---

## 📖 Hướng dẫn thiết lập

<details>
<summary><b>💳 Nhà cung cấp đăng ký</b></summary>

### Mã Claude (Pro/Max)

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

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

**Mẹo chuyên nghiệp:** Sử dụng Opus cho các tác vụ phức tạp, Sonnet cho tốc độ. OmniRoute theo dõi hạn ngạch cho mỗi mô hình!

### 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
```

### Gemini CLI (MIỄN PHÍ 180K/tháng!)

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

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

**Giá trị tốt nhất:** Cấp miễn phí rất lớn! Sử dụng điều này trước các bậc trả phí.

### Phi công phụ GitHub

```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-pro
```

</details>

<details>
<summary><b>🔑 Nhà cung cấp khóa API</b></summary>

### NVIDIA NIM (1000 tín dụng MIỄN PHÍ!)

1. Đăng ký: [build.nvidia.com](https://build.nvidia.com)
2. Nhận khóa API miễn phí (bao gồm 1000 tín dụng suy luận)
3. Bảng điều khiển → Thêm nhà cung cấp → NVIDIA NIM:
   - Khóa API: `nvapi-your-key`

**Mẫu máy:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct` và hơn 50 mẫu khác

**Mẹo chuyên nghiệp:** API tương thích với OpenAI — hoạt động trơn tru với tính năng dịch định dạng của OmniRoute!

### Tìm kiếm sâu

1. Đăng ký: [platform.deepseek.com](https://platform.deepseek.com)
2. Nhận khóa API
3. Trang tổng quan → Thêm nhà cung cấp → DeepSeek

**Mẫu xe:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder`

### Groq (Có sẵn bậc miễn phí!)

1. Đăng ký: [console.groq.com](https://console.groq.com)
2. Nhận khóa API (bao gồm bậc miễn phí)
3. Bảng điều khiển → Thêm nhà cung cấp → Groq

**Mẫu xe:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b`

**Mẹo chuyên nghiệp:** Suy luận cực nhanh — tốt nhất cho mã hóa thời gian thực!

### OpenRouter (Hơn 100 mẫu)

1. Sign up: [openrouter.ai](https://openrouter.ai)
2. Nhận khóa API
3. Bảng điều khiển → Thêm nhà cung cấp → OpenRouter

**Mô hình:** Truy cập hơn 100 mô hình từ tất cả các nhà cung cấp chính thông qua một khóa API duy nhất.

</details>

<details>
<summary><b>💰 Nhà cung cấp giá rẻ (Dự phòng)</b></summary>

### GLM-4.7 (Đặt lại hàng ngày, 0,6 USD/1 triệu)

1. Đăng ký: [Zhipu AI](https://open.bigmodel.cn/)
2. Nhận khóa API từ Gói mã hóa
3. Bảng điều khiển → Thêm khóa API:
   - Nhà cung cấp: `glm`
   - Khóa API: `your-key`

**Sử dụng:** `glm/glm-4.7`

**Mẹo chuyên nghiệp:** Gói mã hóa cung cấp hạn ngạch 3× với chi phí 1/7! Đặt lại vào 10:00 sáng hàng ngày.

### MiniMax M2.1 (đặt lại 5 giờ, 0,20 USD/1M)

1. Đăng ký: [MiniMax](https://www.minimax.io/)
2. Nhận khóa API
3. Bảng điều khiển → Thêm khóa API

**Sử dụng:** `minimax/MiniMax-M2.1`

**Mẹo chuyên nghiệp:** Tùy chọn rẻ nhất cho ngữ cảnh dài (1 triệu mã thông báo)!

### Kimi K2 ($9/tháng cố định)

1. Đăng ký: [Moonshot AI](https://platform.moonshot.ai/)
2. Nhận khóa API
3. Bảng điều khiển → Thêm khóa API

**Sử dụng:** `kimi/kimi-latest`

**Mẹo chuyên nghiệp:** Đã sửa lỗi 9 USD/tháng cho 10 triệu mã thông báo = 0,90 USD/1 triệu chi phí hiệu quả!

</details>

<details>
<summary><b>🆓 Nhà cung cấp MIỄN PHÍ (Dự phòng khẩn cấp)</b></summary>

### iFlow (8 mẫu MIỄN PHÍ)

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

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

### Qwen (3 mẫu MIỄN PHÍ)

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

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

### Kiro (Claude MIỄN PHÍ)

```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>🎨 Tạo Combo</b></summary>

### Ví dụ 1: Tối đa hóa đăng ký → Sao lưu giá rẻ

```
Dashboard → Combos → Create New

Name: premium-coding
Models:
  1. cc/claude-opus-4-6 (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
```

### Example 2: Free-Only (Zero Cost)

```
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>🔧 Tích hợp CLI</b></summary>

### IDE con trỏ

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

### Mã Claude

Sử dụng trang **Công cụ CLI** trong trang tổng quan để định cấu hình bằng một cú nhấp chuột hoặc chỉnh sửa `~/.claude/settings.json` theo cách thủ công.

### Codex CLI

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

codex "your prompt"
```

### OpenClaw

**Tùy chọn 1 — Trang tổng quan (được khuyến nghị):**

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

**Tùy chọn 2 — Thủ công:** Chỉnh sửa `~/.openclaw/openclaw.json`:

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

> **Lưu ý:** OpenClaw chỉ hoạt động với OmniRoute cục bộ. Sử dụng `127.0.0.1` thay vì `localhost` để tránh các vấn đề về độ phân giải IPv6.

### Cline / Tiếp tục / RooCode

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

</details>

---

## 🧪 Đánh giá (Evals)

OmniRoute bao gồm khung đánh giá tích hợp để kiểm tra chất lượng phản hồi LLM dựa trên bộ vàng. Truy cập thông qua **Analytics → Đánh giá** trong bảng điều khiển.

### Bộ vàng tích hợp

"Bộ vàng OmniRoute" được tải sẵn chứa 10 trường hợp thử nghiệm bao gồm:

- Lời chào, toán, địa lý, tạo mã
- Tuân thủ định dạng JSON, dịch thuật, đánh dấu
- Từ chối an toàn (nội dung có hại), đếm, logic boolean

### Chiến lược đánh giá

| Chiến lược | Mô tả                                                           | Ví dụ                            |
| ---------- | --------------------------------------------------------------- | -------------------------------- |
| `exact`    | Đầu ra phải khớp chính xác                                      | `"4"`                            |
| `contains` | Đầu ra phải chứa chuỗi con (không phân biệt chữ hoa chữ thường) | `"Paris"`                        |
| `regex`    | Đầu ra phải khớp với mẫu biểu thức chính quy                    | `"1.*2.*3"`                      |
| `custom`   | Hàm JS tùy chỉnh trả về true/false                              | `(output) => output.length > 10` |

---

## 🐛 Khắc phục sự cố

<details>
<summary><b>Nhấp để mở rộng hướng dẫn khắc phục sự cố</b></summary>

**"Mô hình ngôn ngữ không cung cấp tin nhắn"**

- Đã hết hạn ngạch nhà cung cấp → Kiểm tra trình theo dõi hạn ngạch bảng điều khiển
- Giải pháp: Sử dụng combo dự phòng hoặc chuyển sang tầng rẻ hơn

**Giới hạn tỷ lệ**

- Hết hạn ngạch đăng ký → Dự phòng sang GLM/MiniMax
- Thêm tổ hợp: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`

**Mã thông báo OAuth đã hết hạn**

- Tự động làm mới bởi OmniRoute
- Nếu sự cố vẫn tiếp diễn: Bảng điều khiển → Nhà cung cấp → Kết nối lại

**Chi phí cao**

- Kiểm tra số liệu thống kê sử dụng trong Bảng điều khiển → Chi phí
- Chuyển mô hình chính sang GLM/MiniMax
- Sử dụng bậc miễn phí (Gemini CLI, iFlow) cho các tác vụ không quan trọng

**Bảng điều khiển mở sai cổng**

- Đặt `PORT=20128` và `NEXT_PUBLIC_BASE_URL=http://localhost:20128`

**Lỗi đồng bộ hóa đám mây**

- Xác minh `BASE_URL` trỏ tới phiên bản đang chạy của bạn
- Xác minh `CLOUD_URL` điểm tới điểm cuối đám mây dự kiến của bạn
- Giữ các giá trị `NEXT_PUBLIC_*` được căn chỉnh với các giá trị phía máy chủ

**Đăng nhập lần đầu không hoạt động**

- Kiểm tra `INITIAL_PASSWORD` trong `.env`
- Nếu không được đặt, mật khẩu dự phòng là `123456`

**Không có nhật ký yêu cầu**

- Đặt `ENABLE_REQUEST_LOGS=true` trong `.env`

**Kiểm tra kết nối cho thấy "Không hợp lệ" đối với các nhà cung cấp tương thích với OpenAI**

- Nhiều nhà cung cấp không hiển thị điểm cuối `/models`
- OmniRoute v1.0.6+ bao gồm xác thực dự phòng thông qua hoàn thành trò chuyện
- Đảm bảo URL cơ sở bao gồm hậu tố `/v1`

### 🔐 OAuth trên Servidor Remoto (Thiết lập OAuth từ xa)

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

> **⚠️ QUAN TRỌNG đối với người sử dụng OmniRoute trên VPS/Docker/servidor remoto**

### Bởi vì OAuth làm cho AntiGravity / Gemini CLI có bị ảnh hưởng bởi các dịch vụ điều khiển từ xa không?

Os đã được chứng minh **AntiGravity** e **Gemini CLI** sử dụng **Google OAuth 2.0** để xác thực. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** một trong các URI trước khi lập danh sách trên Google Cloud Console để ứng dụng.

Vì các thông tin xác thực OAuth không có OmniRoute estão cadastradas **apenas para `localhost`**. Bạn có thể truy cập OmniRoute bằng cách điều khiển lại máy chủ (ví dụ: `https://omniroute.meuservidor.com`), hoặc Google sẽ cung cấp thông tin xác thực với:

```
Error 400: redirect_uri_mismatch
```

### Giải pháp: Định cấu hình thông tin đăng nhập OAuth

Bạn nên chú ý **OAuth 2.0 Client ID** không có Google Cloud Console vì URI làm dịch vụ của bạn.

#### Vượt qua một lần nữa

**1. Truy cập vào Google Cloud Console**

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

**2. Hãy yêu cầu ID khách hàng OAuth 2.0 mới**

- Nhấn vào **"+ Tạo thông tin xác thực"** → **"ID khách hàng OAuth"**
- Mẹo ứng dụng: **"Ứng dụng web"**
- Tên: escolha qualquer nome (ví dụ: `OmniRoute Remote`)

**3. Adicione dưới dạng URI chuyển hướng được ủy quyền**

Không có quảng cáo **"URI chuyển hướng được ủy quyền"**, khuyến cáo:

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

> Thay thế `seu-servidor.com` từ địa chỉ IP hoặc dịch vụ IP của bạn (bao gồm một cổng cần thiết, ví dụ: `http://45.33.32.156:20128/callback`).

**4. Lưu và sao chép dưới dạng uy tín**

Sau đó, Google đã đăng trên **ID khách hàng** và **Bí mật khách hàng**.

**5. Định cấu hình theo các biến thể của môi trường**

Không có `.env` (hoặc có nhiều biến thể môi trường xung quanh 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 hoặc OmniRoute**

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

# Se usando Docker:
docker restart omniroute
```

**7. Lều kết nối mới lạ**

Bảng điều khiển → Nhà cung cấp → Anti Gravity (hoặc Gemini CLI) → OAuth

Google đã chuyển hướng điều chỉnh cho `https://seu-servidor.com/callback` và một chức năng xác thực.

---

### Thời gian giải quyết (sem configurar credenciais próprias)

Nếu không có câu hỏi nào về thông tin xác thực trước đây, bạn có thể sử dụng thông tin **hướng dẫn sử dụng URL**:

1. O OmniRoute tìm kiếm URL tự động của Google
2. Sau khi bạn tự động đăng ký, hoặc chuyển hướng Google sang `localhost` (bạn không thể điều chỉnh lại dịch vụ)
3. **Sao chép một URL hoàn chỉnh** da cuối cùng của trình duyệt của bạn (mesmo que a página not carregue)
4. URL này không có khả năng xuất hiện không có phương thức kết nối nào với OmniRoute
5. Kết nối với nhau **"Kết nối"**

> Chức năng giải pháp này có thể giúp tự động cấp quyền cho URL và có thể chuyển hướng độc lập đến mục tiêu hoặc không.

</details>

---

## 🛠️ Ngăn xếp công nghệ

- **Thời gian chạy**: Node.js 18–22 LTS (⚠️ Node.js 24+ **không được hỗ trợ** — `better-sqlite3` các tệp nhị phân gốc không tương thích)
- **Ngôn ngữ**: TypeScript 5.9 — **100% TypeScript** trên `src/` và `open-sse/` (v1.0.6)
- **Khung**: Next.js 16 + React 19 + Tailwind CSS 4
- **Cơ sở dữ liệu**: LowDB (JSON) + SQLite (trạng thái miền + nhật ký proxy)
- **Truyền phát**: Sự kiện do máy chủ gửi (SSE)
- **Xác thực**: OAuth 2.0 (PKCE) + JWT + Khóa API
- **Thử nghiệm**: Trình chạy thử nghiệm Node.js (hơn 368 bài kiểm tra đơn vị)
- **CI/CD**: GitHub Actions (tự động xuất bản npm + Docker Hub khi phát hành)
- **Trang web**: [omniroute.online](https://omniroute.online)
- **Gói**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)
- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)
- **Khả năng phục hồi**: Ngắt mạch, lùi theo cấp số nhân, chống sét bầy đàn, giả mạo TLS

---

## 📖 Tài liệu

| Tài liệu                                     | Mô tả                                                     |
| -------------------------------------------- | --------------------------------------------------------- |
| [User Guide](docs/USER_GUIDE.md)             | Nhà cung cấp, combo, tích hợp CLI, triển khai             |
| [API Reference](docs/API_REFERENCE.md)       | Tất cả các điểm cuối có ví dụ                             |
| [Troubleshooting](docs/TROUBLESHOOTING.md)   | Các vấn đề thường gặp và giải pháp                        |
| [Architecture](docs/ARCHITECTURE.md)         | Kiến trúc hệ thống và nội bộ                              |
| [Contributing](CONTRIBUTING.md)              | Thiết lập và hướng dẫn phát triển                         |
| [OpenAPI Spec](docs/openapi.yaml)            | Đặc tả OpenAPI 3.0                                        |
| [Security Policy](SECURITY.md)               | Báo cáo lỗ hổng bảo mật và thực hành bảo mật              |
| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Hướng dẫn đầy đủ: Thiết lập VM + nginx + Cloudflare       |
| [Features Gallery](docs/FEATURES.md)         | Tham quan bảng điều khiển trực quan với ảnh chụp màn hình |

### 📸 Xem trước bảng điều khiển

<details>
<summary><b>Nhấp để xem ảnh chụp màn hình trang tổng quan</b></summary>

| Trang               | Ảnh chụp màn hình                                 |
| ------------------- | ------------------------------------------------- |
| **Nhà cung cấp**    | ![Providers](docs/screenshots/01-providers.png)   |
| **Combo**           | ![Combos](docs/screenshots/02-combos.png)         |
| **Phân tích**       | ![Analytics](docs/screenshots/03-analytics.png)   |
| **Sức khỏe**        | ![Health](docs/screenshots/04-health.png)         |
| **Người dịch**      | ![Translator](docs/screenshots/05-translator.png) |
| **Cài đặt**         | ![Settings](docs/screenshots/06-settings.png)     |
| **Công cụ CLI**     | ![CLI Tools](docs/screenshots/07-cli-tools.png)   |
| **Nhật ký sử dụng** | ![Usage](docs/screenshots/08-usage.png)           |
| **Điểm cuối**       | ![Endpoint](docs/screenshots/09-endpoint.png)     |

</details>

---

## 🗺️ Lộ trình

OmniRoute có **210+ tính năng được lên kế hoạch** qua nhiều giai đoạn phát triển. Dưới đây là các lĩnh vực chính:

| Danh mục                       | Tính năng dự kiến ​​ | Điểm nổi bật                                                                                                   |
| ------------------------------ | -------------------- | -------------------------------------------------------------------------------------------------------------- |
| 🧠 **Định tuyến & thông minh** | 25+                  | Định tuyến có độ trễ thấp nhất, định tuyến dựa trên thẻ, ưu tiên hạn ngạch, chọn tài khoản P2C                 |
| 🔒 **Bảo mật & Tuân thủ**      | 20+                  | Tăng cường SSRF, che giấu thông tin xác thực, giới hạn tốc độ cho mỗi điểm cuối, phạm vi khóa quản lý          |
| 📊 **Khả năng quan sát**       | 15+                  | Tích hợp OpenTelemetry, giám sát hạn ngạch thời gian thực, theo dõi chi phí trên mỗi mô hình                   |
| 🔄 **Tích hợp nhà cung cấp**   | 20+                  | Đăng ký mô hình động, thời gian hồi chiêu của nhà cung cấp, Codex nhiều tài khoản, phân tích hạn ngạch Copilot |
| ⚡ **Hiệu suất**               | 15+                  | Lớp bộ đệm kép, bộ đệm nhắc nhở, bộ đệm phản hồi, lưu giữ luồng, API hàng loạt                                 |
| 🌐 **Hệ sinh thái**            | 10+                  | API WebSocket, cấu hình tải lại nóng, kho cấu hình phân tán, chế độ thương mại                                 |

### 🔜 Sắp ra mắt

- 🔗 **Tích hợp OpenCode** — Hỗ trợ của nhà cung cấp gốc cho IDE mã hóa OpenCode AI
- 🔗 **Tích hợp TRAE** — Hỗ trợ đầy đủ cho khung phát triển TRAE AI
- 📦 **Batch API** — Xử lý hàng loạt không đồng bộ cho các yêu cầu hàng loạt
- 🎯 **Định tuyến dựa trên thẻ** — Định tuyến các yêu cầu dựa trên thẻ và siêu dữ liệu tùy chỉnh
- 💰 **Chiến lược chi phí thấp nhất** — Tự động chọn nhà cung cấp có sẵn rẻ nhất

> 📝 Thông số kỹ thuật đầy đủ tính năng có sẵn trong [link](docs/new-features/) (217 thông số kỹ thuật chi tiết)

---

## 📧 Hỗ trợ

> 💬 **Tham gia cộng đồng của chúng tôi!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Nhận trợ giúp, chia sẻ mẹo và luôn cập nhật.

- **Trang web**: [omniroute.online](https://omniroute.online)
- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- **Vấn đề**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
- **Dự án gốc**: [9router by decolua](https://github.com/decolua/9router)

---

## 👥 Người đóng góp

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

### Cách đóng góp

1. Phân nhánh kho lưu trữ
2. Tạo nhánh tính năng của bạn (`git checkout -b feature/amazing-feature`)
3. Cam kết thay đổi của bạn (`git commit -m 'Add amazing feature'`)
4. Đẩy vào nhánh (`git push origin feature/amazing-feature`)
5. Mở yêu cầu kéo

Xem [CONTRIBUTING.md](CONTRIBUTING.md) để biết hướng dẫn chi tiết.

### Phát hành phiên bản mới

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

---

## 📊 Lịch sử ngôi sao

<a href="https://star-history.com/#diegosouzapw/OmniRoute&Date">
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=diegosouzapw/OmniRoute&type=Date&theme=dark" />
   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=diegosouzapw/OmniRoute&type=Date" />
   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=diegosouzapw/OmniRoute&type=Date" />
 </picture>
</a>

---

## 🙏 Lời cảm ơn

Đặc biệt cảm ơn **[9router](https://github.com/decolua/9router)** của **[decolua](https://github.com/decolua)** — dự án ban đầu đã truyền cảm hứng cho đợt phân nhánh này. OmniRoute được xây dựng dựa trên nền tảng đáng kinh ngạc đó với các tính năng bổ sung, API đa phương thức và viết lại TypeScript đầy đủ.

Đặc biệt cảm ơn **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — cách triển khai Go ban đầu đã truyền cảm hứng cho cổng JavaScript này.

---

## 📄 Giấy phép

Giấy phép MIT - xem [LICENSE](LICENSE) để biết chi tiết.

---

<div align="center">
  <sub>Được xây dựng với ❤️ dành cho nhà phát triển viết mã 24/7</sub>
  <br/>
  <sub><a href="https://omniroute.online">omniroute.online</a></sub>
</div>
