biblioteca_conocimiento_laboratorio/documentacion/omniroute-guia-autorouting-combos.md

OmniRoute — Guía autorouting y combos auto/*

Fecha: 13-sep-2026 · Estado: documentación estable para replicar en cualquier equipo (sobremesa / portátil / VPS)

---

1. Qué es OmniRoute en este setup

OmniRoute es un proxy/router de modelos self-hosted que corre en local. Hace routing entre tus proveedores conectados con fallback automático, circuit breakers, y combos virtuales.

• Servidor: paquete npm global omniroute
  • Comando: omniroute serve → lanza node .../omniroute/dist/server-ws.mjs
  • Escucha en: http://localhost:20128 (OpenAI-compatible /v1)
• Datos: C:\Users\juanm\.omniroute\
  • storage.sqlite (estado, streaks, kv de combos)
  • call_logs\AAAA-MM-DD\*.json (cada request ruteado: modelo real elegido, tokens, fallbacks)
  • logs\application\app.log (routing trace: decisiones, fallbacks, límites)
  • .env (config servidor, secretos — nunca exponer)
  • server\.pid / supervisor\.pid
• Supervisor: omniroute.mjs serve es el padre; el worker real es server-ws.mjs
• Sin autostart por tarea programada en sobremesa (se lanza manualmente). Replicar igual en portátil.

2. Estado actual: bug de opencode y los 38 modelos manuales

Problema raíz: el plugin @omniroute/opencode-plugin no puede registrar providers fuera del catálogo models.dev de opencode → los auto/* NO aparecen en el picker por defecto.

• Issues: anomalyco/opencode #38839 (provider hook skipped for non-catalog providers) y #25630 (Regression: plugin provider.models() hook no longer populates custom providers, post #25167).

Workaround aplicado (decisión: mantener hasta que se arregle el bug):

• Los 38 modelos auto/* están declarados a mano en ~/.config/opencode/opencode.jsonc → sección provider.omniroute, con label amigable (Auto ♟ Best Coding, etc.) y baseURL: http://localhost:20128/v1, npm: @ai-sdk/openai-compatible.
• El plugin se carga con: providerId: omniroute, baseURL: http://localhost:20128.
• El enrutado y el failover funcionan igual aunque los modelos estén a mano: la lógica de routing vive 100% en el servidor OmniRoute, opencode solo manda el nombre auto/... a localhost:20128. El picker manual solo afecta al catálogo visible, NO al comport­amiento de routing.

Check automático del fix:

• scripts/check_omniroute_fix.ps1 (tarea programada OmnirouteFixCheck, diaria 09:00) consulta los issues #38839/#25630.
• Si alguno está cerrado → crea documentacion/omniroute_fix_fixed.flag y actualiza documentacion/omniroute_fix_status.txt.
• Cuando exista ese flag: avisar al usuario → reactivar catálogo dinámico del plugin y quitar los 38 modelos manuales de opencode.jsonc.

3. Cómo funciona el routing auto/* (mecánica por detrás)

Los auto/* no son modelos reales: son alias virtuales de ruta. OmniRoute los materializa al vuelo en cada request sin guardarlos en la BD (tabla combos vacía).

Flujo real (trace de app.log):

POST /v1/chat/completions | auto/best-coding | 28 msgs | 71 tools
Virtual auto-combo created: auto/best-coding (2 candidates)          ← shortlist puntuada
Combo "auto/best-coding" [auto] with 13 models                       ← pool total (nested "auto")
auto with nested resolution: 13 total targets
Auto selection: oc/big-pickle | intent=medium task=default | strategy=lkgp | LKGP
Trying model 1/8: oc/big-pickle
ROUTING oc/big-pickle ⇒ opencode/big-pickle                          ← modelo REAL elegido
Model oc/big-pickle succeeded (880ms, 0 fallbacks)

• En cada request el Auto-Combo Engine puntúa a los candidatos con 15 factores: salud del provider, cuota restante, coste, latencia, task fit, calidad, disponibilidad de sesión, etc.
• lkgp = Last-Known-Good: sticky al último target que funcionó mientras siga OK (no cambia por aburrimiento).
• Fallback automático: si el elegido falla (429/5xx/timeout), re-engancha al siguiente candidato dentro del mismo request (sin que opencode se entere).
• Recuperación: circuit breakers/cooldowns auto-reset; el primer éxito limpia el estado de error. Un candidato agotado deja de ganar el scoring y vuelve cuando recupera cuota.

Mapa de variantes (catalog real, open-sse/services/autoCombo/builtinCatalog.ts)

Modelo	Variante	Optimiza
auto	default	Balanceado (LKGP)
auto/best-coding	coding	Quality-first para código
auto/best-reasoning	smart	Calidad + 10% exploración
auto/best-fast	fast	Menor latencia
auto/best-vision	smart (+filtro visión)	Calidad en inputs visuales
auto/best-chat	default	Chat general
auto/best-coding-fast	fast	Velocidad en código
auto/best-free	cheap	Solo tier free
auto/best-chaos	chaos	Despacho paralelo top-N
auto/pro-*	idem	Tier de pago forzado
auto/coding, auto/fast, auto/cheap, auto/offline, auto/smart, auto/chat	idem	Variantes básicas
auto/coding:fast, auto/coding:pro, auto/vision, auto/multimodal, auto/reasoning	sufijo	Categoría[:tier]
auto/gemini, auto/llama, auto/glm, auto/claude-sonnet, auto/claude-opus...	familia	Solo esa familia como candidatos

Los 38 declarados a mano en opencode.jsonc son este catálogo auto/*.

4. Límites y quotas

• Límite de contexto del combo auto/*: 200.000 tokens (source=target) — confirmado en logs: Combo context limit: 200000 (source=target).
  • source = lo que opencode envía (conversación + tools)
  • target = lo que el modelo de destino admite
• Salida (out): sin tope fijo en el combo; depende del modelo real que rute en ese momento.
• "¿Me bloquean por usarlo varios días?": NO. Los bloqueos (circuit breaker / model lockout) solo saltan ante fallos reales repetidos (429/5xx/timeout) y se auto-recuperan. El único bloqueo real sería agotar la cuota de TODOS los candidatos a la vez (cuenta opencode = big-pickle + reserva del pool).

5. Candidatos actuales para auto/best-coding (13-sep-2026)

• Shortlist directa: 2 candidatos (log: 2 candidates). Ganador actual estable: oc/big-pickle → provider opencode (cuenta opencode, API key OMNI-1).
• Pool anidado: 13 targets (combo base auto con "nested resolution").
• Intentos de fallback por request: hasta 8 (Trying model 1/8); si todos fallan → error al usuario.
• La identidad exacta del 2º candidato no está persistida en la BD: la construye el engine en runtime puntuando tus conexiones. Para verla en vivo: call_logs o logs/application/app.log (líneas con Auto selection:/VRouting).

6. Replicación en el portátil

Para que el asistente del portátil deje todo igual:

1. Instalar servidor: npm i -g omniroute (mismo paquete que en sobremesa).
2. Config .omniroute: copiar C:\Users\juanm\.omniroute\.env (secretos) y, si se quiere historial, storage.sqlite + call_logs.
3. Lanzar: omniroute serve (debe quedar escuchando en http://localhost:20128).
4. Config opencode (~/.config/opencode/opencode.jsonc):
   • Plugin: file:///C:/Users/juanm/AppData/Roaming/opencode/plugins/omniroute/dist/index.js con { "providerId": "omniroute", "baseURL": "http://localhost:20128" }
   • Provider omniroute: npm @ai-sdk/openai-compatible, baseURL http://localhost:20128/v1, los 38 modelos auto/* (ver sección 3 para el catálogo; el JSON exacto está en el opencode.jsonc de la sobremesa).
5. Fix checker: copiar scripts/check_omniroute_fix.ps1 + tarea OmnirouteFixCheck (diaria 09:00).
6. Comprobar en logs/application/app.log que aparece Combo context limit: 200000 (source=target).

7. Origen de esta guía

Recopilado 13-sep-2026 en sesión RE (sobremesa): logs reales del servidor, builtinCatalog.ts del paquete npm, y verificación en vivo con requests de opencode bajo omniroute/auto/best-coding. Memoria Engram asociada (project biblioteca_conocimiento_laboratorio): "Cómo funcionan los modelos auto/* de OmniRoute (alias virtuales + routing)". Esta guía se sincroniza a todos los equipos vía git + Engram Cloud para que el asistente pueda aplicarla en el portátil.