OpenClaw Skills安装实战指南：新手篇和进阶篇

Skill技能
,
1

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

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

:package: 1. Skills 加载位置与优先级

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

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

:hammer_and_wrench: 2. 三种安装方式

方式一：ClawHub 安装（推荐） :white_check_mark:

# 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!".

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

方式三：通过插件安装

# 查看已安装插件
openclaw plugins list

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

# 启用插件
openclaw plugins enable <id>

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

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

方式四：CoCoLoop技能商店

地址：https://hub.cocoloop.cn/

目前已经收录了 5000+ 技能，需要技能可以在这个技能商店获取。

image
image1383×883 175 KB

:gear: 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.*.config Skill 自定义配置容器

:video_game: 4. 在会话中触发技能

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

Frontmatter 开关详解：

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

:rocket: 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

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

:warning: 6. 沙箱模式注意事项

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

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

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

:bug: 7. 常见问题与排障

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

检查顺序：

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

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

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

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

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

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

# 1. 安装 CLI
npm i -g clawhub

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

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

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

:locked: 9. 安全建议（务必看）

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

:graduation_cap: 总结（记住这 4 句话）

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

:books: OpenClaw Skills 分层架构

:bullseye: 核心概述

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

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

:bar_chart: 三层技能对比表

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

:magnifying_glass_tilted_left: 三层详解

:one: BUILT_IN SKILLS（内置技能）

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

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

:two: WORKSPACE SKILLS（工作区技能）

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

场景示例：

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

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

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

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

:three: EXTRA SKILLS（扩展技能）

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

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

:high_voltage: 加载优先级机制

就近原则查找顺序：

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

:light_bulb: 覆写技巧 (Override)

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

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

:white_check_mark: 使用建议总结

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

:memo: 关键结论

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

2

我来进阶一下