升级QClaw失败多因OpenClaw 3.2版配置不兼容，需按序回滚版本、用backup恢复配置、重建微信通道、迁移workspace、重置SecretRef凭据链。
如果您在升级 qclaw 时遇到启动失败、配置丢失、功能异常或“聊天龙虾”等现象，很可能是由于 openclaw 底层版本迭代剧烈导致配置兼容性断裂。以下是解决此问题的步骤：
一、回滚至稳定版本并保留配置
QClaw 基于 OpenClaw 运行，其配置文件 openclaw.json 在 3.2 版本后结构变动较大，直接升级易引发解析错误。建议先回退到已验证稳定的前一版本（如 3.1.x），再迁移关键配置。
1、访问 https://github.com/openclaw/openclaw/releases，找到标有 “stable” 或发布日期早于 2026-03-08 的版本。
2、下载对应平台（Windows/macOS）的二进制包，解压覆盖当前安装目录（保留原 ~/.openclaw/ 目录不删除）。
3、手动编辑 ~/.openclaw/openclaw.json，将旧版中有效的 "tools": { "profile": "full", "allow": [...] } 段落复制粘贴至新配置文件对应位置。
4、执行 openclaw config validate 验证语法与密钥引用是否合法，无报错后启动 QClaw。
二、使用内置备份工具恢复
自 2026 年 3 月 8 日起，OpenClaw 内置 openclaw backup 子命令，可精准还原配置快照，避免手动修复 JSON 结构错误。
1、若此前执行过 openclaw backup create --config-only，则进入备份目录（默认为 ~/.openclaw/backups/）查找最近的 config-*.tar.gz 文件。
2、运行 openclaw backup verify ~/.openclaw/backups/config-20260307.tar.gz 校验完整性。
3、执行 openclaw backup restore --config-only ~/.openclaw/backups/config-20260307.tar.gz，仅恢复配置不触碰 workspace。
4、重启 QClaw 客户端，观察微信连接与技能调用是否恢复正常。
三、重建微信绑定通道
QClaw 升级失败常伴随微信会话通道中断，表现为扫码后无响应、客服消息不显示或指令无反馈。该问题多因本地凭证缓存与新版协议不匹配所致。
1、完全退出 QClaw 客户端（右键任务栏图标 → 退出，确保进程消失）。
2、删除微信绑定相关缓存：rm -rf ~/.openclaw/wechat_session*（macOS/Linux）或在 Windows 中清除 %USERPROFILE%\.openclaw\wechat_session* 文件夹。
3、重新启动 QClaw，等待左下角弹出「配置微信远程控制」弹窗。
4、使用微信扫描新生成的二维码，**务必在手机端点击「客服消息」→ 找到 QClaw → 点击「发消息」进入对话页**，完成双向握手。
四、重装并迁移技能与数据
当升级导致 ClawHub 技能失效、任务无法调度或 runtime 快照损坏时，需在保留用户数据前提下重建运行环境。
1、备份当前 workspace 路径：cp -r ~/QClaw_Workspace ~/QClaw_Workspace_backup_$(date +%Y%m%d)。
2、卸载当前 QClaw，从 claw.guanjia.qq.com 下载最新官方安装包（非 GitHub 源码编译版）。
3、安装完成后，首次启动跳过自动配置，进入设置页手动指定 workspace 路径为 ~/QClaw_Workspace_backup_20260314。
4、在 QClaw 内打开「ClawHub」面板，点击「同步技能」，等待 5000+ Skills 列表刷新完成，再逐一启用高频使用的技能（如 imap-smtp-email、fs、runtime）。
五、强制重置 SecretRef 凭据链
3.2 版本对 SecretRef 做了深度重构，若升级后出现“凭据未找到”、“密钥静默失效”或 ACP 任务卡在初始化阶段，说明 runtime 快照未正确加载旧密钥。
1、关闭 QClaw，执行 openclaw secret list 查看当前已注册凭据 ID（如 kimi_api_key、email_smtp_pass）。
2、对每个关键凭据，运行 openclaw secret delete <id> 彻底清除旧引用。
3、重新进入 QClaw 设置 → 「凭据管理」，逐项输入新值；对于邮箱类凭据，**必须使用 IMAP/SMTP 授权码而非登录密码**。
4、保存后，在终端执行 openclaw config validate --strict，确认所有 SecretRef 解析成功且无 warning。
