# 故障排查

> 先判断失败发生在哪一层，再排查登录、模型、文件、知识库、MCP、插件、批量任务与自动化。

Canonical page: /troubleshooting



<Takeaways>
  <li>
    先保留失败现场，不连续点击重试
  </li>

  <li>
    从账号、模型、工作区、能力到任务逐层缩小范围
  </li>

  <li>
    同时检查界面状态、执行记录和真实产物
  </li>
</Takeaways>

遇到问题时，先记录发生时间、当前入口和最后一个成功步骤。反馈问题可使用 **设置 → 通用设置 → 导出诊断包**；不要附完整访问密钥、Cookie、OAuth 凭证或含隐私的项目内容。

## 五分钟快速定位 [#五分钟快速定位]

<Checklist title="先做这些检查">
  <li>
    确认 Astravia、网络和目标外部服务当前可用。
  </li>

  <li>
    新建一个短会话，显式选择模型，只发送一条最小消息。
  </li>

  <li>
    确认会话绑定的工作目录真实存在，当前系统用户可访问。
  </li>

  <li>
    暂时移除不必要的 MCP、技能、附件和长上下文，缩小变量。
  </li>

  <li>
    打开失败任务的会话或历史，记录原始错误和发生时间。
  </li>
</Checklist>

| 现象         | 可能所在层          | 第一项检查                       |
| ---------- | -------------- | --------------------------- |
| 任何会话都无法回复  | 登录、模型或网络       | 新会话中显式选择一个已验证模型             |
| 只有某个项目失败   | 工作目录、项目指令或权限   | 路径是否存在，沙盒是否允许目标动作           |
| 只有某个外部工具失败 | MCP 进程、URL 或授权 | **能力 → 我的** 中的连接和启用状态       |
| 显示成功但没有文件  | 任务验收条件或路径      | 检查工具记录和目标目录，而不是最终回复         |
| 到点未执行      | 自动化状态或本机环境     | Astravia 是否运行、设备是否睡眠、任务是否启用 |
| 多个子任务同时失败  | 共享提示、模型限流或目录模式 | 把并发降到 1，并打开一个代表性会话          |

## 按现象排查 [#按现象排查]

