OpenClaw Skills 安装实战指南（新手→进阶）

holidaypenguin
10 阅读7分钟

📚 OpenClaw Skills 安装实战指南（新手→进阶）

文档参考（官方）：

🎯 快速概览

Skill = 给智能体的"可调用能力说明书"

  • 核心文件：SKILL.md（YAML frontmatter + Markdown 指令）
  • 作用：告诉模型"这个技能能解决什么问题、需要什么工具"

📦 1. Skills 加载位置与优先级

优先级从高到低：
┌─────────────────────────────┐
│ /skills（工作区）            │ ← 最高，覆盖同名
├─────────────────────────────┤
│ ~/.openclaw/skills          │ ← 全局扩展
├─────────────────────────────┤
│ BUILT_IN（内置）             │ ← 兜底
└─────────────────────────────┘

附加目录：skills.load.extraDirs（最低优先级，用于共享技能仓库）

🛠️ 2. 三种安装方式

方式一：ClawHub 安装（推荐） ✅

# 1. 安装 CLI
npm i -g clawhub    # 或 pnpm add -g clawhub

# 2. 搜索技能
clawhub search "calendar"
clawhub search "image edit" --limit 20

# 3. 安装技能（默认到 ./skills）
clawhub install <skill-slug>

# 4. 指定目录安装
clawhub install <skill-slug> --workdir /path/to/workspace

# 5. 更新全部技能
clawhub update --all

# 6. 查看已安装记录
clawhub list

# 7. 发布本地技能到云端
clawhub publish ./my-skill \
  --slug my-skill \
  --name "My Skill" \
  --version 1.0.0 \
  --tags latest

clawhub sync --all  # 同步所有变化

方式二：手动创建本地技能

# 1. 创建目录
mkdir -p <workspace>/skills/hello-world

# 2. 编写 SKILL.md
---
name: hello_world
description: A simple skill that says hello.
---

# Hello World Skill

When the user asks for a greeting, use the `echo` tool to say "Hello from your custom skill!".

✅ 然后重启 Gateway 或开新会话即可生效。

方式三：通过插件安装

# 查看已安装插件
openclaw plugins list

# 安装带技能的插件
openclaw plugins install @openclaw/voice-call

# 启用插件
openclaw plugins enable <id>

# 查看插件详情
openclaw plugins info <id>

⚠️ 注意： 插件与 Gateway 同进程运行，默认按"受信任代码"处理，只安装来源可靠的插件。

方式四：SkillHub安装（国内推荐）

SkillHub-专为中国用户优化的Skills社区

若未安装，请根据 skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/ski… 安装Skillhub商店，但是只安装CLI，然后安装find-skills技能。

直接给 OpenClaw 这句话，他就能自动安装了。安装后 skillhub 完全等同于 clawhub

⚙️ 3. 核心配置（~/.openclaw/openclaw.json）

完整示例：

{
  "skills": {
    "allowBundled": ["gemini", "peekaboo"],
    "load": {
      "extraDirs": [
        "~/Projects/shared-skills",
        "~/Projects/team-skill-pack/skills"
      ],
      "watch": true,
      "watchDebounceMs": 250
    },
    "install": {
      "preferBrew": true,
      "nodeManager": "npm"
    },
    "entries": {
      "nano-banana-pro": {
        "enabled": true,
        "apiKey": "GEMINI_KEY_HERE",
        "env": {
          "GEMINI_API_KEY": "GEMINI_KEY_HERE"
        },
        "config": {
          "endpoint": "https://example.invalid",
          "model": "nano-pro"
        }
      },
      "sag": {
        "enabled": false
      }
    }
  }
}

字段速记：

字段作用
allowBundled内置技能白名单
load.extraDirs附加扫描目录（优先级最低）
load.watch监听文件变化自动刷新
install.nodeManager安装器优先 npm/pnpm/yarn/bun
entries.*.enabled单个技能开关
entries.*.env为智能体注入环境变量（运行结束后恢复）
entries.*.apiKey快捷密钥字段（与 primaryEnv 联动）
entries.*.configSkill 自定义配置容器

