第 4 章 Skills 深度解析：从概念到实战

🧩 本章特色：在《OpenClaw 实战指南》的系列章节中，本章系统讲解 Skills（技能）的设计哲学、技术规范、加载机制、管理工具和协同应用。Skills 是 OpenClaw 生态中最核心的扩展单元，它们让 AI 从"只会聊天"变成"能干活"的数字助手。你负责描述意图，Skills 负责执行落地。

本章目录：

1. Skills 的本质：赋予大模型"身体"的执行器

1.1 从对话到行动的跨越

想象一个场景：你对 OpenClaw 说"帮我把这份合同的甲方名称提取出来"。这个看似简单的请求，背后涉及多个步骤：AI 需要先理解你的意图是"文档信息抽取"，然后找到能处理文档的 Skill，调用底层工具解析 PDF 文件，提取文本内容，最后将结果整理为自然语言回复给你。

如果没有 Skills，OpenClaw 就是一个只能和你聊天的程序。它能理解你的意思，但无法执行任何操作。就像一个聪明的大脑被关在玻璃房里：看得见你的需求，却伸不出手来帮忙。

Skills 就是打破这层玻璃的工具。它们将抽象的自然语言指令转化为具体的系统操作，让 AI 从"理解意图"跨越到"完成任务"。当你在对话中说"发邮件给张三"，Skills 让 OpenClaw 能够真正调用邮件发送服务、填写收件人地址、组织邮件正文并完成发送。当你说"查一下明天北京的天气"，Skills 让 OpenClaw 能够调用天气 API、解析返回数据、用自然语言告诉你"明天北京晴，最高温度 28 度"。

这种从对话到行动的跨越，是 OpenClaw 区别于普通聊天机器人的核心能力。普通聊天机器人只能和你对话，而 OpenClaw 通过 Skills 获得了"动手能力"，成为了一个真正能帮你干活的数字助手。

1.2 标准化能力单元的设计哲学

在 OpenClaw 的设计中，每个 Skill 都是一个标准化封装的能力单元，对应一项具体操作或一类相关操作。Skills 不是随意编写的脚本，而是遵循统一规范的模块化组件。这种设计带来了几个重要的好处。

统一接口。所有 Skills 都使用相同的文件格式（SKILL.md）、相同的元数据结构（YAML Frontmatter）和相同的加载机制。OpenClaw 不需要为每种 Skill 编写特殊的加载代码，只需要一套通用的加载器就能处理所有 Skills。这大大降低了系统的复杂度。

独立部署。每个 Skill 是一个自包含的目录，包含所有需要的文件和资源。你可以单独安装、更新、卸载某个 Skill，而不影响其他 Skills 或 OpenClaw 核心系统。这种独立性让 Skills 的管理变得简单可靠。

可组合性。多个 Skills 可以在同一次对话中协同工作。OpenClaw 根据用户意图自动选择合适的 Skills，并按需调用。你不需要预先知道会用到哪些 Skills，系统会根据上下文动态编排。

以下是一些常见 Skill 及其对应的能力：

这些 Skills 并非硬编码在 OpenClaw 核心引擎中，而是以独立、可替换、可组合的模块形式存在。当用户发出指令时，OpenClaw 根据上下文判断需要调用哪些 Skill，并将任务委托给它执行。这种架构让 OpenClaw 的能力边界可以无限扩展，而不需要修改核心代码。

1.3 核心价值三维解析

Skills 的引入解决了 AI 自动化领域的三个根本问题，我们可以从三个维度来理解其核心价值。

第一维度：能力具象化。 大语言模型擅长语义理解和文本生成，但无法直接操作计算机系统。它能理解"帮我发邮件"这句话的含义，但不知道如何打开邮件客户端、填写收件人、编写正文、点击发送。Skills 充当了"翻译层"和"执行层"，将抽象的自然语言意图转化为具体的系统操作。每个 Skill 就像给 AI 安装了一双特定功能的手：weather Skill 是查天气的手，github Skill 是管理代码的手，nano-pdf Skill 是编辑文档的手。

第二维度：解耦与可维护性。 OpenClaw 核心引擎只负责消息路由、Skill 加载和结果调度，具体的能力实现全部由各个 Skill 独立完成。这种解耦架构带来了显著的好处：更新某个 Skill 不影响其他功能，一个 Skill 出错不会导致整个系统崩溃，可以按 Skill 粒度设置安全策略和权限控制。想象一下，如果所有功能都写在核心引擎里，每次修改一个小功能都需要重新编译整个系统，任何一个小错误都可能导致系统崩溃。Skills 的模块化设计避免了这种风险。

第三维度：生态可扩展。 OpenClaw 采用开放的 Skill 生态，任何人都可以开发、分享、复用 Skill。官方提供了 ClawHub（clawhub.ai）作为公共技能市场，类似于手机上的应用商店。开发者可以将自己编写的 Skill 发布到 ClawHub，其他用户可以一键安装使用。目前已收录了数百个高质量 Skill，涵盖办公自动化、开发运维、个人效率、硬件控制、媒体处理等领域。这种社区驱动的生态模式让 OpenClaw 的能力增长远超任何单一团队的开发速度。

┌─────────────────────────────────────────────────┐
│            Skills 的三层价值                      │
│                                                   │
│  ┌─────────────────────────────────────────┐     │
│  │  第三层：生态可扩展                       │     │
│  │  ClawHub 社区市场、一键安装、共享复用     │     │
│  └─────────────────────────────────────────┘     │
│  ┌─────────────────────────────────────────┐     │
│  │  第二层：解耦与可维护                     │     │
│  │  模块化、独立更新、故障隔离               │     │
│  └─────────────────────────────────────────┘     │
│  ┌─────────────────────────────────────────┐     │
│  │  第一层：能力具象化                       │     │
│  │  意图→操作、翻译层、执行层                │     │
│  └─────────────────────────────────────────┘     │
└─────────────────────────────────────────────────┘

