故障排查

遇到问题时，本文帮助你快速定位原因并解决。涵盖常见问题、连接问题、性能问题、日志查看和重置方法。

常见问题

AI 不回复 / 回复为空

现象：发送消息后 AI 没有任何回复，或者返回空内容。

排查步骤：

1. 检查模型配置

   • 设置 → 模型 → 确认已选择可用的模型
   • 确认 API Key 已正确配置

2. 检查网络连接

   • 确认能访问 AI 模型提供商的 API
   • 如使用代理，确认代理配置正确

3. 检查余额

   • 如使用付费模型，确认账户余额充足
   • WES 平台用户检查是否欠费

4. 查看错误信息

   • 注意对话界面是否显示红色错误提示
   • 查看日志文件中的详细错误

应用无法启动

现象：点击 Wesclaw 图标后没有反应，或闪退。

排查步骤：

1. 检查系统要求

   • macOS 12+ / Windows 10+ / Ubuntu 20.04+
   • 至少 4GB 可用内存

2. 清理缓存

   # macOS
   rm -rf ~/Library/Application\ Support/wesclaw/Cache/
   rm -rf ~/Library/Application\ Support/wesclaw/GPUCache/
   

3. 检查数据库完整性

   • 如果数据库损坏，应用可能无法启动
   • 查看 crashes/ 目录中的崩溃日志

4. 尝试安全模式启动

   • 临时移走 config.yaml，用默认配置启动
   • 如果能启动，说明是配置问题

对话记录丢失

现象：之前的对话记录不见了。

可能原因：

解决方法：

• 从备份恢复（Time Machine 等）
• 检查数据目录是否正确
• 查看 *.bak 备份文件

技能加载失败

现象：已安装的技能不生效或报错。

排查：

1. 确认技能文件完整（skills/ 目录下有对应的 SKILL.md）
2. 检查技能是否与当前版本兼容
3. 尝试重新安装技能

连接问题

API 连接失败

现象：提示"无法连接到 AI 服务"或超时错误。

排查：

1. 网络检查
   curl https://api.openai.com/v1/models     # OpenAI
   curl https://api.anthropic.com/v1/messages  # Anthropic

2. API Key 验证
   设置 → Provider → 点击"测试连接"

3. 代理配置
   如果在公司网络，可能需要配置 HTTP 代理
   设置 → 网络 → 代理设置

WES 平台连接失败

现象：使用 WES 平台提供的模型时连接失败。

排查：

1. 确认已登录 WES 账号
2. 检查 WES 服务状态
3. 确认网络可以访问 WES 平台地址
4. 如显示"欠费"，需要先充值

IM 渠道断连

现象：企业微信/飞书/钉钉的 AI 助手不响应。

排查：

1. 检查回调 URL 是否可达
2. 确认应用凭证是否过期
3. 查看 IM 平台的开发者控制台是否有错误日志
4. 确认 Wesclaw 后端服务正在运行

SSE 流中断

现象：AI 回复到一半突然中断。

可能原因：

• 网络不稳定
• 代理超时设置过短
• 模型生成超时

解决：

• 检查网络稳定性
• 增大超时设置
• 重试发送消息（AI 会继续生成）

性能问题

应用卡顿

现象：Wesclaw 操作时明显卡顿。

排查与解决：

AI 回复速度慢

现象：每次等待 AI 回复需要很长时间。

影响因素：

响应时间 = 网络延迟 + 模型处理时间 + 输出生成时间
            ↑          ↑              ↑
        取决于网络     取决于任务      取决于输出长度
        和模型服务    复杂度和模型    和模型速度

优化建议：

1. 选择更快的模型：较小的模型通常响应更快
2. 控制输出长度：明确要求简短回答
3. 减少上下文：定期开始新对话
4. 检查网络：使用更稳定的网络连接

内存占用过高

现象：Wesclaw 占用大量内存（>1GB）。

解决：

1. 关闭不活跃的对话标签
2. 重启 Wesclaw 释放内存
3. 检查是否有大文件上下文（如大 PDF）
4. 清理浏览器缓存（Electron 使用 Chromium 内核）

日志查看

日志文件位置

macOS:   ~/Library/Application Support/wesclaw/logs/
Linux:   ~/.local/share/wesclaw/logs/
Windows: %APPDATA%\wesclaw\logs\

日志文件列表

查看日志

方法一：通过 Wesclaw 查看

设置 → 高级 → 查看日志

方法二：直接查看文件

# 查看最近的日志
tail -f ~/Library/Application\ Support/wesclaw/logs/wescode.log

# 搜索错误信息
grep "ERROR\|error\|Error" ~/Library/Application\ Support/wesclaw/logs/wescode.log

日志级别

提交问题时附带日志

向技术支持提交问题时，附上相关日志有助于快速定位：

1. 复现问题
2. 记录大致时间
3. 导出对应时间段的日志
4. 注意脱敏：删除日志中的 API Key、邮箱地址等敏感信息

重置方法

重置设置（保留数据）

只重置应用设置，保留对话和数据：

设置 → 高级 → 重置设置

影响范围：
✅ 界面设置恢复默认
✅ 快捷键恢复默认
✅ 显示选项恢复默认
❌ 不影响对话记录
❌ 不影响记忆数据
❌ 不影响 Provider 配置

重置单个功能

重置记忆：设置 → 记忆 → 清空所有记忆
重置技能：设置 → 技能 → 恢复默认技能
重置 Agent：设置 → Agent → 恢复默认 Agent

清理缓存

# 清理 Electron 缓存（不影响数据）
rm -rf ~/Library/Application\ Support/wesclaw/Cache/
rm -rf ~/Library/Application\ Support/wesclaw/Code\ Cache/
rm -rf ~/Library/Application\ Support/wesclaw/GPUCache/

完全重置（出厂设置）

⚠️ 此操作不可逆，请先备份重要数据！

# 1. 关闭 Wesclaw

# 2. 备份数据（可选）
cp -r ~/Library/Application\ Support/wesclaw/ ~/Desktop/wesclaw-backup/

# 3. 删除数据目录
rm -rf ~/Library/Application\ Support/wesclaw/

# 4. 重新启动 Wesclaw（会自动创建全新的数据目录）

数据库修复

如果数据库损坏但不想重置：

# 1. 关闭 Wesclaw

# 2. 尝试修复 SQLite 数据库
sqlite3 ~/Library/Application\ Support/wesclaw/db/wesclaw.db "PRAGMA integrity_check;"

# 3. 如果完整性检查报错，尝试导出再导入
sqlite3 ~/Library/Application\ Support/wesclaw/db/wesclaw.db ".dump" | sqlite3 wesclaw-new.db

# 4. 用修复后的文件替换原文件

获取帮助

自助排查清单

在寻求帮助前，请先确认：

• 已检查网络连接
• 已确认 API Key 配置正确
• 已查看错误提示信息
• 已检查日志文件
• 已尝试重启 Wesclaw
• 已确认使用的是最新版本

提交问题

提交问题时请包含以下信息：

1. Wesclaw 版本号
2. 操作系统及版本
3. 问题描述（步骤、现象、期望行为）
4. 相关日志片段（已脱敏）
5. 截图（如有）

紧急恢复

如果 Wesclaw 完全无法使用：

1. 确认数据已备份
2. 卸载当前版本
3. 下载最新版本安装
4. 从备份恢复数据