ReplyRabbit 故障排除
大多数 ReplyRabbit 问题归结为以下三种之一:API 密钥缺失或错误、使用您的计划层级不允许的提供商,或 FreeScout 缓存过期。请按下面的匹配部分逐一处理,每个问题先列出症状,然后给出修复方法。
不生成草稿
症状: 您打开一个对话,但没有出现 AI 草稿,似乎什么也没发生。
修复: 打开邮箱的 ReplyRabbit 设置(邮箱 > 设置 > ReplyRabbit)并确认已选择提供商且已设置其 API 密钥。在免费版中,唯一可用的提供商是 OpenAI,因此如果你选择了其他提供商,请切换回 OpenAI 或升级。然后检查 ReplyRabbit 是否已为你正在使用的邮箱启用,因为草稿只会为已启用的邮箱生成。
API 密钥或提供商无效错误
症状: 您看到错误,提示密钥无效、身份验证失败或无法访问提供商。
修复: 重新检查密钥是否有拼写错误和多余空格,确认它是你实际选择的提供商的密钥(OpenAI 密钥无法用于 Anthropic),并确保该密钥在提供商仪表板上仍有额度和访问权限。余额耗尽或访问被撤销的密钥会产生相同错误。
升级 PHP 后的错误
症状: 在服务器升级后(例如,升级到 Ubuntu 26.04 和 PHP 8.5), 测试连接 失败或后台作业停止,并且 FreeScout 日志显示以以下内容结尾的消息 is deprecated since 8.5.
修复: 从 管理 > 模块,然后运行 php artisan freescout:clear-cache 和 php artisan queue:restart。ReplyRabbit 支持 PHP 8.0 到 8.5。请参阅 修复 FreeScout 中的 "deprecated since 8.5" 错误 以找出消息来自哪个模块。
ReplyRabbit 菜单缺失
症状: 安装后,ReplyRabbit 未出现在 FreeScout 菜单或设置中。
修复: 首先确保模块在 管理 > 模块。然后从你的 FreeScout 根目录清除缓存:
php artisan freescout:clear-cache如果仍然缺失,请检查用户的权限:无权访问相关邮箱或管理员设置的用户将看不到 ReplyRabbit 选项。
草稿在一段时间后停止
症状: 草稿起初有效,但在当月晚些时候停止生成。
修复: 免费层每月允许 10 份草稿。达到该限制后,草稿会暂停直到下个月。Pro 和 Team 没有草稿限制。在任何计划中,如果邮箱的 每月令牌预算 已用完,因此也请检查该设置(0 表示无预算)。
提示缓存不会改变每月 token 计数
症状: 重复的草稿似乎符合提供商提示缓存的条件,但 ReplyRabbit 的令牌用量仍显示完整的输入和输出总量。
修复: 这是预期行为。ReplyRabbit 保持每月预算保守,并计算总令牌数,即使提供商对缓存输入的计费方式不同。提供商缓存节省取决于提供商、模型、重复的提示前缀和提供商报告。Anthropic 缓存控制仅用于符合条件的重复草稿工作,在不支持时回退到正常生成。
Linear 工单未被创建
症状: 检测到下一步行动,但未创建 Linear 工单。
修复: 在 ReplyRabbit 设置中,检查 Linear API 密钥、选定的团队,以及工单是否处于等待确认的待处理状态。还要确认您的层级包含 Linear:手动创建 Linear 工单是 Pro 功能,自动创建工单是 Team 功能。
Jira 问题未被创建
症状: 对话需要工程工作,但未创建 Jira 问题。
修复: 在 ReplyRabbit 设置中,确认 Jira 被选为邮箱问题跟踪器。检查 Jira Cloud 站点 URL、账户电子邮件、API 令牌、默认项目和默认问题类型。还要确认您的层级包含问题创建:手动创建 Jira 问题是 Pro 功能,自动创建问题是 Team 功能。有关完整设置路径,请参阅 Jira 集成.
工作流标签未被应用
症状: 您预期会看到诸如 rr_priority_critical, rr_no_reply_needed,或 rr_linear_issue_created,但该对话没有 ReplyRabbit 标签。
修复: 打开邮箱的 ReplyRabbit 设置并确认 启用工作流同步 和 应用 FreeScout 标签 已开启,在 工作流标签 部分。如果信号标签缺失,请确认 AI 信号 开启并且对话已被分析。如果 Linear 标签缺失,请确认对话有 ReplyRabbit 创建的 Linear 问题。
如果 FreeScout Workflows 配方没有触发,首先确认 ReplyRabbit 正在添加预期的 FreeScout 标签。然后测试你安装的 Workflows 模块是否响应程序化标签更改。ReplyRabbit 可以应用标签,但 Workflows 模块控制配方是否从该标签更改运行。
知识来源:草稿未使用我的帮助页面、知识库、产品或之前的回复
症状: 草稿忽略了你确定存在于帮助页面、知识库、产品列表或早期回复中的信息。
修复: 从回复编辑器中草稿下方的行开始。它列出草稿使用了什么,例如“包含:2 个帮助页面、1 篇知识库文章、3 条此前给该客户的回复”。点击它可查看链接,以及每个已开启但未添加任何内容的来源的说明:
- 已开启但尚未索引任何内容: 索引尚未完成。检查队列工作进程(见下文),然后等待索引完成。
- 没有找到与此消息匹配的内容: 来源没问题,但其中没有任何内容与该客户的消息足够接近。添加或改进能回答此类问题的内容。
- 索引超过搜索限制: 一旦索引超过 6,000 个索引部分,仅运行关键词匹配,而不是基于含义的匹配。移除您不需要的来源以使其回到限制以下。
- 你的计划不包含它: 该来源在你当前的计划中不可用。
- 知识库模块未安装或未激活: 在 管理 > 模块.
设置状态警告
邮箱设置中的设置状态横幅现在会在以下情况发出警告:
- 队列工作进程似乎没有运行。 没有它,索引和自动草稿永远不会完成。FreeScout 通过 cron 作业运行队列
php artisan schedule:run或一个queue:work流程,因此请确保已设置其中之一。 - 未启用任何知识源。 在 Mailbox settings, Knowledge sources 中至少开启一项。
- 某个源已开启但尚未索引。 让索引完成。
网站来源
- 爬取默认在 200 页处停止,源现在会说明这一点,并提供一个按钮来提高限制。之后保存您的设置,然后再次爬取。
- 无法读取的页面会连同原因一起计数,例如被网站阻止(403)、未找到(404)、请求过多(429)、服务器错误、过大或没有可读文本(通常是用 JavaScript 构建的页面)。请让您的主机允许爬虫通过,或将来源指向不需要 JavaScript 的页面。
- 非常长的页面会缩短到约 24,000 个字符。当语义匹配开启时,源会显示有多少页面被缩短。如果您需要的内容靠近末尾,请拆分长页面。
Outline 和基于含义的匹配
- Outline 同步在 1,000 个文档处停止。超过该数量的文档不会被同步。
- 基于含义(语义)的匹配需要嵌入提供商。一些嵌入模型尚未针对仅含义匹配进行校准并会显示警告,因此如果看到警告,请切换到其他嵌入模型。
仍然卡住?