2. 技术规范与解剖：SKILL.md 的身份证与说明书

Skills 不是随意编写的脚本文件，而是遵循 AgentSkills 开放规范（agentskills.io）的标准化组件。这种规范化设计确保了 Skills 在不同环境下的兼容性和一致性。本节将深入解剖 SKILL.md 文件的结构，让你理解每个字段的作用和编写要点。

2.1 AgentSkills 开放规范与目录结构

一个合法的 Skill 是一个命名规范的目录，内部至少包含一个 SKILL.md 文件。SKILL.md 是 Skill 的"身份证"和"说明书"，包含了元数据（告诉 OpenClaw 这个 Skill 是什么、需要什么条件）和执行指令（告诉 AI 如何使用这个 Skill）。

标准的 Skill 目录结构如下：

skill-name/
├── SKILL.md          # 必需：元数据 + 使用说明
├── scripts/          # 可选：可执行脚本（Python/Bash/Node.js 等）
├── references/       # 可选：详细参考文档（供 AI 按需阅读）
├── assets/           # 可选：模板、图标、配置文件等静态资源
├── examples/         # 可选：使用示例
├── templates/        # 可选：输出模板
└── ...               # 其他辅助文件

目录命名规则：

• 仅允许小写字母（a-z）、数字（0-9）和单连字符（-）
• 不能以连字符开头或结尾
• 不能包含连续连字符（如 my--skill 不合法）
• 目录名应与 SKILL.md 中的 name 字段保持一致（推荐但非强制）
• 合法的目录名示例：weather、sql-toolkit、ai-image-gen
• 不合法的目录名示例：My-Skill（含大写字母）、--bad（以连字符开头）、a--b（连续连字符）

OpenClaw 会在配置的 Skill 根目录下递归搜索 SKILL.md 文件（最深 6 层），因此你可以用子目录来组织 Skills，保持目录结构清晰：

<workspace>/skills/research/SKILL.md          ✓ 发现为 "research"
<workspace>/skills/personal/research/SKILL.md ✓ 同样发现为 "research"
<workspace>/skills/tools/dev/github/SKILL.md  ✓ 发现为 "github"

在分组目录结构中，找到 SKILL.md 后会停止对该目录的进一步遍历。无效的 Skill 文件会被报告并跳过，但同级目录中有效的 Skill 仍然可以正常加载。

需要注意的是，Skill 的名称和斜杠命令来自 SKILL.md 中的 name 字段（如果 name 缺失则使用目录名），而不是文件夹路径。文件夹路径仅用于组织和管理。

2.2 元数据驱动加载机制：YAML Frontmatter 关键字段

SKILL.md 采用 YAML Frontmatter + Markdown 正文的混合格式。Frontmatter 位于文件开头，用三条短横线 --- 包裹，定义 Skill 的元数据。正文在 Frontmatter 之后，提供执行指令。

必需字段

每个 Skill 必须包含以下两个字段：

---
name: email-sender
description: 发送电子邮件。当用户要求发邮件、查收件箱或管理邮件时使用。
---

description 字段的编写质量至关重要，因为它会被注入到 AI 的系统提示词中，帮助 AI 判断何时使用该 Skill。一个好的 description 应该包含两个要素：做什么（功能）和什么时候用（触发条件）。

好的 description 示例：

• 发送电子邮件。当用户要求发邮件、查收件箱或管理邮件时使用。（功能+触发条件）
• 搜索和安装社区技能。当用户需要查找、安装或发布 Skill 时使用。（功能+触发条件）
• 查询当前天气与预报。当用户询问天气、气温或是否需要带伞时使用。（功能+触发条件）

差的 description 示例：

• 一个工具（太模糊，AI 无法判断何时使用）
• 这个 Skill 可以帮助用户完成各种邮件相关的任务，包括发送、接收、管理等（太长，超过 160 字符限制）

可选字段

除了必需字段，SKILL.md 还支持多个可选字段，用于更精细地控制 Skill 的行为：

---
name: gemini-search
description: 使用 Gemini CLI 进行语义搜索。
metadata:
  openclaw:
    requires:
      bins: ["gemini"]
      env: ["GEMINI_API_KEY"]
    primaryEnv: "GEMINI_API_KEY"
homepage: https://github.com/example/gemini-skill
license: MIT
user-invocable: true
disable-model-invocation: false
---

依赖门控（Gating）详解

metadata.openclaw.requires 是 Skill 的"门槛"机制。它告诉 OpenClaw："这个 Skill 需要以下条件满足才能工作，如果条件不满足，就不要加载它。"

bins（二进制工具检查）：列出 Skill 依赖的命令行工具。OpenClaw 启动时会检查这些工具是否存在于系统 PATH 中。例如，一个使用 ffmpeg 处理视频的 Skill 可以这样声明：

metadata:
  openclaw:
    requires:
      bins: ["ffmpeg", "ffprobe"]

如果用户系统上没有安装 ffmpeg，这个 Skill 就不会被加载，也不会出现在 AI 的可用能力列表中。这避免了 AI 尝试调用不存在的工具而导致的错误。

anyBins（任一存在即可）：与 bins 不同，anyBins 只需要列表中的至少一个工具存在即可。适用于支持多种后端实现的 Skill：

metadata:
  openclaw:
    requires:
      anyBins: ["docker", "podman"]

这个 Skill 在安装了 Docker 或 Podman 的系统上都能工作。

env（环境变量检查）：确保必要的环境变量已设置。常用于需要 API Key 的 Skill：

