QClaw Skills运行时v2.1补丁更新操作指南

QClaw v2026.3.1及以上版本的用户，可能会遇到一个奇怪现象：已安装的第三方Skill运行一段时间后突然无响应。日志中没有任何错误提示，但功能就是无法触发。根本原因往往在于底层运行时的版本不匹配。如果当前环境仍在使用v2.0或更旧的Runtime，即使skill.json校验通过，entry函数也不会被调用，所有自定义命令都将彻底失效。

本文带你快速完成Skills Runtime v2.1补丁的更新流程，让技能重新恢复正常运行。

确认当前运行时版本

首先，确认你当前使用的是哪个Runtime版本。操作虽然简单，但这一步至关重要。

打开QClaw，点击左下角齿轮图标进入设置，选择「关于 QClaw」，滚动到底部，查找“Skills Runtime”字段。如果显示为v2.0或根本没有该字段，说明尚未安装v2.1补丁，必须立即更新。

这一步绝对不能跳过。v2.1补丁改变了技能生命周期钩子的签名以及事件分发机制。简而言之，旧版Runtime无法兼容新版接口，即使skill.json校验通过，entry函数也不会被触发，你的自定义命令等于被完全阻塞。

下载并安装v2.1运行时补丁包

推荐优先使用内建通道更新——有网络、能运行、省时省力。

具体操作：确保QClaw正在运行，进入设置→「高级」→「运行时管理」，点击「检查运行时更新」。若检测到v2.1可用，界面将显示“Skills Runtime v2.1（20260528）”，点击「下载并应用」，等待进度条完成，出现“重启后生效”提示即可。

如果网络受限或内建通道一直无法检测到更新，可采用手动覆盖安装的备选方案。

前往对应补丁页面下载压缩包：Windows用户选择runtime-win-v2.1.zip，macOS用户选择runtime-mac-v2.1.tar.gz。解压后，将skills_runtime文件夹整体复制到QClaw安装目录下的lib/子目录中，直接覆盖同名文件夹。

特别提醒：macOS用户在覆写/Applications/QClaw.app/Contents/Resources/lib/路径时，需先关闭SIP（系统完整性保护），否则系统会直接阻止写入操作。

验证补丁是否生效

补丁安装完成后，重启QClaw。打开终端（Windows用户使用PowerShell，macOS/Linux用户使用Terminal），切换到QClaw安装目录，执行：python -m qclaw.cli runtime version。

检查输出是否显示：Skills Runtime v2.1 (build 20260528)。若版本号和构建日期一致，说明补丁已成功应用。

接着，进入设置→技能管理，查看列表中所有已注册的Skill，确认其状态是否从灰色变为绿色“已就绪”。若有技能仍显示“未就绪”，需使用qclaw.cli skill register 命令重新注册一次。

这一步必须逐个确认，没有捷径。v2.1补丁启用了强签名校验，任何未经register命令注册的Skill都会被直接屏蔽——即使文件结构完整，也不会出现在加载列表中。不要心存侥幸，老老实实走完整个流程。