<Accordions type="single">
  <Accordion id="login-failed" title="登录失败或授权链接失效">
    **先确认**：系统时间正确，网络可访问认证服务，浏览器完成授权后能够返回应用。

    **如何恢复**：在登录弹层中使用 **重新授权** 或 **重新打开链接**。企业账号仍失败时，记录发生时间和组织信息后联系组织管理员，不要把浏览器 Cookie 发到问题报告。
  </Accordion>

  <Accordion id="model-failed" title="模型无法调用">
    **先确认**：

    1. 会话或任务中已显式选择可用模型，或已设置默认模型。
    2. **设置 → 模型配置** 中 API Key、Base URL、模型 ID 与 API 类型正确。
    3. 网络与代理可访问对应上游，账户没有触发配额或速率限制。
    4. 知识库加工场景已在 **知识库设置** 中执行 **测试连接**。

    **如何验证**：新建空白会话，只发送短消息。短消息成功而原任务失败时，再检查上下文长度、工具或任务专属模型。

    <Callout title="不要泄露密钥" type="warn">
      不要把完整访问密钥写进日志或问题报告。配置文件默认在 `~/.astravia/agent/models.json`。
    </Callout>
  </Accordion>

  <Accordion id="file-access" title="无法读取或写入项目文件">
    **先确认**：会话绑定了正确工作目录，目标路径仍存在，当前系统用户有权限，文件没有被其它程序锁定。

    **如何恢复**：先在「沙盒受限」内把任务缩小到工作区。确实需要更广访问时才切换为 **完全访问**，并重新核对允许修改的范围。不要用提升权限掩盖错误路径。
  </Accordion>

  <Accordion id="knowledge" title="知识库不整理或不检索">
    **先确认**：知识库总开关已开、处理模型已选且测试连接成功；查看待加工文件和 **整理记录**。

    **如何恢复**：对失败项使用 **重试失败文件**。清空 Wiki 只删除整理结果、保留原始文件，但会触发重新加工；操作前确认配额和时间成本。会话回答仍异常时，先问一个只依赖单份已完成资料的问题并核对来源。
  </Accordion>

  <Accordion id="mcp" title="MCP 工具不可用">
    **先确认**：在 **能力 → 我的** 中 MCP 已添加且启用，凭证或 OAuth 已完成。检查 `~/.astravia/agent/mcp.json` 中 command/url，stdio 命令在 PATH 中可执行，HTTP 地址可从当前网络访问。

    **如何验证**：使用 [MCP 最小验证任务](/product/mcp/#自动批准与排错) 先列出工具并调用一个只读工具。连接状态正常但没有工具时，检查服务端暴露项和当前会话是否已刷新能力。
  </Accordion>

  <Accordion id="plugin-load" title="插件加载失败">
    **先确认**：导入 zip 根目录包含 `plugin.json` 与构建产物（如 `dist/mf-manifest.json`）；`remoteName`、`expose`、`entry` 与 Vite 配置一致。

    **如何恢复**：重新构建并导入，再在 **启用与权限** 对话框中启用和授权。系统内置插件权限自动授予且不可改；外置插件只申请完成任务需要的权限。
  </Accordion>

  <Accordion id="claw" title="Claw / IM 无回复">
    **先确认**：**设置 → Claw** 总开关打开、活动渠道正确、对话模型可用，并保持 Astravia 运行。

    **如何恢复**：先发 `/help` 验证命令通道，再使用 **查看日志** 定位并按需 **重启**。命令通道正常但普通消息失败时，继续检查模型和渠道绑定。
  </Accordion>

  <Accordion id="batch-stop" title="批量任务状态异常或无法删除">
    **先确认**：打开一个失败子任务的会话，判断是共享提示、单目录结构、模型限流还是超时。删除运行中的批量项目前需要先 **停止**。

    **如何恢复**：单个失败优先使用失败项重试；大量相同失败先把并发降为 1 并验证代表性目录。停止会重置未完成任务的会话、产物和状态，已完成项是否保留以确认对话框为准。
  </Accordion>

  <Accordion id="automation" title="自动化到点没有执行或没有产物">
    **先确认**：Astravia 正在运行、设备未睡眠、任务已启用、系统时区和下次执行时间正确、工作目录没有移动。

    **如何恢复**：先暂停计划，使用 **立即执行** 暴露模型、路径和权限错误；同时检查执行历史与真实输出文件。验证通过后再启用，错过的时间点不会自动补跑。
  </Accordion>

  <Accordion id="runtime" title="Agent 里 Node、Python 或 Git 不可用">
    **先确认**：Astravia 内置环境与系统终端环境彼此独立。Git 面板使用的是 **应用环境** 里检测到的 Git，不一定等于终端里的 `git`。

    **如何恢复**：打开 **设置 → 应用环境**。对 Node / Python 执行获取或重装；Git 未安装时按页面给出的方式安装，再点 **重新检测**。然后在 **Astravia 会话** 中验证版本。
  </Accordion>

  <Accordion id="phone" title="手机连不上这台电脑">
    **先确认**：电脑上的 Astravia 仍在运行，**设置 → 远程连接** 没有报错。二维码或连接码大约 10 分钟就会更新，用过的码不能再用。出门后连不上时，看 **允许在外网访问** 是否打开，以及中继地址能否连通。

    **如何恢复**：点 **刷新** 重新配对。手动输入地址时，两端的 6 位验证码必须一致，并且网络不能把两台设备隔开。会话正常但 Android 没有桌面画面时，确认这部手机在线，并且它旁边电脑图标的右下角是绿色对勾。不要把二维码、连接码或密码发到问题报告里。详见[远程连接与移动端](/product/remote-control/)。
  </Accordion>
</Accordions>

## 提交可复现的问题 [#提交可复现的问题]

如果最小场景仍失败，请在 [GitHub Issues](https://github.com/maomaochong-ai/open-astravia/issues) 提供：

* Astravia 版本、操作系统和安装来源。
* 最小复现步骤、期望结果和实际结果。
* 问题发生时间，以及是稳定复现还是偶发。
* 已脱敏的原始错误、相关执行历史和诊断包。
* 一个不含私有数据的最小示例项目（确有必要时）。

安全问题不要公开披露利用细节或凭证，先阅读[安全与数据边界](/reference/security-and-data/)中的报告入口。

<Continue>
  <ContinueLink href="/product/models/" title="配置模型" description="核对服务商、模型 ID、默认项和验证方式。" />

  <ContinueLink href="/core/progress-results-and-recovery/" title="检查过程和结果" description="从工具、待办、后台任务和真实产物定位失败。" />

  <ContinueLink href="/reference/security-and-data/" title="安全与数据边界" description="了解凭证、文件、外部服务和安全报告要求。" />
</Continue>