OmniRoute/docs/i18n/es/docs/guides/USER_GUIDE.md

User Guide (Español)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇮🇳 hi · 🇭🇷 hr · 🇭🇺 hu · 🇦🇲 hy · 🇮🇩 id · 🇳🇬 ig · 🇮🇹 it · 🇯🇵 ja · 🇬🇪 ka · 🇰🇭 km · 🇮🇳 kn · 🇰🇷 ko · 🇱🇹 lt · 🇱🇻 lv · 🇮🇳 ml · 🇮🇳 mr · 🇲🇾 ms · 🇲🇹 mt · 🇲🇲 my · 🇳🇵 ne · 🇳🇱 nl · 🇳🇴 no · 🇮🇳 or · 🇮🇳 pa · 🇵🇭 phi · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇱🇰 si · 🇸🇰 sk · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW

---

🌐 Idiomas: 🇺🇸 English | 🇪🇹 አማርኛ | 🇸🇦 العربية | 🇦🇿 Azərbaycan dili | 🇧🇬 Български | 🇧🇩 বাংলা | 🇨🇿 Čeština | 🇩🇰 Dansk | 🇩🇪 Deutsch | 🇬🇷 Ελληνικά | 🇪🇸 Español | 🇪🇪 Eesti | 🇮🇷 فارسی | 🇫🇮 Suomi | 🇫🇷 Français | 🇮🇪 Gaeilge | 🇮🇳 ગુજરાતી | 🇳🇬 Hausa | 🇮🇱 עברית | 🇮🇳 हिन्दी | 🇭🇷 Hrvatski | 🇭🇺 Magyar | 🇦🇲 Հայերեն | 🇮🇩 Bahasa Indonesia | 🇳🇬 Igbo | 🇮🇹 Italiano | 🇯🇵 日本語 | 🇬🇪 ქართული | 🇰🇭 ខ្មែរ | 🇮🇳 ಕನ್ನಡ | 🇰🇷 한국어 | 🇱🇹 Lietuvių | 🇱🇻 Latviešu | 🇮🇳 മലയാളം | 🇮🇳 मराठी | 🇲🇾 Bahasa Melayu | 🇲🇹 Malti | 🇲🇲 မြန်မာ | 🇳🇵 नेपाली | 🇳🇱 Nederlands | 🇳🇴 Norsk | 🇮🇳 ଓଡ଼ିଆ | 🇮🇳 ਪੰਜਾਬੀ | 🇵🇭 Filipino | 🇵🇱 Polski | 🇵🇹 Português (Portugal) | 🇧🇷 Português (Brasil) | 🇷🇴 Română | 🇷🇺 Русский | 🇱🇰 සිංහල | 🇸🇰 Slovenčina | 🇸🇮 Slovenščina | 🇷🇸 Српски | 🇸🇪 Svenska | 🇰🇪 Kiswahili | 🇮🇳 தமிழ் | 🇮🇳 తెలుగు | 🇹🇭 ไทย | 🇹🇷 Türkçe | 🇺🇦 Українська | 🇵🇰 اردو | 🇺🇿 Oʻzbekcha | 🇻🇳 Tiếng Việt | 🇳🇬 Yorùbá | 🇨🇳 中文 (简体) | 🇹🇼 中文 (繁體)

Guía completa para configurar proveedores, crear combinaciones, integrar herramientas de CLI e implementar OmniRoute.

---

Tabla de contenidos

• Precios de un vistazo
• Casos de uso
• Configuración de proveedores
• Integración con la CLI
• Despliegue
• Modelos disponibles
• Funciones avanzadas
• Enrutamiento automático (sin configuración)
• Integración con MCP y A2A
• Sistema de habilidades
• Sistema de memoria
• Webhooks
• Agentes en la nube
• Gestión programática
• CLI interna
• Aplicación de escritorio (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 un 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.

🔐 Proveedores por suscripción

Claude Code (Pro/Max)

Panel de control → Proveedores → Conectar Claude Code
→ Inicio de sesión mediante OAuth → Renovación automática del token
→ Seguimiento de cuotas de 5 horas y semanales

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!

Las rutas compatibles con Claude y Claude Code conservan el esfuerzo de razonamiento max para los modelos Opus y Sonnet. Los modelos Haiku no admiten 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)

