Troubleshooting (Español)

Referencia rápida

¿Eres nuevo en OmniRoute? Empieza aquí: esto resuelve el 90 % de los problemas:

Veo esto	Qué significa	Qué hacer
“No se puede conectar”	OmniRoute no se está ejecutando	Ejecuta omniroute o docker restart omniroute
“Clave de API no válida”	Tu clave es incorrecta o ha caducado	Vuelve a copiar la clave desde el sitio web del proveedor
“Límite de solicitudes excedido”	Estás enviando demasiadas solicitudes	Espera 1 minuto o usa model: "auto" para recurrir automáticamente a otra opción
“Cuota excedida”	Has agotado tu cuota gratuita o de pago	Conecta más proveedores o usa proveedores gratuitos (Kiro, Pollinations)
“Respuestas lentas”	El proveedor está ocupado o se encuentra muy lejos	Usa model: "auto/fast" o conecta un proveedor más rápido (Groq, Cerebras)
“Se usó el proveedor equivocado”	auto eligió un proveedor diferente	¡Es normal! auto elige el mejor. Fuerza un proveedor específico con model: "openai/gpt-4o"
“502 Puerta de enlace incorrecta”	El proveedor no está disponible	Espera y vuelve a intentarlo, o usa model: "auto" para cambiar de proveedor
“401 No autorizado”	Tus credenciales son incorrectas	Comprueba tu clave de API o vuelve a autenticarte con OAuth
“omniroute no se reconoce”	Al PATH de Windows le faltan los módulos globales de node	Añade tu prefijo global de npm al PATH de Windows. Encuéntralo con npm config get prefix.
“429 Demasiadas solicitudes”	Se ha aplicado un límite de solicitudes	Espera 1 minuto o conecta más proveedores

¿Sigues atascado? Consulta la solución de problemas detallada a continuación o pregunta en Discord.

---

Solución de problemas detallada

---

Limitación de solicitudes en proveedores gratuitos (429 / 400 / 401)

Síntoma: Al usar model: "auto" con proveedores gratuitos o sin autenticación (opencode, auggie, etc.), recibes de forma intermitente HTTP 429, 400 o 401 en lugar de respuestas. Las solicitudes se completan correctamente al volver a intentar la misma instrucción unos instantes después, pero la automatización (tareas cron, agentes, scripts) falla en el primer error.

Causa raíz: Se acumulan tres modos de fallo independientes:

