必须分阶段排查并针对性修复：先确认SkillHub商店启用状态，再切换至腾讯国内镜像源，接着清理冲突缓存并重建索引，最后修复Python依赖缺失问题，确保签名验证、限流及解压错误全部解决。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
QClaw安装SkillHub技能时反复提示“签名验证失败”“Rate limit exceeded”或弹窗报错“资源解压出错”，说明当前环境已无法走通标准安装链路，必须分阶段排查并针对性修复。
确认SkillHub商店是否真正启用
很多用户误以为点击了「绑定腾讯账号」就完成了全部准备，其实QClaw只在完成身份认证后约10秒才向本地写入ClawHub直连通道开关——这一步失败会导致后续所有安装请求被拦截为“未授权源”。
打开QClaw设置→「技能管理」→「技能市场」，检查「允许从ClawHub安装技能」开关右侧是否显示绿色对勾；若为灰色或无响应，说明绑定流程未完成。
返回「关于QClaw」页面，点击右上角「刷新设备状态」按钮，等待3秒后重新进入技能市场页。这一步强制触发客户端与腾讯鉴权中心的二次握手，【跳过此步将导致后续所有安装请求直接返回403】。
绕过ClawHub限流，切换至SkillHub国内镜像源
ClawHub官方服务器自2026年3月起持续超载，即使登录成功也会频繁触发Rate limit错误。此时必须手动切换至腾讯托管的SkillHub国内源，该源不经过ClawHub中转，且拥有3.3万+技能的完整镜像缓存。
方法一：对话式强制切换（推荐）
在QClaw微信对话框中，发送以下完整指令：
根据https://skillhub.tencent.com/install/skillhub.md 重装SkillHub商店
方法二：命令行覆盖配置
关闭QClaw→打开终端→执行：
qclaw --set-skill-source https://skillhub.tencent.com → 回车确认
执行后无需重启，QClaw会在下次技能请求时自动拉取SkillHub元数据而非ClawHub。注意：该命令仅修改源地址，不触发重装，若此前安装失败残留了损坏缓存，需同步执行下一步清理。
清理冲突技能缓存并重建索引
旧版本QClaw在ClawHub通道异常时会将半截下载的ZIP包写入缓存目录，这些损坏文件会阻塞新技能的校验流程，表现为“解压出错”或“SKILL.md缺失”。
第一步：定位缓存路径
Windows系统默认路径为：
%APPDATA%\Tencent\QClaw\cache\skills
macOS系统默认路径为：
~/Library/Caches/Tencent/QClaw/skills
第二步：删除全部内容
进入对应文件夹，全选所有子文件夹与文件→按Shift+Delete彻底清除（不要放入回收站）。
第三步：重建索引
重新启动QClaw→进入「技能中心」→点击右上角「刷新技能列表」图标（两个循环箭头）→等待进度条走完。此时QClaw会清空本地技能注册表，并从SkillHub源重新拉取最新索引。
这一步完成后，所有技能卡片将恢复可点击状态，且安装按钮不再灰显。
修复Python依赖缺失导致的安装中断
部分Windows用户使用uv管理Python环境，但QClaw安装脚本默认调用系统级python3命令，而uv未向PATH注入python.exe别名，导致install.sh脚本在解析阶段直接退出，报错“Python was not found”。
方法一：临时创建python3软链接（管理员权限运行）
在PowerShell中执行：
cmd /c "mklink /D C:\Windows\System32\python3.exe $env:USERPROFILE\AppData\Roaming\uv\python\cpython-3.13.9-windows-x86_64-none\python.exe"
方法二：改用py启动器（无需管理员）
找到QClaw安装目录下的conf\config.yaml，在末尾添加：
python_interpreter: "py"
保存后重启QClaw，所有技能安装流程将改用py命令调用Python解释器，【该配置可绕过所有App execution aliases干扰】。
验证安装是否真正生效
执行完上述任一修复路径后，立即测试：在QClaw微信对话框发送「安装小红书工具」。
若5秒内弹出绿色提示框显示「✅ 已通过SkillHub官方签名验证」，则说明SkillHub商店已完全激活；若仍卡在「正在下载」或弹出红色报错，则说明缓存未清干净或网络策略仍在拦截cos.ap-guangzhou.myqcloud.com域名。
此时需打开Windows防火墙高级设置→出站规则→新建规则→程序路径指向QClaw.exe→放行TCP 443端口→应用。这一步解除企业级网络设备对腾讯云COS桶的默认拦截。
