omniroute 0.8.8 → 0.9.0

package/README.es.md

@@ -0,0 +1,995 @@
+<div align="center">
+  <img src="./images/omniroute.png" alt="OmniRoute Dashboard" width="800"/>
+  
+  # 🚀 OmniRoute — El Gateway de IA Gratuito
+
+### Nunca dejes de programar. Enrutamiento inteligente hacia **modelos de IA GRATUITOS y económicos** con fallback automático.
+
+_Tu proxy de API universal — un endpoint, 36+ proveedores, cero tiempo de inactividad._
+
+**Chat Completions • Embeddings • Generación de Imágenes • Audio • Reranking • 100% TypeScript**
+
+---
+
+### 🤖 Proveedor de IA Gratuito para tus agentes de programación favoritos
+
+_Conecta cualquier IDE o herramienta CLI con IA a través de OmniRoute — gateway de API gratuito para programación 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 los agentes se conectan vía <code>http://localhost:20128/v1</code> o <code>http://cloud.omniroute.online/v1</code> — una configuración, modelos y cuota 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) • [🚀 Inicio Rápido](#-inicio-rápido) • [💡 Características](#-características-principales) • [📖 Docs](#-documentación) • [💰 Precios](#-precios-resumidos)
+
+🌐 **Disponible en:** [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 qué OmniRoute?
+
+**Deja de desperdiciar dinero y chocar con límites:**
+
+- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> La cuota de suscripción expira sin usar cada mes
+- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> Los límites de tasa te detienen en medio de la programación
+- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> APIs caras ($20-50/mes por proveedor)
+- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> Cambiar manualmente entre proveedores
+
+**OmniRoute resuelve esto:**
+
+- ✅ **Maximiza suscripciones** - Rastrea cuotas, usa cada bit antes del reset
+- ✅ **Fallback automático** - Suscripción → API Key → Barato → Gratuito, cero tiempo de inactividad
+- ✅ **Multi-cuenta** - Round-robin entre cuentas por proveedor
+- ✅ **Universal** - Funciona con Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, cualquier herramienta CLI
+
+---
+
+## 🔄 Cómo Funciona
+
+```
+┌─────────────┐
+│  Tu CLI     │  (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)
+│   Tool      │
+└──────┬──────┘
+       │ http://localhost:20128/v1
+       ↓
+┌─────────────────────────────────────────┐
+│        OmniRoute (Enrutador Inteligente)  │
+│  • Traducción de formato (OpenAI ↔ Claude) │
+│  • Rastreo de cuota + Embeddings + Imágenes │
+│  • Renovación automática de tokens        │
+└──────┬──────────────────────────────────┘
+       │
+       ├─→ [Tier 1: SUSCRIPCIÓN] Claude Code, Codex, Gemini CLI
+       │   ↓ cuota agotada
+       ├─→ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.
+       │   ↓ límite de presupuesto
+       ├─→ [Tier 3: BARATO] GLM ($0.6/1M), MiniMax ($0.2/1M)
+       │   ↓ límite de presupuesto
+       └─→ [Tier 4: GRATUITO] iFlow, Qwen, Kiro (ilimitado)
+
+Resultado: Nunca dejes de programar, costo mínimo
+```
+
+---
+
+## ⚡ Inicio Rápido
+
+**1. Instala globalmente:**
+
+```bash
+npm install -g omniroute
+omniroute
+```
+
+🎉 El Dashboard se abre en `http://localhost:20128`
+
+| Comando                 | Descripción                                    |
+| ----------------------- | ---------------------------------------------- |
+| `omniroute`             | Iniciar servidor (puerto predeterminado 20128) |
+| `omniroute --port 3000` | Usar puerto personalizado                      |
+| `omniroute --no-open`   | No abrir navegador automáticamente             |
+| `omniroute --help`      | Mostrar ayuda                                  |
+
+**2. Conecta un proveedor GRATUITO:**
+
+Dashboard → Proveedores → Conectar **Claude Code** o **Antigravity** → Login OAuth → ¡Listo!
+
+**3. Usa en tu herramienta CLI:**
+
+```
+Claude Code/Codex/Gemini CLI/OpenClaw/Cursor/Cline Configuración:
+  Endpoint: http://localhost:20128/v1
+  API Key: [copiar del dashboard]
+  Model: if/kimi-k2-thinking
+```
+
+**¡Eso es todo!** Comienza a programar con modelos de IA GRATUITOS.
+
+**Alternativa — ejecutar desde código fuente:**
+
+```bash
+cp .env.example .env
+npm install
+PORT=20128 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev
+```
+
+---
+
+## 🐳 Docker
+
+OmniRoute está disponible como imagen Docker pública en [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).
+
+**Ejecución rápida:**
+
+```bash
+docker run -d \
+  --name omniroute \
+  --restart unless-stopped \
+  -p 20128:20128 \
+  -v omniroute-data:/app/data \
+  diegosouzapw/omniroute:latest
+```
+
+**Con archivo de entorno:**
+
+```bash
+# Copia y edita el .env primero
+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 (sin herramientas CLI)
+docker compose --profile base up -d
+
+# Perfil CLI (Claude Code, Codex, OpenClaw integrados)
+docker compose --profile cli up -d
+```
+
+| Imagen                   | Tag      | Tamaño | Descripción            |
+| ------------------------ | -------- | ------ | ---------------------- |
+| `diegosouzapw/omniroute` | `latest` | ~250MB | Última versión estable |
+| `diegosouzapw/omniroute` | `0.9.0`  | ~250MB | Versión actual         |
+
+---
+
+## 💰 Precios Resumidos
+
+| Tier               | Proveedor         | Costo                        | Reset de Cuota    | Mejor Para              |
+| ------------------ | ----------------- | ---------------------------- | ----------------- | ----------------------- |
+| **💳 SUSCRIPCIÓN** | Claude Code (Pro) | $20/mes                      | 5h + semanal      | Ya suscrito             |
+|                    | Codex (Plus/Pro)  | $20-200/mes                  | 5h + semanal      | Usuarios OpenAI         |
+|                    | Gemini CLI        | **GRATUITO**                 | 180K/mes + 1K/día | ¡Todos!                 |
+|                    | GitHub Copilot    | $10-19/mes                   | Mensual           | Usuarios GitHub         |
+| **🔑 API KEY**     | NVIDIA NIM        | **GRATUITO** (1000 créditos) | Único             | Pruebas gratuitas       |
+|                    | DeepSeek          | Por uso                      | Ninguno           | Mejor precio/calidad    |
+|                    | Groq              | Tier gratuito + pago         | Limitado          | Inferencia ultra-rápida |
+|                    | xAI (Grok)        | Por uso                      | Ninguno           | Modelos Grok            |
+|                    | Mistral           | Tier gratuito + pago         | Limitado          | IA Europea              |
+|                    | OpenRouter        | Por uso                      | Ninguno           | 100+ modelos            |
+| **💰 BARATO**      | GLM-4.7           | $0.6/1M                      | Diario 10h        | Respaldo económico      |
+|                    | MiniMax M2.1      | $0.2/1M                      | Rotativo 5h       | Opción más barata       |
+|                    | Kimi K2           | $9/mes fijo                  | 10M tokens/mes    | Costo predecible        |
+| **🆓 GRATUITO**    | iFlow             | $0                           | Ilimitado         | 8 modelos gratuitos     |
+|                    | Qwen              | $0                           | Ilimitado         | 3 modelos gratuitos     |
+|                    | Kiro              | $0                           | Ilimitado         | Claude gratuito         |
+
+**💡 Consejo Pro:** ¡Comienza con Gemini CLI (180K gratis/mes) + iFlow (ilimitado gratis) = $0 de costo!
+
+---
+
+## 🎯 Casos de Uso
+
+### Caso 1: "Tengo suscripción Claude Pro"
+
+**Problema:** La cuota expira sin usar, límites de tasa durante programación intensa
+
+```
+Combo: "maximize-claude"
+  1. cc/claude-opus-4-6        (usar suscripción al máximo)
+  2. glm/glm-4.7               (respaldo barato cuando la cuota se agota)
+  3. if/kimi-k2-thinking       (fallback de emergencia gratuito)
+
+Costo mensual: $20 (suscripción) + ~$5 (respaldo) = $25 total
+vs. $20 + chocar con límites = frustración
+```
+
+### Caso 2: "Quiero costo cero"
+
+**Problema:** No puede pagar suscripciones, necesita IA confiable para programar
+
+```
+Combo: "free-forever"
+  1. gc/gemini-3-flash         (180K gratis/mes)
+  2. if/kimi-k2-thinking       (ilimitado gratis)
+  3. qw/qwen3-coder-plus       (ilimitado gratis)
+
+Costo mensual: $0
+Calidad: Modelos listos para producción
+```
+
+### Caso 3: "Necesito programar 24/7, sin interrupciones"
+
+**Problema:** Plazos ajustados, no puede permitirse tiempo de inactividad
+
+```
+Combo: "always-on"
+  1. cc/claude-opus-4-6        (mejor calidad)
+  2. cx/gpt-5.2-codex          (segunda suscripción)
+  3. glm/glm-4.7               (barato, reset diario)
+  4. minimax/MiniMax-M2.1      (más barato, reset 5h)
+  5. if/kimi-k2-thinking       (gratuito ilimitado)
+
+Resultado: 5 capas de fallback = cero tiempo de inactividad
+```
+
+### Caso 4: "Quiero IA GRATUITA en OpenClaw"
+
+**Problema:** Necesita asistente de IA en apps de mensajería, completamente gratuito
+
+```
+Combo: "openclaw-free"
+  1. if/glm-4.7                (ilimitado gratis)
+  2. if/minimax-m2.1           (ilimitado gratis)
+  3. if/kimi-k2-thinking       (ilimitado gratis)
+
+Costo mensual: $0
+Acceso vía: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
+```
+
+---
+
+## 💡 Características Principales
+
+### 🧠 Enrutamiento e Inteligencia
+
+| Característica                         | Qué Hace                                                                        |
+| -------------------------------------- | ------------------------------------------------------------------------------- |
+| 🎯 **Fallback Inteligente 4 Tiers**    | Auto-enrutamiento: Suscripción → API Key → Barato → Gratuito                    |
+| 📊 **Rastreo de Cuota en Tiempo Real** | Conteo de tokens en vivo + countdown de reset por proveedor                     |
+| 🔄 **Traducción de Formato**           | OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro transparente                           |
+| 👥 **Soporte Multi-Cuenta**            | Múltiples cuentas por proveedor con selección inteligente                       |
+| 🔄 **Renovación Automática de Token**  | Tokens OAuth se renuevan automáticamente con reintentos                         |
+| 🎨 **Combos Personalizados**           | 6 estrategias: fill-first, round-robin, p2c, random, least-used, cost-optimized |
+| 🧩 **Modelos Personalizados**          | Agrega cualquier ID de modelo a cualquier proveedor                             |
+| 🌐 **Enrutador Wildcard**              | Enruta patrones `provider/*` a cualquier proveedor dinámicamente                |
+| 🧠 **Presupuesto de Razonamiento**     | Modos passthrough, auto, custom y adaptativo para modelos de razonamiento       |
+| 💬 **Inyección de System Prompt**      | System prompt global aplicado en todas las solicitudes                          |
+| 📄 **API Responses**                   | Soporte completo de la API Responses de OpenAI (`/v1/responses`) para Codex     |
+
+### 🎵 APIs Multi-Modal
+
+| Característica                | Qué Hace                                               |
+| ----------------------------- | ------------------------------------------------------ |
+| 🖼️ **Generación de Imágenes** | `/v1/images/generations` — 4 proveedores, 9+ modelos   |
+| 📐 **Embeddings**             | `/v1/embeddings` — 6 proveedores, 9+ modelos           |
+| 🎤 **Transcripción de Audio** | `/v1/audio/transcriptions` — Compatible con Whisper    |
+| 🔊 **Texto a Voz**            | `/v1/audio/speech` — Síntesis de audio multi-proveedor |
+| 🛡️ **Moderaciones**           | `/v1/moderations` — Verificaciones de seguridad        |
+| 🔀 **Reranking**              | `/v1/rerank` — Reranking de relevancia de documentos   |
+
+### 🛡️ Resiliencia y Seguridad
+
+| Característica                     | Qué Hace                                                         |
+| ---------------------------------- | ---------------------------------------------------------------- |
+| 🔌 **Circuit Breaker**             | Auto-apertura/cierre por proveedor con umbrales configurables    |
+| 🛡️ **Anti-Thundering Herd**        | Mutex + semáforo rate-limit para proveedores con API key         |
+| 🧠 **Caché Semántico**             | Caché de dos niveles (firma + semántico) reduce costo y latencia |
+| ⚡ **Idempotencia de Solicitud**   | Ventana de dedup de 5s para solicitudes duplicadas               |
+| 🔒 **Spoofing de Fingerprint TLS** | Bypass de detección de bot vía TLS con wreq-js                   |
+| 🌐 **Filtrado de IP**              | Allowlist/blocklist para control de acceso a la API              |
+| 📊 **Rate Limits Editables**       | RPM, gap mínimo y concurrencia máxima configurables              |
+
+### 📊 Observabilidad y Analytics
+
+| Característica                 | Qué Hace                                                              |
+| ------------------------------ | --------------------------------------------------------------------- |
+| 📝 **Logs de Solicitud**       | Modo debug con logs completos de request/response                     |
+| 💾 **Logs SQLite**             | Logs de proxy persistentes sobreviven a reinicios                     |
+| 📊 **Dashboard de Analytics**  | Recharts: cards de estadísticas, gráfico de uso, tabla de proveedores |
+| 📈 **Rastreo de Progreso**     | Eventos de progreso SSE opt-in para streaming                         |
+| 🧪 **Evaluaciones de LLM**     | Pruebas con conjunto golden y 4 estrategias de match                  |
+| 🔍 **Telemetría de Solicitud** | Agregación de latencia p50/p95/p99 + rastreo X-Request-Id             |
+| 📋 **Logs + Cuotas**           | Páginas dedicadas para navegación de logs y rastreo de cuotas         |
+| 🏥 **Dashboard de Salud**      | Uptime, estados de circuit breaker, lockouts, stats de caché          |
+| 💰 **Rastreo de Costos**       | Gestión de presupuesto + configuración de precios por modelo          |
+
+### ☁️ Deploy y Sincronización
+
+| Característica                    | Qué Hace                                                                        |
+| --------------------------------- | ------------------------------------------------------------------------------- |
+| 💾 **Cloud Sync**                 | Sincroniza configuraciones entre dispositivos vía Cloudflare Workers            |
+| 🌐 **Deploy en Cualquier Lugar**  | Localhost, VPS, Docker, Cloudflare Workers                                      |
+| 🔑 **Gestión de API Keys**        | Genera, rota y define alcance de API keys por proveedor                         |
+| 🧙 **Asistente de Configuración** | Setup guiado en 4 pasos para nuevos usuarios                                    |
+| 🔧 **Dashboard CLI Tools**        | Configuración en un clic para Claude, Codex, Cline, OpenClaw, Kilo, Antigravity |
+| 🔄 **Backups de DB**              | Backup y restauración automáticos de todas las configuraciones                  |
+
+<details>
+<summary><b>📖 Detalles de Características</b></summary>
+
+### 🎯 Fallback Inteligente 4 Tiers
+
+Crea combos con fallback automático:
+
+```
+Combo: "my-coding-stack"
+  1. cc/claude-opus-4-6        (tu suscripción)
+  2. nvidia/llama-3.3-70b      (API NVIDIA gratuita)
+  3. glm/glm-4.7               (respaldo barato, $0.6/1M)
+  4. if/kimi-k2-thinking       (fallback gratuito)
+
+→ Cambia automáticamente cuando la cuota se agota o ocurren errores
+```
+
+### 📊 Rastreo de Cuota en Tiempo Real
+
+- Consumo de tokens por proveedor
+- Countdown de reset (5 horas, diario, semanal)
+- Estimación de costo para tiers pagos
+- Reportes de gastos mensuales
+
+### 🔄 Traducción de Formato
+
+Traducción transparente entre formatos:
+
+- **OpenAI** ↔ **Claude** ↔ **Gemini** ↔ **OpenAI Responses**
+- Tu herramienta CLI envía formato OpenAI → OmniRoute traduce → El proveedor recibe formato nativo
+- Funciona con cualquier herramienta que soporte endpoints OpenAI personalizados
+
+### 👥 Soporte Multi-Cuenta
+
+- Agrega múltiples cuentas por proveedor
+- Round-robin automático o enrutamiento por prioridad
+- Fallback a la siguiente cuenta cuando una alcanza la cuota
+
+### 🔄 Renovación Automática de Token
+
+- Los tokens OAuth se renuevan automáticamente antes de expirar
+- Sin necesidad de re-autenticación manual
+- Experiencia transparente en todos los proveedores
+
+### 🎨 Combos Personalizados
+
+- Crea combinaciones ilimitadas de modelos
+- 6 estrategias: fill-first, round-robin, power-of-two-choices, random, least-used, cost-optimized
+- Comparte combos entre dispositivos con Cloud Sync
+
+### 🏥 Dashboard de Salud
+
+- Estado del sistema (uptime, versión, uso de memoria)
+- Estados de circuit breaker por proveedor (Closed/Open/Half-Open)
+- Estado de rate limit y lockouts activos
+- Estadísticas de caché de firma
+- Telemetría de latencia (p50/p95/p99) + caché de prompt
+- Reset de salud con un clic
+
+### 🔧 Playground del Traductor
+
+- Debug, prueba y visualiza traducciones de formato de API
+- Envía solicitudes y ve cómo OmniRoute traduce entre formatos de proveedores
+- Invaluable para troubleshooting de problemas de integración
+
+### 💾 Cloud Sync
+
+- Sincroniza proveedores, combos y configuraciones entre dispositivos
+- Sincronización automática en segundo plano
+- Almacenamiento cifrado seguro
+
+</details>
+
+---
+
+## 📖 Guía de Configuración
+
+<details>
+<summary><b>💳 Proveedores por Suscripción</b></summary>
+
+### Claude Code (Pro/Max)
+
+```bash
+Dashboard → Proveedores → Conectar Claude Code
+→ Login OAuth → Renovación automática de token
+→ Rastreo de cuota 5h + semanal
+
+Modelos:
+  cc/claude-opus-4-6
+  cc/claude-sonnet-4-5-20250929
+  cc/claude-haiku-4-5-20251001
+```
+
+**Consejo Pro:** Usa Opus para tareas complejas, Sonnet para velocidad. ¡OmniRoute rastrea cuota por modelo!
+
+### OpenAI Codex (Plus/Pro)
+
+```bash
+Dashboard → Proveedores → Conectar Codex
+→ Login OAuth (puerto 1455)
+→ Reset 5h + semanal
+
+Modelos:
+  cx/gpt-5.2-codex
+  cx/gpt-5.1-codex-max
+```
+
+### Gemini CLI (¡GRATUITO 180K/mes!)
+
+```bash
+Dashboard → Proveedores → Conectar Gemini CLI
+→ Google OAuth
+→ 180K completions/mes + 1K/día
+
+Modelos:
+  gc/gemini-3-flash-preview
+  gc/gemini-2.5-pro
+```
+
+**Mejor Valor:** ¡Tier gratuito enorme! Úsalo antes de los tiers pagos.
+
+### GitHub Copilot
+
+```bash
+Dashboard → Proveedores → Conectar GitHub
+→ OAuth vía GitHub
+→ Reset mensual (1ro del mes)
+
+Modelos:
+  gh/gpt-5
+  gh/claude-4.5-sonnet
+  gh/gemini-3-pro
+```
+
+</details>
+
+<details>
+<summary><b>🔑 Proveedores por API Key</b></summary>
+
+### NVIDIA NIM (¡GRATUITO 1000 créditos!)
+
+1. Regístrate: [build.nvidia.com](https://build.nvidia.com)
+2. Obtén API key gratuita (1000 créditos de inferencia incluidos)
+3. Dashboard → Agregar Proveedor → NVIDIA NIM:
+   - API Key: `nvapi-your-key`
+
+**Modelos:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, y 50+ más
+
+**Consejo Pro:** ¡API compatible con OpenAI — funciona perfectamente con la traducción de formato de OmniRoute!
+
+### DeepSeek
+
+1. Regístrate: [platform.deepseek.com](https://platform.deepseek.com)
+2. Obtén API key
+3. Dashboard → Agregar Proveedor → DeepSeek
+
+**Modelos:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder`
+
+### Groq (¡Tier Gratuito Disponible!)
+
+1. Regístrate: [console.groq.com](https://console.groq.com)
+2. Obtén API key (tier gratuito incluido)
+3. Dashboard → Agregar Proveedor → Groq
+
+**Modelos:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b`
+
+**Consejo Pro:** ¡Inferencia ultra-rápida — mejor para programación en tiempo real!
+
+### OpenRouter (100+ Modelos)
+
+1. Regístrate: [openrouter.ai](https://openrouter.ai)
+2. Obtén API key
+3. Dashboard → Agregar Proveedor → OpenRouter
+
+**Modelos:** Accede a 100+ modelos de todos los principales proveedores a través de una única API key.
+
+</details>
+
+<details>
+<summary><b>💰 Proveedores Baratos (Respaldo)</b></summary>
+
+### GLM-4.7 (Reset diario, $0.6/1M)
+
+1. Regístrate: [Zhipu AI](https://open.bigmodel.cn/)
+2. Obtén API key del Plan Coding
+3. Dashboard → Agregar API Key:
+   - Proveedor: `glm`
+   - API Key: `your-key`
+
+**Usa:** `glm/glm-4.7`
+
+**Consejo Pro:** ¡El Plan Coding ofrece 3× cuota a 1/7 del costo! Reset diario 10:00 AM.
+
+### MiniMax M2.1 (Reset 5h, $0.20/1M)
+
+1. Regístrate: [MiniMax](https://www.minimax.io/)
+2. Obtén API key
+3. Dashboard → Agregar API Key
+
+**Usa:** `minimax/MiniMax-M2.1`
+
+**Consejo Pro:** ¡Opción más barata para contexto largo (1M tokens)!
+
+### Kimi K2 ($9/mes fijo)
+
+1. Suscríbete: [Moonshot AI](https://platform.moonshot.ai/)
+2. Obtén API key
+3. Dashboard → Agregar API Key
+
+**Usa:** `kimi/kimi-latest`
+
+**Consejo Pro:** ¡$9/mes fijo por 10M tokens = $0.90/1M de costo efectivo!
+
+</details>
+
+<details>
+<summary><b>🆓 Proveedores GRATUITOS (Respaldo de Emergencia)</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
+→ Autorización 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 o Google/GitHub
+→ Uso ilimitado
+
+Modelos:
+  kr/claude-sonnet-4.5
+  kr/claude-haiku-4.5
+```
+
+</details>
+
+<details>
+<summary><b>🎨 Crear Combos</b></summary>
+
+### Ejemplo 1: Maximizar Suscripción → Respaldo Barato
+
+```
+Dashboard → Combos → Crear Nuevo
+
+Nombre: premium-coding
+Modelos:
+  1. cc/claude-opus-4-6 (Suscripción primaria)
+  2. glm/glm-4.7 (Respaldo barato, $0.6/1M)
+  3. minimax/MiniMax-M2.1 (Fallback más barato, $0.20/1M)
+
+Usa en CLI: premium-coding
+```
+
+### Ejemplo 2: Solo Gratuito (Costo Cero)
+
+```
+Nombre: free-combo
+Modelos:
+  1. gc/gemini-3-flash-preview (180K gratis/mes)
+  2. if/kimi-k2-thinking (ilimitado)
+  3. qw/qwen3-coder-plus (ilimitado)
+
+Costo: ¡$0 para siempre!
+```
+
+</details>
+
+<details>
+<summary><b>🔧 Integración CLI</b></summary>
+
+### Cursor IDE
+
+```
+Configuración → Modelos → Avanzado:
+  OpenAI API Base URL: http://localhost:20128/v1
+  OpenAI API Key: [del dashboard OmniRoute]
+  Model: cc/claude-opus-4-6
+```
+
+### Claude Code
+
+Usa la página **CLI Tools** en el dashboard para configuración en un clic, o edita `~/.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
+
+**Opción 1 — Dashboard (recomendado):**
+
+```
+Dashboard → CLI Tools → OpenClaw → Seleccionar Modelo → Aplicar
+```
+
+**Opción 2 — Manual:** Edita `~/.openclaw/openclaw.json`:
+
+```json
+{
+  "models": {
+    "providers": {
+      "omniroute": {
+        "baseUrl": "http://127.0.0.1:20128/v1",
+        "apiKey": "sk_omniroute",
+        "api": "openai-completions"
+      }
+    }
+  }
+}
+```
+
+> **Nota:** OpenClaw solo funciona con OmniRoute local. Usa `127.0.0.1` en lugar de `localhost` para evitar problemas de resolución IPv6.
+
+### Cline / Continue / RooCode
+
+```
+Configuración → Configuración de API:
+  Proveedor: OpenAI Compatible
+  Base URL: http://localhost:20128/v1
+  API Key: [del dashboard OmniRoute]
+  Model: if/kimi-k2-thinking
+```
+
+</details>
+
+---
+
+## 📊 Modelos Disponibles
+
+<details>
+<summary><b>Ver todos los modelos disponibles</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+ más modelos en [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`
+- Cualquier modelo de [openrouter.ai/models](https://openrouter.ai/models)
+
+</details>
+
+---
+
+## 🧪 Evaluaciones (Evals)
+
+OmniRoute incluye un framework de evaluación integrado para probar la calidad de respuestas de LLM contra un conjunto golden. Accede vía **Analytics → Evals** en el dashboard.
+
+### Conjunto Golden Integrado
+
+El "OmniRoute Golden Set" precargado contiene 10 casos de prueba que cubren:
+
+- Saludos, matemáticas, geografía, generación de código
+- Conformidad de formato JSON, traducción, markdown
+- Rechazo de seguridad (contenido dañino), conteo, lógica booleana
+
+### Estrategias de Evaluación
+
+| Estrategia | Descripción                                          | Ejemplo                          |
+| ---------- | ---------------------------------------------------- | -------------------------------- |
+| `exact`    | La salida debe coincidir exactamente                 | `"4"`                            |
+| `contains` | La salida debe contener subcadena (case-insensitive) | `"Paris"`                        |
+| `regex`    | La salida debe coincidir con el patrón regex         | `"1.*2.*3"`                      |
+| `custom`   | Función JS personalizada retorna true/false          | `(output) => output.length > 10` |
+
+---
+
+## 🐛 Solución de Problemas
+
+<details>
+<summary><b>Haz clic para expandir la guía de solución de problemas</b></summary>
+
+**"Language model did not provide messages"**
+
+- Cuota del proveedor agotada → Verifica el rastreador de cuota en el dashboard
+- Solución: Usa combo con fallback o cambia a tier más barato
+
+**Rate limiting**
+
+- Cuota de suscripción agotada → Fallback a GLM/MiniMax
+- Agrega combo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`
+
+**Token OAuth expirado**
+
+- Renovado automáticamente por OmniRoute
+- Si persiste: Dashboard → Proveedor → Reconectar
+
+**Costos altos**
+
+- Verifica estadísticas de uso en Dashboard → Costos
+- Cambia modelo primario a GLM/MiniMax
+- Usa tier gratuito (Gemini CLI, iFlow) para tareas no críticas
+
+**Dashboard se abre en el puerto equivocado**
+
+- Establece `PORT=20128` y `NEXT_PUBLIC_BASE_URL=http://localhost:20128`
+
+**Errores de cloud sync**
+
+- Verifica que `BASE_URL` apunte a tu instancia en ejecución
+- Verifica que `CLOUD_URL` apunte a tu endpoint cloud esperado
+- Mantén los valores `NEXT_PUBLIC_*` alineados con los valores del servidor
+
+**Primer login no funciona**
+
+- Verifica `INITIAL_PASSWORD` en `.env`
+- Si no está definido, la contraseña predeterminada es `123456`
+
+**Sin logs de solicitud**
+
+- Establece `ENABLE_REQUEST_LOGS=true` en `.env`
+
+**Prueba de conexión muestra "Invalid" para proveedores compatibles con OpenAI**
+
+- Muchos proveedores no exponen el endpoint `/models`
+- OmniRoute v0.9.0+ incluye validación vía chat completions como fallback
+- Asegúrate de que la URL base incluya el sufijo `/v1`
+
+</details>
+
+---
+
+## 🛠️ Stack Tecnológico
+
+- **Runtime**: Node.js 20+
+- **Lenguaje**: TypeScript 5.9 — **100% TypeScript** en `src/` y `open-sse/` (v0.9.0)
+- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4
+- **Base de Datos**: LowDB (JSON) + SQLite (estado del dominio + logs de proxy)
+- **Streaming**: Server-Sent Events (SSE)
+- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys
+- **Testing**: Node.js test runner (368+ tests unitarios)
+- **CI/CD**: GitHub Actions (publicación automática npm + Docker Hub en release)
+- **Website**: [omniroute.online](https://omniroute.online)
+- **Paquete**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)
+- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)
+- **Resiliencia**: Circuit breaker, backoff exponencial, anti-thundering herd, spoofing TLS
+
+---
+
+## 📖 Documentación
+
+| Documento                                        | Descripción                                        |
+| ------------------------------------------------ | -------------------------------------------------- |
+| [Guía del Usuario](docs/USER_GUIDE.md)           | Proveedores, combos, integración CLI, deploy       |
+| [Referencia de API](docs/API_REFERENCE.md)       | Todos los endpoints con ejemplos                   |
+| [Solución de Problemas](docs/TROUBLESHOOTING.md) | Problemas comunes y soluciones                     |
+| [Arquitectura](docs/ARCHITECTURE.md)             | Arquitectura del sistema e internos                |
+| [Contribuir](CONTRIBUTING.md)                    | Setup de desarrollo y directrices                  |
+| [Spec OpenAPI](docs/openapi.yaml)                | Especificación OpenAPI 3.0                         |
+| [Política de Seguridad](SECURITY.md)             | Reportar vulnerabilidades y prácticas de seguridad |
+
+---
+
+## 📧 Soporte
+
+- **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)
+- **Proyecto 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)
+
+### Cómo Contribuir
+
+1. Haz fork del repositorio
+2. Crea tu rama de funcionalidad (`git checkout -b feature/amazing-feature`)
+3. Haz commit de tus cambios (`git commit -m 'Add amazing feature'`)
+4. Haz push a la rama (`git push origin feature/amazing-feature`)
+5. Abre un Pull Request
+
+Consulta [CONTRIBUTING.md](CONTRIBUTING.md) para directrices detalladas.
+
+### Lanzar una Nueva Versión
+
+```bash
+# Crea un release — la publicación en npm ocurre automáticamente
+gh release create v0.9.0 --title "v0.9.0" --generate-notes
+```
+
+---
+
+## 📊 Historial 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>
+
+---
+
+## 🙏 Agradecimientos
+
+Agradecimiento especial a **[9router](https://github.com/decolua/9router)** por **[decolua](https://github.com/decolua)** — el proyecto original que inspiró este fork. OmniRoute se construye sobre esa increíble base con características adicionales, APIs multi-modal y una reescritura completa en TypeScript.
+
+Agradecimiento especial a **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — la implementación original en Go que inspiró esta adaptación a JavaScript.
+
+---
+
+## 📄 Licencia
+
+Licencia MIT - consulta [LICENSE](LICENSE) para detalles.
+
+---
+
+<div align="center">
+  <sub>Hecho con ❤️ para desarrolladores que programan 24/7</sub>
+  <br/>
+  <sub><a href="https://omniroute.online">omniroute.online</a></sub>
+</div>