故障排除

遇到问题时，先找到与现象对应的条目。通常可以从当前会话、连接状态或设置中的诊断入口恢复，不必先重装应用或清空数据。

常见问题

以前的会话找不到了

按 ⌘ + K（macOS）或 Ctrl + K（Windows），用会话标题或消息中的关键词搜索。检查结果中的工作区与会话来源，避免打开另一个同名会话。

如果搜索没有找到，打开设置 > 对话历史，分别检查归档和回收站。已归档会话可以恢复；回收站中仍可恢复的会话也可以找回。会话状态快照是额外的恢复入口，但不能恢复项目中被删除的所有文件。

搜索失败或结果不完整时，先重试搜索，不要把它当作会话已经删除。

EvoX 打开了，但模型不回复

先查看会话是否正在等待批准、登录或工具结果。如果没有等待提示，打开设置 > AI 服务：

1. 确认当前会话使用的模型对应哪个提供方和连接实例。
2. 对该实例执行连接测试，保留测试中的原始错误。
3. 根据错误检查凭证、接口地址、模型名称或代理。
4. 测试通过后，在新会话发送一条简短请求，再回到原任务继续。

网页能打开不代表模型接口一定可达。诊断时优先测试正在使用的连接，不要一次更换所有模型配置。

设置已经保存，行为却没有变化

重新打开对应面板，区分“保存失败”和“已保存但未应用”。后者表示配置已经存下，但运行中的服务可能尚未采用它；使用面板提供的重试、服务状态或重启入口处理。

还要确认修改的是正确范围：界面语言不等于回复语言，风格预设的生效范围也可能只包含标题或交付文案。具体说明见设置。

功能或按钮没有出现

先检查 EvoX 版本、当前模式、操作系统与已连接能力。有些操作需要工作区，有些需要已有会话，还有些只在对应插件连接后可用。

如果界面说明该选项受组织策略限制，应按策略处理，不要通过修改本地配置绕过。某个模式没有按钮，也不代表其他模式中相似名称的功能具有相同行为。

没有收到任务完成通知

打开设置 > 外观，检查声音反馈与通知提示。声音、系统通知和桌宠气泡是不同的反馈渠道，打开其中一个不会自动开启另外两个。

macOS 通知权限被拒绝时，使用页面提供的系统设置入口授权，再返回 EvoX 重新检测。如果提示通知服务不可用，按提示查看日志或重启。任务是否完成，以会话中的状态和结果为准。

任务卡住或执行中断

先区分等待与失败

1. 查看最后一条工具记录，确认是在运行、等待批准、等待登录，还是已经报错。
2. 检查文件选择器、浏览器授权页和需要确认的弹窗。
3. 需要你提供信息时，直接补充缺少的材料；已经失败时，先处理明确的错误原因。
4. 没有进展且需要中断时，使用当前回复的停止按钮，或在会话输入框中按 Esc。

菜单或输入候选框打开时，Esc 会先处理当前界面。需要停止多个正在执行的任务时，可使用 ⌘ + Shift + K 或 Ctrl + Shift + K。紧急停止不会取消计划任务之后的调度。

停止后怎样继续

先查看已完成的步骤、文件改动和外部操作，再给出范围明确的后续指令。例如：

先检查上次任务已经完成的部分，列出剩余事项。保留现有文件，只继续未完成的检查；涉及再次发送或发布时先告诉我。

停止不会撤销已经写入的文件、已经发送的消息或已经提交的外部请求。结果不明确时，先在目标服务中确认，避免重复操作。

如果仅原会话异常、其他会话正常，可以整理当前目标、已有结果和未完成事项，在新会话继续。不要假定新会话自动拥有旧会话的全部上下文。

蜂群只有部分任务完成

打开蜂群面板，分别查看失败、等待与已完成的分支。保留仍然适用的结果，处理失败原因后只补做未完成部分；如果各路已经完成但汇总缺失，请主智能体重新整合已有记录。