Panel de control → Proveedores → Conectar Codex
→ Inicio de sesión mediante 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

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
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: ¡El Coding Plan ofrece una cuota 3 veces mayor por 1/7 del coste! Se restablece diariamente a las 10:00 AM.

MiniMax M2.1 (restablecimiento cada 5 h, $0.20/1M)

1. Regístrate: MiniMax
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 barata para contextos largos (1M de tokens)!

Kimi K2 ($9/mes, tarifa fija)

1. Suscríbete: Moonshot AI
2. Obtén una clave de API → Panel de control → Añadir clave de API

Uso: kimi/kimi-k2.5 — Consejo profesional: ¡$9/mes fijos por 10M de tokens equivalen a un coste efectivo de $0.90/1M!

Baidu Qianfan / ERNIE

1. Regístrate: Baidu AI Cloud Qianfan
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 deshabilita ese proveedor, se elimina de las vistas configurada/compacta de Proveedores y sus modelos se eliminan de /v1/models.

Qoder (9 modelos GRATUITOS)

Panel de control → Conectar Qoder → Inicio de sesión mediante 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)

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.

Claude Code

Edita ~/.claude/settings.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

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:

{
  "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)

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:

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:

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:

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

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:

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

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

# 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

# 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 <zenobit@disroot.org>"
license="MIT"
homepage="https://github.com/diegosouzapw/OmniRoute"
distfiles="https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz"
checksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b
system_accounts="_omniroute"
omniroute_homedir="/var/lib/omniroute"
export NODE_ENV=production
export npm_config_engine_strict=false
export npm_config_loglevel=error
export npm_config_fund=false
export npm_config_audit=false

do_build() {
	# 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.

---

📊 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 <term> 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 una actualización de la aplicación:

# 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 hay una sección independiente de Modelos personalizados para esos proveedores.
• La sección Modelos personalizados está pensada para proveedores que no permiten importaciones gestionadas de modelos disponibles.

Encadenamiento de pares de OmniRoute

Se puede añadir otra puerta de enlace de 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 opcional contra bucles en cada puerta de enlace:

# gateway-a
OMNIROUTE_INSTANCE_ID=gateway-a
OMNIROUTE_PEER_URLS=http://gateway-b:20128/v1
OMNIROUTE_PEER_MAX_HOPS=4

# 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 la cabecera X-OmniRoute-Peer-Trace. Una puerta de enlace rechaza un ID de instancia repetido o un límite de saltos agotado con HTTP 508 Loop Detected; los proveedores ascendentes convencionales no reciben metadatos del par.

El encadenamiento de pares no constituye replicación de bases de datos ni conmutación por error del host. Cada puerta de enlace 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 del cliente para obtener disponibilidad activa/pasiva o activa/activa, y nunca montes una misma base de datos SQLite en varias instancias de OmniRoute en ejecución.

Rutas de proveedor dedicadas

Enruta las solicitudes directamente a un proveedor específico con validación del modelo:

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

# 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ífico de la clave → Específico de la combinación → Específico del proveedor → Global → Entorno.

API del catálogo de modelos

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, combinaciones y ajustes entre dispositivos
• Sincronización automática en segundo plano con tiempo de espera y detención inmediata ante errores
• En producción, da preferencia a NEXT_PUBLIC_BASE_URL/NEXT_PUBLIC_CLOUD_URL del lado del servidor

Túnel rápido de Cloudflare

• Disponible en Panel → Puntos de conexión para Docker y otras implementaciones autoalojadas
• Crea una URL temporal https://*.trycloudflare.com que reenvía al punto de conexión /v1 actual compatible con OpenAI
• La primera activación instala cloudflared solo cuando es necesario; los reinicios posteriores reutilizan el mismo binario gestionado
• Los túneles rápidos no se restauran automáticamente después de reiniciar OmniRoute o el contenedor; vuelve a activarlos desde el panel 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 gestionados usan de forma predeterminada el transporte HTTP/2 para evitar las molestas advertencias sobre el búfer UDP de QUIC en contenedores con recursos limitados
• Establece CLOUDFLARED_PROTOCOL=quic o auto si quieres sobrescribir la opción de transporte gestionada
• Establece CLOUDFLARED_BIN si prefieres usar un binario cloudflared preinstalado en lugar de la descarga gestionada
• Los paneles de Túnel rápido de Cloudflare, Tailscale Funnel y Túnel ngrok se pueden mostrar u ocultar en Ajustes → 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 con temperature=0 (omite la caché con X-OmniRoute-No-Cache: true)
• Idempotencia de solicitudes — Deduplica las solicitudes dentro de un intervalo de 5 s mediante la cabecera Idempotency-Key o X-Request-Id
• Seguimiento del progreso — Eventos SSE opcionales event: progress mediante la cabecera X-OmniRoute-Progress: true

---

Entorno de pruebas del traductor

Accede mediante Panel → Traductor. Depura y visualiza cómo OmniRoute traduce las solicitudes de API entre proveedores.

Modo	Finalidad
Entorno de pruebas	Selecciona los formatos de origen y destino, pega una solicitud y consulta al instante el resultado traducido
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 múltiples combinaciones de formatos para verificar la corrección de la traducción
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 la API Responses

---

Estrategias de enrutamiento

Configúrelo 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
Completar primero	Usa las cuentas según el orden de prioridad: la cuenta principal gestiona todas las solicitudes hasta que deja de estar disponible
Turno rotatorio	Alterna entre todas las cuentas con un límite de afinidad configurable (valor predeterminado: 3 llamadas por cuenta)
P2C (Potencia de dos opciones)	Elige 2 cuentas al azar y enruta a la que esté en mejor estado; equilibra la carga teniendo en cuenta el estado
Aleatoria	Selecciona aleatoriamente una cuenta para cada solicitud mediante el algoritmo de Fisher-Yates
Menos utilizada	Enruta a la cuenta con la marca de tiempo lastUsedAt más antigua, distribuyendo el tráfico de manera uniforme
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/*; consulte AUTO-COMBO.md):

• priority — orden estricto, sin alternancia
• weighted — distribución proporcional del tráfico según los pesos de cada modelo
• fill-first — agota el primer modelo hasta alcanzar los límites
• round-robin / strict-random / random
• p2c (Potencia de dos opciones)
• least-used y cost-optimized
• auto — basada en puntuaciones entre todos los candidatos
• lkgp (Último proveedor conocido como válido) — fija el último proveedor que tuvo éxito y, después, recurre a las reglas
• context-optimized — elige el modelo con la mayor ventana de contexto libre
• context-relay — encadena modelos de contexto amplio para los turnos de seguimiento

Encabezado externo de sesión persistente

Para establecer afinidad de sesión externa (por ejemplo, para agentes de Claude Code/Codex detrás de proxies inversos), envíe:

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 utiliza Nginx y envía encabezados con guiones bajos, habilite:

underscores_in_headers on;

Alias de modelos con comodines

Cree 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 carácter) y ? (un solo carácter).

Cadenas de respaldo

Defina 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

---

Resiliencia y disyuntores

Configúrelo mediante Panel de control → Configuración → Resiliencia.

OmniRoute implementa resiliencia a nivel de proveedor mediante cinco componentes:

1. Cola y regulación de solicitudes — Control 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 después de errores que permiten reintentos:

   • Tiempo de espera base — Intervalo predeterminado de espera ante errores ascendentes que permiten reintentos
   • Usar indicaciones de reintento del servicio ascendente — Respeta Retry-After u otras indicaciones fiables de restablecimiento cuando se proporcionan
   • Máximo de pasos de espera incremental — Nivel máximo de espera exponencial para errores repetidos

3. Disyuntor del proveedor — Supervisa los errores del proveedor de extremo a extremo, marca un 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 — Número de errores consecutivos del proveedor antes de entrar en DEGRADED
   • Umbral de errores — Número de errores consecutivos del proveedor antes de entrar en OPEN
   • Tiempo de espera para el restablecimiento — Intervalo antes de volver a probar el proveedor
   • CLOSED (En buen estado) — Las solicitudes circulan con normalidad
   • DEGRADED — Las solicitudes siguen circulando mientras se supervisa el aumento de errores
   • OPEN — El proveedor se bloquea temporalmente tras errores repetidos
   • HALF_OPEN — Se comprueba si el proveedor se ha recuperado

   Los límites de tasa 429 asociados a una conexión permanecen en Tiempo de espera de la conexión y no cuentan para 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 termine el primer periodo de espera y reintentar automáticamente la misma solicitud del cliente.

5. Detección automática de límites de tasa — Cuando los proveedores ascendentes devuelven intervalos de espera explícitos, esas indicaciones prevalecen sobre 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

Gestione 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, ajustes, combos, conexiones de proveedores (sin credenciales) y metadatos de claves de API
Importar base de datos	Carga un archivo .sqlite para reemplazar 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

# 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 obligatorias (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 archivo)

---

Panel de ajustes

La página de ajustes 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, conmutadores de paneles para las tarjetas de túneles de Cloudflare/Tailscale/ngrok
IA	Presupuesto de razonamiento (transferencia directa / eliminación automática / personalizado / adaptativo; consulte THINKING_BUDGET.md), prompt global del sistema, estadísticas de caché de prompts
Seguridad	Ajustes 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 (llenar primero / round robin / P2C / aleatorio / menos usado / optimizado por coste), alias de modelos con comodines, cadenas de respaldo, valores predeterminados de combos
Resiliencia	Cola de solicitudes, tiempo de espera de conexiones, configuración del disyuntor de proveedores y comportamiento de espera durante el tiempo de espera
Avanzado	Configuración global del proxy (HTTP/SOCKS5), anulaciones del proxy por proveedor

La pestaña General ya no duplica las notas de solo lectura sobre el registro y la caché. Los ajustes de retención y optimización de la base de datos se conservan mediante /api/settings/database; para borrar manualmente la caché se 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

Acceda mediante Panel → Costes.

Pestaña	Finalidad
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

# 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. Consulte 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:

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, utilice openrouter/deepgram/nova-3.

Proveedores de conversión 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 conversión 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 compatibles con la transcripción: mp3, wav, m4a, flac, ogg, webm. Los formatos de salida de TTS dependen del proveedor (mp3, wav, opus, pcm, mulaw).

---

Estrategias de balanceo de combos

Configure el balanceo de cada combo en Panel → Combos → Crear/Editar → Estrategia.

Estrategia	Descripción
Round-Robin	Rota secuencialmente entre los modelos
Prioridad	Siempre prueba primero el primer modelo; solo recurre al siguiente en caso de error
Aleatoria	Selecciona un modelo aleatorio 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 las métricas de la combinación)
Optimizada por costes	Enruta al modelo disponible más económico (utiliza la tabla de precios)

Los valores predeterminados globales de las combinaciones pueden configurarse en Panel de control → Configuración → Enrutamiento → Valores predeterminados de combinaciones. De forma predeterminada, los tiempos de espera de los destinos de una combinación heredan el tiempo de espera de la solicitud actual. Use Tiempo de espera del destino (segundos) en los valores predeterminados de las combinaciones o en una combinación individual solo cuando un límite más corto por destino deba activar antes la conmutación por error.

Las optimizaciones de latencia cero son opcionales. Deje desactivada la opción Optimizaciones de latencia cero para evitar que estas funciones de latencia hagan competir a los destinos de conmutación por error, omitan destinos según el historial de TTFT o compriman las solicitudes de conmutación por error; al activarla, se permiten la cobertura configurada, las omisiones predictivas basadas en TTFT y la compresión proactiva de la conmutación por error para intercambiar fidelidad de enrutamiento/solicitud por una menor latencia de cola.

Desactive Búfer de tokens de razonamiento cuando los proveedores ascendentes requieran límites estrictos de max_tokens / maxOutputTokens. Cuando está activado, el enrutamiento de combinaciones solo añade margen para modelos de razonamiento en aquellos 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 supera un límite conocido, OmniRoute lo reduce a ese límite antes de enviar la solicitud al proveedor ascendente.

---

Panel de estado

Acceda mediante Panel de control → 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 y directorio de datos
Estado del proveedor	Estado global en tiempo de ejecución del disyuntor del proveedor
Límites de velocidad	Tiempos de espera de conexiones activos por cuenta con el tiempo restante
Bloqueos activos	Bloqueos activos específicos del modelo y exclusiones temporales
Caché de firmas	Estadísticas de la caché de deduplicación (claves activas y 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. Use 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:

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, 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:

{
  "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 para ver el inventario oficial de ámbitos y herramientas, y 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.

---

💾 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.

---

🔔 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.

---

☁️ 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.

---

🛠️ 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:

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

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 <id>      # Prueba en vivo una conexión de proveedor
omniroute combos list              # Enumera las combinaciones
omniroute combos switch <name>     # 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 [<timestamp>]    # 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

# 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

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