# 故障排查

按模型、运行、权限、连接器和部署逐层定位问题。

## 记录问题与已有结果

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

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

## 模型没有响应

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

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

详细对照见[模型服务与默认模型](/docs/providers)。

## 一直显示执行中

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

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

## 文件不存在或打不开

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

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

## 浏览器或连接器不可用

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

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

## 定时任务没有运行

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

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

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

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

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

## 显示结果待确认

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

## 提交有效的问题报告

在[官方 Issues](https://github.com/nexus-research-lab/nexus/issues)提供最小复现步骤、预期行为、实际行为、版本与脱敏错误片段。截图只保留必要区域，隐藏账号凭据、私人文件和无关对话。

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