metadata:
  openclaw:
    requires:
      env: ["OPENAI_API_KEY"]

config（配置路径检查）：验证 openclaw.json 中的特定配置项是否为真值：

metadata:
  openclaw:
    requires:
      config: ["channels.discord"]

这个 Skill 只在用户配置了 Discord 通道时才会加载。

os（平台过滤）：限制 Skill 只在特定操作系统上加载：

os: ["darwin"]  # 只在 macOS 上加载

适用于依赖特定平台 API 的 Skill，如 macOS 的 AppleScript 或 Linux 的 systemd。

使用 {baseDir} 引用 Skill 内部文件

在 SKILL.md 正文中，你可能需要引用 Skill 目录内的脚本或资源文件。不要硬编码绝对路径，而是使用 {baseDir} 占位符，OpenClaw 会自动将其替换为 Skill 的实际目录路径：

运行辅助脚本：

```bash
python {baseDir}/scripts/helper.py --input data.csv

这样做的好处是 Skill 可以在不同的安装路径下正常工作，无需修改代码。

### 2.3 Markdown 正文编写最佳实践

Frontmatter 告诉 OpenClaw "这个 Skill 是什么"，而 Markdown 正文则告诉 AI "如何使用这个 Skill"。正文是 AI 理解和使用 Skill 的"操作手册"，其编写质量直接影响 AI 能否正确执行任务。

#### 正文结构建议

一个结构良好的正文通常包含以下部分：

```markdown
# Skill 名称

## When to Use
描述 AI 应该在什么场景下使用此 Skill。

## How to Use
具体的操作步骤和工具调用方式。

## Common Issues
常见问题及解决方案。

## Security Considerations
安全注意事项（如有）。

最佳实践

原则一：简洁为上。 正文内容会被注入到 AI 的系统提示词中，过长的正文会占用上下文窗口，拖慢推理速度。建议正文控制在 5000 tokens 以内。复杂的参考文档应移至 references/ 目录，AI 会在需要时按需阅读。

原则二：用正向指令。 告诉 AI "做什么"而不是"不要做什么"。正向指令比否定指令更容易被模型准确执行。

# 好的写法
运行脚本后，检查返回状态码，0 表示成功，非 0 表示失败。

# 差的写法
不要忽略脚本的返回状态码。

原则三：提供可检查的完成标准。 每个步骤都应该有一个明确的完成标志，让 AI 能够判断步骤是否成功执行。

1. 执行 `python {baseDir}/scripts/setup.py` 完成初始化。
   **完成标志**：脚本输出 "Setup complete" 且退出码为 0。

2. 验证配置文件已生成。
   **完成标志**：`config.yaml` 文件存在于当前目录。

原则四：避免发明不存在的工具或参数。 正文中提到的每一个工具、命令、参数都必须是真实存在的。AI 会严格按照正文指令执行，如果你写了一个不存在的命令，AI 会尝试执行它并失败。

原则五：处理错误场景。 告诉 AI 当操作失败时应该怎么做，而不是只描述成功路径。

## Common Issues

- 如果返回 `Authentication failed`，提示用户检查 API Key 是否正确配置
- 如果超时（超过 30 秒无响应），建议用户检查网络连接
- 如果文件不存在，先检查路径是否正确，再尝试重新生成

一个完整的 SKILL.md 示例

以下是一个结构完整、内容规范的 Skill 示例：

---
name: csv-analyzer
description: 分析 CSV 文件的数据统计信息。当用户需要分析表格数据、查看 CSV 统计或生成数据报告时使用。
metadata:
  openclaw:
    requires:
      bins: ["python3"]
---

# CSV Analyzer

## When to Use

当用户提供 CSV 文件并要求分析数据时使用此 Skill。
适用场景包括：数据统计、分布分析、异常值检测、数据质量评估。

## How to Use

1. 确认用户提供的 CSV 文件路径存在。
   **完成标志**：文件可读且非空。

2. 运行分析脚本：

   ```bash
   python3 {baseDir}/scripts/analyze.py \
     --input "<csv文件路径>" \
     --output "<输出报告路径>"
   ```

   **完成标志**：脚本退出码为 0，输出文件已生成。

3. 读取输出报告，用自然语言向用户总结关键发现。

## Parameters

- `--input`：CSV 文件路径（必需）
- `--output`：报告输出路径（默认：当前目录下的 report.md）
- `--top-n`：显示前 N 条记录（默认：10）

## Common Issues

- 如果文件编码不是 UTF-8，尝试用 `--encoding gbk` 参数
- 如果文件过大（超过 100MB），脚本会自动采样前 10 万行
- 如果某列数据全为空，该列会被自动跳过并在报告中说明

这个示例展示了规范的 SKILL.md 应该具备的所有要素：清晰的触发条件、具体的操作步骤、可检查的完成标志、完整的参数说明和常见问题的处理方案。

3. 加载与执行链路：从系统提示词到结果返回

理解了 Skill 的文件结构后，接下来需要知道 OpenClaw 是如何发现、加载、选择和执行 Skills 的。这条从"文件存在"到"任务完成"的完整链路，是掌握 Skills 工作机制的关键。

3.1 多层优先级覆盖模型

OpenClaw 采用多层加载优先级来管理 Skills。当同名 Skill 出现在多个位置时，优先级高的会覆盖优先级低的。这种设计让你可以在不同层级定制 Skills，而不影响其他层级。

覆盖规则详解：

同名 Skill 优先级高的覆盖优先级低的。这个机制的实际意义在于：

场景一：项目级定制。 假设你有一个 github Skill，官方版本使用 gh CLI 管理 Issue。但你在某个项目中需要添加自定义的参数（如自动打上特定标签）。你只需把修改后的 github Skill 放入该项目的工作区 skills/ 目录，OpenClaw 就会自动选用你的版本，其他项目不受影响。

