omniroute 0.8.5 → 0.9.0

package/README.pt-BR.md

@@ -0,0 +1,995 @@
+<div align="center">
+  <img src="./images/omniroute.png" alt="OmniRoute Dashboard" width="800"/>
+  
+  # 🚀 OmniRoute — O Gateway de IA Gratuito
+
+### Nunca pare de programar. Roteamento inteligente para **modelos de IA GRATUITOS e baratos** com fallback automático.
+
+_Seu proxy de API universal — um endpoint, 36+ provedores, zero tempo de inatividade._
+
+**Chat Completions • Embeddings • Geração de Imagem • Áudio • Reranking • 100% TypeScript**
+
+---
+
+### 🤖 Provedor de IA Gratuito para seus agentes de programação favoritos
+
+_Conecte qualquer IDE ou ferramenta CLI com IA através do OmniRoute — gateway de API gratuito para programação ilimitada._
+
+  <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>📡 Todos os agentes se conectam via <code>http://localhost:20128/v1</code> ou <code>http://cloud.omniroute.online/v1</code> — uma configuração, modelos e cota ilimitados</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)
+
+[🌐 Website](https://omniroute.online) • [🚀 Início Rápido](#-início-rápido) • [💡 Funcionalidades](#-funcionalidades-principais) • [📖 Docs](#-documentação) • [💰 Preços](#-preços-resumidos)
+
+🌐 **Disponível em:** [English](README.md) | [Português](README.pt-BR.md) | [Español](README.es.md) | [Русский](README.ru.md) | [中文](README.zh-CN.md) | [Deutsch](README.de.md) | [Français](README.fr.md) | [Italiano](README.it.md)
+
+</div>
+
+---
+
+## 🤔 Por que OmniRoute?
+
+**Pare de desperdiçar dinheiro e bater em limites:**
+
+- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> Cota de assinatura expira sem uso todo mês
+- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> Limites de taxa param você no meio da programação
+- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> APIs caras ($20-50/mês por provedor)
+- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> Trocar manualmente entre provedores
+
+**OmniRoute resolve isso:**
+
+- ✅ **Maximize assinaturas** - Rastreie cotas, use tudo antes do reset
+- ✅ **Fallback automático** - Assinatura → API Key → Barato → Gratuito, zero tempo de inatividade
+- ✅ **Multi-conta** - Round-robin entre contas por provedor
+- ✅ **Universal** - Funciona com Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, qualquer ferramenta CLI
+
+---
+
+## 🔄 Como Funciona
+
+```
+┌─────────────┐
+│  Sua CLI    │  (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)
+│   Tool      │
+└──────┬──────┘
+       │ http://localhost:20128/v1
+       ↓
+┌─────────────────────────────────────────┐
+│           OmniRoute (Roteador Inteligente) │
+│  • Tradução de formato (OpenAI ↔ Claude) │
+│  • Rastreamento de cota + Embeddings + Imagens │
+│  • Renovação automática de tokens        │
+└──────┬──────────────────────────────────┘
+       │
+       ├─→ [Tier 1: ASSINATURA] Claude Code, Codex, Gemini CLI
+       │   ↓ cota esgotada
+       ├─→ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.
+       │   ↓ limite de orçamento
+       ├─→ [Tier 3: BARATO] GLM ($0.6/1M), MiniMax ($0.2/1M)
+       │   ↓ limite de orçamento
+       └─→ [Tier 4: GRATUITO] iFlow, Qwen, Kiro (ilimitado)
+
+Resultado: Nunca pare de programar, custo mínimo
+```
+
+---
+
+## ⚡ Início Rápido
+
+**1. Instale globalmente:**
+
+```bash
+npm install -g omniroute
+omniroute
+```
+
+🎉 Dashboard abre em `http://localhost:20128`
+
+| Comando                 | Descrição                             |
+| ----------------------- | ------------------------------------- |
+| `omniroute`             | Iniciar servidor (porta padrão 20128) |
+| `omniroute --port 3000` | Usar porta personalizada              |
+| `omniroute --no-open`   | Não abrir navegador automaticamente   |
+| `omniroute --help`      | Mostrar ajuda                         |
+
+**2. Conecte um provedor GRATUITO:**
+
+Dashboard → Provedores → Conectar **Claude Code** ou **Antigravity** → Login OAuth → Pronto!
+
+**3. Use na sua ferramenta CLI:**
+
+```
+Claude Code/Codex/Gemini CLI/OpenClaw/Cursor/Cline Configurações:
+  Endpoint: http://localhost:20128/v1
+  API Key: [copie do dashboard]
+  Model: if/kimi-k2-thinking
+```
+
+**Pronto!** Comece a programar com modelos de IA GRATUITOS.
+
+**Alternativa — rodar a partir do código-fonte:**
+
+```bash
+cp .env.example .env
+npm install
+PORT=20128 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev
+```
+
+---
+
+## 🐳 Docker
+
+OmniRoute está disponível como imagem Docker pública no [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).
+
+**Execução rápida:**
+
+```bash
+docker run -d \
+  --name omniroute \
+  --restart unless-stopped \
+  -p 20128:20128 \
+  -v omniroute-data:/app/data \
+  diegosouzapw/omniroute:latest
+```
+
+**Com arquivo de ambiente:**
+
+```bash
+# Copie e edite o .env primeiro
+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
+```
+
+**Usando Docker Compose:**
+
+```bash
+# Perfil base (sem ferramentas CLI)
+docker compose --profile base up -d
+
+# Perfil CLI (Claude Code, Codex, OpenClaw integrados)
+docker compose --profile cli up -d
+```
+
+| Imagem                   | Tag      | Tamanho | Descrição             |
+| ------------------------ | -------- | ------- | --------------------- |
+| `diegosouzapw/omniroute` | `latest` | ~250MB  | Última versão estável |
+| `diegosouzapw/omniroute` | `0.9.0`  | ~250MB  | Versão atual          |
+
+---
+
+## 💰 Preços Resumidos
+
+| Tier              | Provedor          | Custo                        | Reset de Cota     | Melhor Para             |
+| ----------------- | ----------------- | ---------------------------- | ----------------- | ----------------------- |
+| **💳 ASSINATURA** | Claude Code (Pro) | $20/mês                      | 5h + semanal      | Já é assinante          |
+|                   | Codex (Plus/Pro)  | $20-200/mês                  | 5h + semanal      | Usuários OpenAI         |
+|                   | Gemini CLI        | **GRATUITO**                 | 180K/mês + 1K/dia | Todos!                  |
+|                   | GitHub Copilot    | $10-19/mês                   | Mensal            | Usuários GitHub         |
+| **🔑 API KEY**    | NVIDIA NIM        | **GRATUITO** (1000 créditos) | Único             | Testes gratuitos        |
+|                   | DeepSeek          | Por uso                      | Nenhum            | Melhor preço/qualidade  |
+|                   | Groq              | Tier gratuito + pago         | Limitado          | Inferência ultra-rápida |
+|                   | xAI (Grok)        | Por uso                      | Nenhum            | Modelos Grok            |
+|                   | Mistral           | Tier gratuito + pago         | Limitado          | IA Europeia             |
+|                   | OpenRouter        | Por uso                      | Nenhum            | 100+ modelos            |
+| **💰 BARATO**     | GLM-4.7           | $0.6/1M                      | Diário 10h        | Backup econômico        |
+|                   | MiniMax M2.1      | $0.2/1M                      | Rotativo 5h       | Opção mais barata       |
+|                   | Kimi K2           | $9/mês fixo                  | 10M tokens/mês    | Custo previsível        |
+| **🆓 GRATUITO**   | iFlow             | $0                           | Ilimitado         | 8 modelos gratuitos     |
+|                   | Qwen              | $0                           | Ilimitado         | 3 modelos gratuitos     |
+|                   | Kiro              | $0                           | Ilimitado         | Claude gratuito         |
+
+**💡 Dica Pro:** Comece com Gemini CLI (180K grátis/mês) + iFlow (ilimitado grátis) = $0 de custo!
+
+---
+
+## 🎯 Casos de Uso
+
+### Caso 1: "Tenho assinatura Claude Pro"
+
+**Problema:** Cota expira sem uso, limites de taxa durante programação intensa
+
+```
+Combo: "maximize-claude"
+  1. cc/claude-opus-4-6        (usar assinatura ao máximo)
+  2. glm/glm-4.7               (backup barato quando a cota acabar)
+  3. if/kimi-k2-thinking       (fallback de emergência gratuito)
+
+Custo mensal: $20 (assinatura) + ~$5 (backup) = $25 total
+vs. $20 + bater em limites = frustração
+```
+
+### Caso 2: "Quero custo zero"
+
+**Problema:** Não pode pagar assinaturas, precisa de IA confiável para programar
+
+```
+Combo: "free-forever"
+  1. gc/gemini-3-flash         (180K grátis/mês)
+  2. if/kimi-k2-thinking       (ilimitado grátis)
+  3. qw/qwen3-coder-plus       (ilimitado grátis)
+
+Custo mensal: $0
+Qualidade: Modelos prontos para produção
+```
+
+### Caso 3: "Preciso programar 24/7, sem interrupções"
+
+**Problema:** Prazos apertados, não pode ter tempo de inatividade
+
+```
+Combo: "always-on"
+  1. cc/claude-opus-4-6        (melhor qualidade)
+  2. cx/gpt-5.2-codex          (segunda assinatura)
+  3. glm/glm-4.7               (barato, reset diário)
+  4. minimax/MiniMax-M2.1      (mais barato, reset 5h)
+  5. if/kimi-k2-thinking       (gratuito ilimitado)
+
+Resultado: 5 camadas de fallback = zero tempo de inatividade
+```
+
+### Caso 4: "Quero IA GRATUITA no OpenClaw"
+
+**Problema:** Precisa de assistente de IA em aplicativos de mensagens, completamente gratuito
+
+```
+Combo: "openclaw-free"
+  1. if/glm-4.7                (ilimitado grátis)
+  2. if/minimax-m2.1           (ilimitado grátis)
+  3. if/kimi-k2-thinking       (ilimitado grátis)
+
+Custo mensal: $0
+Acesso via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
+```
+
+---
+
+## 💡 Funcionalidades Principais
+
+### 🧠 Roteamento e Inteligência
+
+| Funcionalidade                            | O que Faz                                                                       |
+| ----------------------------------------- | ------------------------------------------------------------------------------- |
+| 🎯 **Fallback Inteligente 4 Tiers**       | Auto-roteamento: Assinatura → API Key → Barato → Gratuito                       |
+| 📊 **Rastreamento de Cota em Tempo Real** | Contagem de tokens ao vivo + countdown de reset por provedor                    |
+| 🔄 **Tradução de Formato**                | OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro transparente                           |
+| 👥 **Suporte Multi-Conta**                | Múltiplas contas por provedor com seleção inteligente                           |
+| 🔄 **Renovação Automática de Token**      | Tokens OAuth renovam automaticamente com retry                                  |
+| 🎨 **Combos Personalizados**              | 6 estratégias: fill-first, round-robin, p2c, random, least-used, cost-optimized |
+| 🧩 **Modelos Personalizados**             | Adicione qualquer ID de modelo a qualquer provedor                              |
+| 🌐 **Roteador Wildcard**                  | Roteie padrões `provider/*` para qualquer provedor dinamicamente                |
+| 🧠 **Budget de Raciocínio**               | Modos passthrough, auto, custom e adaptativo para modelos de raciocínio         |
+| 💬 **Injeção de System Prompt**           | System prompt global aplicado em todas as requisições                           |
+| 📄 **API Responses**                      | Suporte completo à API Responses da OpenAI (`/v1/responses`) para Codex         |
+
+### 🎵 APIs Multi-Modal
+
+| Funcionalidade              | O que Faz                                            |
+| --------------------------- | ---------------------------------------------------- |
+| 🖼️ **Geração de Imagem**    | `/v1/images/generations` — 4 provedores, 9+ modelos  |
+| 📐 **Embeddings**           | `/v1/embeddings` — 6 provedores, 9+ modelos          |
+| 🎤 **Transcrição de Áudio** | `/v1/audio/transcriptions` — Compatível com Whisper  |
+| 🔊 **Texto para Fala**      | `/v1/audio/speech` — Síntese de áudio multi-provedor |
+| 🛡️ **Moderações**           | `/v1/moderations` — Verificações de segurança        |
+| 🔀 **Reranking**            | `/v1/rerank` — Reranking de relevância de documentos |
+
+### 🛡️ Resiliência e Segurança
+
+| Funcionalidade                     | O que Faz                                                             |
+| ---------------------------------- | --------------------------------------------------------------------- |
+| 🔌 **Circuit Breaker**             | Auto-abertura/fechamento por provedor com limites configuráveis       |
+| 🛡️ **Anti-Thundering Herd**        | Mutex + semáforo rate-limit para provedores com API key               |
+| 🧠 **Cache Semântico**             | Cache de duas camadas (assinatura + semântico) reduz custo e latência |
+| ⚡ **Idempotência de Requisição**  | Janela de dedup de 5s para requisições duplicadas                     |
+| 🔒 **Spoofing de Fingerprint TLS** | Bypass de detecção de bot via TLS com wreq-js                         |
+| 🌐 **Filtragem de IP**             | Allowlist/blocklist para controle de acesso à API                     |
+| 📊 **Rate Limits Editáveis**       | RPM, gap mínimo e concorrência máxima configuráveis                   |
+
+### 📊 Observabilidade e Analytics
+
+| Funcionalidade                   | O que Faz                                                             |
+| -------------------------------- | --------------------------------------------------------------------- |
+| 📝 **Logs de Requisição**        | Modo debug com logs completos de request/response                     |
+| 💾 **Logs SQLite**               | Logs de proxy persistentes sobrevivem a reinicializações              |
+| 📊 **Dashboard de Analytics**    | Recharts: cards de estatísticas, gráfico de uso, tabela de provedores |
+| 📈 **Rastreamento de Progresso** | Eventos de progresso SSE opt-in para streaming                        |
+| 🧪 **Avaliações de LLM**         | Testes com conjunto golden e 4 estratégias de match                   |
+| 🔍 **Telemetria de Requisição**  | Agregação de latência p50/p95/p99 + rastreamento X-Request-Id         |
+| 📋 **Logs + Cotas**              | Páginas dedicadas para navegação de logs e rastreamento de cotas      |
+| 🏥 **Dashboard de Saúde**        | Uptime, estados de circuit breaker, lockouts, stats de cache          |
+| 💰 **Rastreamento de Custo**     | Gestão de orçamento + configuração de preços por modelo               |
+
+### ☁️ Deploy e Sincronização
+
+| Funcionalidade                    | O que Faz                                                                        |
+| --------------------------------- | -------------------------------------------------------------------------------- |
+| 💾 **Cloud Sync**                 | Sincronize configurações entre dispositivos via Cloudflare Workers               |
+| 🌐 **Deploy em Qualquer Lugar**   | Localhost, VPS, Docker, Cloudflare Workers                                       |
+| 🔑 **Gestão de API Keys**         | Gere, rotacione e defina escopo de API keys por provedor                         |
+| 🧙 **Assistente de Configuração** | Setup guiado em 4 etapas para novos usuários                                     |
+| 🔧 **Dashboard CLI Tools**        | Configuração em um clique para Claude, Codex, Cline, OpenClaw, Kilo, Antigravity |
+| 🔄 **Backups de DB**              | Backup e restauração automáticos de todas as configurações                       |
+
+<details>
+<summary><b>📖 Detalhes das Funcionalidades</b></summary>
+
+### 🎯 Fallback Inteligente 4 Tiers
+
+Crie combos com fallback automático:
+
+```
+Combo: "my-coding-stack"
+  1. cc/claude-opus-4-6        (sua assinatura)
+  2. nvidia/llama-3.3-70b      (API NVIDIA gratuita)
+  3. glm/glm-4.7               (backup barato, $0.6/1M)
+  4. if/kimi-k2-thinking       (fallback gratuito)
+
+→ Troca automaticamente quando a cota acaba ou erros ocorrem
+```
+
+### 📊 Rastreamento de Cota em Tempo Real
+
+- Consumo de tokens por provedor
+- Countdown de reset (5 horas, diário, semanal)
+- Estimativa de custo para tiers pagos
+- Relatórios de gastos mensais
+
+### 🔄 Tradução de Formato
+
+Tradução transparente entre formatos:
+
+- **OpenAI** ↔ **Claude** ↔ **Gemini** ↔ **OpenAI Responses**
+- Sua ferramenta CLI envia formato OpenAI → OmniRoute traduz → Provedor recebe formato nativo
+- Funciona com qualquer ferramenta que suporte endpoints OpenAI customizados
+
+### 👥 Suporte Multi-Conta
+
+- Adicione múltiplas contas por provedor
+- Round-robin automático ou roteamento por prioridade
+- Fallback para próxima conta quando uma atinge a cota
+
+### 🔄 Renovação Automática de Token
+
+- Tokens OAuth renovam automaticamente antes de expirar
+- Sem necessidade de re-autenticação manual
+- Experiência transparente em todos os provedores
+
+### 🎨 Combos Personalizados
+
+- Crie combinações ilimitadas de modelos
+- 6 estratégias: fill-first, round-robin, power-of-two-choices, random, least-used, cost-optimized
+- Compartilhe combos entre dispositivos com Cloud Sync
+
+### 🏥 Dashboard de Saúde
+
+- Status do sistema (uptime, versão, uso de memória)
+- Estados de circuit breaker por provedor (Closed/Open/Half-Open)
+- Status de rate limit e lockouts ativos
+- Estatísticas de cache de assinatura
+- Telemetria de latência (p50/p95/p99) + cache de prompt
+- Reset de saúde com um clique
+
+### 🔧 Playground do Tradutor
+
+- Debug, teste e visualize traduções de formato de API
+- Envie requisições e veja como o OmniRoute traduz entre formatos de provedores
+- Inestimável para troubleshooting de problemas de integração
+
+### 💾 Cloud Sync
+
+- Sincronize provedores, combos e configurações entre dispositivos
+- Sincronização automática em background
+- Armazenamento criptografado seguro
+
+</details>
+
+---
+
+## 📖 Guia de Configuração
+
+<details>
+<summary><b>💳 Provedores por Assinatura</b></summary>
+
+### Claude Code (Pro/Max)
+
+```bash
+Dashboard → Provedores → Conectar Claude Code
+→ Login OAuth → Renovação automática de token
+→ Rastreamento de cota 5h + semanal
+
+Modelos:
+  cc/claude-opus-4-6
+  cc/claude-sonnet-4-5-20250929
+  cc/claude-haiku-4-5-20251001
+```
+
+**Dica Pro:** Use Opus para tarefas complexas, Sonnet para velocidade. OmniRoute rastreia cota por modelo!
+
+### OpenAI Codex (Plus/Pro)
+
+```bash
+Dashboard → Provedores → Conectar Codex
+→ Login OAuth (porta 1455)
+→ Reset 5h + semanal
+
+Modelos:
+  cx/gpt-5.2-codex
+  cx/gpt-5.1-codex-max
+```
+
+### Gemini CLI (GRATUITO 180K/mês!)
+
+```bash
+Dashboard → Provedores → Conectar Gemini CLI
+→ Google OAuth
+→ 180K completions/mês + 1K/dia
+
+Modelos:
+  gc/gemini-3-flash-preview
+  gc/gemini-2.5-pro
+```
+
+**Melhor Valor:** Tier gratuito enorme! Use antes dos tiers pagos.
+
+### GitHub Copilot
+
+```bash
+Dashboard → Provedores → Conectar GitHub
+→ OAuth via GitHub
+→ Reset mensal (1º do mês)
+
+Modelos:
+  gh/gpt-5
+  gh/claude-4.5-sonnet
+  gh/gemini-3-pro
+```
+
+</details>
+
+<details>
+<summary><b>🔑 Provedores por API Key</b></summary>
+
+### NVIDIA NIM (GRATUITO 1000 créditos!)
+
+1. Cadastre-se: [build.nvidia.com](https://build.nvidia.com)
+2. Obtenha API key gratuita (1000 créditos de inferência incluídos)
+3. Dashboard → Adicionar Provedor → NVIDIA NIM:
+   - API Key: `nvapi-your-key`
+
+**Modelos:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, e 50+ mais
+
+**Dica Pro:** API compatível com OpenAI — funciona perfeitamente com a tradução de formato do OmniRoute!
+
+### DeepSeek
+
+1. Cadastre-se: [platform.deepseek.com](https://platform.deepseek.com)
+2. Obtenha API key
+3. Dashboard → Adicionar Provedor → DeepSeek
+
+**Modelos:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder`
+
+### Groq (Tier Gratuito Disponível!)
+
+1. Cadastre-se: [console.groq.com](https://console.groq.com)
+2. Obtenha API key (tier gratuito incluído)
+3. Dashboard → Adicionar Provedor → Groq
+
+**Modelos:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b`
+
+**Dica Pro:** Inferência ultra-rápida — melhor para programação em tempo real!
+
+### OpenRouter (100+ Modelos)
+
+1. Cadastre-se: [openrouter.ai](https://openrouter.ai)
+2. Obtenha API key
+3. Dashboard → Adicionar Provedor → OpenRouter
+
+**Modelos:** Acesse 100+ modelos de todos os principais provedores através de uma única API key.
+
+</details>
+
+<details>
+<summary><b>💰 Provedores Baratos (Backup)</b></summary>
+
+### GLM-4.7 (Reset diário, $0.6/1M)
+
+1. Cadastre-se: [Zhipu AI](https://open.bigmodel.cn/)
+2. Obtenha API key do Plano Coding
+3. Dashboard → Adicionar API Key:
+   - Provedor: `glm`
+   - API Key: `your-key`
+
+**Use:** `glm/glm-4.7`
+
+**Dica Pro:** Plano Coding oferece 3× cota a 1/7 do custo! Reset diário 10:00 AM.
+
+### MiniMax M2.1 (Reset 5h, $0.20/1M)
+
+1. Cadastre-se: [MiniMax](https://www.minimax.io/)
+2. Obtenha API key
+3. Dashboard → Adicionar API Key
+
+**Use:** `minimax/MiniMax-M2.1`
+
+**Dica Pro:** Opção mais barata para contexto longo (1M tokens)!
+
+### Kimi K2 ($9/mês fixo)
+
+1. Assine: [Moonshot AI](https://platform.moonshot.ai/)
+2. Obtenha API key
+3. Dashboard → Adicionar API Key
+
+**Use:** `kimi/kimi-latest`
+
+**Dica Pro:** $9/mês fixo por 10M tokens = $0.90/1M de custo efetivo!
+
+</details>
+
+<details>
+<summary><b>🆓 Provedores GRATUITOS (Backup de Emergência)</b></summary>
+
+### iFlow (8 modelos GRATUITOS)
+
+```bash
+Dashboard → Conectar iFlow
+→ Login OAuth iFlow
+→ Uso ilimitado
+
+Modelos:
+  if/kimi-k2-thinking
+  if/qwen3-coder-plus
+  if/glm-4.7
+  if/minimax-m2
+  if/deepseek-r1
+```
+
+### Qwen (3 modelos GRATUITOS)
+
+```bash
+Dashboard → Conectar Qwen
+→ Autorização por código de dispositivo
+→ Uso ilimitado
+
+Modelos:
+  qw/qwen3-coder-plus
+  qw/qwen3-coder-flash
+```
+
+### Kiro (Claude GRATUITO)
+
+```bash
+Dashboard → Conectar Kiro
+→ AWS Builder ID ou Google/GitHub
+→ Uso ilimitado
+
+Modelos:
+  kr/claude-sonnet-4.5
+  kr/claude-haiku-4.5
+```
+
+</details>
+
+<details>
+<summary><b>🎨 Criar Combos</b></summary>
+
+### Exemplo 1: Maximizar Assinatura → Backup Barato
+
+```
+Dashboard → Combos → Criar Novo
+
+Nome: premium-coding
+Modelos:
+  1. cc/claude-opus-4-6 (Assinatura primária)
+  2. glm/glm-4.7 (Backup barato, $0.6/1M)
+  3. minimax/MiniMax-M2.1 (Fallback mais barato, $0.20/1M)
+
+Use na CLI: premium-coding
+```
+
+### Exemplo 2: Somente Gratuito (Custo Zero)
+
+```
+Nome: free-combo
+Modelos:
+  1. gc/gemini-3-flash-preview (180K grátis/mês)
+  2. if/kimi-k2-thinking (ilimitado)
+  3. qw/qwen3-coder-plus (ilimitado)
+
+Custo: $0 para sempre!
+```
+
+</details>
+
+<details>
+<summary><b>🔧 Integração CLI</b></summary>
+
+### Cursor IDE
+
+```
+Configurações → Modelos → Avançado:
+  OpenAI API Base URL: http://localhost:20128/v1
+  OpenAI API Key: [do dashboard OmniRoute]
+  Model: cc/claude-opus-4-6
+```
+
+### Claude Code
+
+Use a página **CLI Tools** no dashboard para configuração em um clique, ou edite `~/.claude/settings.json` manualmente.
+
+### Codex CLI
+
+```bash
+export OPENAI_BASE_URL="http://localhost:20128"
+export OPENAI_API_KEY="your-omniroute-api-key"
+
+codex "your prompt"
+```
+
+### OpenClaw
+
+**Opção 1 — Dashboard (recomendado):**
+
+```
+Dashboard → CLI Tools → OpenClaw → Selecionar Modelo → Aplicar
+```
+
+**Opção 2 — Manual:** Edite `~/.openclaw/openclaw.json`:
+
+```json
+{
+  "models": {
+    "providers": {
+      "omniroute": {
+        "baseUrl": "http://127.0.0.1:20128/v1",
+        "apiKey": "sk_omniroute",
+        "api": "openai-completions"
+      }
+    }
+  }
+}
+```
+
+> **Nota:** OpenClaw funciona apenas com OmniRoute local. Use `127.0.0.1` em vez de `localhost` para evitar problemas de resolução IPv6.
+
+### Cline / Continue / RooCode
+
+```
+Configurações → Configuração de API:
+  Provedor: OpenAI Compatible
+  Base URL: http://localhost:20128/v1
+  API Key: [do dashboard OmniRoute]
+  Model: if/kimi-k2-thinking
+```
+
+</details>
+
+---
+
+## 📊 Modelos Disponíveis
+
+<details>
+<summary><b>Ver todos os modelos disponíveis</b></summary>
+
+**Claude Code (`cc/`)** - Pro/Max:
+
+- `cc/claude-opus-4-6`
+- `cc/claude-sonnet-4-5-20250929`
+- `cc/claude-haiku-4-5-20251001`
+
+**Codex (`cx/`)** - Plus/Pro:
+
+- `cx/gpt-5.2-codex`
+- `cx/gpt-5.1-codex-max`
+
+**Gemini CLI (`gc/`)** - GRATUITO:
+
+- `gc/gemini-3-flash-preview`
+- `gc/gemini-2.5-pro`
+
+**GitHub Copilot (`gh/`)**:
+
+- `gh/gpt-5`
+- `gh/claude-4.5-sonnet`
+
+**NVIDIA NIM (`nvidia/`)** - Créditos GRATUITOS:
+
+- `nvidia/llama-3.3-70b-instruct`
+- `nvidia/mistral-7b-instruct`
+- 50+ mais modelos em [build.nvidia.com](https://build.nvidia.com)
+
+**GLM (`glm/`)** - $0.6/1M:
+
+- `glm/glm-4.7`
+
+**MiniMax (`minimax/`)** - $0.2/1M:
+
+- `minimax/MiniMax-M2.1`
+
+**iFlow (`if/`)** - GRATUITO:
+
+- `if/kimi-k2-thinking`
+- `if/qwen3-coder-plus`
+- `if/deepseek-r1`
+- `if/glm-4.7`
+- `if/minimax-m2`
+
+**Qwen (`qw/`)** - GRATUITO:
+
+- `qw/qwen3-coder-plus`
+- `qw/qwen3-coder-flash`
+
+**Kiro (`kr/`)** - GRATUITO:
+
+- `kr/claude-sonnet-4.5`
+- `kr/claude-haiku-4.5`
+
+**OpenRouter (`or/`)** - 100+ modelos:
+
+- `or/anthropic/claude-4-sonnet`
+- `or/google/gemini-2.5-pro`
+- Qualquer modelo de [openrouter.ai/models](https://openrouter.ai/models)
+
+</details>
+
+---
+
+## 🧪 Avaliações (Evals)
+
+OmniRoute inclui um framework de avaliação integrado para testar a qualidade de respostas de LLM contra um conjunto golden. Acesse via **Analytics → Evals** no dashboard.
+
+### Conjunto Golden Integrado
+
+O "OmniRoute Golden Set" pré-carregado contém 10 casos de teste cobrindo:
+
+- Saudações, matemática, geografia, geração de código
+- Conformidade de formato JSON, tradução, markdown
+- Recusa de segurança (conteúdo prejudicial), contagem, lógica booleana
+
+### Estratégias de Avaliação
+
+| Estratégia | Descrição                                      | Exemplo                          |
+| ---------- | ---------------------------------------------- | -------------------------------- |
+| `exact`    | Saída deve corresponder exatamente             | `"4"`                            |
+| `contains` | Saída deve conter substring (case-insensitive) | `"Paris"`                        |
+| `regex`    | Saída deve corresponder ao padrão regex        | `"1.*2.*3"`                      |
+| `custom`   | Função JS customizada retorna true/false       | `(output) => output.length > 10` |
+
+---
+
+## 🐛 Solução de Problemas
+
+<details>
+<summary><b>Clique para expandir o guia de solução de problemas</b></summary>
+
+**"Language model did not provide messages"**
+
+- Cota do provedor esgotada → Verifique o rastreador de cota no dashboard
+- Solução: Use combo com fallback ou mude para tier mais barato
+
+**Rate limiting**
+
+- Cota de assinatura esgotada → Fallback para GLM/MiniMax
+- Adicione combo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`
+
+**Token OAuth expirado**
+
+- Renovado automaticamente pelo OmniRoute
+- Se persistir: Dashboard → Provedor → Reconectar
+
+**Custos altos**
+
+- Verifique estatísticas de uso em Dashboard → Custos
+- Mude modelo primário para GLM/MiniMax
+- Use tier gratuito (Gemini CLI, iFlow) para tarefas não-críticas
+
+**Dashboard abre na porta errada**
+
+- Defina `PORT=20128` e `NEXT_PUBLIC_BASE_URL=http://localhost:20128`
+
+**Erros de cloud sync**
+
+- Verifique se `BASE_URL` aponta para sua instância em execução
+- Verifique se `CLOUD_URL` aponta para seu endpoint cloud esperado
+- Mantenha valores `NEXT_PUBLIC_*` alinhados com valores do servidor
+
+**Primeiro login não funciona**
+
+- Verifique `INITIAL_PASSWORD` no `.env`
+- Se não definido, senha padrão é `123456`
+
+**Sem logs de requisição**
+
+- Defina `ENABLE_REQUEST_LOGS=true` no `.env`
+
+**Teste de conexão mostra "Invalid" para provedores compatíveis com OpenAI**
+
+- Muitos provedores não expõem endpoint `/models`
+- OmniRoute v0.9.0+ inclui validação via chat completions como fallback
+- Certifique-se de que a base URL inclui sufixo `/v1`
+
+</details>
+
+---
+
+## 🛠️ Stack Tecnológico
+
+- **Runtime**: Node.js 20+
+- **Linguagem**: TypeScript 5.9 — **100% TypeScript** em `src/` e `open-sse/` (v0.9.0)
+- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4
+- **Banco de Dados**: LowDB (JSON) + SQLite (estado do domínio + logs de proxy)
+- **Streaming**: Server-Sent Events (SSE)
+- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys
+- **Testes**: Node.js test runner (368+ testes unitários)
+- **CI/CD**: GitHub Actions (publicação automática npm + Docker Hub no release)
+- **Website**: [omniroute.online](https://omniroute.online)
+- **Pacote**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)
+- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)
+- **Resiliência**: Circuit breaker, backoff exponencial, anti-thundering herd, spoofing TLS
+
+---
+
+## 📖 Documentação
+
+| Documento                                       | Descrição                                         |
+| ----------------------------------------------- | ------------------------------------------------- |
+| [Guia do Usuário](docs/USER_GUIDE.md)           | Provedores, combos, integração CLI, deploy        |
+| [Referência da API](docs/API_REFERENCE.md)      | Todos os endpoints com exemplos                   |
+| [Solução de Problemas](docs/TROUBLESHOOTING.md) | Problemas comuns e soluções                       |
+| [Arquitetura](docs/ARCHITECTURE.md)             | Arquitetura do sistema e internos                 |
+| [Contribuindo](CONTRIBUTING.md)                 | Setup de desenvolvimento e diretrizes             |
+| [Spec OpenAPI](docs/openapi.yaml)               | Especificação OpenAPI 3.0                         |
+| [Política de Segurança](SECURITY.md)            | Reportar vulnerabilidades e práticas de segurança |
+
+---
+
+## 📧 Suporte
+
+- **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)
+- **Projeto Original**: [9router por decolua](https://github.com/decolua/9router)
+
+---
+
+## 👥 Contribuidores
+
+[![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)
+
+### Como Contribuir
+
+1. Faça fork do repositório
+2. Crie sua branch de funcionalidade (`git checkout -b feature/amazing-feature`)
+3. Faça commit das suas alterações (`git commit -m 'Add amazing feature'`)
+4. Faça push para a branch (`git push origin feature/amazing-feature`)
+5. Abra um Pull Request
+
+Veja [CONTRIBUTING.md](CONTRIBUTING.md) para diretrizes detalhadas.
+
+### Lançando uma Nova Versão
+
+```bash
+# Crie um release — publicação no npm acontece automaticamente
+gh release create v0.9.0 --title "v0.9.0" --generate-notes
+```
+
+---
+
+## 📊 Histórico de Stars
+
+<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>
+
+---
+
+## 🙏 Agradecimentos
+
+Agradecimento especial a **[9router](https://github.com/decolua/9router)** por **[decolua](https://github.com/decolua)** — o projeto original que inspirou este fork. OmniRoute se baseia nessa fundação incrível com funcionalidades adicionais, APIs multi-modal e uma reescrita completa em TypeScript.
+
+Agradecimento especial a **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — a implementação original em Go que inspirou esta adaptação em JavaScript.
+
+---
+
+## 📄 Licença
+
+Licença MIT - veja [LICENSE](LICENSE) para detalhes.
+
+---
+
+<div align="center">
+  <sub>Feito com ❤️ para desenvolvedores que programam 24/7</sub>
+  <br/>
+  <sub><a href="https://omniroute.online">omniroute.online</a></sub>
+</div>