跳到主要内容
文档导航

故障排除

本页按症状组织，帮助你在遇到问题时快速定位原因、执行非破坏性的检查步骤，并在需要时收集足够的信息提交 issue。请尽量从「先做这些检查」开始，避免一上来就删除本地数据。

Deskmate 仍处于 early access 阶段，部分行为可能在版本之间变化。遇到问题时，先确认是否已升级到最新版本。

先做这些检查

在深入排查具体症状之前，先快速过一遍下面的清单。多数常见问题都能在这一步定位：

  • 确认 Deskmate 是最新版本。
  • 确认网络可用。
  • 确认 provider 认证仍有效。
  • 确认 MCP server 来源可信，且能独立启动。
  • 确认本地数据已备份，再做任何破坏性操作。
  • 记录错误文案和发生时间，便于后续排查与提交 issue。

应用无法启动

可能原因：

  • 安装包损坏。
  • 操作系统安全策略阻止启动。
  • 原生依赖或运行时问题。
  • 上一次崩溃残留的状态。

处理步骤：

  1. 重新下载安装包。
  2. 校验文件完整性。
  3. 查看系统安全提示。
  4. 尝试从终端启动，以获取更详细的错误输出。
  5. 备份 ~/.deskmate/ 后，再尝试清理数据。

不同平台还需要分别确认：

  • macOS：检查 Gatekeeper 提示，确认下载来源可信。
  • Windows：检查 SmartScreen，确认安装包来源可信。

模型调用失败

常见症状：

  • 未认证。
  • token 过期。
  • 模型不存在。
  • provider 限流。
  • 网络错误。
  • 模型不支持工具调用。

处理：

  1. 打开 Provider 设置。
  2. 重新登录或更新 API key。
  3. 选择应用内列出的模型。
  4. 换用支持工具调用的模型。
  5. 降低并发或稍后重试。
  6. 查看日志中的 provider 错误。

MCP 连接失败

常见症状：

  • server disconnected。
  • auth required。
  • 工具列表为空。
  • 调用工具失败。

处理：

  1. 检查 MCP server 配置。
  2. 检查命令路径和环境变量。
  3. 重新授权。
  4. 查看 server 的 stderr 或 Deskmate 日志。
  5. 确认 Agent 已启用该 server。
  6. 使用只读工具先做一次测试。

工具执行失败

工具执行失败时，先确认失败的是哪一类工具，再按下面的清单逐项检查。

Shell 命令失败

检查：

  • 命令是否存在。
  • 当前工作目录是否正确。
  • 环境变量是否缺失。
  • 命令是否需要交互输入。

文件读写失败

检查：

  • 路径是否存在。
  • 是否有读写权限。
  • 文件是否被其它程序占用。
  • Agent 是否试图访问不该访问的位置。

Web 工具失败

检查：

  • URL 是否可访问。
  • 网站是否需要登录。
  • 网络是否被代理或防火墙阻断。
  • 下载来源是否有效。

计划任务失败

检查：

  • 应用是否在计划时间运行。
  • Schedule 是否启用。
  • Provider 凭证是否有效。
  • MCP server 是否可用。
  • 任务 prompt 是否过于宽泛。
  • 是否触发 provider 限流。

建议：

先把 schedule 的 prompt 复制到普通 session 里试跑，确认可用后再恢复计划任务。

数据或会话异常

常见症状：

  • Agent 消失。
  • 会话加载失败。
  • 历史消息异常。
  • 升级后数据不兼容。

处理：

  1. 不要立即删除 ~/.deskmate/。
  2. 退出应用。
  3. 备份完整的 ~/.deskmate/。
  4. 查看 release notes 中是否提到数据迁移。
  5. 提交 issue 时，附上脱敏后的错误信息。

查看日志

Deskmate 使用 pino + sqlite 保存结构化日志。日志默认保存在本机的 ~/.deskmate/logs/。

日志位置：

  • dev：~/.deskmate/logs/dev.db
  • prod：~/.deskmate/logs/app.db

日志中可能记录的信息：

  • 错误。
  • 组件名。
  • trace id。
  • 工具调用元数据。
  • IPC / chat / provider 状态。

提交日志前，请检查是否包含敏感路径、token、文件名或业务内容，并先做脱敏处理。

提交 issue

提交 issue 时，建议尽量提供以下信息：

  • Deskmate 版本。
  • 操作系统和架构。
  • 发生时间。
  • 具体操作步骤。
  • 完整错误文案。
  • 是否能稳定复现。
  • provider / MCP 类型（不要附带 key）。
  • 脱敏后的日志或 trace id。
  • 截图（如涉及 UI）。

可以使用下面的模板：

## 问题

## 复现步骤
1.
2.
3.

## 预期结果

## 实际结果

## 环境
- OS:
- Deskmate version:
- Provider:
- MCP server:

## 日志/截图

FAQ

可以直接删除 ~/.deskmate 修复问题吗？

可以作为最后手段，但这会删除本地数据。请先备份。

日志可以发给维护者吗？

可以，但请先脱敏。

为什么模型昨天能用今天不能？

可能是 token 过期、provider 限流、网络问题，或 provider 服务发生变化。

下一步