场景二：全局覆盖。 如果你希望所有项目都使用定制版的某个 Skill，可以把它放在 <state-dir>/skills 目录下（通常是 ~/.openclaw/skills）。这个目录的优先级高于内置 Skills，所以你的版本会覆盖官方版本。

场景三：开发调试。 当你正在开发一个新 Skill 时，把它放在工作区的 skills/ 目录中，优先级最高，方便快速测试和迭代。

每代理 vs 共享 Skills

在多代理配置中，每个代理有自己的工作区。Skills 的可见范围取决于它们的存放位置：

Workshop 中由一个代理学习的 Skills 不会自动共享给其他代理。如果需要跨代理共享，应该将 Skill 发布到托管库（managed library）。

代理级白名单

除了文件位置控制可见性，OpenClaw 还支持通过配置进一步限制每个代理可用的 Skills：

{
  "agents": {
    "defaults": {
      "skills": ["github", "weather"]  // 所有代理的共享基线
    },
    "entries": {
      "writer": { "default": true },           // 继承 github、weather
      "docs": { "skills": ["docs-search"] },    // 替换默认，仅有 docs-search
      "locked-down": { "skills": [] }           // 禁用所有 Skills
    }
  }
}

白名单规则说明：

• 省略 agents.defaults.skills 表示默认不限制 Skills
• 省略 agents.entries.*.skills 表示继承 agents.defaults.skills
• 设置 agents.entries.*.skills: [] 表示该代理禁用所有 Skills
• 非空的 agents.entries.*.skills 列表是最终的集合，不会与默认值合并

3.2 启动时的依赖门控与环境验证

OpenClaw 启动时（以及 Skills 文件发生变化时），会执行以下加载流程：

第一步：扫描 Skill 目录。 按优先级从高到低，依次扫描每个 Skill 根目录，递归搜索 SKILL.md 文件（最深 6 层）。

第二步：解析元数据。 读取每个 SKILL.md 的 YAML Frontmatter，提取 name、description、metadata.openclaw.requires 等字段。

第三步：检查依赖。 验证 metadata.openclaw.requires 中声明的所有条件：

• bins：检查 PATH 中是否存在指定的二进制工具（使用 which 或等效命令）
• anyBins：检查列表中至少一个工具是否存在
• env：检查环境变量是否已设置（在进程环境或 openclaw.json 配置中）
• config：检查 openclaw.json 中的配置路径是否为真值
• os：检查当前操作系统是否匹配

第四步：标记状态。 仅当所有依赖条件都满足时，才将该 Skill 标记为"可用"（ready）。依赖不满足的 Skill 不会被加载，也不会报错，它们只是安静地"隐身"，直到条件具备。

你可以通过以下命令检查所有 Skills 的状态：

openclaw skills check

输出示例：

Status        Skill              Description                    Source
✓ ready       weather            查询天气与预报                  openclaw-bundled
✓ ready       github             管理 GitHub 仓库               openclaw-bundled
△ needs setup gemini-search      使用 Gemini CLI 搜索           openclaw-workspace
✗ missing     notion             操作 Notion（缺少 API Key）     openclaw-bundled

状态说明：

• ✓ ready：所有依赖满足，Skill 已加载并可用
• △ needs setup：部分依赖未满足，需要安装工具或配置环境变量
• ✗ missing：关键依赖缺失，Skill 无法工作

环境变量配置

对于需要 API Key 的 Skill，可以在 openclaw.json 中配置：

{
  "skills": {
    "entries": {
      "gemini-search": {
        "enabled": true,
        "apiKey": *** source: "env", provider: "default", id: "GEMINI_API_KEY" },
        "env": { "GEMINI_API_KEY": "your-api-key-here" }
      }
    }
  }
}

apiKey 字段支持两种形式：直接写字符串（明文，不推荐）或使用 SecretRef 引用环境变量（更安全）。env 字段中的环境变量仅在代理执行 Skill 时注入进程，执行完成后即清除，防止泄露。

重要提示： skills.entries.<skill>.env 和 apiKey 仅对宿主机运行生效。在 Docker 沙箱中，需要通过 agents.defaults.sandbox.docker.env 单独传递环境变量：

{
  "agents": {
    "defaults": {
      "sandbox": {
        "docker": {
          "env": { "GEMINI_API_KEY": "your-api-key-here" }
        }
      }
    }
  }
}

3.3 完整执行闭环流程

在每个会话开始时，OpenClaw 会将所有可用 Skills 的 name 和 description 编码为紧凑格式，注入 AI 的系统提示词中。这样 AI 在生成回复时就能"知道"自己有哪些能力可用。

完整的执行链路如下：

步骤 1：用户发送消息。 用户在聊天中描述需求，如"发邮件给张三，主题：会议提醒，内容：明天下午 3 点开会"。

步骤 2：AI 分析意图。 AI 从系统提示词中看到所有可用 Skills 的描述，识别出这是"发送邮件"任务，匹配到 email-sender Skill。

步骤 3：OpenClaw 加载 Skill。 系统找到 Skill 目录，读取 SKILL.md 正文作为执行上下文，AI 根据正文中的指令生成工具调用请求。

步骤 4：执行工具调用。 OpenClaw 执行 AI 请求的工具操作，如运行脚本、调用 API 等。

步骤 5：返回结果。 工具执行完成后，结果返回给 AI。AI 将结果整理为用户可读的自然语言回复。

以下是一个具体的执行流程示例：

用户输入：
  "发邮件给张三，主题：会议提醒，内容：明天下午 3 点开会"

AI 分析：
  意图 = 发送邮件
  匹配 Skill = email-sender
  参数 = ***