1. Límite de solicitudes del proveedor (429): Los niveles gratuitos pueden imponer una cuota por intervalo. Una ráfaga de llamadas paralelas la agota, por lo que la siguiente solicitud se rechaza hasta que se restablece el intervalo.
2. Modelo defectuoso en passthrough (400/401): Los grupos auto/* pueden incluir modelos passthrough de opencode que están registrados en el catálogo, pero no tienen credenciales activas (por ejemplo, oc/north-mini-code-free → 401). El enrutador automático prueba uno, falla y el error se propaga antes de que se active la alternativa.
3. Amplificación de concurrencia (429 bajo carga): Cuando varias sesiones de agentes o cron acceden a auto al mismo tiempo, la tasa agregada de solicitudes supera lo que toleran los proveedores gratuitos, por lo que las llamadas legítimas se marcan como abusivas.

Solución verificada (informada por la comunidad, 2026-08-10): ajusta tres variables de entorno para que la rotación, la concurrencia y las alternativas absorban la inestabilidad del nivel gratuito en lugar de fallar por ella:

export OMNIROUTE_ROTATE_ON_400=true           # salta a otro modelo/proveedor ante un 400/401 (omite los modelos passthrough defectuosos)
export OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT=4   # límite explícito de admisión para solicitudes pesadas (sin definir de forma predeterminada: sin límite por número de solicitudes; consulta la nota siguiente)
export OMNIROUTE_CHAT_ADMISSION_QUEUE_MS=5000 # espera limitada más larga para obtener capacidad para solicitudes pesadas, en lugar de un 503 reintentable inmediato

Configúralas en el entorno del proceso de OmniRoute (el daemon, por ejemplo, mediante el plist de LaunchAgent o systemctl edit) y, a continuación, reinicia OmniRoute. La opción de rotación es, por sí sola, la medida de mayor impacto: convierte un fallo definitivo en un reintento transparente con un proveedor operativo del grupo.

Nota: OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT limita cuántas solicitudes pesadas —de contexto largo— se ejecutan al mismo tiempo; este límite es una puerta de admisión, no un limitador de solicitudes del proveedor. Actualización sobre la propagación de errores #503: esta variable ya no se establece de forma predeterminada (ahora solo se aplica cuando se configura explícitamente, como se muestra arriba). En su lugar, la admisión de solicitudes pesadas se controla mediante un presupuesto de bytes derivado automáticamente (OMNIROUTE_CHAT_MAX_INFLIGHT_BYTES) que se ajusta en función del límite real de memoria del host, por lo que una implementación nueva debería generar muchos menos rechazos 503 chat_admission_busy sin necesidad de establecer esta variable; establecerla explícitamente aquí sigue funcionando exactamente como se documenta. Las anulaciones explícitas del presupuesto de bytes se restringen al intervalo de 8 MiB a 2 GiB. Un error 413 body_exceeds_budget no es transitorio: aumenta ese presupuesto de bytes, reduce OMNIROUTE_CHAT_HARD_MAX_BODY_BYTES o aumenta el límite de memoria del proceso. Un descarte inflight_bytes_budget se debe a una contención temporal y se puede volver a intentar. La limitación de solicitudes por proveedor (open-sse/services/rateLimitManager.ts) se controla por separado mediante RATE_LIMIT_MAX_WAIT_MS, RATE_LIMIT_MAX_QUEUE_DEPTH y RATE_LIMIT_AUTO_ENABLE; consulta .env.example.

Cómo verificar que funcionó: ejecuta tu agente/cron dos veces seguidas en rápida sucesión y confirma que ambas ejecuciones se completen correctamente. Antes de la corrección, la segunda ejecución suele producir un error 429/401. Después de la corrección, los fallos (si los hay) se reintentan de forma transparente y la llamada se completa. También puedes ejecutar curl /monitoring/health y observar el campo rateLimitedUntil en las conexiones de los proveedores y circuitBreakers.providerBreakers[].state para los proveedores afectados; el estado puede ser CLOSED, DEGRADED, OPEN o HALF_OPEN (consulta src/shared/utils/circuitBreaker.ts), y un proveedor que siga fallando pasará de CLOSED → DEGRADED → OPEN antes de que la ventana de restablecimiento permita una solicitud de prueba (HALF_OPEN).

Si sigues viendo 429: la cuenta activa de ese proveedor realmente ha agotado su cuota (no solo el límite de solicitudes). Añade una segunda cuenta para el mismo proveedor en el panel de OmniRoute → Providers → Accounts, o incorpora otro proveedor gratuito (por ejemplo, routeway, auggie). La rotación solo ayuda con errores transitorios de límite de solicitudes/400/401; el agotamiento total de la cuota requiere una segunda credencial o un proveedor diferente.

Si ves 403 en modelos de visión (auto/vision, bazaarlink/*): la cuenta conectada no tiene un plan de pago que incluya visión, o la clave de API no tiene permisos suficientes. Verifica en el panel del proveedor que el alcance de la clave incluya visión/multimodal, o conecta una cuenta de un nivel de pago y mantenla como destino para visión.

---

Advertencias de npm install (ERESOLVE / peer / deprecated)

Al ejecutar npm install -g omniroute, es posible que vea una gran cantidad de advertencias como npm warn ERESOLVE, avisos sobre dependencias de pares y mensajes deprecated. Son esperados e inofensivos. La instalación se completó correctamente si ve added <N> packages en la salida.

Para suprimir las advertencias de resolución de dependencias de pares, use la forma de instalación compatible con OmniRoute:

npm install -g omniroute --legacy-peer-deps

--legacy-peer-deps solo suprime los avisos de ERESOLVE y de dependencias de pares. Los avisos de obsolescencia permanecen visibles porque proceden de paquetes transitivos de terceros; no indican que la instalación haya fallado.

Las advertencias proceden de rangos obsoletos de dependencias de pares en paquetes de terceros que OmniRoute no controla:

1. marked-terminal requiere marked >=1 <16, pero se encontró marked@18 — en la práctica funciona correctamente; el rango de pares del proyecto original simplemente está obsoleto.
2. deprecated prebuild-install@7.1.3 — un auxiliar transitivo para obtener binarios nativos. No se utiliza para instalar el enlace de transporte wreq-js fijado y no indica que haya fallado la configuración de transporte del proveedor de cookies web.

No es necesario realizar ninguna acción — las advertencias no pueden silenciarse por completo sin bifurcar los paquetes originales.

---

Gemini Web y Playwright Chromium

Si una solicitud de Gemini Web devuelve 503 con un mensaje que indica que Playwright Chromium no está instalado, el paquete npm está presente, pero falta el binario del navegador. Playwright mantiene deliberadamente las descargas del navegador separadas de la instalación del paquete npm, por lo que esta respuesta es esperada hasta que se instale el navegador.

Para una instalación global de npm, instale Chromium desde el directorio del paquete OmniRoute para que la caché del navegador pertenezca a la misma instalación de Playwright:

cd "$(npm root -g)/omniroute"
npx playwright install chromium

Reinicie OmniRoute después de la instalación y vuelva a intentar la solicitud de Gemini Web. Si ejecuta OmniRoute desde una imagen de Docker, use la imagen -web (o el objetivo de compilación runner-web), que incluye Chromium y sus dependencias; la imagen base no los incluye.

---

Soluciones rápidas

Problema	Solución
El primer inicio de sesión no funciona	Configure INITIAL_PASSWORD en .env (no hay un valor predeterminado codificado)
El panel se abre en el puerto incorrecto	Configure PORT=20128 y NEXT_PUBLIC_BASE_URL=http://localhost:20128
No se escriben registros en el disco	Configure APP_LOG_TO_FILE=true y verifique que la captura de registros de llamadas esté habilitada
EACCES: permiso denegado	Configure DATA_DIR=/path/to/writable/dir para sustituir ~/.omniroute
La estrategia de enrutamiento no se guarda	Actualice a la versión v3.x más reciente (la corrección del esquema de Zod para la persistencia de la configuración se incluyó en versiones anteriores)
Fallo al iniciar sesión / página en blanco	Compruebe la versión de Node.js; consulte Compatibilidad con Node.js más abajo
dlopen / slice is not valid mach-o file (macOS)	Ejecute cd $(npm root -g)/omniroute/app && npm rebuild better-sqlite3 && omniroute; consulte recompilación del módulo nativo de macOS más abajo
“fetch failed” del proxy	Asegúrese de que la configuración del proxy esté establecida en el nivel correcto; consulte Problemas con el proxy más abajo
curl: (56) Recv failure: Connection reset by peer de Docker	Es posible que la vinculación de puertos de Docker esté usando IPv6. Use -p 127.0.0.1:20128:20128 para forzar IPv4 o pruebe con curl -4. Consulte IPv6 de Docker más abajo
El antivirus pone README.md en cuarentena	Falso positivo; consulte Falsos positivos del antivirus más abajo
Kaspersky identifica la aplicación de escritorio como un troyano	Falso positivo de comportamiento en el instalador sin firmar; consulte Falsos positivos del antivirus más abajo

---

Falsos positivos del antivirus

Avast/AVG pone en cuarentena README.md con MD:HttpRequest-inf[Susp]

Este es un falso positivo. Nada está infectado y no es necesario realizar ninguna acción.

Avast y AVG ejecutan una heurística que marca archivos de texto sin formato/Markdown que contienen muchos enlaces que parecen solicitudes HTTP. El archivo README.md de OmniRoute se incluye en el paquete npm (aparece en package.json → files), por lo que termina en node_modules/omniroute/README.md tras una instalación global, y contiene unos 15 ejemplos de http://localhost:20128/... (los endpoints HTTP/SSE de MCP, la URL .well-known de A2A y fragmentos de curl). Esa densidad de enlaces es suficiente para activar la heurística.

Si esto comenzó hace poco: el tipo de archivo no cambió. El README amplió su tabla de endpoints (se añadieron MCP HTTP + SSE + A2A) y se incorporaron más ejemplos de curl, lo que hizo que superara el umbral.

El archivo es documentación inerte sin ningún contenido ejecutable. Puede restaurarlo de la cuarentena con total seguridad.

Qué hacer:

1. Detenga las notificaciones — excluya el directorio de instalación en su antivirus (Avast: Configuración → Excepciones), añadiendo la ruta global de node_modules y/o el directorio de datos de OmniRoute (~/.omniroute/).
2. Informe del falso positivo — https://www.avast.com/false-positive-file-form.php, adjuntando el archivo README.md en cuarentena. Esta es la solución que ayuda a todos, ya que es la heurística del proveedor la que está reaccionando de forma exagerada ante un archivo de texto.

Por qué no lo «solucionamos» de nuestro lado: todos los ejemplos usan http://localhost, y localhost no puede usar https sin las complicaciones propias de los certificados autofirmados. Alterar la documentación para eludir la heurística de un proveedor perjudicaría a todos los lectores para satisfacer un error del escáner.

Kaspersky marca la aplicación de escritorio como PDM:Trojan.Win32.Generic

Este es un falso positivo de una heurística de comportamiento. Nada está infectado. El prefijo PDM: de Kaspersky significa que el veredicto proviene de su Módulo de Defensa Proactiva (System Watcher), que evalúa lo que el instalador hace en lugar de compararlo con malware conocido. Cuando se activa, Kaspersky «revierte» toda la instalación —eliminando archivos que ya había escrito—, por lo que la aplicación queda dañada o desaparece.

Los archivos que marca son componentes estándar de dependencias de código abierto declaradas e incluidas con la aplicación de escritorio, por ejemplo:

• resources/app/.build/next/node_modules/playwright-<hash>/lib/…/agentParser.js y workerProcessEntry.js — Playwright, la biblioteca de automatización de navegadores utilizada para el inicio de sesión de proveedores desde la aplicación y el chat respaldado por navegador.
• resources/app/.build/next/node_modules/@wreq-js/binding-win32-<arch>-msvc-<hash>/wreq-js.win32-<arch>-msvc.node — el binding nativo fijado de wreq-js, utilizado para HTTP con huella digital de navegador en proveedores basados en cookies web (<arch> es x64 o arm64).

Por qué se activa: el instalador de Windows todavía no está firmado con código, por lo que un instalador NSIS sin firmar no tiene reputación alguna y las heurísticas de comportamiento se ejecutan con la máxima agresividad. Combinado con una DLL nativa incluida y cientos de archivos .js escritos en %LOCALAPPDATA%\Programs\OmniRoute (incluidos directorios de paquetes con sufijos hash procedentes de la compilación independiente de Next.js), esto es suficiente para activar la heurística. Está previsto implementar la firma de código; hasta que ocurra, esto puede repetirse en nuevas versiones.

Qué hacer:

1. Verifique primero la descarga (esto descarta que el archivo haya sido manipulado). Cada versión publica latest.yml, cuyo campo sha512 (base64) corresponde al instalador OmniRoute.Setup.<version>.exe. En PowerShell, desde la carpeta que contiene el instalador:

   $b = [System.Security.Cryptography.SHA512]::Create().ComputeHash(
     [System.IO.File]::ReadAllBytes("$PWD\OmniRoute.Setup.<version>.exe"))
   [Convert]::ToBase64String($b)

   La salida debe coincidir con latest.yml → sha512. Si no coincide, elimine el archivo y vuelva a descargarlo únicamente desde la página de versiones de GitHub.
2. Restaure y excluya — restaure de la cuarentena los elementos eliminados durante la reversión y añada una exclusión para %LOCALAPPDATA%\Programs\OmniRoute (Kaspersky → Configuración → Amenazas y exclusiones); después, vuelva a instalar.
3. Informe del falso positivo — https://opentip.kaspersky.com/. Los informes de falsos positivos enviados por los usuarios realmente aceleran la inclusión en la lista de permitidos.

---

Compatibilidad con Node.js

La página de inicio de sesión se bloquea o muestra el error “Module self-registration”

Causa: Está ejecutando una versión de Node.js fuera del nivel mínimo de ejecución segura aprobado por OmniRoute. El caso más común es ejecutar una versión de parche antigua de Node 22 o 24 que está por debajo del nivel mínimo de seguridad con parches requerido por OmniRoute.

Síntomas:

• La página de inicio de sesión muestra una pantalla en blanco o un error del servidor
• La consola muestra Error: Module did not self-register o errores similares de enlaces nativos
• La página de inicio de sesión muestra un banner de advertencia naranja con su versión de Node si el entorno de ejecución no cumple la política segura compatible

Solución:

1. Instale una versión LTS compatible de Node.js (recomendado: Node.js 24.x):

   nvm install 24
   nvm use 24

2. Compruebe su versión: node --version debe mostrar v24.0.0 o una versión posterior de la línea LTS 24.x
3. Vuelva a instalar OmniRoute: npm install -g omniroute
4. Reinicie: omniroute

Versiones seguras compatibles: >=22.22.2 <23 o >=24.0.0 <27. Node.js 24.x LTS (Krypton) y Node.js 26 son totalmente compatibles.

npm v11+: better-sqlite3 no está instalado (Cannot find module)

Causa: npm v11 (incluido con Node.js 24+) bloquea de forma predeterminada los scripts de instalación de las dependencias opcionales. Dado que better-sqlite3 aparece en optionalDependencies y requiere compilación nativa (node-gyp rebuild), npm lo omite silenciosamente.

Síntomas:

• El servidor se bloquea al iniciarse con Cannot find module 'better-sqlite3'
• ls node_modules/better-sqlite3 muestra “No such file or directory”
• npm ls better-sqlite3 muestra (empty)

Solución:

1. Apruebe los scripts de instalación y vuelva a instalar:

   npm approve-scripts better-sqlite3
   npm install

2. O instale manualmente el paquete precompilado:

   npm pack better-sqlite3@13.0.1
   tar -xzf better-sqlite3-*.tgz -C node_modules
   mv node_modules/package node_modules/better-sqlite3
   rm better-sqlite3-*.tgz

3. Compruebe que funciona: node -e "require('better-sqlite3')(':memory:').close(); console.log('OK')"

macOS: dlopen / “slice is not valid mach-o file”

Causa: Después de ejecutar globalmente npm install -g omniroute, es posible que el binario nativo de better-sqlite3 incluido en el paquete se haya compilado para una arquitectura o ABI de Node.js diferente a la que se ejecuta localmente. Esto es habitual en macOS (tanto con Apple Silicon como con Intel) cuando el binario precompilado no coincide con su entorno.

Síntomas:

• El servidor falla inmediatamente al iniciarse con un error de dlopen
• El error contiene slice is not valid mach-o file
• Ejemplo completo:

dlopen(/Users/<user>/.nvm/versions/node/v24.14.1/lib/node_modules/omniroute/app/node_modules/better-sqlite3/build/Release/better_sqlite3.node, 0x0001): tried: '...' (slice is not valid mach-o file)

Solución — vuelva a compilar para su entorno local (no es necesario cambiar a una versión anterior de Node.js):

cd $(npm root -g)/omniroute/app
npm rebuild better-sqlite3
omniroute

Nota: Esto vuelve a compilar el enlace nativo para su versión local de Node.js y la arquitectura de su CPU, lo que resuelve la incompatibilidad binaria. El intervalo de entornos de ejecución oficialmente compatible es >=22.22.2 <23 o >=24.0.0 <27 (SUPPORTED_NODE_RANGE en src/shared/utils/nodeRuntimeSupport.ts, alineado con el campo engines de package.json). Node.js 24.x LTS (Krypton) y Node.js 26 son totalmente compatibles con better-sqlite3 v12.x.

---

Problemas con el proxy

La validación del proveedor muestra “fetch failed”

Causa: El endpoint de validación de claves de API (POST /api/providers/validate) anteriormente omitía la configuración del proxy, lo que provocaba errores en entornos que requieren el enrutamiento mediante proxy.

Solución (v3.5.5+): Esto ya está corregido. La validación del proveedor se ejecuta mediante runWithProxyContext y respeta automáticamente la configuración de proxy tanto del proveedor como global.

La comprobación del estado del token falla con “fetch failed”

Causa: La actualización de tokens OAuth en segundo plano no resolvía la configuración del proxy para cada conexión.

Solución (v3.5.5+): El programador de comprobaciones del estado de los tokens ahora resuelve la configuración del proxy para cada conexión antes de intentar la actualización. Actualice a v3.5.5+.

El proxy SOCKS5 devuelve “invalid onRequestStart method”

Causa: En Node.js 22, el dispatcher de undici@8 es incompatible con la implementación integrada de fetch() de Node.

Solución (v3.5.5+): OmniRoute ahora utiliza la función fetch() propia de undici cuando hay un dispatcher de proxy activo, lo que garantiza un comportamiento coherente. Actualice a v3.5.5+.

Proxy MITM en WSL: las aplicaciones de escritorio del host Windows no son interceptadas

Causa: El proxy MITM y su certificado de CA se instalan en el entorno donde se ejecuta OmniRoute. En WSL, dicho entorno es el sistema Linux invitado, mientras que las aplicaciones de IA de escritorio (Kiro, Trae, Copilot, Zed, …) se ejecutan en el host Windows. Las aplicaciones del host no confían en el almacén de certificados del sistema invitado ni enrutan el tráfico a través del proxy del sistema invitado, por lo que la interceptación de aplicaciones de escritorio no funciona en ese entorno.

Recomendación: Ejecute OmniRoute de forma nativa en el mismo sistema operativo que las aplicaciones de escritorio que desea interceptar (Windows para aplicaciones de Windows; lo mismo se aplica a macOS/Linux). Mantener OmniRoute dentro de WSL mientras se interceptan aplicaciones del host requiere confiar manualmente en el certificado de CA generado en el host Windows y configurar los ajustes de red/proxy de cada aplicación del host para que apunten al endpoint del proxy de WSL; se trata de una configuración frágil y no compatible oficialmente.

---

Problemas con los proveedores

“Language model did not provide messages”

Causa: Se ha agotado la cuota del proveedor.

Solución:

1. Compruebe el indicador de cuota del panel
2. Utilice una combinación con niveles de respaldo
3. Cambie a un nivel más barato o gratuito

Limitación de solicitudes

Causa: Se ha agotado la cuota de la suscripción.

Solución:

• Añada alternativas de respaldo: cc/claude-opus-4-6 → glm/glm-4.7 → if/qwen3.8-max-preview
• Utilice GLM/MiniMax como alternativa económica

Token OAuth caducado

OmniRoute actualiza los tokens automáticamente. Si los problemas persisten:

1. Panel → Proveedor → Volver a conectar
2. Elimine y vuelva a añadir la conexión del proveedor

Varias cuentas de Kiro: la segunda cuenta invalida la primera

Causa: El backend de Kiro impone una única sesión activa por registro de cliente OIDC. Cuando dos cuentas comparten el mismo cliente registrado (conexiones importadas antes de v3.8.0), la actualización del token de una cuenta invalida el token de actualización de la otra.

Solución (v3.8.0+): Vuelva a importar las conexiones afectadas. A partir de v3.8.0, cada conexión nueva de Kiro creada mediante Importar token, Inicio de sesión social con Google/GitHub o Importación automática registra automáticamente su propio cliente OIDC dedicado. De este modo, la conexión queda completamente aislada y la actualización de una cuenta no afecta a ninguna otra.

Las conexiones importadas antes de v3.8.0 no incluyen un registro de cliente específico para cada conexión. Esas conexiones continúan utilizando el endpoint compartido de actualización de autenticación social. Para obtener aislamiento, elimine la conexión antigua desde Panel → Proveedores y vuelva a añadirla mediante cualquiera de los tres flujos de importación.

Para obtener todos los detalles e instrucciones paso a paso sobre cómo añadir dos cuentas de Kiro en paralelo, consulte docs/guides/KIRO_SETUP.md.

---

Problemas con la nube

Errores de sincronización con la nube

1. Verifique que BASE_URL apunte a su instancia en ejecución (p. ej., http://localhost:20128)
2. Verifique que CLOUD_URL apunte a su endpoint en la nube (p. ej., https://omniroute.dev)
3. Mantenga los valores NEXT_PUBLIC_* alineados con los valores del servidor

stream=false en la nube devuelve 500

Síntoma: Unexpected token 'd'... en el endpoint de la nube para llamadas sin streaming.

Causa: El servicio upstream devuelve una carga útil SSE mientras el cliente espera JSON.

Solución alternativa: Use stream=true para llamadas directas a la nube. El entorno de ejecución local incluye un mecanismo alternativo SSE→JSON.

La nube indica que está conectada, pero muestra “Clave de API no válida”

1. Cree una clave nueva desde el panel local (/api/keys)
2. Ejecute la sincronización con la nube: Activar nube → Sincronizar ahora
3. Las claves antiguas o no sincronizadas aún pueden devolver 401 en la nube

---

Problemas con Docker

IPv6 de Docker / Restablecimiento de conexión

Síntomas: curl http://localhost:20128/v1/models devuelve curl: (56) Recv failure: Connection reset by peer. El panel y los endpoints no autenticados funcionan, pero los endpoints autenticados fallan; parece un problema de autenticación, pero no lo es.

Causa: docker run -p 20128:20128 publica tanto en 0.0.0.0 (IPv4) como en :: (IPv6), pero el proceso dentro del contenedor solo escucha en IPv4. En hosts donde localhost se resuelve primero como ::1, la conexión llega al puerto IPv6 publicado sin que haya un proceso escuchando detrás de él → restablecimiento de conexión.

Solución:

1. Diagnóstico rápido: Ejecute curl -4 http://localhost:20128/v1/models. Si funciona con -4, pero falla sin esta opción, tiene una incompatibilidad de enlace IPv6.
2. Solución permanente: Enlace explícitamente a IPv4 mediante -p 127.0.0.1:20128:20128 en su comando docker run:

   docker run -d --name omniroute --restart unless-stopped --stop-timeout 40 \
     -p 127.0.0.1:20128:20128 -v omniroute-data:/app/data diegosouzapw/omniroute:latest

   Esto fuerza el enlace IPv4 y también evita exponer el proxy en todas las interfaces del host.

---

La herramienta CLI aparece como no instalada

1. Compruebe los campos del entorno de ejecución: curl http://localhost:20128/api/cli-tools/runtime/codex | jq
2. Para el modo portátil: use el destino de imagen runner-cli (incluye las CLI)
3. Para el modo de montaje del host: configure CLI_EXTRA_PATHS y monte el directorio de binarios del host como de solo lectura
4. Si installed=true y runnable=false: se encontró el binario, pero falló la comprobación de estado

Validación rápida del entorno de ejecución

curl -s http://localhost:20128/api/cli-tools/codex-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
curl -s http://localhost:20128/api/cli-tools/claude-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'

---

Problemas de costes

Costes elevados

1. Compruebe las estadísticas de uso en Panel → Uso
2. Cambie el modelo principal a GLM/MiniMax
3. Use el nivel gratuito (Qoder, Kiro) para tareas no críticas
4. Establezca presupuestos de costes por clave de API: Panel → Claves de API → Presupuesto

---

Depuración

Activar archivos de registro

Configure APP_LOG_TO_FILE=true en su archivo .env. Los registros de la aplicación se escriben en logs/. Los artefactos de las solicitudes se almacenan en ${DATA_DIR}/call_logs/ cuando la canalización de registros de llamadas está activada en la configuración. Cuando la captura de la canalización esté activada, configure CALL_LOG_PIPELINE_CAPTURE_STREAM_CHUNKS=false para omitir las cargas útiles de fragmentos de streaming, o ajuste CALL_LOG_PIPELINE_MAX_SIZE_KB para cambiar el límite de los artefactos en KB.

Comprobar el estado del proveedor

# Panel de estado
http://localhost:20128/dashboard/health

# Comprobación del estado de la API
curl http://localhost:20128/api/monitoring/health

Almacenamiento del entorno de ejecución

• Estado principal: ${DATA_DIR}/storage.sqlite (proveedores, combinaciones, alias, claves, configuración)
• Uso: tablas SQLite en storage.sqlite (usage_history, call_logs, proxy_logs) + ${DATA_DIR}/call_logs/ opcional
• Registros de la aplicación: <repo>/logs/... (cuando APP_LOG_TO_FILE=true)
• Artefactos de registros de llamadas: ${DATA_DIR}/call_logs/YYYY-MM-DD/... cuando la canalización de registros de llamadas está activada

La acción Limpiar historial de la página Registros de solicitudes borra call_logs, el request_detail_logs heredado y el directorio local de artefactos ${DATA_DIR}/call_logs/.

---

Problemas del disyuntor

Proveedor bloqueado en estado OPEN

Cuando el disyuntor de un proveedor está en estado OPEN, las solicitudes se bloquean hasta que finaliza el periodo de espera.

Solución:

1. Ve a Panel de control → Configuración → Resiliencia
2. Comprueba la tarjeta del disyuntor del proveedor afectado
3. Haz clic en Restablecer todo para restablecer todos los disyuntores, o espera a que finalice el periodo de espera
4. Antes de restablecerlo, verifica que el proveedor esté realmente disponible

El proveedor activa continuamente el disyuntor

Si un proveedor entra repetidamente en estado OPEN:

1. Consulta Panel de control → Estado → Estado del proveedor para identificar el patrón de fallos
2. Ve a Configuración → Resiliencia → Perfiles de proveedores y aumenta el umbral de fallos
3. Comprueba si el proveedor ha cambiado los límites de la API o requiere volver a autenticarse
4. Revisa la telemetría de latencia: una latencia alta puede provocar fallos por tiempo de espera agotado

---

Problemas de transcripción de audio

Error «Modelo no compatible»

• Usa un id de modelo cuyo primer segmento corresponda a un proveedor para el que tengas credenciales (openai/whisper-1, openrouter/deepgram/nova-3). Usar únicamente deepgram/nova-3 requiere una clave nativa de Deepgram.
• Verifica que el proveedor esté conectado en Panel de control → Proveedores

La transcripción está vacía o falla

• Comprueba los formatos de audio compatibles: mp3, wav, m4a, flac, ogg, webm
• Verifica que el tamaño del archivo esté dentro de los límites del proveedor (normalmente < 25 MB)
• Comprueba la validez de la clave de API del proveedor en la tarjeta correspondiente

---

Depuración del traductor

Usa Panel de control → Traductor para depurar problemas de traducción de formatos:

Modo	Cuándo usarlo
Entorno de pruebas	Compara los formatos de entrada y salida en paralelo; pega una solicitud que falle para ver cómo se traduce
Probador de chat	Envía mensajes en directo e inspecciona la carga útil completa de la solicitud y la respuesta, incluidos los encabezados
Banco de pruebas	Ejecuta pruebas por lotes en distintas combinaciones de formatos para determinar qué traducciones no funcionan
Monitor en directo	Observa el flujo de solicitudes en tiempo real para detectar problemas intermitentes de traducción

Problemas de formato comunes

• No aparecen las etiquetas de razonamiento — Comprueba si el proveedor de destino admite el razonamiento y revisa la configuración del presupuesto de razonamiento
• Se pierden las llamadas a herramientas — Algunas traducciones de formatos pueden eliminar campos no compatibles; verifícalo en el modo Entorno de pruebas
• Falta el prompt del sistema — Claude y Gemini gestionan los prompts del sistema de forma diferente; comprueba el resultado de la traducción
• El SDK devuelve una cadena sin procesar en lugar de un objeto — Resuelto en v1.x; el saneador de respuestas elimina los campos no estándar (x_groq, usage_breakdown, etc.) que provocan fallos de validación de Pydantic en el SDK de OpenAI. Si sigues viendo este problema en v3.x+, notifícalo.
• GLM/ERNIE rechaza el rol system — Resuelto en v1.x; el normalizador de roles combina automáticamente los mensajes del sistema con los mensajes del usuario para los modelos incompatibles. Si sigues viendo este problema en v3.x+, notifícalo.
• No se reconoce el rol developer — Resuelto en v1.x; se convierte automáticamente a system para los proveedores distintos de OpenAI. Si sigues viendo este problema en v3.x+, notifícalo.
• json_schema no funciona con Gemini — Resuelto en v1.x; ahora response_format se convierte en responseMimeType + responseSchema de Gemini. Si sigues viendo este problema en v3.x+, notifícalo.

---

Configuración de resiliencia

La limitación automática de tasa no se activa

• La limitación automática de tasa solo se aplica a proveedores con clave de API (no a OAuth/suscripción)
• Verifique que Configuración → Resiliencia → Perfiles de proveedor tenga habilitada la limitación automática de tasa
• Compruebe si el proveedor devuelve códigos de estado 429 o encabezados Retry-After

Ajuste del retroceso exponencial

Los perfiles de proveedor admiten estas opciones:

• Retraso base — Tiempo de espera inicial después del primer fallo (valor predeterminado: 1s)
• Retraso máximo — Límite máximo del tiempo de espera (valor predeterminado: 30s)
• Multiplicador — Cuánto aumentar el retraso por cada fallo consecutivo (valor predeterminado: 2x)

Prevención del efecto estampida

Cuando muchas solicitudes simultáneas llegan a un proveedor con limitación de tasa, OmniRoute utiliza mutex y limitación automática de tasa para serializar las solicitudes y evitar fallos en cascada. Esto es automático para los proveedores con clave de API.

Las solicitudes de chat fallan con 503 / chat_admission_busy

Síntomas:

• El endpoint de finalizaciones de chat devuelve una respuesta reintentable 503 cuyo código de error es chat_admission_busy.
• La respuesta incluye Retry-After. Desde #12135, el valor se deriva de la ocupación observada: el mayor valor entre la ventana OMNIROUTE_CHAT_ADMISSION_QUEUE_MS que la solicitud ya esperó y el tiempo durante el cual se han mantenido las concesiones pesadas actuales, redondeado hacia arriba a segundos enteros y limitado a 60. Cuando la puerta está inactiva, mantiene los mínimos históricos: 2 segundos en la ruta basada en bytes y 1 segundo en la ruta basada en estructura (que también incluye reason: "structure_limit").
• Esto puede ocurrir mientras otro chat pesado o una respuesta de streaming de larga duración aún está en curso.

El cuerpo de la respuesta basada en bytes es:

{
  "error": {
    "message": "Chat admission capacity is temporarily unavailable. Retry shortly.",
    "type": "server_error",
    "code": "chat_admission_busy"
  }
}

La respuesta basada en estructura utiliza el mismo tipo y código, con el mensaje Local chat admission capacity is busy for this structurally heavy request; upstream provider routing was not attempted. Retry shortly. y reason: "structure_limit". Con los umbrales predeterminados, una solicitud se considera estructuralmente pesada cuando tiene al menos 200 mensajes, al menos 64 herramientas o al menos 32,000 tokens estimados, o cuando la estimación acotada de la estructura agota sus límites de 10,000 nodos visitados o una profundidad de 12.

Causa: Se trata de un descarte deliberado de carga dentro de OmniRoute, no de un fallo del proveedor ascendente. Cada proceso utiliza una protección local del proceso para reservar una capacidad pesada limitada antes de retener y analizar el cuerpo de una solicitud grande. Una concesión pesada permanece retenida durante toda la vida útil de una respuesta SSE.

#503-fanout: antes de esta corrección, la protección limitaba la simultaneidad a un NÚMERO fijo de solicitudes (OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT, valor predeterminado 1) independientemente de la memoria del host, por lo que la distribución en abanico de agentes de programación (varios subagentes/CLI, con cuerpos habitualmente > 256 KB) se reducía a una simultaneidad efectiva de ~1 y producía errores 503 con una carga completamente normal. Ahora la protección se autoajusta: está controlada por un presupuesto de BYTES de ingesta derivado automáticamente (OMNIROUTE_CHAT_MAX_INFLIGHT_BYTES), dimensionado a partir del límite real de memoria del proceso, y también consulta una señal activa de presión sobre los recursos, de modo que solo descarta carga cuando el host está realmente bajo presión de memoria, no simplemente porque haya llegado más de una solicitud pesada a la vez. El antiguo límite por cantidad (OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT) se sigue respetando, pero solo si se configura explícitamente.

Cuando la capacidad está ocupada, una solicitud pesada espera primero hasta OMNIROUTE_CHAT_ADMISSION_QUEUE_MS (valor predeterminado 2000; 0 deshabilita la espera) a que se libere un espacio antes de responder con el 503 reintentable. La espera acotada existe para que los clientes de estilo agente (OpenCode, Claude Code, Cursor) que distribuyen simultáneamente solicitudes secundarias pesadas serialicen la ráfaga en lugar de agotar todo su presupuesto de reintentos con rechazos inmediatos y detenerse en mitad de una tarea. La ocupación actual de concesiones pesadas, el presupuesto de bytes resultante y la gravedad de la presión activa se muestran en GET /api/monitoring/health → chatAdmission (inflightBytes, maxInflightBytes, budgetSource, pressureSeverity, countCapEnabled); compruebe estos valores antes de modificar cualquier variable de entorno. Configuración → Resiliencia → Cola de solicitudes → Solicitudes simultáneas no controla esto; esa opción rige un mecanismo independiente de cola de solicitudes del proveedor.

Solución:

1. Primero, vuelva a intentarlo. Los clientes deben respetar Retry-After y utilizar retroceso en lugar de repetir inmediatamente la solicitud.
2. Compruebe /api/monitoring/health → chatAdmission antes de ajustar nada. countCapEnabled: false y un valor generoso de maxInflightBytes significan que el presupuesto derivado automáticamente ya está haciendo su trabajo; un valor de pressureSeverity de high/critical significa que el host realmente tiene poca memoria; esto no puede solucionarse mediante una variable de entorno de admisión: se necesita más RAM o una carga de trabajo menor.
3. Solo si /api/monitoring/health muestra que el presupuesto derivado automáticamente es realmente demasiado pequeño para el host (algo poco frecuente, ya que se escala desde contenedores hasta bare metal), sobrescríbalo directamente con OMNIROUTE_CHAT_MAX_INFLIGHT_BYTES en lugar de volver al límite heredado por número de solicitudes.

Consulte la referencia de variables de entorno para conocer la configuración de admisión oficial.

---

Taxonomía opcional de fallos de RAG / LLM (16 problemas)

Algunos usuarios de OmniRoute colocan el gateway delante de pilas de RAG o agentes. En esas configuraciones es común observar un patrón extraño: OmniRoute parece funcionar correctamente (proveedores activos, perfiles de enrutamiento correctos, sin alertas de límites de solicitudes), pero la respuesta final sigue siendo incorrecta.

En la práctica, estos incidentes suelen proceder del pipeline de RAG posterior, no del propio gateway.

Si desea utilizar un vocabulario compartido para describir esos fallos, puede usar WFGY ProblemMap, un recurso de texto externo con licencia MIT que define dieciséis patrones recurrentes de fallos de RAG / LLM. A grandes rasgos, abarca:

• desviación de la recuperación y límites de contexto defectuosos
• índices y almacenes vectoriales vacíos u obsoletos
• discrepancias entre embeddings y semántica
• problemas de ensamblado de prompts y de la ventana de contexto
• colapso lógico y respuestas excesivamente confiadas
• fallos en cadenas largas y en la coordinación de agentes
• desviación de la memoria y los roles en sistemas multiagente
• problemas de orden de despliegue e inicialización

La idea es sencilla:

1. Cuando investigue una respuesta incorrecta, registre:
   • la tarea y la solicitud del usuario
   • la combinación de ruta o proveedor en OmniRoute
   • cualquier contexto de RAG utilizado posteriormente (documentos recuperados, llamadas a herramientas, etc.)
2. Asigne el incidente a uno o dos números de WFGY ProblemMap (No.1 … No.16).
3. Guarde el número en su propio panel, manual operativo o sistema de seguimiento de incidentes junto a los registros de OmniRoute.
4. Utilice la página correspondiente de WFGY para decidir si necesita cambiar su pila de RAG, el recuperador o la estrategia de enrutamiento.

El texto completo y las recetas concretas están disponibles aquí (licencia MIT, solo texto):

README de WFGY ProblemMap

Puede ignorar esta sección si no ejecuta pipelines de RAG o agentes detrás de OmniRoute.

---

Problemas conocidos de v3.8.0

Problemas específicos de la versión v3.8.0 y sus soluciones provisionales actuales. Si se incluye una corrección en un parche posterior, la entrada se actualizará o eliminará.

Fallos de autenticación de Devin CLI

Síntomas:

• “Devin CLI no encontrado” o “falló la autenticación” al invocar herramientas respaldadas por Devin
• La comprobación del entorno de ejecución de la CLI informa installed=false

Causas:

• CLI_DEVIN_BIN apunta a una ruta que no existe
• Devin CLI no está instalado en el host

Solución:

1. Instale Devin CLI para su plataforma
2. Establezca CLI_DEVIN_BIN=/usr/local/bin/devin (o la ruta real) en .env
3. Reinicie OmniRoute y vuelva a realizar la prueba desde Panel → Herramientas de CLI

Tiempo de espera del modelo bloqueado (restablecimiento manual)

Síntomas:

• Un modelo continúa apareciendo en tiempo de espera incluso después de que haya pasado la hora de vencimiento
• Las solicitudes siguen omitiendo el modelo en el enrutamiento combinado, aunque la marca de tiempo esté en el pasado

Restablecimiento manual:

• Panel: Configuración → Tiempos de espera de modelos → haga clic en Volver a habilitar en la tarjeta afectada
• API: DELETE /api/resilience/model-cooldowns con encabezados de autenticación de administración

La conexión con el proveedor Command Code falla con un error 403

Síntomas:

• Error 403 al probar la conexión con el proveedor Command Code
• La tarjeta del proveedor muestra “no autorizado” después de añadirlo de nuevo

Causa: El flujo de OAuth no se completó (no se recibió la devolución de llamada o no se guardó el token).

Solución:

• Ejecute omniroute providers desde la CLI para volver a activar el flujo de OAuth, o
• Vuelva a ejecutar OAuth desde Panel → Proveedores → Command Code → Volver a conectar

ModelScope devuelve tiempos de espera 429 agresivos

Síntomas:

• Tiempos de espera muy breves o inmediatos en ModelScope después de una pequeña ráfaga de solicitudes
• El enrutamiento combinado omite ModelScope antes de lo esperado

Causa: ModelScope emite encabezados Retry-After específicos del proveedor. v3.8.0 incluye un tratamiento específico para esos encabezados, por lo que las versiones anteriores los interpretan erróneamente como indicaciones genéricas de límite de solicitudes.

Solución:

• Asegúrese de utilizar v3.8.0 o una versión posterior
• Compruebe que la opción useUpstream429BreakerHints esté habilitada en Configuración → Resiliencia

Falta OMNIROUTE_WS_BRIDGE_SECRET en producción

Síntomas:

• Error 401 en todas las solicitudes al puente WebSocket de Codex/Responses cuando se ejecuta en un host remoto de producción
• El protocolo de enlace del puente WebSocket se cierra inmediatamente después de conectarse

Causa: La variable de entorno OMNIROUTE_WS_BRIDGE_SECRET no está presente en el entorno de producción.

Solución:

1. Genere un secreto aleatorio: openssl rand -hex 32
2. Establezca OMNIROUTE_WS_BRIDGE_SECRET=<random-secret> en el entorno del servidor de producción (y en cualquier cliente que se comunique con el puente)
3. Reinicie OmniRoute

Responses API: modo en segundo plano degradado a síncrono

Síntomas:

• Advertencia registrada: background mode degraded to synchronous
• Una solicitud con background: true devuelve una respuesta síncrona normal en lugar de un identificador de trabajo en segundo plano

Causa: v3.8.0 degrada intencionadamente background: true en Responses API a una ejecución síncrona y, al mismo tiempo, emite una advertencia. La ejecución asíncrona completa en segundo plano es una funcionalidad prevista para el futuro.

Solución:

• Ajuste el cliente para realizar la llamada sin background, o
• Espere a una versión posterior que incluya el modo asíncrono completo en segundo plano (consulte el registro de cambios)

---

Inicio lento / Tiempo de espera de disponibilidad

Si la CLI muestra ⚠ Server did not respond within 60s, pero el servidor realmente funciona, el tiempo asignado a la sonda de disponibilidad es demasiado corto para su entorno.

Esto suele ocurrir en Windows (antivirus, observadores del sistema de archivos) o en contenedores con cargas de trabajo pesadas durante el inicio.

Solución — aumente el tiempo asignado:

# Mediante una variable de entorno (se mantiene entre inicios):
export OMNIROUTE_READY_TIMEOUT_MS=180000   # 3 minutos
omniroute serve

# Mediante una opción de la CLI (solo para esta ejecución):
omniroute serve --ready-timeout 180000

El valor predeterminado es 60 000 ms (60 s). La advertencia es solo informativa; el servidor continúa iniciándose en segundo plano y estará accesible cuando se complete el arranque.

Consulte docs/reference/ENVIRONMENT.md para obtener todos los detalles sobre OMNIROUTE_READY_TIMEOUT_MS.

---

¿Sigue atascado?

• Incidencias de GitHub: github.com/diegosouzapw/OmniRoute/issues
• Arquitectura: Consulte docs/architecture/ARCHITECTURE.md para obtener detalles internos
• Referencia de la API: Consulte docs/reference/API_REFERENCE.md para ver todos los endpoints
• Panel de estado: Consulte Panel → Estado para ver el estado del sistema en tiempo real
• Traductor: Use Panel → Traductor para depurar problemas de formato

---

Código fuente de OmniRoute (a58000c7685f)