Resolución de problemas de ReplyRabbit
La mayoría de los problemas de ReplyRabbit se reducen a una de tres cosas: una clave de API faltante o incorrecta, usar un proveedor que tu nivel de plan no permite, o una caché de FreeScout obsoleta. Revisa la sección correspondiente a continuación, donde cada problema enumera primero el síntoma y luego la solución.
No se genera ningún borrador
Síntoma: abres una conversación, pero no aparece ningún borrador de IA y parece que no sucede nada.
Solución: abre la configuración de ReplyRabbit del buzón (Buzón > Configuración > ReplyRabbit) y confirma que hay un proveedor seleccionado y que su clave de API está configurada. En el plan Free el único proveedor disponible es OpenAI, así que si elegiste otro, vuelve a OpenAI o mejora tu plan. Luego comprueba que ReplyRabbit está activado para el buzón en el que trabajas, ya que los borradores solo se generan para los buzones activados.
Error de clave de API no válida o del proveedor
Síntoma: ves un error que menciona una clave no válida, un fallo de autenticación o un proveedor que no se puede alcanzar.
Solución: vuelve a comprobar la clave por errores tipográficos y espacios sobrantes, confirma que es la clave del proveedor que realmente seleccionaste (una clave de OpenAI no funcionará con Anthropic), y asegúrate de que la clave aún tenga crédito y acceso en el panel del proveedor. Una clave sin saldo restante o con acceso revocado produce el mismo error.
Errores después de actualizar PHP
Síntoma: después de una actualización del servidor (por ejemplo, a Ubuntu 26.04 con PHP 8.5), Probar conexión falla o las tareas en segundo plano se detienen, y el registro de FreeScout muestra mensajes que terminan en is deprecated since 8.5.
Solución: mantén ReplyRabbit y tus otros módulos actualizados desde Gestionar > Módulos, luego ejecuta php artisan freescout:clear-cache y php artisan queue:restart. ReplyRabbit es compatible con PHP 8.0 a 8.5. Consulta Corregir errores de "deprecated since 8.5" en FreeScout para encontrar de qué módulo proviene un mensaje.
Falta el menú de ReplyRabbit
Síntoma: ReplyRabbit no aparece en los menús ni en la configuración de FreeScout después de instalarlo.
Solución: primero asegúrate de que el módulo está activado en Gestionar > Módulos. Luego vacía la caché desde la raíz de tu FreeScout:
php artisan freescout:clear-cacheSi aún falta, revisa los permisos del usuario: un usuario sin acceso al buzón correspondiente o a la configuración de administración no verá las opciones de ReplyRabbit.
Los borradores se detuvieron después de un tiempo
Síntoma: los borradores funcionaron al principio y luego dejaron de generarse más adelante en el mes.
Solución: el nivel Free permite 10 borradores al mes. Una vez que alcanzas ese límite, los borradores se pausan hasta el mes siguiente. Pro y Team no tienen límite de borradores. En cualquier plan, los borradores también se pausan si el Presupuesto mensual de tokens está agotado, así que comprueba también ese ajuste (0 significa sin presupuesto).
La caché de prompts no cambia el recuento mensual de tokens
Síntoma: los borradores repetidos parecen aptos para el almacenamiento en caché de prompts del proveedor, pero el uso de tokens de ReplyRabbit sigue mostrando el total completo de entrada y salida.
Solución: esto es esperado. ReplyRabbit mantiene los presupuestos mensuales conservadores y cuenta los tokens totales, incluso cuando un proveedor factura la entrada en caché de forma diferente. Los ahorros de caché del proveedor dependen del proveedor, el modelo, los prefijos de prompt repetidos y los informes del proveedor. El control de caché de Anthropic se usa solo para trabajo de borradores repetidos elegible y recurre a la generación normal cuando no es compatible.
No se están creando tickets de Linear
Síntoma: se detectan las próximas acciones, pero no se crea ningún ticket de Linear.
Solución: en la configuración de ReplyRabbit, comprueba la clave de API de Linear, el equipo seleccionado y si los tickets están en un estado pendiente esperando confirmación. Confirma también que tu nivel incluye Linear: la creación manual de tickets de Linear es una función Pro, y la creación automática de tickets es una función Team.
No se están creando incidencias de Jira
Síntoma: una conversación necesita trabajo de ingeniería, pero no se crea ninguna incidencia de Jira.
Solución: en la configuración de ReplyRabbit, confirma que Jira está seleccionado como gestor de incidencias del buzón. Comprueba la URL del sitio de Jira Cloud, el correo de la cuenta, el token de API, el proyecto predeterminado y el tipo de incidencia predeterminado. Confirma también que tu nivel incluye la creación de incidencias: la creación manual de incidencias de Jira es una función Pro, y la creación automática de incidencias es una función Team. Para la ruta de configuración completa, consulta Integración con Jira.
Las etiquetas de Workflow no se están aplicando
Síntoma: esperabas etiquetas como rr_priority_critical, rr_no_reply_needed, o rr_linear_issue_created, pero la conversación no tiene etiquetas de ReplyRabbit.
Solución: abre la configuración de ReplyRabbit del buzón y confirma Activar la sincronización de flujos de trabajo y Aplicar etiquetas de FreeScout están activos en el Etiquetas de Workflow sección. Si faltan las etiquetas de señal, confirma Señales de IA está activado y la conversación se ha analizado. Si faltan las etiquetas de Linear, confirma que la conversación tiene una incidencia de Linear creada por ReplyRabbit.
Si las recetas de FreeScout Workflows no se activan, primero confirma que ReplyRabbit está añadiendo la etiqueta de FreeScout esperada. Luego prueba si tu módulo Workflows instalado reacciona a los cambios de etiquetas programáticos. ReplyRabbit puede aplicar las etiquetas, pero el módulo Workflows controla si una receta se ejecuta a partir de ese cambio de etiqueta.
Fuentes de conocimiento: un borrador no usó mis páginas de ayuda, la Base de conocimiento, los productos ni respuestas anteriores
Síntoma: un borrador ignoró información que sabes que está en tus páginas de ayuda, Base de Conocimiento, lista de productos o respuestas anteriores.
Solución: comienza con la línea debajo del borrador en el editor de respuestas. Enumera lo que usó el borrador, por ejemplo "Incluido: 2 páginas de ayuda, 1 artículo de la base de conocimiento, 3 respuestas anteriores a este cliente". Haz clic en ella para ver los enlaces, además de una nota para cada fuente activada que no aportó nada:
- Activado pero aún no se ha indexado nada: la indexación no ha terminado. Comprueba el worker de la cola (ver abajo) y luego espera a que se complete la indexación.
- No hay una buena coincidencia para este mensaje: la fuente está bien, pero nada en ella coincidió lo suficiente con el mensaje de este cliente. Agrega o mejora contenido que responda a este tipo de pregunta.
- Índice por encima del límite de búsqueda: una vez que el índice supera las 6.000 secciones indexadas, solo se ejecuta la coincidencia por palabras clave, no la coincidencia por significado. Elimina las fuentes que no necesites para volver a estar por debajo del límite.
- Tu plan no lo incluye: esa fuente no está disponible en tu plan actual.
- El módulo Base de conocimiento no está instalado o activo: instálalo o actívalo en Gestionar > Módulos.
Advertencias del estado de configuración
El aviso de estado de configuración en los ajustes del buzón ahora advierte cuando:
- El worker de la cola no parece estar en ejecución. La indexación y los borradores automáticos nunca terminan sin él. FreeScout ejecuta la cola mediante el cron job
php artisan schedule:runo unaqueue:workproceso, así que asegúrate de que uno de ellos esté configurado. - No hay ninguna fuente de conocimiento activada. Activa al menos una en Mailbox settings, Knowledge sources.
- Una fuente está activada pero aún no indexada. Deja que termine la indexación.
Fuentes del sitio web
- El rastreo se detiene en 200 páginas de forma predeterminada, y la fuente ahora lo indica, con un botón para aumentar el límite. Guarda tu configuración después y vuelve a rastrear.
- Las páginas que no se pueden leer se cuentan con un motivo, por ejemplo bloqueada por el sitio (403), no encontrada (404), demasiadas solicitudes (429), un error del servidor, demasiado grande o sin texto legible (a menudo una página creada con JavaScript). Pide a tu proveedor de alojamiento que deje pasar al rastreador o apunta la fuente a páginas que no necesiten JavaScript.
- Las páginas muy largas se acortan a unos 24.000 caracteres. Cuando la coincidencia semántica está activada, la fuente muestra cuántas páginas se acortaron. Divide las páginas largas si la parte que necesitas está cerca del final.
Outline y coincidencia basada en significado
- La sincronización de Outline se detiene en 1.000 documentos. Los documentos más allá de esa cifra no se sincronizan.
- La coincidencia basada en significado (semántica) necesita un proveedor de embeddings. Algunos modelos de embedding aún no están calibrados para coincidencias solo de significado y muestran una advertencia, así que cambia a un modelo de embedding diferente si la ves.
¿Sigues atascado?