AI 生成工具调用：
  {
    "tool": "exec",
    "command": "python3 /skills/email-sender/scripts/send.py \
      --to 'zhangsan@example.com' \
      --subject '会议提醒' \
      --body '明天下午 3 点开会'"
  }

工具执行结果：
  Exit code: 0
  Output: "Email sent successfully to zhangsan@example.com"

AI 生成回复：
  "已成功发送邮件给张三（zhangsan@example.com），主题为'会议提醒'。"

在提示词中引用 Skill

在 Control UI 的输入框中，你可以用 $ 符号快速引用 Skill。输入 $ 后会弹出搜索框，选择 Skill 后会在消息中插入其稳定命令名：

使用 $github 和 $release_notes 来总结这次变更。

OpenClaw 会在每条消息中解析这些引用，并指示 AI 先阅读对应的 SKILL.md 再执行操作。单条消息最多可以引用 8 个不同的 Skill。

常见的 shell 环境变量如 $HOME、$PATH、$EDITOR 不会被误识别为 Skill 引用。如果你确实想引用名为 home 的 Skill，使用小写形式 $home。如果需要转义 $ 使其保持为普通文本，使用 \$name。

3.4 快照与刷新机制

Skills 的加载不是一次性的静态过程，而是一个动态的、可刷新的机制。

文件监视（Watch）： 默认情况下，OpenClaw 会监视 Skill 目录中的文件变化。当你修改了某个 SKILL.md 文件，OpenClaw 会自动检测变更并刷新 Skills 快照。下一次对话轮次就会使用更新后的 Skill。

这个行为由配置项 skills.load.watch 控制，默认值为 true。如果禁用了文件监视，你需要开启新的对话会话（/new）或重启 Gateway（openclaw gateway restart）才能让修改生效。

快照（Snapshot）： OpenClaw 将当前可用的 Skills 列表保存为快照。快照用于构建系统提示词、斜杠命令发现和沙箱同步。当 Skill 文件发生变化或配置更新时，快照会自动刷新。

会话选择： 每个会话保留其选定的 Skill ID 和版本。当有人加入或接管会话时，不会替换已选定的 Skills。新发布的 Skills 对新会话可用，但已有会话需要显式附加或刷新才能使用。

4. 双轨制管理工具：终端用户与开发者的差异化体验

OpenClaw 提供了两套互补的命令行工具来管理 Skills：openclaw skills 面向日常用户，提供搜索、安装、升级等日常操作；clawhub CLI 面向技能开发者，提供发布、同步、账号管理等进阶功能。这种双轨制设计确保了不同角色都能获得最佳的使用体验。

4.1 openclaw skills：日常运维的瑞士军刀

openclaw skills 是 OpenClaw 内置的命令，随 OpenClaw 一起安装，无需额外配置。它适合普通用户和轻度开发者完成日常的 Skill 管理操作。

命令速查表

搜索技能

openclaw skills search "postgres backups"

搜索基于语义理解，即使你的措辞与 Skill 的 description 不完全一致，也能找到相关技能。例如搜索"备份数据库"也能找到 description 中写的是"dump and restore PostgreSQL databases"的 Skill。返回结果包括技能名称、描述、标签、下载量与星标数。

安装技能

# 安装到当前工作区（默认）
openclaw skills install sql-toolkit

# 安装指定版本
openclaw skills install sql-toolkit --version 1.2.3

# 全局安装（所有代理共享）
openclaw skills install sql-toolkit --global

安装完成后，Skill 会被下载到工作区的 skills/ 目录（或全局目录），元数据记录在 .clawhub/lock.json 中。如果启用了文件监视（默认启用），下一次对话轮次就能使用新安装的 Skill。如果文件监视被禁用，需要开启新的对话会话（/new）或重启 Gateway。

安装前验证： 建议在安装第三方 Skill 前先验证其来源和依赖：

openclaw skills verify my-skill

验证会检查 Skill 的来源是否可信、依赖是否完整、是否存在已知的安全问题。

查看已安装技能

openclaw skills list

输出示例：

Status        Skill              Description                    Source
✓ ready       weather            查询天气与预报                  openclaw-bundled
✓ ready       sql-toolkit        SQL 数据库管理工具              clawhub
✓ ready       github             管理 GitHub 仓库               openclaw-bundled
△ needs setup gemini-search      使用 Gemini CLI 搜索           openclaw-workspace

Status 列显示 Skill 的当前状态（ready 可用、needs setup 需要配置、missing 缺失依赖）。Source 列显示 Skill 的来源（openclaw-bundled 内置、clawhub 从市场安装、openclaw-workspace 工作区本地）。

升级技能

# 升级单个技能
openclaw skills update sql-toolkit

# 升级所有已安装的 ClawHub 技能
openclaw skills update --all

升级操作会从 ClawHub 拉取最新版本，替换本地文件，并更新 lock.json 中的版本记录。内置 Skills 不通过此命令升级，它们随 OpenClaw 版本更新。

检查依赖

openclaw skills check

这个命令会扫描所有 Skills 的依赖要求，并报告哪些 Skill 缺少必要的工具或环境变量。这是排查 Skill 不可用问题的第一步。

4.2 clawhub CLI：开发者进阶的完整工具链

clawhub 是一个独立的命令行工具，专为技能开发者设计。它提供了完整的发布、同步和账号管理能力，是 Skill 开发生命周期的核心工具。

安装与认证

# 安装 CLI
npm install -g clawhub

# 登录（自动打开浏览器完成 OAuth 授权）
clawhub login
# OK. Logged in as @zhangyongzhi.

# 查看当前身份
clawhub whoami

# 登出
clawhub logout

