WechatExplorer/docs/user-guide/troubleshooting.md

常见问题与排查

先按现象定位，不要为了“重置”而直接删除微信数据库或整个应用目录。

连接微信失败

依次检查：

1. 数据目录是否指向当前登录账号，而不是旧备份或迁移前目录；
2. 微信版本是否属于当前代码面向的 4.x 数据结构；
3. 微信是否处于页面要求的登录/退出状态；
4. macOS 是否完成页面要求的授权；
5. 连接页面的诊断项是否明确指出密钥、账号或数据库问题。

重新输入密钥或断开连接不会删除微信原始数据库。macOS 的 SIP 和授权说明见平台说明。

连接成功但没有联系人或消息

确认账号身份和数据目录匹配。返回“设置 → 账号与数据库”查看数据库连接状态，重新加载会话后再试。若仍为空，记录系统、微信版本和错误提示后提交 Issue。

AI 没有结果或回答失败

• 先在“设置 → AI 模型”测试 Provider；
• 检查问题的时间范围和会话范围是否过窄；
• 确认 Knowledge 没有正在同步；
• 打开检索详情，查看是本地查找为空、Provider 失败还是来源被过滤；
• 把问题改成要求“只根据来源原文回答”。

AI Search 失败时可能仍保留部分来源；不要把部分结果当成完整覆盖。

AI 答案看起来不对

打开来源和原始消息，检查发送者、时间和上下文。若来源不支持结论，扩大或缩小范围后重问。涉及未转写语音、缺失图片、转发和引用时，优先以原消息为准。

Knowledge 一直在同步

首次建立或增量同步会在后台运行。查看“已索引消息、知识片段、磁盘占用”和同步详情；同步期间暂不能开始新的 AI 分析。若出现错误，旧索引可能仍可用，重启应用或在“缓存与清理”清理后重新建立。

语音转写失败

检查本地模型是否已准备、磁盘空间是否足够、单条语音是否仍有原始资源。批量任务可能部分成功；先处理失败项，不必重复转写已缓存内容。

媒体显示或导出异常

原图/缩略图目录缺失、权限不足或微信资源已被清理都会导致图片、视频或语音不可用。导出时可以切换缩略图、关闭媒体或保留缺失项，先确认文本档案是否正常。

文字正常但图片打不开时，进入“设置 → 图片解密”查看状态并尝试自动获取。密钥正确也不能恢复已经被微信清理的原图文件。

日报生成失败

日报只支持群聊。确认已选择群聊、时间范围内确实有消息、Provider 可用，并尝试先只选择文字消息。图片理解失败不会自动变成图片内容；报告可能跳过图片精选但仍生成文字日报。

Agent 无法读取

确认：

1. WechatExplorer 正在运行且 API Center 显示本地服务在线；
2. Agent 使用的是当前 Reader Skill，而不是旧的 MCP 配置；
3. 请求地址为 http://127.0.0.1:6131；
4. 非 health 请求带有最新 Authorization: Bearer <TOKEN>；
5. Token 重新生成后，Agent 配置已同步更新。

详细步骤见Agent 接入概览和API 安全。

微信机器人无法连接或不回复

Agent Hub 和外部 Agent 是两条路径。机器人异常时依次确认：

1. “Agent”页面中的 Agent Hub、微信连接器和数据库状态是否正常；
2. 二维码是否过期，手机是否已经确认登录；
3. 是否由另一个微信账号向已登录的机器人账号发送文字；
4. 请求是否属于当前支持的最近会话、联系人聊天、近 7 天联系人总结、群聊总结或群成员发言总结；
5. 需要总结或自然语言理解时，AI Provider 是否可用。

当前机器人不支持群发、定时任务或与文字同等的图片、语音、文件和视频理解。详细边界见Agent Hub。

防撤回没有保留消息

防撤回只能尽量保留开启后且应用成功捕获到的撤回变化。确认开启时数据库已经连接、WechatExplorer 在撤回发生时保持运行，并检查聊天加载是否明显变慢。开启前已经消失、应用未捕获或微信结构无法识别的消息不能保证恢复；详见防撤回。