🎮 4. 在会话中触发技能

大多数情况： 无需手动调用，直接描述任务即可。模型根据已加载 Skills 自动选择。

Frontmatter 开关详解：

user-invocable: true|false          # 是否暴露为用户可触发命令
disable-model-invocation: true|false # 是否禁止模型自动调用
command-dispatch: tool              # 斜杠命令直接分发到工具
command-tool: xxx                  # 命令分发目标工具
command-arg-mode: raw              # 原始参数直传工具

🚀 5. 进阶：门控（加载过滤）

在 metadata.openclaw 中声明依赖，让技能仅在条件满足时加载：

---
name: nano-banana-pro
description: Generate or edit images via Gemini 3 Pro Image
metadata:
  openclaw:
    requires:
      bins: ["uv"]           # 需要 uv 命令
      env: ["GEMINI_API_KEY"] # 需要环境变量
      config: ["browser.enabled"] # 需要配置项启用
    primaryEnv: "GEMINI_API_KEY"
---

常用门控字段：

  • requires.bins / requires.anyBins
  • requires.env
  • requires.config
  • os（darwin|linux|win32）
  • always: true

✅ 这对团队环境非常有用，能避免"装了但不可用"的假可用状态。

⚠️ 6. 沙箱模式注意事项

当智能体跑在 Docker 沙箱里时：

问题说明
❌ 宿主机环境变量不会自动带入容器需要在 agents.defaults.sandbox.docker.env 单独配置
⚠️ skills.entries.*.env/apiKey 仅作用于宿主机流程沙箱内不生效
🔍 requires.bins 检查通过不代表沙箱内有对应命令容器内也必须有二进制文件

结论：宿主机可用 ≠ 沙箱可用！

🐛 7. 常见问题与排障

问题 1：安装了技能但没生效？

检查顺序：

  1. ✅ 安装目录是否在 /skills 或 ~/.openclaw/skills
  2. ✅ 是否有同名技能被更高优先级目录覆盖
  3. ✅ skills.entries.*.enabled 是否为 true
  4. ✅ requires.* 条件是否满足（bin/env/config）
  5. ✅ 是否开启新会话（会话会缓存技能快照）

问题 2：改了 SKILL.md 没立即更新？

  • ✅ 确认 skills.load.watch: true
  • ✅ 确认 watchDebounceMs 不是过大
  • ✅ 保守做法：开新会话或重启 Gateway

问题 3：插件带的技能不出现？

  • ✅ openclaw plugins list 看插件是否启用
  • ✅ 检查 plugins.entries.*.enabled
  • ✅ 检查插件是否声明了 skills 目录
  • ✅ 修改配置后重启 Gateway

📋 8. 推荐工作流（可直接照抄）

# 1. 安装 CLI
npm i -g clawhub

# 2. 搜索技能
clawhub search "your use case"

# 3. 安装技能
clawhub install <skill-slug>

# 4. 保持更新
clawhub update --all

🔒 9. 安全建议（务必看）

✅ 要做❌ 不要做
第三方技能先读 SKILL.md把密钥写进提示词与日志
高风险操作启用沙箱隔离生产环境盲目用 latest 版本
固定版本依赖信任未经验证的来源

🎓 总结（记住这 4 句话）

  1. 安装首选：clawhub install，查找用 clawhub search
  2. 优先级记住：/skills 最高
  3. 配置集中：~/.openclaw/openclaw.json 的 skills 节点
  4. 验证方法：改完配置或技能，最好开新会话

📚 OpenClaw Skills 分层架构

🎯 核心概述

OpenClaw 的能力由三层技能构成：

