QClaw异常时需按五步排查：一查进程状态，二验微信客服通道，三检OpenClaw技能加载，四排除网络代理干扰，五重置微信会话缓存。
如果您在使用qclaw过程中遇到功能异常、响应延迟、微信无法接收消息或任务执行失败等情况，则可能是由于本地环境配置、微信通信链路或openclaw底层服务状态不稳定所致。以下是快速定位问题的多种排查技巧：
一、检查QClaw基础运行状态
该步骤用于确认QClaw主程序是否正常加载并维持与本地OpenClaw实例的连接，避免因进程崩溃或初始化失败导致后续所有功能不可用。
1、打开任务管理器（Windows）或活动监视器（Mac），查找名为“QClaw”和“OpenClaw”的进程是否存在。
2、若仅存在QClaw进程而无OpenClaw进程，说明QClaw未成功启动或关联本地龙虾，需重新执行关联操作。
3、若两个进程均存在但CPU/内存占用持续为0%，则可能处于假死状态，需强制结束进程后重启QClaw。
二、验证微信通信通道是否激活
QClaw依赖微信客服消息通道实现双向通信，该通道并非好友关系，而是企业客服模式，其可用性受微信客户端版本、消息权限及后台保活策略影响。
1、打开微信，进入“我 → 设置 → 新消息通知”，确认“接收新消息通知”和“声音/振动”已开启。
2、在微信中点击“我 → 设置 → 隐私 → 通讯录黑名单”，检查QClaw是否被误加入黑名单。
3、手动进入“微信 → 客服消息”，查找是否有QClaw条目；如无显示，需重新扫码绑定，且必须在绑定后5分钟内完成首次对话触发通道激活。
三、确认OpenClaw技能与插件加载状态
QClaw的功能延展高度依赖OpenClaw所加载的skills（如imap-smtp-email、browser-control等），任一关键skill未就绪将导致对应指令完全失效。
1、在QClaw主界面左下角点击“终端日志”按钮，查看启动日志末尾是否出现“all skills loaded successfully”字样。
2、若日志中反复报错“failed to load skill: xxx”，则需进入QClaw安装目录下的“skills”子文件夹，检查对应插件文件夹是否存在且不为空。
3、对报错插件执行手动重载：右键该插件文件夹 → 选择“刷新配置”，随后在QClaw中输入指令“reload skill xxx”并发送。
四、隔离网络与代理干扰
QClaw虽为本地运行，但在调用浏览器、邮件服务或远程API时仍需联网；部分系统级代理或防火墙规则可能拦截其出站请求，造成任务卡顿或超时。
1、临时关闭系统代理设置：Windows前往“设置 → 网络和Internet → 代理”，Mac前往“系统设置 → 网络 → 高级 → 代理”，关闭所有代理选项。
2、在QClaw日志中搜索关键词“timeout”或“connection refused”，若集中出现在涉及“smtp.gmail.com”或“api.openai.com”等域名的记录中，表明网络路径受阻，需检查本地DNS解析是否正常。
3、执行命令行测试：在终端中运行“ping smtp.qq.com”，若无法通达，说明本地网络出口限制了邮件协议端口（如465/587）。
五、复位微信会话上下文缓存
QClaw在微信端维护独立的会话上下文，用于记忆用户偏好、历史任务与文件路径；该缓存若损坏，会导致指令语义识别错误、重复提醒或路径跳转失败。
1、在微信客服消息界面长按QClaw对话框，选择“不显示该聊天”，彻底清除当前会话。
2、重启QClaw软件，等待左下角弹出新二维码，重新扫码绑定。
3、绑定成功后，立即发送一条纯文本指令如“status”，观察是否返回完整运行摘要；若返回空或乱码，说明上下文重建失败，需删除QClaw用户数据目录中的“wechat_context.db”文件后重试。
