第 9 章：技能系统 🎯

工具是 Agent 的"双手"，技能就是 Agent 的"职业培训"。

---

9.1 什么是 Skill？

工具（Tool）和技能（Skill）有什么区别？

	工具	技能
本质	可调用的功能函数	MK 说明文档
类比	给你一把菜刀	给你一本《川菜食谱》
作用	能做某个动作	知道什么时候用、怎么用
形式	代码实现	Markdown 文档
谁创建的	OpenClaw 或插件作者	你或社区

技能的核心理念： Agent 可能已经有所有的工具（菜刀、锅、砧板），但它不知道怎么用它们做出好菜（回锅肉）。技能就是那本菜谱——告诉 Agent 组合工具的步骤和最佳实践。

技能系统工作原理：SKILL.md → Agent → 工具组合

每个技能就是一个 SKILL.md 文件，放在特定目录下，系统启动时会加载到 Agent 的提示词中。

---

9.2 SKILL.md 结构

一个 SKILL.md 文件由两部分组成：

YAML 前置元数据（Frontmatter）

---
name: weather
description: 查询天气和获取天气预报
---

最低要求只需要 name 和 description。

可选的前置字段

字段	作用
homepage	在 macOS UI 显示为"网站链接"
user-invocable	是否作为斜杠命令暴露（默认 true）
disable-model-invocation	是否不进系统提示词，仅作为斜杠命令
command-dispatch	设为 tool 时绕过模型直接调度工具
command-tool	调度到哪个工具

Markdown 正文

这是技能的核心——告诉 Agent 怎么做：

---
name: weather
description: 查询天气和获取天气预报
---

# 天气查询技能

## 什么时候用
当用户询问天气时，使用本技能。

## 步骤
1. 用 `web_search` 搜索 "今日天气 [城市名]"
2. 或使用 `web_fetch` 查询 wttr.in
3. 整理天气信息：温度、湿度、风速、降水概率

## 示例
用户：「明天北京天气怎么样？」
步骤：
1. web_fetch("https://wttr.in/Beijing")
2. 提取数据：温度范围、是否下雨
3. 回答：「明天北京 25-32°C，晴转多云，适合出门！」

---

9.3 技能的加载机制

技能按优先级从高到低加载：

① 工作区技能    → <workspace>/skills/（最高优先级）
② 项目 Agent    → <workspace>/.agents/skills/
③ 个人 Agent    → ~/.agents/skills/
④ 本地管理      → ~/.openclaw/skills/
⑤ 内置技能      → 安装时自带（最低优先级）
⑥ 额外目录      → skills.load.extraDirs 配置的目录

同名覆盖： 如果多个位置存在同名技能，优先级高的覆盖低的。

示例目录结构：

~/.openclaw/workspace/skills/
├── weather/
│   └── SKILL.md
├── research/
│   └── SKILL.md
└── personal/
    └── diary/
        └── SKILL.md      # 技能名还是 flat 的，按 frontmatter 的 name

目录层级只用来组织文件，技能名取 name 字段的值（或文件夹名）。

---

9.4 内置 Skill

OpenClaw 自带了一些实用的技能：

weather（天气技能）

---
name: weather
description: 查询今日天气和天气预报
metadata: { "openclaw": { "requires": { "bins": [] } } }
---

## 何时使用
当用户问天气、温度、会不会下雨时使用此技能。

## 步骤
用 `web_fetch` 查询 wttr.in/[城市名] 获取天气信息。
整理并回答用户的问题。

这个技能告诉 Agent 用 web_search 或 web_fetch 来查天气。开箱即用，无需任何 API Key。

healthcheck（安全检查技能）

用于检查 OpenClaw 主机的安全状况——SSH、防火墙、更新包、备份等。更偏运维场景。

browser-automation（浏览器自动化技能）

教 Agent 如何使用浏览器工具完成多步骤操作——登录、填写表单、截图等。

---

9.5 技能的条件门控

不是所有技能都需要加载到每个 Agent 里。技能可以通过 metadata.openclaw 控制加载条件：

---
name: image-lab
description: 用提供商支持的图像工作流生成或编辑图片
metadata:
  {
    "openclaw":
      {
        "requires": { "bins": ["uv"], "env": ["GEMINI_API_KEY"] },
        "primaryEnv": "GEMINI_API_KEY",
      },
  }