请求重试、任务重跑与重新汇总不是同一种恢复动作。递归任务有恢复入口时，先检查任务树和快照，不要把普通蜂群的重跑当作快照恢复。详见恢复与追加。

浏览器与联网搜索

浏览器面板打不开

打开设置 > 协作，查看内置浏览器的状态和不可用原因。使用页面提供的重试入口；如果涉及后台服务，前往高级设置查看诊断结果。

面板能打开但某个网站失败时，检查网址、网络与允许的站点范围。不要用放开所有站点的方式解决单一地址的访问问题。

浏览器里没有我原来的登录状态

先检查设置 > 协作 > 浏览器中的身份选择。EvoX 专属浏览器与日常 Chrome 使用不同环境，日常 Chrome 已登录不代表专属浏览器也已登录。

使用独立环境时，在该环境中完成登录；需要复用日常 Chrome 时，按使用日常 Chrome完成连接。还应检查浏览器的会话存储设置，以及是否清理过浏览数据。

日常 Chrome 一直等待连接

1. 确认选择了“接管我的日常 Chrome”，并且 Chrome 仍在运行。
2. 检查 Playwright Extension 是否安装，在 EvoX 中点击重新检测。
3. 首次发起浏览器任务时，在 Chrome 连接页完成 Allow 授权。
4. 返回原任务检查连接结果，再决定是否重试。

扩展安装与连接授权是两步。不要反复启动相同任务来替代授权。如果要撤销旧访问权，只关闭静默连接还不够，需要按扩展的说明重新生成 token。

联网搜索报错或没有来源

打开设置 > AI 服务 > 联网搜索，确认所选通道及配置状态。EvoMap 使用已有模型或内置通道凭证，Tavily 需要 API Key，Google 需要 API Key 与搜索引擎 ID。

凭证拒绝、额度不足、限流和网络超时应分别处理。需要切换通道时，选择另一个已经配置好的通道，再执行一次搜索。确认工具结果实际返回了来源，不要把没有来源的普通模型回答当作搜索成功。

插件与附加应用

插件已安装，但工具不可用

使用 /mcp 查看 MCP 状态，并回到插件详情核对启用状态、连接与凭证。已安装、已启用和已连接不是同一个状态。

1. 先完成插件要求的账号或模型服务配置。
2. 执行连接测试，处理登录过期或服务启动错误。
3. 确认当前任务可以使用该插件，再重试一个范围较小的操作。

生图或语音插件未完成供应商配置时，仅安装插件不能让它开始工作。工具仍未出现时，查看当前模式与工具可用范围，再收集相关诊断信息。详情见插件。

附加的应用窗口无法读取

确认目标窗口仍然打开，从输入框的 @应用 重新选择。macOS 上检查 EvoX 所需的屏幕录制权限；读取界面文字时还可能需要辅助功能权限。授权后按系统或应用提示重新打开 EvoX。

部分应用不会提供可读取的文字，受保护的窗口也可能无法捕获。此时可以改用你主动提供的截图或文件，而不是重复授权或无限重试。具体条件见附加应用。

编码与终端

终端无响应，或命令在错误的位置运行

先确认终端中是否仍有命令运行，以及它是否正在等待输入。不要在一个等待中的命令后继续粘贴新的指令。

在空闲终端中，可以使用以下只读命令核对目录和仓库状态：

pwd
git status

PowerShell 中也可以用 Get-Location 查看当前目录。git status 需要当前目录位于 Git 仓库中；“不是 Git 仓库”的提示不代表终端坏了。

如果使用独立工作副本，核对实际目录和分支，不要假设它与原项目目录共享所有未提交文件和依赖。命令表现异常时，先查看项目自己的安装与启动说明。

只有终端视图异常时，先尝试收起并重新打开面板。需要重启应用或后台服务前，先保存工作并处理仍在运行的任务。

终端找不到 EvoX 命令

打开设置 > 高级 > 命令行，刷新状态。如果显示缺失或需要修复，使用页面中的安装或修复按钮，再重新打开终端验证。

如果状态提示被其他命令覆盖，检查终端实际解析到的路径：

