# User Guide (Español)
🌐 **Languages:** 🇺🇸 [English](../../../../guides/USER_GUIDE.md) · 🇪🇹 [am](../../../am/docs/guides/USER_GUIDE.md) · 🇸🇦 [ar](../../../ar/docs/guides/USER_GUIDE.md) · 🇦🇿 [az](../../../az/docs/guides/USER_GUIDE.md) · 🇧🇬 [bg](../../../bg/docs/guides/USER_GUIDE.md) · 🇧🇩 [bn](../../../bn/docs/guides/USER_GUIDE.md) · 🇧🇦 [bs](../../../bs/docs/guides/USER_GUIDE.md) · 🇨🇿 [cs](../../../cs/docs/guides/USER_GUIDE.md) · 🇩🇰 [da](../../../da/docs/guides/USER_GUIDE.md) · 🇩🇪 [de](../../../de/docs/guides/USER_GUIDE.md) · 🇬🇷 [el](../../../el/docs/guides/USER_GUIDE.md) · 🇪🇪 [et](../../../et/docs/guides/USER_GUIDE.md) · 🇮🇷 [fa](../../../fa/docs/guides/USER_GUIDE.md) · 🇫🇮 [fi](../../../fi/docs/guides/USER_GUIDE.md) · 🇫🇷 [fr](../../../fr/docs/guides/USER_GUIDE.md) · 🇮🇪 [ga](../../../ga/docs/guides/USER_GUIDE.md) · 🇮🇳 [gu](../../../gu/docs/guides/USER_GUIDE.md) · 🇳🇬 [ha](../../../ha/docs/guides/USER_GUIDE.md) · 🇮🇱 [he](../../../he/docs/guides/USER_GUIDE.md) · 🇮🇳 [hi](../../../hi/docs/guides/USER_GUIDE.md) · 🇭🇷 [hr](../../../hr/docs/guides/USER_GUIDE.md) · 🇭🇺 [hu](../../../hu/docs/guides/USER_GUIDE.md) · 🇦🇲 [hy](../../../hy/docs/guides/USER_GUIDE.md) · 🇮🇩 [id](../../../id/docs/guides/USER_GUIDE.md) · 🇳🇬 [ig](../../../ig/docs/guides/USER_GUIDE.md) · 🇮🇹 [it](../../../it/docs/guides/USER_GUIDE.md) · 🇯🇵 [ja](../../../ja/docs/guides/USER_GUIDE.md) · 🇬🇪 [ka](../../../ka/docs/guides/USER_GUIDE.md) · 🇰🇭 [km](../../../km/docs/guides/USER_GUIDE.md) · 🇮🇳 [kn](../../../kn/docs/guides/USER_GUIDE.md) · 🇰🇷 [ko](../../../ko/docs/guides/USER_GUIDE.md) · 🇱🇹 [lt](../../../lt/docs/guides/USER_GUIDE.md) · 🇱🇻 [lv](../../../lv/docs/guides/USER_GUIDE.md) · 🇮🇳 [ml](../../../ml/docs/guides/USER_GUIDE.md) · 🇮🇳 [mr](../../../mr/docs/guides/USER_GUIDE.md) · 🇲🇾 [ms](../../../ms/docs/guides/USER_GUIDE.md) · 🇲🇹 [mt](../../../mt/docs/guides/USER_GUIDE.md) · 🇲🇲 [my](../../../my/docs/guides/USER_GUIDE.md) · 🇳🇵 [ne](../../../ne/docs/guides/USER_GUIDE.md) · 🇳🇱 [nl](../../../nl/docs/guides/USER_GUIDE.md) · 🇳🇴 [no](../../../no/docs/guides/USER_GUIDE.md) · 🇮🇳 [or](../../../or/docs/guides/USER_GUIDE.md) · 🇮🇳 [pa](../../../pa/docs/guides/USER_GUIDE.md) · 🇵🇭 [phi](../../../phi/docs/guides/USER_GUIDE.md) · 🇵🇱 [pl](../../../pl/docs/guides/USER_GUIDE.md) · 🇵🇹 [pt](../../../pt/docs/guides/USER_GUIDE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/guides/USER_GUIDE.md) · 🇷🇴 [ro](../../../ro/docs/guides/USER_GUIDE.md) · 🇷🇺 [ru](../../../ru/docs/guides/USER_GUIDE.md) · 🇱🇰 [si](../../../si/docs/guides/USER_GUIDE.md) · 🇸🇰 [sk](../../../sk/docs/guides/USER_GUIDE.md) · 🇸🇮 [sl](../../../sl/docs/guides/USER_GUIDE.md) · 🇷🇸 [sr](../../../sr/docs/guides/USER_GUIDE.md) · 🇸🇪 [sv](../../../sv/docs/guides/USER_GUIDE.md) · 🇰🇪 [sw](../../../sw/docs/guides/USER_GUIDE.md) · 🇮🇳 [ta](../../../ta/docs/guides/USER_GUIDE.md) · 🇮🇳 [te](../../../te/docs/guides/USER_GUIDE.md) · 🇹🇭 [th](../../../th/docs/guides/USER_GUIDE.md) · 🇹🇷 [tr](../../../tr/docs/guides/USER_GUIDE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/guides/USER_GUIDE.md) · 🇵🇰 [ur](../../../ur/docs/guides/USER_GUIDE.md) · 🇺🇿 [uz](../../../uz/docs/guides/USER_GUIDE.md) · 🇻🇳 [vi](../../../vi/docs/guides/USER_GUIDE.md) · 🇳🇬 [yo](../../../yo/docs/guides/USER_GUIDE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/guides/USER_GUIDE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/guides/USER_GUIDE.md)
---
🌐 **Languages:** 🇺🇸 [English](../../../../guides/USER_GUIDE.md) · 🇪🇹 [am](../../../am/docs/guides/USER_GUIDE.md) · 🇸🇦 [ar](../../../ar/docs/guides/USER_GUIDE.md) · 🇦🇿 [az](../../../az/docs/guides/USER_GUIDE.md) · 🇧🇬 [bg](../../../bg/docs/guides/USER_GUIDE.md) · 🇧🇩 [bn](../../../bn/docs/guides/USER_GUIDE.md) · 🇧🇦 [bs](../../../bs/docs/guides/USER_GUIDE.md) · 🇨🇿 [cs](../../../cs/docs/guides/USER_GUIDE.md) · 🇩🇰 [da](../../../da/docs/guides/USER_GUIDE.md) · 🇩🇪 [de](../../../de/docs/guides/USER_GUIDE.md) · 🇬🇷 [el](../../../el/docs/guides/USER_GUIDE.md) · 🇪🇪 [et](../../../et/docs/guides/USER_GUIDE.md) · 🇮🇷 [fa](../../../fa/docs/guides/USER_GUIDE.md) · 🇫🇮 [fi](../../../fi/docs/guides/USER_GUIDE.md) · 🇫🇷 [fr](../../../fr/docs/guides/USER_GUIDE.md) · 🇮🇪 [ga](../../../ga/docs/guides/USER_GUIDE.md) · 🇮🇳 [gu](../../../gu/docs/guides/USER_GUIDE.md) · 🇳🇬 [ha](../../../ha/docs/guides/USER_GUIDE.md) · 🇮🇱 [he](../../../he/docs/guides/USER_GUIDE.md) · 🇮🇳 [hi](../../../hi/docs/guides/USER_GUIDE.md) · 🇭🇷 [hr](../../../hr/docs/guides/USER_GUIDE.md) · 🇭🇺 [hu](../../../hu/docs/guides/USER_GUIDE.md) · 🇦🇲 [hy](../../../hy/docs/guides/USER_GUIDE.md) · 🇮🇩 [id](../../../id/docs/guides/USER_GUIDE.md) · 🇳🇬 [ig](../../../ig/docs/guides/USER_GUIDE.md) · 🇮🇹 [it](../../../it/docs/guides/USER_GUIDE.md) · 🇯🇵 [ja](../../../ja/docs/guides/USER_GUIDE.md) · 🇬🇪 [ka](../../../ka/docs/guides/USER_GUIDE.md) · 🇰🇭 [km](../../../km/docs/guides/USER_GUIDE.md) · 🇮🇳 [kn](../../../kn/docs/guides/USER_GUIDE.md) · 🇰🇷 [ko](../../../ko/docs/guides/USER_GUIDE.md) · 🇱🇹 [lt](../../../lt/docs/guides/USER_GUIDE.md) · 🇱🇻 [lv](../../../lv/docs/guides/USER_GUIDE.md) · 🇮🇳 [ml](../../../ml/docs/guides/USER_GUIDE.md) · 🇮🇳 [mr](../../../mr/docs/guides/USER_GUIDE.md) · 🇲🇾 [ms](../../../ms/docs/guides/USER_GUIDE.md) · 🇲🇹 [mt](../../../mt/docs/guides/USER_GUIDE.md) · 🇲🇲 [my](../../../my/docs/guides/USER_GUIDE.md) · 🇳🇵 [ne](../../../ne/docs/guides/USER_GUIDE.md) · 🇳🇱 [nl](../../../nl/docs/guides/USER_GUIDE.md) · 🇳🇴 [no](../../../no/docs/guides/USER_GUIDE.md) · 🇮🇳 [or](../../../or/docs/guides/USER_GUIDE.md) · 🇮🇳 [pa](../../../pa/docs/guides/USER_GUIDE.md) · 🇵🇭 [phi](../../../phi/docs/guides/USER_GUIDE.md) · 🇵🇱 [pl](../../../pl/docs/guides/USER_GUIDE.md) · 🇵🇹 [pt](../../../pt/docs/guides/USER_GUIDE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/guides/USER_GUIDE.md) · 🇷🇴 [ro](../../../ro/docs/guides/USER_GUIDE.md) · 🇷🇺 [ru](../../../ru/docs/guides/USER_GUIDE.md) · 🇱🇰 [si](../../../si/docs/guides/USER_GUIDE.md) · 🇸🇰 [sk](../../../sk/docs/guides/USER_GUIDE.md) · 🇸🇮 [sl](../../../sl/docs/guides/USER_GUIDE.md) · 🇷🇸 [sr](../../../sr/docs/guides/USER_GUIDE.md) · 🇸🇪 [sv](../../../sv/docs/guides/USER_GUIDE.md) · 🇰🇪 [sw](../../../sw/docs/guides/USER_GUIDE.md) · 🇮🇳 [ta](../../../ta/docs/guides/USER_GUIDE.md) · 🇮🇳 [te](../../../te/docs/guides/USER_GUIDE.md) · 🇹🇭 [th](../../../th/docs/guides/USER_GUIDE.md) · 🇹🇷 [tr](../../../tr/docs/guides/USER_GUIDE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/guides/USER_GUIDE.md) · 🇵🇰 [ur](../../../ur/docs/guides/USER_GUIDE.md) · 🇺🇿 [uz](../../../uz/docs/guides/USER_GUIDE.md) · 🇻🇳 [vi](../../../vi/docs/guides/USER_GUIDE.md) · 🇳🇬 [yo](../../../yo/docs/guides/USER_GUIDE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/guides/USER_GUIDE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/guides/USER_GUIDE.md)
Guía completa para configurar proveedores, crear combinaciones, integrar herramientas de CLI e implementar OmniRoute.
---
## Tabla de contenidos
- [Precios de un vistazo](#-pricing-at-a-glance)
- [Casos de uso](#-use-cases)
- [Configuración de proveedores](#-provider-setup)
- [Integración con la CLI](#-cli-integration)
- [Despliegue](#-deployment)
- [Modelos disponibles](#-available-models)
- [Funciones avanzadas](#-advanced-features)
- [Enrutamiento automático (sin configuración)](#-auto-routing-zero-config)
- [Integración con MCP y A2A](#-mcp--a2a-integration)
- [Sistema de habilidades](#-skills-system)
- [Sistema de memoria](#-memory-system)
- [Webhooks](#-webhooks)
- [Agentes en la nube](#-cloud-agents)
- [Gestión programática](#-programmatic-management)
- [CLI interna](#-internal-cli)
- [Aplicación de escritorio (Electron)](#-desktop-application-electron)
---
## 💰 Precios de un vistazo
| Nivel | Proveedor | Coste | Restablecimiento de cuota | Ideal para |
| ------------------- | ----------------- | ------------ | ------------------------------------ | --------------------------------- |
| **💳 SUSCRIPCIÓN** | Claude Code (Pro) | $20/mes | 5 h + semanal | Quienes ya tienen una suscripción |
| | Codex (Plus/Pro) | $20-200/mes | 5 h + semanal | Usuarios de OpenAI |
| | GitHub Copilot | $10-19/mes | Mensual | Usuarios de GitHub |
| **🔑 CLAVE DE API** | DeepSeek | Pago por uso | Ninguno | Razonamiento económico |
| | Groq | Pago por uso | Ninguno | Inferencia ultrarrápida |
| | xAI (Grok) | Pago por uso | Ninguno | Razonamiento con Grok 4 |
| | Mistral | Pago por uso | Ninguno | Modelos alojados en la UE |
| | Perplexity | Pago por uso | Ninguno | Búsqueda aumentada |
| | Together AI | Pago por uso | Ninguno | Modelos de código abierto |
| | Fireworks AI | Pago por uso | Ninguno | Imágenes FLUX rápidas |
| | Cerebras | Pago por uso | Ninguno | Velocidad a escala de oblea |
| | Cohere | Pago por uso | Ninguno | RAG con Command R+ |
| | NVIDIA NIM | Pago por uso | Ninguno | Modelos empresariales |
| | Baidu Qianfan | Pago por uso | Ninguno | Modelos ERNIE |
| **💰 ECONÓMICO** | GLM-4.7 | $0.6/1M | Diariamente a las 10:00 | Alternativa económica |
| | MiniMax M2.1 | $0.2/1M | Ventana móvil de 5 horas | Opción más económica |
| | Kimi K2 | $9/mes fijo | 10M tokens/mes | Coste predecible |
| **🆓 GRATIS** | Qoder | $0 | Se aplican los límites del proveedor | Verificar el catálogo actual |
| | Kiro | $0 | ~50 créditos/mes | Claude gratis |
---
## 🎯 Casos de uso
### Caso 1: "Tengo una suscripción a Claude Pro"
**Problema:** La cuota caduca sin utilizarse y se alcanzan los límites de uso durante sesiones intensivas de programación
```
Combinación: "maximize-claude"
1. cc/claude-opus-4-7 (aprovechar al máximo la suscripción)
2. glm/glm-4.7 (alternativa económica cuando se agota la cuota)
3. if/qwen3.8-max-preview (alternativa gratuita de emergencia)
Coste mensual: $20 (suscripción) + ~$5 (alternativa) = $25 en total
frente a $20 + alcanzar los límites = frustración
```
### Caso 2: "Quiero un coste cero"
**Problema:** No puedo permitirme suscripciones y necesito una IA fiable para programar
```
Combinación: "zero-cost"
1. if/kimi-k2.7-code (acceso gratuito indicado; pueden aplicarse límites de uso)
2. kr/qwen3-coder-next (Kiro como alternativa gratuita)
Coste mensual: $0
Calidad: verifica el modelo, los límites, la privacidad y el SLA para tu carga de trabajo
```
### Caso 3: "Necesito programar las 24 horas del día, los 7 días de la semana, sin interrupciones"
**Problema:** Hay plazos de entrega y no puedo permitirme tiempos de inactividad
```
Combinación: "always-on"
1. cc/claude-opus-4-7 (la mejor calidad)
2. cx/gpt-5.5 (segunda suscripción)
3. glm/glm-4.7 (económico, se restablece diariamente)
4. minimax/MiniMax-M2.1 (el más económico, se restablece cada 5 h)
5. if/deepseek-v4-flash (acceso gratuito indicado; pueden aplicarse límites de uso)
Resultado: 5 niveles de respaldo aumentan la resiliencia; no se garantiza la disponibilidad de los proveedores
Coste mensual: $20-200 (suscripciones) + $10-20 (alternativas)
```
### Caso 4: "Quiero IA GRATUITA en OpenClaw"
**Problema:** Necesito un asistente de IA en aplicaciones de mensajería, completamente gratis
```
Combinación: "openclaw-free"
1. if/qwen3.8-max-preview (acceso gratuito indicado; pueden aplicarse límites de uso)
2. if/deepseek-v4-flash (acceso gratuito indicado; pueden aplicarse límites de uso)
3. if/kimi-k2.7-code (acceso gratuito indicado; pueden aplicarse límites de uso)
Coste mensual: $0
Acceso mediante: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
```
---
## 📖 Configuración de proveedores
Para añadir en bloque conexiones con claves de API desde un archivo CSV o JSON, usa **Panel de control → Proveedores → Importar desde archivo**. Las columnas son posicionales (`provider,name,apiKey,baseUrl,priority`); `provider` ya debe existir como proveedor administrado o nodo compatible. Consulta [Importar proveedores desde un archivo CSV o JSON](../providers/CSV-IMPORT.md).
### 🔐 Proveedores por suscripción
#### Claude Code (Pro/Max)
```bash
Panel de control → Proveedores → Conectar Claude Code
→ Inicio de sesión OAuth → Renovación automática del token
→ Seguimiento de la cuota de 5 horas y semanal
Modelos:
cc/claude-opus-4-7
cc/claude-sonnet-4-6
cc/claude-haiku-4-5-20251001
```
**Consejo profesional:** Usa Opus para tareas complejas y Sonnet para obtener mayor velocidad. ¡OmniRoute realiza un seguimiento de la cuota por modelo!
¿No hay un navegador en el host de OmniRoute? Ejecuta `claude setup-token` en cualquier lugar donde se haya iniciado sesión en Claude Code y pega el token válido durante un año en la pestaña **Token de configuración**. Consulta [Claude Code con un token de configuración](../providers/CLAUDE_CODE_SETUP_TOKEN.md).
Las rutas compatibles con Claude y Claude Code conservan el esfuerzo de razonamiento `max` para los modelos Opus y Sonnet. Los modelos Haiku no aceptan el nivel de esfuerzo `max`, por lo que OmniRoute reduce esa solicitud a un presupuesto de razonamiento alto antes de enviarla al proveedor ascendente.
#### OpenAI Codex (Plus/Pro)
```bash
Panel de control → Proveedores → Conectar Codex
→ Inicio de sesión OAuth (puerto 1455)
→ Restablecimiento cada 5 horas y semanal
Modelos:
cx/gpt-5.5
cx/gpt-5.4
cx/gpt-5.3-codex
cx/gpt-5.3-codex-spark
```
#### GitHub Copilot
```bash
Panel de control → Proveedores → Conectar GitHub
→ OAuth mediante GitHub
→ Restablecimiento mensual (el día 1 de cada mes)
Modelos:
gh/gpt-5.5
gh/gpt-5.4
gh/claude-sonnet-4.6
gh/claude-opus-4.7
gh/gemini-3.1-pro-preview
```
### 💰 Proveedores económicos
#### GLM-4.7 (restablecimiento diario, $0.6/1M)
1. Regístrate: [Zhipu AI](https://open.bigmodel.cn)
2. Obtén una clave de API del Coding Plan
3. Panel de control → Añadir clave de API: Proveedor: `glm`, clave de API: `your-key`
**Uso:** `glm/glm-4.7` — **Consejo profesional:** ¡Coding Plan ofrece una cuota 3 veces mayor por 1/7 del coste! Se restablece diariamente a las 10:00 a. m.
#### MiniMax M2.1 (restablecimiento cada 5 h, $0.20/1M)
1. Regístrate: [MiniMax](https://www.minimax.io)
2. Obtén una clave de API → Panel de control → Añadir clave de API
**Uso:** `minimax/MiniMax-M2.1` — **Consejo profesional:** ¡La opción más económica para contextos largos (1M de tokens)!
#### Kimi K2 ($9/mes, tarifa plana)
1. Suscríbete: [Moonshot AI](https://platform.kimi.ai?aff=omniroute)
2. Obtén una clave de API → Panel de control → Añadir clave de API
**Uso:** `kimi/kimi-k2.5` — **Consejo profesional:** ¡La tarifa fija de $9/mes por 10M de tokens equivale a un coste efectivo de $0.90/1M!
#### Baidu Qianfan / ERNIE
1. Regístrate: [Baidu AI Cloud Qianfan](https://cloud.baidu.com/product/wenxinworkshop)
2. Crea una clave de API de Qianfan → Panel de control → Añadir clave de API: Proveedor: `qianfan`
**Uso:** `qianfan/ernie-5.1`, `qianfan/ernie-x1.1` u otro ID de modelo de Qianfan compatible con OpenAI.
### 🆓 Proveedores GRATUITOS
Los proveedores gratuitos sin autenticación tienen un interruptor junto a **No se requiere autenticación** en su página de proveedor. Al desactivarlo, se inhabilita ese proveedor, se elimina de las vistas configurada/compacta de Proveedores y se eliminan sus modelos de `/v1/models`.
#### Qoder (9 modelos GRATUITOS)
```bash
Panel de control → Conectar Qoder → Inicio de sesión OAuth → El acceso está sujeto a los límites actuales del proveedor
Modelos: if/qwen3.8-max-preview, if/qwen3.7-max, if/qwen3.7-plus, if/kimi-k3, if/kimi-k2.7-code, if/glm-5.2, if/deepseek-v4-pro, if/deepseek-v4-flash, if/minimax-m3
```
#### Kiro (Claude GRATIS)
```bash
Panel de control → Conectar Kiro → AWS Builder ID o Google/GitHub → ~50 créditos/mes
Modelos: kr/claude-sonnet-4.5, kr/claude-haiku-4.5
```
---
## 🎨 Combinaciones
Puedes reordenar las tarjetas de combinaciones directamente en **Panel → Combinaciones** arrastrando el control de cada tarjeta. El orden se almacena en SQLite y se restaura al recargar.
### Ejemplo 1: Maximizar suscripción → Respaldo económico
```
Panel → Combinaciones → Crear nueva
Nombre: premium-coding
Modelos:
1. cc/claude-opus-4-7 (Suscripción principal)
2. glm/glm-4.7 (Respaldo económico, $0.6/1M)
3. minimax/MiniMax-M2.7 (Alternativa más barata, $0.3/1M)
Uso en la CLI: premium-coding
```
### Ejemplo 2: Solo gratuitos (coste cero)
```
Nombre: free-combo
Modelos:
1. if/kimi-k2.7-code (acceso gratuito indicado; pueden aplicarse límites del proveedor)
2. kr/qwen3-coder-next (alternativa gratuita de Kiro)
Coste: actualmente figura como $0; los términos y la disponibilidad pueden cambiar
```
---
## 🔧 Integración con la CLI
### Cursor IDE
**Uso de Cursor como cliente de OmniRoute** (enruta el chat de Cursor a través de OmniRoute):
```
Configuración → Modelos → Avanzado:
URL base de la API de OpenAI: http://localhost:20128/v1
Clave de la API de OpenAI: [desde el panel de OmniRoute]
Modelo: cc/claude-opus-4-7
```
**Uso de OmniRoute como proveedor de Cursor** (OmniRoute llama a Cursor como servicio ascendente): se recomienda
**Panel → Proveedores → Cursor → Iniciar sesión con Cursor**. En Docker, consulta
[`docs/providers/CURSOR-DOCKER.md`](../providers/CURSOR-DOCKER.md).
### Claude Code
Edita `~/.claude/settings.json`:
```json
{
"env": {
"ANTHROPIC_BASE_URL": "http://localhost:20128",
"ANTHROPIC_AUTH_TOKEN": "tu-clave-de-api-de-omniroute"
}
}
```
Utiliza aquí el endpoint raíz compatible con Claude. No añadas `/v1` a `ANTHROPIC_BASE_URL`.
### Codex CLI
```bash
export OPENAI_BASE_URL="http://localhost:20128"
export OPENAI_API_KEY="tu-clave-de-api-de-omniroute"
codex "tu instrucción"
```
### OpenClaw
Edita `~/.openclaw/openclaw.json`:
```json
{
"agents": {
"defaults": {
"model": { "primary": "omniroute/if/kimi-k2.7-code" }
}
},
"models": {
"providers": {
"omniroute": {
"baseUrl": "http://localhost:20128/v1",
"apiKey": "tu-clave-de-api-de-omniroute",
"api": "openai-completions",
"models": [{ "id": "if/kimi-k2.7-code", "name": "Kimi K2.7 Code" }]
}
}
}
}
```
**O utiliza el panel:** Herramientas de la CLI → OpenClaw → Configuración automática
### Cline / Continue / RooCode
```
Proveedor: Compatible con OpenAI
URL base: http://localhost:20128/v1
Clave de API: [desde el panel]
Modelo: cc/claude-opus-4-7
```
---
## 🚀 Despliegue
### Instalación global con npm (recomendada)
```bash
npm install -g omniroute
# Crear el directorio de configuración
mkdir -p ~/.omniroute
# Crear el archivo .env (consulta .env.example)
cp .env.example ~/.omniroute/.env
# Iniciar el servidor
omniroute
# O con un puerto personalizado:
omniroute --port 3000
```
La CLI carga automáticamente `.env` desde `~/.omniroute/.env` o `./.env`.
### Modo de bandeja del sistema
Inicia OmniRoute en la bandeja del sistema:
```bash
omniroute serve --tray
```
El comando finaliza una vez que el servidor y la bandeja están listos.
El servidor continúa ejecutándose sin la terminal.
El modo de bandeja es compatible con macOS, Windows y sesiones gráficas de Linux. El modo de bandeja no abre automáticamente el panel.
Utiliza el menú de la bandeja para realizar estas acciones:
- Abrir el panel.
- Abrir `/dashboard/logs`.
- Cambiar el inicio automático.
- Detener OmniRoute.
No combines `--tray` con estas opciones:
- `--daemon`
- `--log`
- `--no-recovery`
Estos modos requieren una gestión de procesos diferente.
Activa el inicio durante el próximo inicio de sesión en la máquina:
```bash
omniroute autostart enable
```
El inicio automático utiliza el modo de bandeja en macOS, Windows y sesiones gráficas de Linux. Linux sin interfaz gráfica utiliza el servicio de usuario existente de systemd.
Desactiva el inicio al iniciar sesión:
```bash
omniroute autostart disable
```
### Desinstalación
Cuando ya no necesites OmniRoute, proporcionamos dos scripts rápidos para realizar una eliminación limpia:
| Comando | Acción |
| ------------------------ | ---------------------------------------------------------------------------------------------------------- |
| `npm run uninstall` | Elimina la aplicación del sistema, pero **conserva tu base de datos y configuraciones** en `~/.omniroute`. |
| `npm run uninstall:full` | Elimina la aplicación Y **borra permanentemente todas las configuraciones, claves y bases de datos**. |
> Nota: Para ejecutar estos comandos, ve a la carpeta del proyecto OmniRoute (si lo clonaste) y ejecútalos. Como alternativa, si lo instalaste globalmente, puedes ejecutar simplemente `npm uninstall -g omniroute`.
### Despliegue en un VPS
```bash
git clone https://github.com/diegosouzapw/OmniRoute.git
cd OmniRoute && npm install && npm run build
export JWT_SECRET="tu-secreto-seguro-cambia-esto"
export INITIAL_PASSWORD="tu-contraseña"
export DATA_DIR="/var/lib/omniroute"
export PORT="20128"
export HOSTNAME="0.0.0.0"
export NODE_ENV="production"
export NEXT_PUBLIC_BASE_URL="http://localhost:20128"
export API_KEY_SECRET="secreto-de-clave-de-api-del-proxy-del-endpoint"
npm run start
# O: pm2 start npm --name omniroute -- start
```
### Despliegue con PM2 (poca memoria)
Para servidores con RAM limitada, utiliza la opción de límite de memoria:
```bash
# Con un límite de 512 MB (predeterminado)
pm2 start npm --name omniroute -- start
# O con un límite de memoria personalizado
OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start
# O utilizando ecosystem.config.js
pm2 start ecosystem.config.js
```
Crea `ecosystem.config.js`:
```javascript
module.exports = {
apps: [
{
name: "omniroute",
script: "npm",
args: "start",
env: {
NODE_ENV: "production",
OMNIROUTE_MEMORY_MB: "512",
JWT_SECRET: "tu-secreto",
INITIAL_PASSWORD: "tu-contraseña",
},
node_args: "--max-old-space-size=512",
max_memory_restart: "300M",
},
],
};
```
### Docker
```bash
# Compilar la imagen (valor predeterminado = runner-cli con codex/claude/droid preinstalados)
docker build -t omniroute:cli .
# Modo portátil (recomendado)
docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli
```
Para usar el modo integrado con el host y binarios de la CLI, consulta la sección de Docker en la documentación principal.
### Void Linux (xbps-src)
Los usuarios de Void Linux pueden empaquetar e instalar OmniRoute de forma nativa mediante el framework de compilación cruzada `xbps-src`. Esto automatiza la compilación independiente de Node.js junto con los enlaces nativos necesarios de `better-sqlite3`.
Ver plantilla de xbps-src
```bash
# Archivo de plantilla para 'omniroute'
pkgname=omniroute
version=3.8.0
revision=1
hostmakedepends="nodejs python3 make"
depends="openssl"
short_desc="Universal AI gateway with smart routing for multiple LLM providers"
maintainer="zenobit "
license="MIT"
homepage="https://github.com/diegosouzapw/OmniRoute"
distfiles="https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz"
checksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b
system_accounts="_omniroute"
omniroute_homedir="/var/lib/omniroute"
export NODE_ENV=production
export npm_config_engine_strict=false
export npm_config_loglevel=error
export npm_config_fund=false
export npm_config_audit=false
do_build() {
# Determinar la arquitectura de CPU de destino para node-gyp
local _gyp_arch
case "$XBPS_TARGET_MACHINE" in
aarch64*) _gyp_arch=arm64 ;;
armv7*|armv6*) _gyp_arch=arm ;;
i686*) _gyp_arch=ia32 ;;
*) _gyp_arch=x64 ;;
esac
# 1) Instalar todas las dependencias, omitiendo los scripts
NODE_ENV=development npm ci --ignore-scripts
# 2) Compilar el paquete independiente de Next.js
npm run build
# 3) Copiar los recursos estáticos en el paquete independiente
cp -r .next/static .next/standalone/.next/static
[ -d public ] && cp -r public .next/standalone/public || true
# 4) Compilar el enlace nativo de better-sqlite3
local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
(cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
# 5) Colocar el enlace compilado en el paquete independiente
local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
mkdir -p "$_bs3_release"
cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
# 6) Eliminar los paquetes de sharp específicos de cada arquitectura
rm -rf .next/standalone/node_modules/@img
# 7) Copiar las dependencias de ejecución de pino omitidas por el análisis estático de Next.js:
for _mod in pino-abstract-transport split2 process-warning; do
cp -r "node_modules/$_mod" .next/standalone/node_modules/
done
}
do_check() {
npm run test:unit
}
do_install() {
vmkdir usr/lib/omniroute/.next
vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
# Evitar que el hook posterior a la instalación elimine los directorios vacíos del enrutador de aplicaciones de Next.js
for _d in \
.next/standalone/.next/server/app/dashboard \
.next/standalone/.next/server/app/dashboard/settings \
.next/standalone/.next/server/app/dashboard/providers; do
touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
done
cat > "${WRKDIR}/omniroute" <<'EOF'
#!/bin/sh
export PORT="${PORT:-20128}"
export DATA_DIR="${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}"
export APP_LOG_TO_FILE="${APP_LOG_TO_FILE:-false}"
mkdir -p "${DATA_DIR}"
exec node /usr/lib/omniroute/.next/standalone/server.js "$@"
EOF
vbin "${WRKDIR}/omniroute"
}
post_install() {
vlicense LICENSE
}
```
### Variables de entorno
| Variable | Valor predeterminado | Descripción |
| --------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `JWT_SECRET` | `omniroute-default-secret-change-me` | Secreto de firma JWT (**cámbielo en producción**) |
| `INITIAL_PASSWORD` | `CHANGEME` | Contraseña para el primer inicio de sesión |
| `DATA_DIR` | `~/.omniroute` | Directorio de datos (base de datos, uso, registros) |
| `PORT` | predeterminado del framework | Puerto del servicio (`20128` en los ejemplos) |
| `HOSTNAME` | predeterminado del framework | Host de enlace (Docker usa `0.0.0.0` de forma predeterminada) |
| `NODE_ENV` | predeterminado del entorno | Establezca `production` para el despliegue |
| `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128` | URL base pública que se muestra en el panel y se expone al servidor (reemplaza la variable heredada `BASE_URL`) |
| `NEXT_PUBLIC_CLOUD_URL` | `https://omniroute.dev` | URL base del endpoint de sincronización en la nube (reemplaza la variable heredada `CLOUD_URL`) |
| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | Secreto HMAC para las claves de API generadas |
| `REQUIRE_API_KEY` | `false` | Exige una clave de API Bearer en `/v1/*` |
| `ALLOW_API_KEY_REVEAL` | `false` | Permite que los usuarios autenticados del panel revelen bajo demanda los valores completos de las claves de API almacenadas |
| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Frecuencia de actualización del servidor para los datos almacenados en caché de límites de proveedores; los botones de actualización de la interfaz siguen activando la sincronización manual |
| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Desactiva las instantáneas automáticas de SQLite antes de escrituras, importaciones o restauraciones; las copias de seguridad manuales siguen funcionando |
| `APP_LOG_TO_FILE` | `true` | Habilita la escritura en disco de los registros de la aplicación y de auditoría |
| `AUTH_COOKIE_SECURE` | `false` | Fuerza el uso de la cookie de autenticación `Secure` (detrás de un proxy inverso HTTPS) |
| `CLOUDFLARED_BIN` | sin establecer | Usa un binario existente de `cloudflared` en lugar de la descarga administrada |
| `CLOUDFLARED_PROTOCOL` | `http2` | Transporte para los Quick Tunnels administrados (`http2`, `quic` o `auto`) |
| `OMNIROUTE_MEMORY_MB` | `512` | Límite del heap de Node.js en MB |
| `PROMPT_CACHE_MAX_SIZE` | `50` | Número máximo de entradas en la caché de prompts |
| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Número máximo de entradas en la caché semántica |
Para consultar la referencia completa de variables de entorno, consulte el [README](../README.md).
---
## 📊 Modelos disponibles
Ver todos los modelos disponibles
> La siguiente lista se ha seleccionado a partir de `open-sse/config/providerRegistry.ts` para v3.8.0. Los catálogos en la nube (Gemini, OpenRouter, etc.) se sincronizan dinámicamente; para consultar el catálogo completo y actualizado, abre **Panel → Proveedores → [proveedor] → Modelos disponibles** o llama a `GET /api/models/catalog`.
>
> Si la lista integrada de un proveedor ha quedado desactualizada, usa **Importar desde /models** en esa página (o activa la **Sincronización automática**) para obtener el catálogo actualizado del servicio de origen. Esto se verificó en v3.8.50 para LLM7.io (`gemini-3.1-flash-lite`) y UncloseAI (`solidrust/Hermes-3-Llama-3.1-8B-AWQ`); el acceso anónimo a Pollinations siguió sujeto a las limitaciones del servicio de origen durante la misma ronda de pruebas.
**Claude Code (`cc/`)** — OAuth Pro/Max: `cc/claude-opus-4-8`, `cc/claude-opus-4-7`, `cc/claude-opus-4-6`, `cc/claude-opus-4-5-20251101`, `cc/claude-sonnet-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
**Codex (`cx/`)** — OAuth Plus/Pro: `cx/gpt-5.5` (+ niveles de esfuerzo: `gpt-5.5-xhigh`, `gpt-5.5-high`, `gpt-5.5-medium`, `gpt-5.5-low`), `cx/gpt-5.4`, `cx/gpt-5.4-mini`, `cx/gpt-5.3-codex`, `cx/gpt-5.3-codex-spark`
**GitHub Copilot (`gh/`)** — OAuth: `gh/gpt-5.5`, `gh/gpt-5.4`, `gh/gpt-5.4-mini`, `gh/gpt-5-mini`, `gh/gpt-5.3-codex`, `gh/claude-opus-4.7`, `gh/claude-opus-4.6`, `gh/claude-opus-4-5-20251101`, `gh/claude-sonnet-4.6`, `gh/claude-sonnet-4.5`, `gh/claude-haiku-4.5`, `gh/gemini-3.1-pro-preview`, `gh/gemini-3-flash-preview`, `gh/oswe-vscode-prime`
**Kiro (`kr/`)** — OAuth GRATUITO: usa el catálogo actualizado que aparece en **Panel → Proveedores → Kiro → Modelos disponibles**. La disponibilidad depende de la cuenta y del plan.
**Qoder (`if/`)** — OAuth GRATUITO: `if/qwen3.8-max-preview`, `if/qwen3.7-max`, `if/qwen3.7-plus`, `if/kimi-k3`, `if/kimi-k2.7-code`, `if/glm-5.2`, `if/deepseek-v4-pro`, `if/deepseek-v4-flash`, `if/minimax-m3`
**GLM (`glm/`, `glm-cn/`, `zai/`, `glmt/`)** — $0.2–0.6/1M: `glm/glm-5.1`, `glm/glm-5`, `glm/glm-5-turbo`, `glm/glm-4.7`, `glm/glm-4.7-flash`, `glm/glm-4.6`, `glm/glm-4.6v`, `glm/glm-4.5`, `glm/glm-4.5v`, `glm/glm-4.5-air`
**MiniMax (`minimax/`, `minimax-cn/`)** — $0.2/1M: `minimax/MiniMax-M2.7`, `minimax/MiniMax-M2.7-highspeed`, `minimax/MiniMax-M2.5`, `minimax/MiniMax-M2.5-highspeed`
**Kimi (`kimi/`, `kimi-coding/`, `kimi-coding-apikey/`)** — $9/mes, tarifa plana o por uso: `kimi/kimi-k2.6`, `kimi/kimi-k2.5`
**DeepSeek (`ds/`)** — Clave de API: `ds/deepseek-v4-pro`, `ds/deepseek-v4-flash`
**Groq (`groq/`)** — Ultrarrápido: `groq/llama-3.3-70b-versatile`, `groq/meta-llama/llama-4-maverick-17b-128e-instruct`, `groq/qwen/qwen3-32b`, `groq/openai/gpt-oss-120b`
**xAI (`xai/`)** — Grok nativo: `xai/grok-4.3`, `xai/grok-4.20-multi-agent-0309`, `xai/grok-4.20-0309-reasoning`, `xai/grok-4.20-0309-non-reasoning`
**Mistral (`mistral/`)** — Alojado en la UE: `mistral/mistral-large-latest`, `mistral/mistral-medium-3-5`, `mistral/mistral-small-latest`, `mistral/devstral-latest`, `mistral/codestral-latest`
**Perplexity (`pplx/`)** — Ampliado con búsqueda: `pplx/sonar-deep-research`, `pplx/sonar-reasoning-pro`, `pplx/sonar-pro`, `pplx/sonar`
**Together AI (`together/`)** — Código abierto: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo-Free` (gratuito), `together/meta-llama/Llama-Vision-Free`, `together/deepseek-ai/DeepSeek-R1-Distill-Llama-70B-Free`, `together/deepseek-ai/DeepSeek-R1`, `together/Qwen/Qwen3-235B-A22B`, `together/meta-llama/Llama-4-Maverick-17B-128E-Instruct-FP8`
**Fireworks AI (`fireworks/`)** — Inferencia rápida: `fireworks/accounts/fireworks/models/kimi-k2p6`, `fireworks/accounts/fireworks/models/minimax-m2p7`, `fireworks/accounts/fireworks/models/qwen3p6-plus`, `fireworks/accounts/fireworks/models/glm-5p1`, `fireworks/accounts/fireworks/models/deepseek-v4-pro`
**Cerebras (`cerebras/`)** — A escala de oblea: `cerebras/zai-glm-4.7`, `cerebras/gpt-oss-120b`
**Cohere (`cohere/`)** — Centrado en RAG: `cohere/command-a-reasoning-08-2025`, `cohere/command-a-vision-07-2025`, `cohere/command-a-03-2025`, `cohere/command-r-08-2024`
**NVIDIA NIM (`nvidia/`)** — Empresarial: `nvidia/z-ai/glm-5.1`, `nvidia/minimaxai/minimax-m2.7`, `nvidia/google/gemma-4-31b-it`, `nvidia/mistralai/mistral-small-4-119b-2603`, `nvidia/mistralai/mistral-large-3-675b-instruct-2512`, `nvidia/qwen/qwen3.5-397b-a17b`, `nvidia/deepseek-ai/deepseek-v4-pro`, `nvidia/openai/gpt-oss-120b`, `nvidia/nvidia/nemotron-3-super-120b-a12b`
**Baidu Qianfan (`qianfan/`)** — ERNIE: `qianfan/ernie-5.1`, `qianfan/ernie-5.0-thinking-latest`, `qianfan/ernie-x1.1`
**Ollama Cloud (`ollama-cloud/`)**: `ollama-cloud/deepseek-v4-pro`, `ollama-cloud/deepseek-v4-flash`, `ollama-cloud/kimi-k2.6`, `ollama-cloud/glm-5.1`, `ollama-cloud/minimax-m2.7`, `ollama-cloud/gemma4:31b`, `ollama-cloud/qwen3.5:397b`
**Gemini (Google Cloud `gemini/`)**: Se sincroniza en tiempo real desde Google para cada clave de API; no hay una lista estática. Conecta una clave en **Panel → Proveedores** y, a continuación, usa **Modelos disponibles** para importar el catálogo actual (p. ej., `gemini/gemini-3-pro`, `gemini/gemini-3-flash`).
**Otros proveedores compatibles** (selección): `cohere`, `databricks`, `snowflake`, `together`, `vertex`, `alibaba`, `alibaba-cn`, `bedrock` (mediante `aws-bedrock`), `azure-ai`, `openrouter` (catálogo de paso directo), `siliconflow`, `hyperbolic`, `huggingface`, `featherless-ai`, `cloudflare-ai`, `scaleway`, `deepinfra`, `vercel-ai-gateway`, `bazaarlink`, `friendliai`, `nous-research`, `reka`, `volcengine`, `ai21`, `gigachat`. Cada uno mantiene su propia lista de modelos en `providerRegistry.ts` y puede sincronizarse automáticamente cuando el proveedor ofrece un endpoint `/models`.
**Nota sobre los ID de modelo:** OmniRoute utiliza los ID nativos del proveedor (`claude-opus-4-8`, `gpt-5.5`, `glm-5.1`, `MiniMax-M2.7`, `kimi-k2.5`, `grok-4.20-0309-reasoning`). Algunos ID incluyen versiones con puntos porque así los espera la API de origen. Si un modelo no aparece en la lista anterior, ejecuta `omniroute models --search ` o consulta `GET /api/models/catalog` para confirmar su disponibilidad.
---
## 🧩 Funciones avanzadas
### Modelos personalizados
Añade cualquier ID de modelo a cualquier proveedor sin esperar a una actualización de la aplicación:
```bash
# Mediante la API
curl -X POST http://localhost:20128/api/provider-models \
-H "Content-Type: application/json" \
-d '{"provider": "openai", "modelId": "gpt-5.2", "modelName": "GPT-5.2"}'
# Listar: curl http://localhost:20128/api/provider-models?provider=openai
# Eliminar: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-5.2"
```
También puedes usar el panel: **Proveedores → [Proveedor] → Modelos personalizados**.
Notas:
- Los proveedores compatibles con OpenRouter y OpenAI/Anthropic se gestionan únicamente desde **Modelos disponibles**. La adición manual, la importación y la sincronización automática terminan en la misma lista de modelos disponibles, por lo que no existe una sección independiente de Modelos personalizados para esos proveedores.
- La sección **Modelos personalizados** está destinada a proveedores que no ofrecen importaciones gestionadas de modelos disponibles.
### Proveedores personalizados compatibles con OpenAI
Cualquier gateway que utilice la API de OpenAI (un proxy autoalojado, vLLM o un agregador de terceros)
puede añadirse como su propio nodo de proveedor:
1. **Proveedores → Añadir compatible con OpenAI**.
2. **Nombre**: una etiqueta para mostrar que identifica el nodo.
3. **Prefijo**: el nombre de enrutamiento. Los clientes llaman a los modelos como `/`, por lo que un nodo con
el prefijo `mygw` ofrece `mygw/gpt-4o-mini`. Es obligatorio; no hay restricciones de caracteres.
4. **Tipo de API**: la familia de endpoints que ofrece el gateway (finalizaciones de chat, respuestas,
embeddings, audio e imágenes).
5. **URL base**: la raíz de la API, hasta `/v1` incluido (por ejemplo,
`https://gateway.example.com/v1`), no la ruta completa `/chat/completions`. Los gateways con
rutas no estándar deben configurarlas en **Configuración avanzada** (ruta de chat, ruta de modelos).
6. El campo **Clave de API (para la comprobación)** solo comprueba la conexión. Después de crear el nodo,
ábrelo y usa **Añadir conexión** para guardar la clave que utilizarán las solicitudes.
El nodo obtiene un ID interno con el formato `openai-compatible--`; nunca
necesitas escribirlo, ya que el prefijo es el nombre público.
#### Prefijos reservados
Un prefijo no puede ser el ID ni un alias de un proveedor integrado (por ejemplo, `openai`, `cf`), ni
el ID de un proveedor retirado. El sistema de resolución de modelos comprueba los ID y alias integrados antes que
los nodos personalizados, por lo que un nodo que utilizara uno de esos prefijos nunca recibiría tráfico:
`/model` se dirigiría al proveedor integrado o se bloquearía si ese proveedor
se hubiera retirado. La creación o edición de un nodo con uno de esos prefijos se rechaza con:
```text
prefix: "" es un prefijo de proveedor reservado — elige un prefijo diferente (los ID/alias reservados no pueden utilizarse para nodos personalizados porque las solicitudes como /model se dirigen a un proveedor integrado o se bloquean cuando este se retira)
```
Elige un prefijo distinto (`mygw`, `acme-proxy`). Si las solicitudes a un nodo personalizado fallan con un
error que menciona a un proveedor integrado o sus credenciales, comprueba si el prefijo del nodo está
reservado: los nodos guardados antes de que existiera esta regla siguen almacenados, pero su prefijo dirige el tráfico
al proveedor integrado. Edita el nodo y asígnale un nuevo prefijo.
### Encadenamiento de pares de OmniRoute
Se puede añadir otro gateway OmniRoute como proveedor **Personalizado compatible con OpenAI**. Usa la
URL base `/v1` del par y una clave de API dedicada con privilegios mínimos emitida por ese par.
Para cadenas recíprocas o de varios saltos, activa la protección contra bucles opcional en cada gateway:
```bash
# gateway-a
OMNIROUTE_INSTANCE_ID=gateway-a
OMNIROUTE_PEER_URLS=http://gateway-b:20128/v1
OMNIROUTE_PEER_MAX_HOPS=4
```
```bash
# gateway-b
OMNIROUTE_INSTANCE_ID=gateway-b
OMNIROUTE_PEER_URLS=http://gateway-a:20128/v1
OMNIROUTE_PEER_MAX_HOPS=4
```
Solo las solicitudes enviadas a una URL de par incluida explícitamente en la lista de permitidas reciben el
encabezado `X-OmniRoute-Peer-Trace`. Un gateway rechaza un ID de instancia repetido o un presupuesto de saltos
agotado con HTTP `508 Loop Detected`; los proveedores ascendentes normales no reciben metadatos del par.
El encadenamiento de pares no es replicación de base de datos ni conmutación por error del host. Cada gateway mantiene de forma independiente
su estado de SQLite, cachés, contadores de límites y sesiones. Usa un proxy inverso con comprobaciones de estado o conmutación
por error en el cliente para lograr disponibilidad activa/pasiva o activa/activa, y nunca montes una misma base de datos SQLite
en varias instancias de OmniRoute en ejecución.
### Rutas dedicadas de proveedores
Dirige las solicitudes directamente a un proveedor específico con validación del modelo:
```bash
POST http://localhost:20128/v1/providers/openai/chat/completions
POST http://localhost:20128/v1/providers/openai/embeddings
POST http://localhost:20128/v1/providers/fireworks/images/generations
```
El prefijo del proveedor se añade automáticamente si falta. Los modelos que no coincidan devuelven `400`.
### Configuración del proxy de red
```bash
# Establecer el proxy global
curl -X PUT http://localhost:20128/api/settings/proxy \
-d '{"global": {"type":"http","host":"proxy.example.com","port":"8080"}}'
# Proxy por proveedor
curl -X PUT http://localhost:20128/api/settings/proxy \
-d '{"providers": {"openai": {"type":"socks5","host":"proxy.example.com","port":"1080"}}}'
# Probar el proxy
curl -X POST http://localhost:20128/api/settings/proxy/test \
-d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}'
```
**Precedencia:** Específica de la clave → Específica del combo → Específica del proveedor → Global → Entorno.
### API del catálogo de modelos
```bash
curl http://localhost:20128/api/models/catalog
```
Devuelve los modelos agrupados por proveedor con sus tipos (`chat`, `embedding`, `image`).
### Sincronización en la nube
- Sincroniza proveedores, combos y configuraciones entre dispositivos
- Sincronización automática en segundo plano con tiempo de espera y fallo rápido
- En producción, prioriza `NEXT_PUBLIC_BASE_URL`/`NEXT_PUBLIC_CLOUD_URL` del lado del servidor
### Túnel rápido de Cloudflare
- Disponible en **Panel de control → Endpoints** para Docker y otros despliegues autohospedados
- Crea una URL temporal `https://*.trycloudflare.com` que reenvía las solicitudes a tu endpoint `/v1` actual compatible con OpenAI
- La primera activación instala `cloudflared` solo cuando es necesario; los reinicios posteriores reutilizan el mismo binario administrado
- Los túneles rápidos no se restauran automáticamente después de reiniciar OmniRoute o el contenedor; vuelve a activarlos desde el panel de control cuando sea necesario
- Las URL de los túneles son efímeras y cambian cada vez que detienes o inicias el túnel
- Los túneles rápidos administrados utilizan de forma predeterminada el transporte HTTP/2 para evitar los molestos avisos sobre el búfer UDP de QUIC en contenedores con recursos limitados
- Establece `CLOUDFLARED_PROTOCOL=quic` o `auto` si deseas reemplazar la opción de transporte administrado
- Establece `CLOUDFLARED_BIN` si prefieres utilizar un binario `cloudflared` preinstalado en lugar de la descarga administrada
- Los paneles de Cloudflare Quick Tunnel, Tailscale Funnel y ngrok Tunnel se pueden mostrar u ocultar en **Configuración → Apariencia**. Ocultar un panel no detiene un túnel en ejecución.
### Inteligencia de la puerta de enlace LLM (Fase 9)
- **Caché semántica** — Almacena automáticamente en caché las respuestas sin streaming y con temperature=0 (omite la caché con `X-OmniRoute-No-Cache: true`)
- **Idempotencia de solicitudes** — Deduplica las solicitudes realizadas en un intervalo de 5 s mediante el encabezado `Idempotency-Key` o `X-Request-Id`
- **Seguimiento del progreso** — Eventos SSE `event: progress` opcionales mediante el encabezado `X-OmniRoute-Progress: true`
---
### Entorno de pruebas del traductor
Accede mediante **Panel de control → Traductor**. Depura y visualiza cómo OmniRoute traduce las solicitudes de API entre proveedores.
| Modo | Propósito |
| ---------------------- | ------------------------------------------------------------------------------------------------------------ |
| **Entorno de pruebas** | Selecciona los formatos de origen y destino, pega una solicitud y consulta de inmediato la salida traducida |
| **Probador de chat** | Envía mensajes de chat en vivo a través del proxy e inspecciona el ciclo completo de solicitud y respuesta |
| **Banco de pruebas** | Ejecuta pruebas por lotes con varias combinaciones de formatos para verificar que la traducción sea correcta |
| **Monitor en vivo** | Observa las traducciones en tiempo real a medida que las solicitudes pasan por el proxy |
**Casos de uso:**
- Depurar por qué falla una combinación específica de cliente y proveedor
- Verificar que las etiquetas de razonamiento, las llamadas a herramientas y los prompts del sistema se traduzcan correctamente
- Comparar las diferencias de formato entre OpenAI, Claude, Gemini y los formatos de Responses API
---
### Estrategias de enrutamiento
Configúralas mediante **Panel de control → Configuración → Enrutamiento**. El panel de control muestra las seis estrategias más utilizadas; las combinaciones y el enrutador automático admiten internamente un conjunto más amplio.
**Estrategias visibles en el panel de control (enrutamiento a nivel de cuenta):**
| Estrategia | Descripción |
| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
| **Llenar primero** | Utiliza las cuentas por orden de prioridad: la cuenta principal gestiona todas las solicitudes hasta que deja de estar disponible |
| **Round Robin** | Alterna entre todas las cuentas con un límite de afinidad configurable (valor predeterminado: 3 llamadas por cuenta) |
| **P2C (Potencia de dos elecciones)** | Elige 2 cuentas al azar y enruta a la más saludable, equilibrando la carga según su estado |
| **Aleatoria** | Selecciona aleatoriamente una cuenta para cada solicitud mediante el algoritmo de mezcla Fisher-Yates |
| **Menos utilizada** | Enruta a la cuenta con la marca de tiempo `lastUsedAt` más antigua, distribuyendo el tráfico uniformemente |
| **Optimizada por coste** | Enruta a la cuenta con el valor de prioridad más bajo, optimizando el uso de los proveedores de menor coste |
**Estrategias avanzadas de combinación y automáticas** (configurables por combinación o mediante prefijos `auto/*`; consulta [AUTO-COMBO.md](../routing/AUTO-COMBO.md)):
- `priority` — orden estricto, sin alternancia Round Robin
- `weighted` — distribución proporcional del tráfico según los pesos de cada modelo
- `fill-first` — utiliza el primer modelo hasta alcanzar sus límites
- `round-robin` / `strict-random` / `random`
- `p2c` (Potencia de dos elecciones)
- `least-used` y `cost-optimized`
- `auto` — basado en puntuaciones entre todos los candidatos
- `lkgp` (Último proveedor válido conocido) — fija el último proveedor que respondió correctamente y, después, recurre a las reglas
- `context-optimized` — elige el modelo con la mayor ventana de contexto disponible
- `context-relay` — encadena modelos de contexto largo para los turnos de seguimiento
#### Encabezado externo de sesión con afinidad
Para establecer afinidad con una sesión externa (por ejemplo, agentes de Claude Code/Codex detrás de proxies inversos), envía:
```http
X-Session-Id: your-session-key
```
OmniRoute también acepta `x_session_id` y devuelve la clave de sesión efectiva en `X-OmniRoute-Session-Id`.
Si utilizas Nginx y envías encabezados con guiones bajos, habilita:
```nginx
underscores_in_headers on;
```
#### Alias de modelos con comodines
Crea patrones con comodines para reasignar nombres de modelos:
```
Patrón: claude-sonnet-* → Destino: cc/claude-sonnet-4-6
Patrón: gpt-* → Destino: gh/gpt-5.3-codex
```
Los comodines admiten `*` (cualquier número de caracteres) y `?` (un solo carácter).
#### Cadenas de respaldo
Define cadenas de respaldo globales que se apliquen a todas las solicitudes:
```
Cadena: production-fallback
1. cc/claude-opus-4-7
2. gh/gpt-5.3-codex
3. glm/glm-4.7
```
---
### Combinaciones habituales de proveedores y patrones de enrutamiento
Estos son algunos patrones de ejemplo para combinar varios proveedores y enrutar las solicitudes entre ellos en OmniRoute:
#### 1. Combinación para agentes de programación: razonamiento avanzado con respaldo de coste/velocidad
Ideal para agentes de programación (OpenCode, Claude Code, Cursor, Cline). Enruta inicialmente a modelos de razonamiento de vanguardia y recurre a modelos de programación rápidos cuando se agota la cuota o se producen errores.
- **Panel de control**: Combinaciones → Nueva combinación → Nombre: `agent-coding` → Estrategia: `Prioridad`
- **Modelos**:
1. `claude/claude-sonnet-4-6` (Agente de programación principal)
2. `openai/gpt-4o` (Respaldo secundario de alta capacidad)
3. `deepseek/deepseek-v4-flash` (Respaldo de alta eficiencia y rentable)
```bash
# Ejemplo mediante API
curl -X POST http://localhost:20128/api/combos \
-H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "agent-coding",
"strategy": "priority",
"models": [
{ "model": "claude/claude-sonnet-4-6" },
{ "model": "openai/gpt-4o" },
{ "model": "deepseek/deepseek-v4-flash" }
]
}'
```
#### 2. Combo de conmutación por error automática con niveles gratuitos
Encadena varios proveedores con niveles gratuitos y sin claves para maximizar el tiempo de actividad sin costes de API.
- **Estrategia**: `Least Used` o `Round Robin` (distribuye la carga entre las cuotas)
- **Modelos**:
1. `groq/llama-3.3-70b-versatile`
2. `gemini/gemini-2.5-flash`
3. `cerebras/gpt-oss-120b`
```bash
# Ejemplo mediante CLI
omniroute combo create free-stack \
--models "groq/llama-3.3-70b-versatile,gemini/gemini-2.5-flash,cerebras/gpt-oss-120b" \
--strategy round-robin
```
#### 3. Canalización multimodal / de visión y texto
Combina modelos de visión especializados con generación de texto de alta velocidad para flujos de trabajo que impliquen comprensión de imágenes y generación de código.
- **Patrón**: Un combo `Priority` que enumera primero los modelos con capacidad de visión y, al final, un modelo de texto/código de alto rendimiento.
- **Modelos**:
1. `gemini/gemini-2.5-pro` (Sólida comprensión de imágenes y contenido multimodal)
2. `openai/gpt-4o` (Uso equilibrado de visión y herramientas)
3. `deepseek/deepseek-v4-flash` (Generación de texto/código)
---
### Resiliencia y disyuntores
Configúrelos mediante **Panel de control → Configuración → Resiliencia**.
OmniRoute implementa resiliencia a nivel de proveedor mediante cinco componentes:
1. **Cola y cadencia de solicitudes** — Regulación de solicitudes a nivel del sistema:
- **Solicitudes por minuto (RPM)** — Número máximo de solicitudes por minuto y por cuenta
- **Tiempo mínimo entre solicitudes** — Intervalo mínimo en milisegundos entre solicitudes
- **Máximo de solicitudes simultáneas** — Número máximo de solicitudes simultáneas por cuenta
2. **Tiempo de espera de la conexión** — Configuración por tipo de autenticación para una única conexión tras errores reintentables:
- **Tiempo de espera base** — Ventana de espera predeterminada para errores reintentables del servicio ascendente
- **Usar indicaciones de reintento del servicio ascendente** — Respeta las indicaciones autoritativas de `Retry-After` o de restablecimiento cuando se proporcionan
- **Máximo de pasos de espera exponencial** — Nivel máximo de espera exponencial para errores repetidos
3. **Disyuntor del proveedor** — Registra los errores integrales del proveedor, marca al proveedor como degradado al alcanzar el umbral de advertencia configurado y abre el disyuntor cuando se alcanza el umbral de errores configurado:
- **Umbral de degradación** — Errores consecutivos del proveedor antes de entrar en `DEGRADED`
- **Umbral de errores** — Errores consecutivos del proveedor antes de entrar en `OPEN`
- **Tiempo de espera para el restablecimiento** — Intervalo antes de volver a probar el proveedor
- **CLOSED** (Correcto) — Las solicitudes fluyen con normalidad
- **DEGRADED** — Las solicitudes siguen fluyendo mientras se registran los errores elevados
- **OPEN** — El proveedor se bloquea temporalmente tras errores repetidos
- **HALF_OPEN** — Se comprueba si el proveedor se ha recuperado
Los límites de frecuencia `429` específicos de una conexión permanecen en **Tiempo de espera de la conexión** y no se contabilizan en el disyuntor del proveedor.
El estado de ejecución del disyuntor del proveedor solo se muestra en **Panel de control → Estado**.
4. **Esperar a que finalice el tiempo de espera** — Si todas las conexiones candidatas ya están en espera, OmniRoute puede esperar a que finalice el primer tiempo de espera y reintentar automáticamente la misma solicitud del cliente.
5. **Detección automática de límites de frecuencia** — Cuando los proveedores ascendentes devuelven ventanas de espera explícitas, estas indicaciones sustituyen el tiempo de espera local de la conexión si la opción está habilitada.
**Consejo profesional:** Utilice la página **Estado** para inspeccionar y restablecer los disyuntores activos de los proveedores después de una interrupción. La página Resiliencia solo modifica la configuración.
---
### Exportación/importación de la base de datos
Administre las copias de seguridad de la base de datos en **Panel de control → Configuración → Sistema y almacenamiento**.
| Acción | Descripción |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Exportar base de datos** | Descarga la base de datos SQLite actual como un archivo `.sqlite` |
| **Exportar todo (.tar.gz)** | Descarga un archivo de copia de seguridad completo que incluye: base de datos, configuración, combos, conexiones de proveedores (sin credenciales) y metadatos de claves de API |
| **Importar base de datos** | Carga un archivo `.sqlite` para sustituir la base de datos actual. Se crea automáticamente una copia de seguridad previa a la importación, salvo que `DISABLE_SQLITE_AUTO_BACKUP=true` |
```bash
# API: Exportar la base de datos
curl -o backup.sqlite http://localhost:20128/api/db-backups/export
# API: Exportar todo (archivo completo)
curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll
# API: Importar la base de datos
curl -X POST http://localhost:20128/api/db-backups/import \
-F "file=@backup.sqlite"
```
**Validación de la importación:** Se valida la integridad del archivo importado (comprobación pragma de SQLite), las tablas requeridas (`provider_connections`, `provider_nodes`, `combos`, `api_keys`) y el tamaño (máximo de 100 MB).
**Casos de uso:**
- Migrar OmniRoute entre máquinas
- Crear copias de seguridad externas para la recuperación ante desastres
- Compartir configuraciones entre miembros del equipo (exportar todo → compartir el archivo)
---
### Panel de configuración
La página de configuración está organizada en **7 pestañas** para facilitar la navegación:
| Pestaña | Contenido |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **General** | Herramientas de almacenamiento del sistema, comportamiento predeterminado, visibilidad de túneles de endpoints |
| **Apariencia** | Controles de tema (claro/oscuro/sistema), visibilidad de la barra lateral, controles de panel para las tarjetas de túneles de Cloudflare/Tailscale/ngrok |
| **IA** | Presupuesto de razonamiento (transferencia directa / eliminación automática / personalizado / adaptativo; consulta [THINKING_BUDGET.md](./THINKING_BUDGET.md)), prompt global del sistema, estadísticas de caché de prompts |
| **Seguridad** | Configuración de inicio de sesión/contraseña, control de acceso por IP, autenticación de API para `/models`, bloqueo de proveedores, protección contra inyección de prompts |
| **Enrutamiento** | Estrategia global de enrutamiento (Completar primero / Round Robin / P2C / Aleatorio / Menos usado / Optimizado por coste), alias de modelos con comodines, cadenas de respaldo, valores predeterminados de combinaciones |
| **Resiliencia** | Cola de solicitudes, periodo de espera de conexión, configuración del disyuntor de proveedores y comportamiento de espera durante el periodo de espera |
| **Avanzado** | Configuración global de proxy (HTTP/SOCKS5), anulaciones de proxy por proveedor |
General ya no duplica las notas de solo lectura sobre registros y caché. La configuración de retención y
optimización de la base de datos se conserva mediante `/api/settings/database`; el borrado manual de la caché utiliza
`DELETE /api/cache`. Los límites de filas de los registros de solicitudes y del proxy se controlan mediante
`CALL_LOGS_TABLE_MAX_ROWS` y `PROXY_LOGS_TABLE_MAX_ROWS`.
---
### Gestión de costes y presupuestos
Accede mediante **Panel → Costes**.
| Pestaña | Propósito |
| --------------- | ---------------------------------------------------------------------------------------------------------------------- |
| **Presupuesto** | Establecer límites de gasto por clave de API con presupuestos diarios/semanales/mensuales y seguimiento en tiempo real |
| **Precios** | Ver y editar entradas de precios de modelos: coste por cada 1.000 tokens de entrada/salida por proveedor |
```bash
# API: Establecer un presupuesto
curl -X POST http://localhost:20128/api/usage/budget \
-H "Content-Type: application/json" \
-d '{"keyId": "key-123", "limit": 50.00, "period": "monthly"}'
# API: Obtener el estado actual del presupuesto
curl http://localhost:20128/api/usage/budget
```
**Seguimiento de costes:** Cada solicitud registra el uso de tokens y calcula el coste mediante la tabla de precios. Consulta los desgloses en **Panel → Uso** por proveedor, modelo y clave de API.
---
### Transcripción de audio
OmniRoute admite la transcripción de audio mediante el endpoint compatible con OpenAI:
```bash
POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data
# Ejemplo con curl
curl -X POST http://localhost:20128/v1/audio/transcriptions \
-H "Authorization: Bearer your-api-key" \
-F "file=@audio.mp3" \
-F "model=openai/whisper-1"
```
`deepgram/nova-3` es la ruta nativa de Deepgram y requiere una clave de API de Deepgram.
Si solo está configurado OpenRouter, utiliza `openrouter/deepgram/nova-3`.
Proveedores de **voz a texto (transcripción)**:
- `openai/` (compatible con Whisper)
- `groq/` (Groq Whisper Turbo)
- `deepgram/` (familia Nova)
- `assemblyai/`
- `nvidia/` (Parakeet, Canary)
- `huggingface/` (variantes de Whisper)
- `qwen/`
Proveedores de **texto a voz (`POST /v1/audio/speech`)**:
- `openai/` (tts-1, tts-1-hd)
- `hyperbolic/`
- `deepgram/` (Aura)
- `nvidia/` (Magpie TTS)
- `elevenlabs/`
- `huggingface/`
- `inworld/`
- `cartesia/`
- `playht/`
- `kie/`
- `aws-polly/`
- `xiaomi-mimo/`
- `coqui/`, `tortoise/`
- `qwen/`
Formatos de audio admitidos para la transcripción: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. Los formatos de salida TTS dependen del proveedor (mp3, wav, opus, pcm, mulaw).
---
### Estrategias de equilibrio de combinaciones
Configura el equilibrio de cada combinación en **Panel → Combinaciones → Crear/Editar → Estrategia**.
| Estrategia | Descripción |
| ------------------------ | ---------------------------------------------------------------------------------------- |
| **Round-Robin** | Rota secuencialmente entre los modelos |
| **Prioridad** | Siempre prueba primero el primer modelo; solo recurre al respaldo si se produce un error |
| **Aleatoria** | Elige un modelo al azar de la combinación para cada solicitud |
| **Ponderada** | Enruta proporcionalmente según los pesos asignados a cada modelo |
| **Menos usado** | Enruta al modelo con menos solicitudes recientes (utiliza métricas de la combinación) |
| **Optimizada por coste** | Enruta al modelo disponible más barato (utiliza la tabla de precios) |
Los valores predeterminados globales de las combinaciones se pueden establecer en **Panel → Configuración → Enrutamiento → Valores predeterminados de combinaciones**.
Los tiempos de espera de los destinos de una combinación heredan de forma predeterminada el tiempo de espera actual de las solicitudes. Utiliza **Tiempo de espera del destino
(segundos)** en los valores predeterminados de las combinaciones o en una combinación individual únicamente cuando un límite más corto por destino deba
activar antes el respaldo.
Las optimizaciones de combinaciones de latencia cero son opcionales. Deja **Optimizaciones de latencia cero** desactivado para
evitar que estas funciones de latencia hagan competir a los destinos de respaldo, omitan destinos según el historial de TTFT
o compriman las solicitudes de respaldo; al activarlo, se permiten la cobertura configurada, las omisiones predictivas por TTFT
y la compresión proactiva de las solicitudes de respaldo para intercambiar fidelidad de enrutamiento/solicitud por una menor
latencia de cola.
Deshabilita el **búfer de tokens de razonamiento** cuando los proveedores upstream requieran límites estrictos de
`max_tokens` / `maxOutputTokens`. Cuando está habilitado, el enrutamiento combinado solo añade margen adicional para modelos de razonamiento
en modelos con un límite de salida conocido y mantiene sin cambios el límite de tokens del cliente cuando el
valor seguro con búfer superaría dicho límite. Si el límite del cliente ya está por encima de un límite conocido,
OmniRoute lo reduce a dicho límite antes de enviar la solicitud upstream.
---
### Panel de estado
Accede mediante **Panel → Estado**. Resumen en tiempo real del estado del sistema con 6 tarjetas:
| Tarjeta | Qué muestra |
| -------------------------- | ---------------------------------------------------------------------------- |
| **Estado del sistema** | Tiempo de actividad, versión, uso de memoria, directorio de datos |
| **Estado del proveedor** | Estado global en tiempo de ejecución del disyuntor de los proveedores |
| **Límites de frecuencia** | Tiempos de espera activos de conexiones por cuenta con el tiempo restante |
| **Bloqueos activos** | Bloqueos activos por modelo y exclusiones temporales |
| **Caché de firmas** | Estadísticas de la caché de deduplicación (claves activas, tasa de aciertos) |
| **Telemetría de latencia** | Agregación de latencia p50/p95/p99 por proveedor |
**Consejo profesional:** La página Estado se actualiza automáticamente cada 10 segundos. Usa la tarjeta del disyuntor para identificar qué proveedores están experimentando problemas.
---
## 🤖 Enrutamiento automático (sin configuración)
OmniRoute incluye un **enrutador automático basado en puntuaciones** que selecciona el mejor modelo para cada solicitud entre todos los proveedores conectados, sin necesidad de mantener ninguna combinación. Solo tienes que enviar la solicitud con uno de los prefijos `auto/*` y OmniRoute creará una combinación virtual al instante, puntuando a los candidatos según la latencia, el coste, la tasa de éxito, la adecuación al contexto, la idoneidad del modelo para la tarea, los fallos recientes, la cuota y el estado del disyuntor.
| Prefijo | Optimiza para |
| -------------- | ------------------------------------------------------------------------------------------------- |
| `auto` | Opción predeterminada equilibrada (latencia × coste × tasa de éxito) |
| `auto/coding` | Tareas de programación: prioriza Claude, GPT-5, GLM, Kimi, Qwen Coder y programadores DeepSeek |
| `auto/cheap` | Menor coste por token; acepta una latencia más alta |
| `auto/fast` | Menor latencia; ignora el coste |
| `auto/offline` | Solo proveedores locales (Ollama, vLLM, llama.cpp), útil para entornos aislados |
| `auto/smart` | Prioriza la calidad del razonamiento (Opus, GPT-5 xhigh, R1, razonamiento de GLM 5.1) |
| `auto/lkgp` | «Último proveedor válido conocido»: fija el último proveedor exitoso y luego recurre a las reglas |
Ejemplo:
```bash
curl -X POST http://localhost:20128/v1/chat/completions \
-H "Authorization: Bearer $OMNIROUTE_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "auto/coding",
"messages": [{ "role": "user", "content": "Refactor this Python function" }],
"stream": true
}'
```
El enrutador automático se describe por completo en [AUTO-COMBO.md](../routing/AUTO-COMBO.md), incluida la forma de ajustar los pesos de puntuación, añadir proveedores a la lista negra e inspeccionar las decisiones de enrutamiento en **Panel de control → Combinación automática**.
---
## 🔌 Integración con MCP y A2A
OmniRoute funciona tanto como **servidor MCP** (Model Context Protocol) como **servidor A2A** (Agent-to-Agent JSON-RPC 2.0). Cualquier IDE o host de agentes compatible con MCP puede invocar directamente las herramientas de OmniRoute, sin necesidad de ningún adaptador adicional.
### Transportes MCP
- **SSE**: `http://localhost:20128/api/mcp/sse`
- **HTTP transmisible**: `http://localhost:20128/api/mcp/stream`
- **stdio**: `omniroute --mcp` (para complementos de IDE que prefieran stdio)
### Conectar Claude Desktop
Edita `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) o el archivo equivalente en Windows/Linux:
```json
{
"mcpServers": {
"omniroute": {
"command": "omniroute",
"args": ["--mcp"]
}
}
}
```
### Conectar Cursor / Continue / VS Code MCP
Usa la URL de SSE `http://localhost:20128/api/mcp/sse` y una clave de API Bearer generada en **Panel de control → Claves de API**.
### Ámbitos
Actualmente, MCP define 32 ámbitos con nombre. Cada clave Bearer puede limitarse a ámbitos específicos; consulta [MCP-SERVER.md](../frameworks/MCP-SERVER.md) para ver el inventario oficial de ámbitos y herramientas, y [A2A-SERVER.md](../frameworks/A2A-SERVER.md) para consultar el esquema JSON-RPC.
---
## 🧠 Sistema de habilidades
OmniRoute ofrece un **framework de habilidades** extensible (`src/lib/skills/`) para que los agentes y el endpoint A2A puedan ejecutar rutinas específicas de un dominio (p. ej., `code-review`, `summarize`, `extract-facts`, `web-research`).
- **Interfaz del marketplace** — Explora e instala habilidades desde **Panel de control → Habilidades**
- **Ámbitos por clave** — Restringe qué claves de API pueden invocar cada habilidad
- **Habilidades personalizadas** — Añade un archivo TypeScript en `src/lib/a2a/skills/`, regístralo y podrá invocarse inmediatamente mediante A2A
Referencia completa: [SKILLS.md](../frameworks/SKILLS.md).
---
## 💾 Sistema de memoria
OmniRoute conserva **memoria conversacional a largo plazo** mediante recuperación híbrida:
- **SQLite FTS5** para buscar por palabras clave en interacciones anteriores
- **Almacén vectorial Qdrant** (opcional) para la recuperación semántica
- **Extracción automática de hechos** — las entidades, preferencias y decisiones se resumen después de cada sesión y se almacenan en la tabla `memory_facts`
- Las memorias están delimitadas por clave de API y por sesión
Gestiona las memorias en **Panel de control → Memoria** (buscar, editar, exportar, purgar). La interfaz HTTP (`/api/memory/*`) permite a los agentes enviar y consultar hechos mediante programación; consulta [MEMORY.md](../frameworks/MEMORY.md).
---
## 🔔 Webhooks
Suscríbete a los eventos de OmniRoute para realizar supervisión y automatización en tiempo real.
- Crea un webhook en **Panel de control → Webhooks** con la URL de destino y el secreto de firma HMAC
- Eventos disponibles: `request.completed`, `request.failed`, `provider.unavailable`, `budget.exceeded`, `combo.switched`, `circuit_breaker.opened`, `circuit_breaker.closed`
- Cada carga útil incluye `X-OmniRoute-Signature` (HMAC-SHA256) para su verificación
- Reintentos: 3 intentos con espera exponencial y, después, envío a la cola de mensajes fallidos
Esquema completo en [WEBHOOKS.md](../frameworks/WEBHOOKS.md).
---
## ☁️ Agentes en la nube
OmniRoute se integra con agentes de programación en la nube (**OpenAI Codex Cloud**, **Devin**, **Jules**, **Antigravity**) para que puedas asignar tareas de larga duración desde el mismo panel de control que gestiona tu enrutamiento local.
- Crea tareas en **Panel de control → Agentes en la nube** o mediante `POST /api/v1/agents/tasks`
- Consulta el estado, los registros y los artefactos de cada tarea
- Usa tu propia clave de API para cada proveedor; las credenciales nunca salen de la instancia de OmniRoute
Referencia completa: [CLOUD_AGENT.md](../frameworks/CLOUD_AGENT.md).
---
## 🛠️ Gestión programática
Puedes gestionar todos los recursos de OmniRoute (proveedores, combos, claves y ajustes) mediante HTTP utilizando una **clave Bearer con el ámbito `manage`**.
Genera la clave en **Panel de control → Claves de API → Nueva clave → Ámbito: manage** y, a continuación:
```bash
# Enumerar proveedores
curl http://localhost:20128/api/providers \
-H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY"
# Añadir una conexión de proveedor
curl -X POST http://localhost:20128/api/providers \
-H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY" \
-H "Content-Type: application/json" \
-d '{ "provider": "openai", "apiKey": "sk-...", "name": "main" }'
# Crear un combo
curl -X POST http://localhost:20128/api/combos \
-H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY" \
-H "Content-Type: application/json" \
-d '{ "name": "premium", "strategy": "priority", "models": [{ "model": "cc/claude-opus-4-7" }, { "model": "glm/glm-5.1" }] }'
# Enumerar/crear claves de API
curl http://localhost:20128/api/keys -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY"
curl -X POST http://localhost:20128/api/keys -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY" \
-d '{ "name": "ci-bot", "scopes": ["chat"] }'
```
Consulta [API_REFERENCE.md](../reference/API_REFERENCE.md) para ver el catálogo completo de endpoints y los esquemas de solicitud/respuesta.
---
## 💻 CLI interna
OmniRoute incluye una CLI interna (`omniroute …`) para la configuración, el diagnóstico y el control en tiempo de ejecución. Esta es **independiente de la página "Herramientas de CLI" del panel**, que configura CLI de terceros (Claude Code, Cursor, Codex, Cline, …) para que puedan comunicarse con OmniRoute.
```bash
omniroute setup # Asistente interactivo (contraseña, proveedores, combinaciones)
omniroute setup --non-interactive # Adecuado para CI
omniroute doctor # Diagnósticos de estado (directorio de datos, BD, proveedores, puertos)
omniroute providers available # Enumera los proveedores compatibles
omniroute providers list # Enumera las conexiones configuradas
omniroute providers test # Prueba en vivo una conexión de proveedor
omniroute combos list # Enumera las combinaciones
omniroute combos switch # Establece la combinación predeterminada
omniroute models # Enumera los modelos disponibles (--json, --search)
omniroute keys add | list | remove # Administra las claves de API desde la terminal
omniroute backup # Crea una instantánea de la configuración y la BD
omniroute restore [] # Restaura desde una instantánea
omniroute health # Estado detallado (disyuntores, caché, memoria)
omniroute quota # Uso de cuota de los proveedores
omniroute mcp status # Estado del servidor MCP
omniroute a2a status # Estado del servidor A2A
omniroute tunnel list|create|stop # Túneles de Cloudflare/Tailscale/ngrok
omniroute reset-password # Restablece la contraseña de administrador
omniroute --mcp # Inicia el servidor MCP mediante stdio
omniroute --port 3000 # Inicia el servidor en un puerto personalizado
```
Consejo: combina `omniroute doctor --json` con tu herramienta de monitorización para recibir alertas sobre conexiones de proveedores que no estén en buen estado.
---
## 🖥️ Aplicación de escritorio (Electron)
OmniRoute está disponible como aplicación de escritorio nativa para Windows, macOS y Linux.
### Instalación
```bash
# Desde el directorio electron:
cd electron
npm install
# Modo de desarrollo (se conecta al servidor de desarrollo de Next.js en ejecución):
npm run dev
# Modo de producción (utiliza la compilación independiente):
npm start
```
### Creación de instaladores
```bash
cd electron
npm run build # Plataforma actual
npm run build:win # Windows (.exe NSIS)
npm run build:mac # macOS (.dmg universal)
npm run build:linux # Linux (.AppImage)
```
Salida → `electron/dist-electron/`
### Características principales
| Característica | Descripción |
| -------------------------------------- | ------------------------------------------------------------------------ |
| **Disponibilidad del servidor** | Consulta el servidor antes de mostrar la ventana (sin pantalla vacía) |
| **Bandeja del sistema** | Minimiza a la bandeja, cambia el puerto y cierra desde su menú |
| **Administración de puertos** | Cambia el puerto desde la bandeja (reinicia el servidor automáticamente) |
| **Política de seguridad de contenido** | CSP restrictiva mediante encabezados de sesión |
| **Instancia única** | Solo puede ejecutarse una instancia de la aplicación a la vez |
| **Modo sin conexión** | El servidor Next.js incluido funciona sin internet |
### Variables de entorno
| Variable | Valor predeterminado | Descripción |
| --------------------- | -------------------- | ---------------------------------------- |
| `OMNIROUTE_PORT` | `20128` | Puerto del servidor |
| `OMNIROUTE_MEMORY_MB` | `512` | Límite del heap de Node.js (64–16384 MB) |
📖 Documentación completa: [`electron/README.md`](../../electron/README.md)