---

门控条件	含义
requires.bins	需要系统已安装的二进制文件（如 uv）
requires.anyBins	至少有一个二进制文件存在
requires.env	需要环境变量存在
requires.config	需要在 openclaw.json 中有对应配置
os	只在特定操作系统加载
always	永不过滤，始终加载

如果没有 metadata.openclaw 块，技能默认总是可用。

手动开关技能

{
  skills: {
    entries: {
      "image-lab": { enabled: false },    // 关掉
      "weather": { enabled: true },       // 打开
      "peekaboo": { enabled: true },      // 打开
    },
  },
}

---

9.6 安装第三方 Skill

从 ClawHub 安装

ClawHub 是 OpenClaw 的公共技能市场（clawhub.ai）：

# 安装到当前工作区
openclaw skills install @owner/skill-name

# 安装到全局（所有 Agent 可用）
openclaw skills install @owner/skill-name --global

# 从 Git 安装
openclaw skills install git:owner/repo@branch

# 从本地安装
openclaw skills install ./path/to/skill --as my-tool

ClawHub 的安全验证

# 验证技能的信任包
openclaw skills verify @owner/skill-name

# 查看技能卡
openclaw skills verify @owner/skill-name --card

更新技能

# 更新所有工作区技能
openclaw skills update --all

# 更新全局技能
openclaw skills update @owner/skill-name --global

⚠️ 安全提示： 第三方技能就像你从网上下载的软件。安装前请自己先读一遍，确保它不会做危险的事。

---

9.7 创建自己的 Skill

你完全可以自己写技能。下面是完整的步骤指南。

场景：创建一个"翻译"技能

第一步：创建文件夹和文件

mkdir -p ~/.openclaw/workspace/skills/translator

第二步：编写 SKILL.md

---
name: translator
description: 多语言翻译助手
user-invocable: true
---

# 翻译技能

## 何时使用
当用户要求翻译文本到另一种语言时使用。

## 步骤
1. 确认源语言和目标语言
2. 使用 `web_fetch` 调用翻译 API（如有道、谷歌翻译）
3. 返回翻译结果

## 示例
用户：「把这段话翻译成英文：今天天气真好」
步骤：
1. 源语言：中文，目标语言：英文
2. web_fetch("翻译API...")
3. 回答：「The weather is great today.」

第三步：测试

重启 OpenClaw 或开启新会话，然后问：

帮我翻译 "Hello world" 成中文

Agent 应该按照技能步骤来操作。

创建带门控的技能

如果需要特定环境变量或工具才能使用：

---
name: github-ops
description: GitHub 仓库管理操作
metadata:
  {
    "openclaw":
      {
        "requires": { "bins": ["gh", "git"] },
        "primaryEnv": "GITHUB_TOKEN",
      },
  }
---

这样如果系统没有安装 gh 和 git，这个技能就不会加载。

---

9.8 技能 Workshop 机制

你是不是担心 Agent 自己写技能会搞砸？OpenClaw 的 Skill Workshop 就是为此设计的。

当 Agent 在对话中发现可重复使用的工作流程时，它不会直接创建技能文件，而是创建一个提案（Proposal）。你先审核，再批准。

# 查看所有待审核的提案
openclaw skills workshop list

# 查看某个提案
openclaw skills workshop inspect <proposal-id>

# 批准应用
openclaw skills workshop apply <proposal-id>

这样你就能保证进入工作区的每个技能都是经过你确认的。

---

9.9 实战：安装并使用天气技能

这是大多数 OpenClaw 用户的第一个技能体验。

第一步：确认内置技能已生效

内置的 weather 技能随安装一起提供，无需额外安装。

第二步：测试

问 Agent：

今天天气怎么样？

Agent 会自动调用天气技能，用 web_fetch 查 wttr.in 的天气数据。

第三步：进阶——从 ClawHub 安装社区天气技能

openclaw skills install @someuser/weather-pro

第四步：查看技能列表

openclaw skills list

---

当当老师 🐾 笔记： 技能系统是 OpenClaw 最容易被忽视但最强大的功能之一。工具决定了 Agent 能做什么，技能决定了 Agent 能不能做得好。用好技能，你的 Agent 就从"实习生"变成了"老师傅"！

---

上一章 ← 第 8 章：工具系统 | 下一章 → 第 10 章：记忆系统