QClaw启动异常时应优先查看命令行控制台日志，其次检查本地logs目录下的main.log和gateway.log，再排查OpenClaw子服务日志，接着启用微信通道调试日志，最后使用内置诊断工具生成报告。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 免费无限量使用 DeepSeek R1 模型☜☜☜
如果您启动QClaw后遇到报错提示但界面未显示具体原因，或程序无响应、闪退、无法登录，很可能是底层OpenClaw服务异常、配置加载失败或权限阻断所致。以下是定位错误根源的多种排查路径：
一、查看主进程控制台日志
QClaw启动时若以命令行方式运行（如通过终端或PowerShell执行qclaw.exe或qclaw），所有初始化错误、模型连接失败、Gateway绑定异常等原始报错会直接输出在控制台窗口中。该日志包含最及时、未经过滤的运行上下文。
1、打开系统终端（Windows：PowerShell；macOS：Terminal）。
2、进入QClaw安装目录，例如：cd "C:\Program Files\QClaw"。
3、执行启动命令：./qclaw --debug（Windows）或 ./qclaw --debug（macOS）。
4、复现报错操作，立即捕获控制台中红色/黄色高亮的堆栈信息与错误码。
二、读取本地日志文件
QClaw默认将结构化运行日志写入本地磁盘，包括服务启动、Agent调度、Skill执行、微信通道握手等全链路记录。日志按日期归档，便于回溯历史异常。
1、定位日志根目录：%APPDATA%\QClaw\logs（Windows）或 ~/Library/Application Support/QClaw/logs（macOS）。
2、进入子目录：latest（当前会话）或按日期命名的文件夹（如2026-03-15）。
3、打开最新生成的main.log与gateway.log文件，用文本编辑器搜索关键词：ERROR、panic、failed to bind、wechat auth timeout。
三、检查OpenClaw子服务日志
当QClaw选择“关联已有OpenClaw”模式时，其自身不托管核心Agent服务，而是作为GUI前端连接本地已运行的OpenClaw实例。此时错误根源往往在OpenClaw侧，需单独查验。
1、确认OpenClaw是否正在运行：ps aux | grep openclaw（macOS/Linux）或 tasklist | findstr openclaw（Windows）。
2、若存在进程，进入OpenClaw安装目录，查找logs/子文件夹。
3、重点查看：openclaw.log（主服务）、skills.log（技能调用）、memory.log（记忆加载失败常在此报错）。
四、启用微信通道调试日志
微信直连功能依赖WebSocket长连接与扫码鉴权，网络策略、防火墙拦截或微信服务端响应异常均会导致静默失败。启用通道级调试可暴露握手细节。
1、在QClaw客户端设置页中，开启高级调试模式开关。
2、重启QClaw，再次尝试微信扫码绑定。
3、回到日志目录，打开新生成的wechat-channel.log，查找以下关键标记：QR code expired、ws connection refused、invalid wechat openid。
五、导出完整诊断包
QClaw内置一键诊断工具，自动收集环境信息、配置快照、最近3小时日志压缩包及系统兼容性报告，适用于向技术支持提交精准问题线索。
1、点击QClaw右上角菜单栏的帮助 → 生成诊断报告。
2、等待进度完成，弹出保存对话框。
3、注意记录生成的报告编号：QCLAW-DIAG-20260315-XXXXX（该编号唯一绑定本次日志集合）。
4、将压缩包与编号一并提交至腾讯电脑管家AI支持入口。
