故障排除
先确认问题发生在哪个表面：应用启动、会话、协作、编码、浏览器、插件、计划任务、站点或文件预览。保留原始错误、发生时间和当前版本，不要在状态未知时连续重试高影响操作。
页面或本地链接打不开
- 确认开发服务仍在运行，并使用启动输出中的实际端口。
localhost:3000与127.0.0.1:3105是不同服务；不要把临时预览端口写成固定产品链接。- 页面空白时检查终端构建错误和浏览器控制台，再刷新一次。
- 端口被占用时，停止旧进程或使用新端口，并更新当前链接。
任务似乎卡住
- 检查是否正在等待批准、文件选择或登录。
- 查看最后一条工具状态和常驻通知。
- 在编码终端运行一个低风险命令，确认工作区仍可响应。
- 能停止时先停止，再用范围更小的请求继续。
- 重启前记录未完成步骤和改动，避免恢复后重复执行外部操作。
浏览器无法打开或操作
- 检查当前版本和操作系统是否提供浏览器面板，并查看界面显示的不可用原因。
- 外部地址被拒绝时，核对站点允许范围；localhost 通常使用单独规则。
- 登录状态不存在时，确认当前使用的是共享、会话还是临时配置范围。
- 页面能看但无法输入时，检查站点权限和当前会话可用的输入能力，不要绕过权限限制。
- 控制台或网络信息缺失可能是当前版本未提供对应工具，不等于页面没有错误。
日常 Chrome 无法连接
- 打开 设置 > 协作 > 浏览器，确认当前选择的是“接管我的日常 Chrome”。
- 检查 Playwright Extension 是否已安装，并在设置页选择“重新检测”。
- 第一次浏览器任务需要在 Chrome 连接页点一次 Allow；没有完成时，任务会继续等待。
- 关闭静默连接后仍担心旧访问权有效时，在扩展中重新生成 token，并重启相关任务。
联网搜索不可用
- 打开 设置 > AI 服务 > 联网搜索，确认当前通道不是“未就绪”。
- EvoMap 搜索复用账号密钥；Tavily 需要 API Key；Google 需要 API Key 和搜索引擎 ID。
- 遇到密钥拒绝、限流、额度耗尽、超时或服务不可用时，先核对供应商状态，再切换到另一个已配置通道。
- 切换后重新发起搜索，并确认工具结果出现新的可点击来源。
附加应用失败
- 确认目标窗口仍然打开，并从输入框中的
@应用重新选择。 - macOS 需要 14 或更高版本和屏幕录制权限；授权后可能需要重启 EvoX。
- 读取档还可能需要辅助功能权限；有些应用不会暴露可读界面文字，此时退回观察档。
- 系统保护的窗口会持续拒绝抓取，不要无休止重试，改为截图或选择其他窗口。
- “操作”档只在当前连接支持时出现；没有按钮不代表观察和读取也不可用。
插件或 MCP 不可用
- 用
/mcp查看服务器是否安装、启用和已连接。 - 回到插件详情执行连接测试，确认凭证仍有效。
- 内置生图和语音插件需要先完成供应商配置，取消配置不会启用插件。
- 工具列表为空时检查插件聚焦方式、当前模式和服务器日志。
- 外部写入结果未知时，先在目标服务中核对，不自动重试。
计划任务没有运行
- 确认任务处于启用状态，下一次运行时间和时区正确。
- 本地项目任务要求计算机开机、EvoX 运行且目录仍存在。
- 检查最近运行记录、模型与插件连接、文件权限和网络权限。
- 定时任务不会自动创建 worktree。若编码定时任务使用的是 EvoX 管理的隔离任务工作副本，请先停用任务并保存改动，再到编码模式的任务面板清理该工作副本。
文件没有出现或预览失败
- 产物必须来自真实文件或明确的预览工具结果；仅有回复文字不会自动创建文件。
- 确认输出路径、文件扩展名和当前版本。
- 办公文件或 PDF 预览异常时重新渲染，并检查字体、分页和资源引用。
- HTML 空白时检查相对资源、脚本错误和是否错误引用本机绝对路径。
诊断和日志
设置的高级页面提供后台服务状态、诊断和维护入口。报告问题时附上：
- EvoX 版本和操作系统；
- 发生时间、所在模式和复现步骤；
- 脱敏后的错误和相关日志；
- 预期结果与实际结果；
- 是否可以稳定复现，以及已经尝试的恢复动作。
共享日志前删除密钥、令牌、客户数据和本地敏感路径。使用 /feedback 或问题反馈入口时，可以选择是否附带当前会话。
EvoX 文档 · 功能 · 参考资料