登录后可以获得更高的 API 请求配额，发布 Skill 也需要先登录。认证信息存储在本地配置文件中，不要提交到代码仓库。

搜索与查看详情

# 语义搜索
clawhub search "sql backups"
clawhub search image gen --limit 5

# 查看详情
clawhub inspect ai-image-gen

inspect 命令会输出 Skill 的完整信息，包括 SKILL.md 内容、标签、许可协议和依赖要求。这对于了解一个 Skill 的内部实现很有帮助。

安装与卸载

# 安装最新版本
clawhub install ai-image-gen

# 安装指定版本
clawhub install ai-image-gen --version 1.1.0

# 强制覆盖已有文件
clawhub install ai-image-gen --force

# 卸载（同时清理 lock.json）
clawhub uninstall ai-image-gen

clawhub uninstall 比手动删除文件夹更干净，因为它会同时清理 .clawhub/lock.json 中的记录，避免残留的元数据导致问题。

卸载时需要指定工作目录：

# 卸载工作区级的 Skill
clawhub --workdir /path/to/agent-workspace uninstall @owner/my-skill

# 卸载全局 Skill
clawhub --workdir ~/.openclaw uninstall @owner/my-skill

如果设置了 OPENCLAW_STATE_DIR 环境变量，使用其值代替 ~/.openclaw。

列表与同步

# 查看已安装技能（简洁格式）
clawhub list
# weather              1.0.0
# self-improving-agent 3.0.13
# sql-toolkit          1.0.0

# 预览将发布哪些技能（不实际发布）
clawhub sync --dry-run

# 自动扫描并发布所有本地变更
clawhub sync --all

sync 命令会扫描本地技能目录，自动检测新增或更新的技能，并将其发布到 ClawHub 注册表。--dry-run 参数可以预览哪些 Skill 会被发布，而不会实际执行发布操作。

发布技能

clawhub skill publish ./my-skill --slug my-skill --version 1.0.0

发布要求：

• 技能目录必须包含有效的 SKILL.md
• GitHub 账户注册满 7 天
• 通过 ClawHub 的危险代码扫描
• 已登录 ClawHub 账号

发布后，其他用户可以通过 openclaw skills install my-skill 或 clawhub install my-skill 安装你的 Skill。

4.3 两套命令的选型指南

面对两套工具，该如何选择？以下是一个清晰的对比和选型建议：

简单来说：

• 日常使用用 openclaw skills：搜索、安装、升级、检查状态，一个命令搞定
• 开发发布用 clawhub：登录、发布、同步、版本管理，专业工具做专业事
• 两者可以混用：用 clawhub 发布的 Skill，可以用 openclaw skills install 安装；用 openclaw skills install 安装的 Skill，可以用 clawhub uninstall 卸载

5. 多 Skill 协同实战：构建复杂自动化流水线

单个 Skill 只能完成原子操作，但多个 Skill 串联起来，就能构建复杂的自动化流水线。Skills 不是孤立的功能块，而是可编排的乐高积木。OpenClaw 的强大之处在于，AI 可以根据用户意图，自动编排多个 Skill 完成复杂任务，你不需要手动指定调用顺序。

5.1 从原子操作到编排组合

让我们先理解"原子操作"和"编排组合"的区别。

原子操作是指单个 Skill 完成的单一任务。例如：

• weather Skill 查询天气是一个原子操作
• github Skill 列出 Issue 是一个原子操作
• exec 工具运行脚本是一个原子操作

编排组合是指多个原子操作按特定顺序协同完成一个复杂目标。例如：

• 先查天气，再根据天气情况生成穿衣建议，最后发送给用户
• 先从 GitHub 拉取 Issue 列表，再分类整理，再生成周报
• 先读取 PDF 合同，再提取关键条款，再生成风险分析报告

OpenClaw 的 AI 会根据用户的自然语言描述，自动规划执行路径，选择合适的 Skills，并按正确的顺序调用它们。你只需要描述最终目标，不需要关心中间步骤。

5.2 典型场景拆解

场景一：自动生成团队周报

用户需求： "帮我生成本周的团队周报，包含 GitHub 上的新 Issue、PR 和客户反馈邮件"

执行流程：

┌─────────────────────────────────────────────────┐
│  步骤 1：调用 github Skill                        │
│  拉取过去一周的新 Issue 和 Pull Request            │
│  命令：gh issue list --since "7 days ago"         │
│        gh pr list --since "7 days ago"            │
└──────────────────────┬──────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────┐
│  步骤 2：读取邮件通道                              │
│  收取本周的客户反馈邮件                            │
└──────────────────────┬──────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────┐
│  步骤 3：AI 聚合信息                               │
│  将 GitHub 数据和邮件内容整理为结构化摘要           │
└──────────────────────┬──────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────┐
│  步骤 4：调用 write 工具                           │
│  将结果写入 reports/weekly-2026-10-03.md           │
└──────────────────────┬──────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────┐
│  步骤 5：调用消息通道（可选）                        │
│  将周报发送给团队成员                              │
└─────────────────────────────────────────────────┘

关键洞察： 整个过程无需人工干预，背后是多个 Skill 的无缝协作。AI 充当"调度员"，根据用户意图动态编排执行流程。你只需要一句话描述目标，系统自动完成所有中间步骤。

场景二：本地知识库问答

用户需求： "帮我分析这份合同的风险条款"

执行流程：

1. 调用 pdf 或 nano-pdf Skill：提取 PDF 合同文本内容
2. AI 分析内容：识别风险条款、关键条款、潜在问题
3. 生成结构化报告：列出风险点、建议措施、参考法条
4. 调用 write 工具：保存分析报告到本地文件

