故障排查 | Nexus 文档

记录问题与已有结果

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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