能力金字塔
┌─────────────────────┐
│ WORKSPACE SKILLS    │ ← 项目专属，优先级最高
├─────────────────────┤
│ EXTRA SKILLS        │ ← 全局扩展，优先级中等  
├─────────────────────┤
│ BUILT_IN SKILLS     │ ← 系统内置，优先级最低（兜底）
└─────────────────────┘

📊 三层技能对比表

维度BUILT_IN
（内置）		WORKSPACE
（工作区）		EXTRA
（扩展）
定义系统自带通用能力当前项目专属技能用户全局安装/社区技能
存储位置系统安装目录~/.openclaw/workspace/skills/（Agent目录）~/.openclaw/skills/
作用范围全局所有项目仅当前项目全局所有项目
修改权限❌ 只读（升级覆盖）✅ 完全可控（Git 版本控制）✅ 可编辑
优先级1️⃣4️⃣最低🥇最高（覆盖同名）2️⃣3️⃣中等
典型用途文件操作、Shell、代码搜索项目构建脚本、内部 API 规范行业工具、个人模板、社区插件

🔍 三层详解

1️⃣ BUILT_IN SKILLS（内置技能）

  • 角色： OpenClaw 的"本能"
  • 示例： read_file, write_file, run_shell_command, search_code
  • 特点：
    • ✅ 稳定性极高（官方严格测试）
    • 🔒 不可见性（无需关心，除非研究底层实现）
  • 联系： 所有自定义技能的基石

我使用root 安装，目录就在 /root/.nvm/versions/node/v25.8.1/lib/node_modules/openclaw/skills

2️⃣ WORKSPACE SKILLS（工作区技能）

  • 角色： 项目的"私有知识库"
  • 核心价值： 上下文隔离

场景示例：

项目 A (Django) → run_migrations 技能
项目 B (React)  → build_bundle 技能

放在 WORKSPACE 中，打开项目 A 只知道迁移命令，打开项目 B 只知道打包命令。

  • 最佳实践：
    • ✅ 部署脚本、代码风格指南、内部文档查询
    • ✅ 提交 Git（团队成员自动获得专属能力）

我使用root 安装，目录就在 /root/.openclaw/workspace/skills

3️⃣ EXTRA SKILLS（扩展技能）

  • 角色： 用户的"个人工具箱"
  • 来源：
    • 用户自制通用技能（放 ~/.openclaw/skills/）
    • ClawHub 社区安装（openclaw skills install）
  • 特点：
    • 🔄 复用性强（如"代码转中文注释"所有项目可用）
    • 📦 易于管理（独立升级/卸载）
  • 联系： 连接通用能力和项目特需的桥梁

我使用root 安装，目录就在 /root/.openclaw/ 这里的某个文件夹下面，还不确定。

⚡ 加载优先级机制

就近原则查找顺序：

1️⃣ 检查 WORKSPACE SKILLS (.openclaw/skills/)
   └─ ✅ 找到 → 立即使用，忽略其他同名技能
   
2️⃣ 检查 EXTRA SKILLS (~/.openclaw/skills/)  
   └─ ✅ 找到 → 使用（全局通用技能）
   
3️⃣ 检查 BUILT_IN SKILLS
   └─ ✅ 兜底 → 系统基础功能

💡 覆写技巧 (Override)

想临时改变全局技能行为？

# 例如：强制当前项目使用特定 Commit Message 格式
# 在项目 .openclaw/skills/ 创建同名 commit 技能文件
# OpenClaw 自动优先使用本地版本，不影响其他项目

✅ 使用建议总结

不要做要做
❌ 修改 Built-in（除非贡献代码）✅ 项目特有逻辑 → Workspace
❌ 全局放项目专属技能（会混淆）✅ 个人通用工具 → Extra
❌ 忽略优先级导致的覆盖问题✅ 调试时检查 Workspace 是否有旧同名技能

📝 关键结论

理解三层分层是掌握 OpenClaw 高级用法、实现团队协作标准化和构建复杂 Agent 工作流的关键。

参考

avatar
文章
阅读
粉丝