隐私保护： 这类应用通常会禁用外部网络访问，确保文档内容始终留在本地，符合数据隐私要求。所有处理都在你的设备上完成，合同内容不会上传到任何外部服务器。

场景三：跨设备告警通知

用户需求： "服务器出现异常时，立即通知我的手机"

执行流程：

1. 监控脚本检测异常：通过 exec 工具定期运行监控脚本
2. 触发消息通知：调用 OpenClaw 的消息通道（如 Telegram、微信）
3. Gateway 路由消息：将告警推送到已配对的手机设备

前提条件：

• Gateway 正常运行
• 手机设备已完成配对（通过 openclaw pairing 命令）
• 配置了相应的消息通道（如 Telegram Bot）

场景四：自动化内容发布

用户需求： "把这篇 Markdown 文章发布到我的博客"

执行流程：

1. 读取 Markdown 文件：调用 read 工具读取文章内容
2. 格式转换：AI 将 Markdown 转换为博客平台要求的格式（如 HTML 或特定 API 格式）
3. 调用发布 API：通过 exec 或特定 Skill 调用博客平台的 API
4. 确认发布：返回发布成功的链接和状态

5.3 隐私与本地优先实践

OpenClaw 的 Skills 设计遵循"本地优先"原则，这是其区别于云端 AI 服务的核心优势之一。

数据不出本地： 除非 Skill 明确需要网络访问（如调用外部 API），否则所有操作在本地完成。你的文件、数据、对话内容不会无缘无故被上传到云端。

环境变量隔离： 敏感信息（如 API Key、密码）仅在 Skill 执行期间注入进程环境，执行完成后立即清除。这种"用完即毁"的机制防止了密钥泄露。

沙箱隔离： 在 Docker 沙箱中运行的 Skill，无法访问宿主机的敏感文件。沙箱提供了一个受控的执行环境，即使 Skill 代码有问题，也不会影响宿主机。

权限最小化： 高风险操作（如文件删除、系统命令执行、网络请求）默认需要用户确认。OpenClaw 会在执行前显示即将运行的命令，让你有机会审查和拒绝。

透明可控： 你可以随时查看 OpenClaw 正在执行什么操作、访问了什么文件、发送了什么网络请求。这种透明性让你对系统行为有完全的掌控。

6. 安全防线与生态治理：能力越大责任越大

Skills 可以读写文件、执行命令、访问网络，如果被滥用，后果不堪设想。一个恶意的 Skill 可以窃取你的 API Key、删除你的文件、甚至在后台运行挖矿程序。OpenClaw 从设计之初就将安全置于核心位置，构建了多层防护体系。

6.1 权限最小化与运行时防护

执行策略控制

OpenClaw 的配置系统允许你按 Skill 粒度控制权限。通过 security.installPolicy 配置，你可以在 Skill 安装前运行自定义检查脚本，阻止不信任的 Skill 安装：

{
  "security": {
    "installPolicy": {
      "enabled": true,
      "targets": ["skill", "plugin"],
      "exec": {
        "command": "/usr/local/bin/openclaw-install-policy",
        "args": ["--json"],
        "timeoutMs": 10000
      }
    }
  }
}

安装策略会在 Skill 安装前运行，检查 Skill 的来源、代码内容、依赖要求等，并返回 allow（允许）、warn（警告但可继续）或 block（阻止）的决策。这为企业环境和安全敏感场景提供了额外的防护层。

沙箱环境隔离

Docker 沙箱是 OpenClaw 提供的另一层安全防护。在沙箱中运行的 Skill 被隔离在一个独立的容器内，无法访问宿主机的文件系统和网络：

{
  "agents": {
    "defaults": {
      "sandbox": {
        "docker": {
          "env": { "GEMINI_API_KEY": "your-key-here" }
        }
      }
    }
  }
}

沙箱隔离的关键点：

• Skill 只能访问沙箱内挂载的目录，无法读取宿主机的其他文件
• 网络访问可以被限制，防止 Skill 向外部发送数据
• 即使 Skill 代码有漏洞或恶意行为，也无法影响宿主机
• 沙箱容器在任务完成后自动销毁，不留痕迹

敏感操作确认

当 Skill 尝试执行高风险操作时，OpenClaw 会要求用户确认。这些高风险操作包括：

• 文件删除：删除多个文件前，列出文件清单并询问"确定要删除这些文件吗？"
• 系统命令执行：执行可能影响系统的命令前，显示完整命令并请求批准
• 网络请求：访问外部 API 或发送数据前，提示用户确认
• 权限提升：需要管理员权限的操作会明确要求授权

这种"人在回路"（human-in-the-loop）的设计确保了用户对系统行为的最终控制权。AI 可以建议和执行操作，但关键决策由用户做出。

6.2 第三方 Skill 审计方法论

ClawHub 上的 Skill 经过静态安全扫描，但扫描不等于绝对安全。安全扫描只能检测已知的危险模式，无法发现所有潜在问题。安装第三方 Skill 时，建议你遵循以下检查清单。

安装前检查清单

第一步：快速浏览 SKILL.md。 确认功能描述与实际代码一致。如果一个 Skill 声称是"天气查询工具"，但正文中包含大量文件操作和网络请求的指令，就要提高警惕。

第二步：审查 scripts/ 目录。 这是 Skill 的执行代码，特别注意以下内容：

• 涉及文件系统写入的操作（write、rm、mv 等）
• 网络请求（curl、wget、requests.get 等）
• 动态代码执行（eval、exec、importlib 等）
• 路径中包含 ../ 等目录遍历操作

第三步：检查环境变量读取。 确认 Skill 不会泄露你的 API Key。合法的 Skill 只会在需要时读取环境变量，不会将其写入日志或发送到外部。

第四步：验证来源。 优先选择高星标、多下载的 Skill。检查发布者的 GitHub 账户是否活跃、是否有其他可信的项目。