将结果与设置中显示的安装状态对照。不要直接删除不明来源的同名程序；它可能属于另一套已安装的工具。

本地预览链接打不开

确认项目的开发服务仍在运行，并使用本次启动输出里的地址与端口。服务重启后端口可能变化，旧链接不会自动跟随。

• 连接被拒绝：检查服务是否已启动、端口是否正确。
• 页面空白或报错：查看开发终端和页面控制台中的首个错误。
• 远程任务中的 localhost：它指向运行服务的那台机器，不一定是你当前电脑；需要对应的预览入口或端口转发。
• 端口被占用：先确认占用者，选择项目支持的其他端口，不要直接终止未知进程。

计划任务与文件

计划任务没有按时运行

确认任务已启用，核对下一次运行时间和时区，再打开最近一次运行记录。

本地任务需要计算机开机、EvoX 与所需服务可用，项目目录仍然存在。任务已开始但失败时，继续检查模型连接、插件授权和目录权限。睡眠、断网和目录移动与“定时配置错误”需要分别处理。

修改后可以在确认不会造成重复外部操作的前提下手动运行一次，检查结果。任务使用独立工作副本时，清理该目录前先暂停相关计划并保存改动。

回复说生成了文件，却找不到

先找实际文件路径或产物附件。回复中描述了文件内容，不代表文件已经写入磁盘。

核对文件属于哪个项目、工作副本或执行设备，再检查路径和文件名。文件在远程环境生成时，需要使用对应的下载或传输入口，不能只在本地同名目录中寻找。

文件存在，但预览不正常

先区分文件内容与预览器问题：用对应的本地应用打开同一个文件进行对照。

• 办公文件或 PDF 字体、分页异常：检查字体是否可用、资源是否完整；需要时重新导出。
• HTML 空白：检查脚本错误和相对资源路径，避免引用仅在生成机器上存在的绝对路径。
• 显示旧内容：确认打开的是最新文件或产物版本，再刷新预览。

重新生成前保留原文件，避免把预览问题误判为内容丢失。

诊断与恢复

打开设置 > 高级查看后台服务状态、健康摘要和配置检查。诊断会区分警告与失败，并为部分问题提供前往设置、授权或重启服务的入口。

建议按以下顺序处理：

1. 记录错误、发生时间与当前任务状态。
2. 运行诊断，优先处理与当前故障相关的失败项。
3. 完成修复后刷新检查，确认状态确实恢复。
4. 用一条简单请求验证，再继续原任务。

后台服务无法连接时，诊断仍可能显示桌面端获取的服务状态。“检查不可用”或超时不等于检查通过。

重启服务、清除历史和恢复初始设置是不同操作。不要把清空数据作为第一步；确实需要重置时，先备份重要文件，并阅读确认框中的删除范围。

反馈与日志

在应用菜单中打开问题反馈，或按 ⌘ + Shift + U（macOS）、Ctrl + Shift + U（Windows）。提交前审阅报告中的截图与诊断内容。

需要日志时，前往设置 > 高级中的服务详情，使用打开日志文件夹或复制诊断信息。不同安装与系统的路径可能不同，优先使用应用入口定位，不必猜测固定目录。应用菜单中的关于可用于查看版本。

报告中写清楚：

问题：我做了什么，出现了什么异常
环境：EvoX 版本、操作系统、所在模式
时间：发生时间与时区
步骤：如何从正常状态复现问题
预期：希望得到什么结果
实际：错误文字、截图或失败状态
已尝试：做过哪些恢复操作，结果如何

分享前检查日志、截图及复制的诊断信息，删除或遮盖 API Key、令牌、会话内容、客户资料，以及含用户名或内部项目名称的本地敏感路径，只保留排查需要的信息。不要把所有工作目录或完整聊天记录无差别打包上传。

/feedback 在会话中可能只是生成反馈请求的提示模板，不代表报告已经提交。以问题反馈窗口显示的提交结果为准。

EvoX 文档 · 功能 · 参考资料