故障排查

记录问题与已有结果

记录发生时间、Nexus 版本、桌面或 Web 环境、对应 Agent/Room、操作和完整错误提示。先核对已有结果，再重试可能写入文件、发送消息或创建资源的操作。

排查期间保留状态目录、Agent 和账号，避免丢失诊断记录与已有成果。

模型没有响应

打开 设置 → 供应商 测试服务与具体模型，再检查默认对话模型和 Agent 指定模型。确认运行机器的网络、代理、模型 ID、Key 权限及额度。

如果文本测试成功而工具任务失败，检查模型的工具调用能力与运行协议。Web 部署中的 API 请求从服务器发出，应在服务器侧排查网络。

详细对照见模型服务与默认模型。

一直显示执行中

先查看哪里	可能需要处理什么
输入区的问题或审批卡片	补充信息或批准具体操作
工具执行记录	超时、命令失败、缺少依赖
Goal 面板	预算上限、额度限制或待解决阻塞
Room 成员与工作图	成员不可用、依赖未完成或验收未提交
服务连接状态	WebSocket 断开或宿主停止

停止或打断后，先检查已写入文件和外部结果，再决定下一步。打断不会自动回滚。

文件不存在或打不开

确认当前 Agent、会话与运行机器。Web Agent 无法直接读取访问者电脑的任意路径；先上传材料。预览不支持的类型可下载后用本机应用打开。

若 Agent 声称生成成功，请它检查实际路径和文件存在情况。权限不足应检查访问范围和审批，确认目标目录可访问后再重试。

浏览器或连接器不可用

桌面浏览器检查扩展是否已连接、版本是否兼容。连接器检查账号状态、配置和资源权限；自定义 MCP 检查地址、认证、本地命令及环境变量。

OAuth 已完成但页面未更新时先刷新状态；出现历史凭据无法读取时检查加密密钥，不要生成新密钥覆盖旧配置。参见连接器。

定时任务没有运行

检查任务是否启用、有效期是否结束、任务时区与下次执行时间是否正确，以及宿主是否在线。再查看运行历史，确认是否已经触发但等待审批。

收到重复消息时检查是否存在重复任务或多个后台实例。暂停重复入口后核对外部操作结果，确认重复来源已消除后再恢复运行。

页面空白、掉线或无法登录

桌面版先完整退出并重新启动，核对应用版本与本地服务日志。Web 版检查 Nexus 与 Control 是否运行、代理是否转发认证和 WebSocket，以及 HTTPS/Cookie/Origin 配置是否一致。

Compose 可运行 make logs 查看后端日志。首次初始化与已有账号登录是不同流程；修改初始化密码变量不能重置已有密码。

显示结果待确认

“请求失败”“已保存但刷新失败”和“结果未知”并不等价。先使用页面的刷新、核对或恢复入口读取当前状态，再决定是否发起新的修改。这样可以避免重复创建任务、反复授权或重复删除。

提交有效的问题报告

在官方 Issues提供最小复现步骤、预期行为、实际行为、版本与脱敏错误片段。截图只保留必要区域，隐藏账号凭据、私人文件和无关对话。

如果刚升级或迁移过数据，一并说明原版本、目标版本和迁移步骤。保留升级或迁移前的备份，以便恢复。