第五步：隔离测试。 对于来源不明的 Skill，先在虚拟机或 Docker 容器中测试，确认行为符合预期后再在正式环境中使用。

危险信号识别

以下特征可能表明 Skill 存在安全风险，遇到时应提高警惕：

使用 verify 命令

安装前使用 openclaw skills verify 命令检查 Skill 的安全性：

openclaw skills verify my-skill

这个命令会检查 Skill 的来源是否可信、是否通过了 ClawHub 的安全扫描、依赖是否完整。如果发现问题，会给出警告或错误提示。

6.3 开发者安全准则与生态规范

如果你自己开发 Skill，请遵循以下安全准则。这不仅是对用户负责，也是建立可信生态的基础。

安全编码规范

规则一：永远不要硬编码密钥。 通过 metadata.openclaw.requires.env 声明依赖，让用户在配置中设置：

# 正确的做法
metadata:
  openclaw:
    requires:
      env: ["API_KEY"]

# 错误的做法
# 在脚本中直接写：API_KEY = "sk-1234567890abcdef"

规则二：对用户输入进行校验。 防止路径遍历攻击和命令注入：

# 错误：直接使用用户输入
cat "$USER_INPUT"

# 正确：验证路径
if [[ "$USER_INPUT" == *..* ]]; then
  echo "Error: Invalid path - directory traversal detected"
  exit 1
fi
cat "$USER_INPUT"

# 错误：直接拼接用户输入
os.system(f"cat {user_input}")

# 正确：使用安全的 API
import subprocess
subprocess.run(["cat", user_input], check=True)

规则三：日志中脱敏敏感信息。 不要将 API Key、密码等写入日志：

# 错误
echo "Using API key: $API_KEY" >> debug.log

# 正确
echo "Using API key: [REDACTED]" >> debug.log

规则四：在 SKILL.md 中清晰声明权限需求。 让用户在安装前就能评估风险：

## Security Considerations

此 Skill 需要以下权限：
- 读取 `~/Documents` 目录下的文件（用于分析文档内容）
- 发送邮件（需要 SMTP 服务器访问，用于发送报告）
- 访问外部 API（仅用于验证许可证，不会发送用户数据）

规则五：最小权限原则。 只请求完成任务所必需的权限。如果你的 Skill 只需要读取文件，就不要请求写入权限；如果只需要访问一个 API，就不要请求所有网络访问权限。

生态治理机制

ClawHub 设有多重安全防护，确保生态的健康和安全：

账户限制： GitHub 账户需注册满 7 天才能发布 Skill。这个限制防止了恶意用户创建临时账户发布恶意 Skill。

危险代码扫描： 安装时会运行内置扫描器，检测已知的危险代码模式（如硬编码密钥、可疑的网络请求、文件删除操作等）。发现问题的 Skill 会被标记或阻止安装。

社区举报： 多个用户举报后，Skill 会被自动隐藏，等待人工审查。这种社区驱动的治理机制能够快速发现和应对新出现的安全威胁。

依赖门控： OpenClaw 加载 Skill 时会根据 SKILL.md 中的元数据检查依赖。如果依赖不满足，Skill 不会被加载，避免了因缺少工具而导致的运行时错误。

版本管理与回滚： ClawHub 采用语义化版本（SemVer），支持版本回滚。如果新版本出现问题，可以快速回退到稳定版本：

# 安装指定版本
openclaw skills install my-skill --version 1.0.0

# 查看已安装版本
clawhub list

安装策略： 企业用户可以通过 security.installPolicy 配置自定义的安装检查脚本，在 Skill 安装前进行额外的安全审查。这为高安全要求的环境提供了额外的防护层。

发布后的维护责任

发布 Skill 不是一次性的行为，而是持续的维护责任：

• 及时修复安全问题：如果发现安全漏洞，应立即发布修复版本，并在更新说明中清晰描述问题
• 保持依赖更新：定期更新 Skill 依赖的外部工具和库，修复已知的安全问题
• 响应用户反馈：关注用户报告的问题和建议，及时改进 Skill
• 清晰的版本说明：每次更新都提供清晰的变更日志，让用户了解新版本带来了什么变化

总结与进阶

本章核心知识回顾

作为使用者的建议

• 善用优先级机制：在项目工作区定制 Skill，避免影响全局配置
• 优先选择 ClawHub 验证过的 Skill：高星标、多下载的 Skill 通常更可靠
• 组合多个 Skill 解决实际问题：不要局限于单个 Skill，尝试让多个 Skill 协同工作
• 始终保持安全意识：安装前审查、使用时观察、发现问题及时反馈

作为开发者的建议

• 以最小权限为准则：只请求必要的权限，清晰声明所有依赖
• 以用户安全为底线：不硬编码密钥、不泄露敏感信息、校验用户输入
• 写出清晰、可靠、可审计的代码：让其他开发者能够轻松审查和理解你的 Skill
• 积极参与社区共建：分享经验、帮助他人、共同维护生态的健康发展

课后练习

1. 基础：使用 openclaw skills list 查看当前已安装的 Skills，找出 3 个状态为"ready"的 Skill，阅读它们的 SKILL.md 文件
2. 进阶：在工作区的 skills/ 目录下创建一个简单的自定义 Skill，功能是将用户输入的文本转换为大写并输出
3. 高级：安装一个 ClawHub 上的第三方 Skill，审查其 SKILL.md 和 scripts/ 目录，评估其安全性
4. 挑战：设计一个多 Skill 协同的自动化流程，用自然语言描述需求，让 OpenClaw 自动编排多个 Skill 完成任务

本章完

本文为《OpenClaw 实战指南》系列第 4 篇。