# 故障排查

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

## 记录问题与已有结果

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

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

## 从症状找到对应检查

| 你看到的情况 | 第一个检查 | 继续阅读 |
| --- | --- | --- |
| 找不到功能入口 | 桌面/Web、账号角色和当前页面 | [运行设置](/docs/runtime) |
| 保存设置后行为没变 | 修改范围与当前会话的明确选择 | [配置作用范围](/docs/runtime) |
| 普通回答也失败 | 当前模型与服务测试 | [模型排错](/docs/model-troubleshooting) |
| 能回答却不能执行工具 | 工具配置、权限和运行依赖 | [权限与审批](/docs/permissions) |
| MCP 详情没有目录 | 先区分 STDIO 与远程服务 | [本地 MCP](/docs/mcp-local)、[远程 MCP](/docs/mcp-remote) |
| 外部聊天没有回复 | 通道接收、配对、执行或投递哪步失败 | [消息通道](/docs/channels) |
| 定时任务成功却没有消息 | 输出文件与投递状态 | [调度参考](/docs/schedule-reference) |
| 迁移后历史不见了 | 实际状态目录、owner 与完整备份 | [备份恢复](/docs/backup) |

一次只复现一个问题。先保留当前错误和已有结果，再修改一个因素；同时换模型、改权限和重建连接，会让下一次成功或失败都难以解释。

## 识别已经发生的操作

“保存失败”“超时”和“结果待确认”需要分别处理。明确校验失败时修正输入；结果待确认时重新读取状态；外部调用超时则先查看目标系统是否已有记录。

例如报告已经写入但通知失败，应检查投递，不再生成一次报告。重复点击创建、发送或立即运行，可能让同一工作执行多次。

## 模型没有响应

打开 **设置 → 供应商** 测试服务与具体模型，再检查默认对话模型和 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` 查看后端日志。首次初始化与已有账号登录是不同流程；修改初始化密码变量不能重置已有密码。

## 显示结果待确认

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

## 重复失败时收集什么

记录发生时间、产品版本、运行引擎、目标功能和最后一个成功步骤。把原始错误文字保留下来，截图只截相关区域。涉及模型或通道时，说明使用的类型，不提供完整 Key 或 Token。

```text
环境    桌面版或 Web 版，版本号
入口    当前功能与操作步骤
预期    应该看到的结果
实际    完整错误文字与发生时间
范围    只有一个会话失败，还是新会话也失败
已查    已完成的检查及结果
产物    文件或外部记录是否已经产生
```

桌面版可使用应用提供的日志导出操作；服务器按[部署指南](/docs/deployment)查看对应服务日志。分享前移除凭据和无关私人内容，保留错误前后的必要上下文。

## 提交有效的问题报告

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

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