夜雨聆风OpenClaw 通过 Skill 机制实现智能体能力的模块化扩展。一个 Skill 就是一个包含 SKILL.md 的文件夹，它告诉智能体在特定场景下如何行动。本文从 Skill 的基本概念讲起，系统梳理 OpenClaw 的三级加载与门控机制，并重点对比 clawhub install、npx clawhub install、npx skills add 三条安装路径的适用场景与差异，帮助开发者根据自身需求选择最优方案。无论你是 OpenClaw 单一用户，还是在 Claude Code、Cursor 等多种智能体间协同工作，都能找到适合自己的 Skill 管理方式。
一、什么是 Skill？
Skill 是 AI 智能体的能力扩展模块。每个 Skill 本质上是一个包含 SKILL.md 文件的文件夹——通过 YAML 元数据和 Markdown 指令，告诉智能体在特定场景下该做什么、怎么做。Skill 生态采用 AgentSkills 开放标准，这意味着一个 Skill 可以同时服务于 OpenClaw、Claude Code、Cursor、Codex、Windsurf 等 40+ 种编码智能体。
目录结构
skills/
SKILL.md # 必需，元数据 + 指令
scripts/ # 可选，辅助脚本
references/ # 可选，参考文档
KILL.md 最小示例
---
name: weather
description: Get weather and forecasts for any location.
---
# Weather Skill
Use wttr.in API to fetch weather data...
二、Skill 的加载机制
2.1 三级加载优先级
OpenClaw 从三个位置加载 Skills，优先级从高到低：
优先级 | 位置 | 作用域 |
|---|---|---|
最高 | <workspace>/skills | 当前智能体专属 |
中 | ~/.openclaw/skills | 本机所有智能体共享 |
最低 | 内置 Skills（随安装包发布） | 全局默认 |
同名 Skill 遵循高优先级覆盖低优先级的规则。
2.2 门控机制
并非所有 Skill 都需要加载。通过 YAML 元数据声明前置条件，仅条件满足时 Skill 才被激活：
metadata:
{
"openclaw": {
"requires": {
"bins": ["uv"],
"env": ["GEMINI_API_KEY"],
"config": ["browser.enabled"]
}
}
}
支持的门控条件：
bins：指定的可执行文件必须存在于 PATH
anyBins：至少一个可执行文件存在即可
env：指定的环境变量必须已设置
config：openclaw.json 中对应的配置项必须为真值
条件检查在 Skill 加载时执行，不满足条件的 Skill 不会进入系统提示词，节省 Token 开销。
三、Skill 安装的三条路径 ⭐
这是本文的重点。目前安装 Skill 有三条路径，各有适用场景：
3.1 clawhub install（ClawHub 注册中心）
适用场景： 从 OpenClaw 官方注册中心安装已发布的 Skill，适合日常使用。
# 安装 ClawHub CLI
npm i -g clawhub
# 搜索
clawhub search "github issues"
# 安装
clawhub install github-issues
# 安装指定版本
clawhub install github-issues --version 1.2.0
# 更新所有已安装的 Skills
clawhub update --all
特点：
数据源为 ClawHub 注册中心（clawhub.com）
支持语义化版本管理和 changelog
基于内容哈希的增量更新
安装记录保存在 .clawhub/lock.json
Skill 安装到 <workspace>/skills 目录
仅限 OpenClaw 生态
3.2 npx clawhub install（免安装版）
适用场景： 环境中没有全局安装 ClawHub CLI，或需要在 CI/CD 等临时环境中快速安装。
# 效果等同于 clawhub install，但不需要预先安装 CLI
npx clawhub install github-issues
# 指定版本
npx clawhub install github-issues --version 1.2.0
特点：
npx 会临时下载并执行 clawhub 包，用完即丢
底层调用完全相同的 ClawHub 注册中心 API
功能与 clawhub install 一致：版本管理、哈希比对、lock 文件等
适合一次性操作、CI/CD 流水线、或不想全局安装额外 CLI 的场景
每次执行都有网络下载开销（npx 有本地缓存机制）
3.3 npx skills add（跨智能体安装）
适用场景： 从 GitHub 仓库、GitLab、本地目录等来源安装 Skill，且需要同时部署到多种智能体。
# 从 GitHub 安装（简写）
npx skills add vercel-labs/agent-skills
# 从 GitHub 安装（完整 URL）
npx skills add https://github.com/vercel-labs/agent-skills
# 从指定目录安装仓库中的某个 Skill
npx skills add https://github.com/vercel-labs/agent-skills/tree/main/skills/web-design
# 从本地路径安装
npx skills add ./my-local-skills
# 安装指定 Skill（一个仓库可能包含多个）
npx skills add owner/repo --skill frontend-design --skill skill-creator
# 安装到指定智能体
npx skills add owner/repo-aopenclaw -a claude-code
# 全局安装（而非项目级别）
npx skills add owner/repo -g
# 非交互模式（CI/CD 友好）
npx skills add owner/repo --skill frontend-design -y
特点：
数据源是任意 Git 仓库（GitHub / GitLab）或本地目录，不依赖特定注册中心
跨智能体支持：可同时安装到 OpenClaw、Claude Code、Cursor、Codex 等 40+ 种智能体
通过 -a 参数指定目标智能体，默认自动检测本地已安装的智能体
支持符号链接（推荐）和文件复制两种安装方式
项目级安装路径（OpenClaw）为 ./skills/，全局为 ~/.openclaw/skills/
社区索引：可在 skills.sh 发现社区 Skill
3.4 三条路径对比
特性 | `clawhub install` | `npx clawhub install` | `npx skills add` |
|---|---|---|---|
前置要求 | 需安装 CLI | 无需安装 | 无需安装 |
数据源 | ClawHub 注册中心 | ClawHub 注册中心 | Git 仓库 / 本地目录 |
版本管理 | ✅ 语义化版本 | ✅ 语义化版本 | ❌ 跟随仓库分支 |
增量更新 | ✅ 哈希比对 | ✅ 哈希比对 | ✅npx skills update |
跨智能体 | ❌ 仅 OpenClaw | ❌ 仅 OpenClaw | ✅ 40+ 种智能体 |
Lock 文件 | ✅ .clawhub/lock.json | ✅ .clawhub/lock.json | ❌ |
3.5 如何选择？
只用 OpenClaw，想要版本管理 → clawhub install
CI/CD 流水线或不想装 CLI → npx clawhub install
同时用多种智能体，从 GitHub 安装 → npx skills add
混用完全没问题：ClawHub 的 Skill 和 GitHub 仓库的 Skill 共存于同一 skills/ 目录，互不冲突
四、ClawHub 完整工作流
4.1 认证
clawhub login
clawhub whoami
仅安装和使用社区 Skill 无需认证，发布 Skill 时才需要登录。
4.2 日常管理命令
操作 | 命令 |
|---|---|
搜索 | clawhub search "关键词" |
安装 | clawhub install <slug> |
更新 | clawhub update --all |
列表 | clawhub list |
发布 | clawhub publish <path> --slug <slug> --version <ver> |
同步 | clawhub sync --all |
4.3 发布与备份
# 发布单个 Skill
clawhub publish ./my-skill \
--slug my-skill \
--name "My Skill" \
--version 1.0.0 \
--changelog "Initial release"
# 批量扫描并发布
clawhub sync --dry-run # 预览将要上传的内容
clawhub sync --all # 确认上传
五、配置管理
通过 ~/.openclaw/openclaw.json 对 Skill 进行细粒度控制：
{
"skills": {
"entries": {
"nano-banana-pro": {
"enabled": true,
"apiKey": "YOUR_API_KEY",
"env": { "GEMINI_API_KEY": "YOUR_API_KEY" },
"config": { "endpoint": "https://your-endpoint.com" }
},
"peekaboo": { "enabled": false }
}
}
}
关键配置项：
enabled: false — 禁用指定 Skill，即使已安装
env — 为 Skill 注入环境变量（仅在未设置时生效）
apiKey — 快捷注入声明了 primaryEnv 的 Skill 的密钥
config — 传递自定义配置参数
六、注意事项
第三方 Skill 视为不受信任代码，安装前务必阅读 SKILL.md 内容
skills.entries.*.env 和 apiKey 注入的是宿主机进程，沙箱模式下不会传递到容器
建议对高风险 Skill 启用沙箱隔离（Docker），限制文件系统和网络访问
Snyk 在 2026 年初发现注册中心存在 386 个恶意 Skill 包，安装时注意甄别来源