21.1 技能平台设计

生成模型：Claude Opus 4.6 (anthropic/claude-opus-4-6) Token 消耗：输入 ~400k tokens，输出 ~7k tokens（本节）

---

LLM 本身是通用的——它什么都能聊，但什么都不精通。要让 Agent 在特定领域（天气查询、GitHub 操作、智能家居控制）变得专业，需要给它注入领域知识和操作指南。OpenClaw 的技能系统（Skills）正是为此而设计：一套可热插拔、自描述、自动发现的 Agent 能力扩展机制。

---

21.1.1 什么是技能：可热插拔的 Agent 能力模块

设计理念

技能的核心思想很简单：一个 Markdown 文件就是一项技能。技能文件（通常名为 SKILL.md）包含两部分：

1. Front Matter（YAML 头部）——结构化元数据：名称、描述、依赖要求、安装方式

2. 正文——Agent 要学习的领域知识：API 用法、命令示例、最佳实践

---
name: weather
description: Get current weather and forecasts (no API key required).
metadata: { "openclaw": { "emoji": "🌤️", "requires": { "bins": ["curl"] } } }
---

# Weather

Two free services, no API keys needed.

## wttr.in (primary)

Quick one-liner:
```bash
curl -s "wttr.in/London?format=3"

Agent 在接收到用户请求时，系统会将符合条件的技能内容注入到系统提示词（System Prompt）中。Agent 不需要"调用"技能——它只需要**阅读**技能文件中的指引，然后使用已有的工具（如 `bash`）执行操作。

> **衍生解释**：这种设计与传统的"插件 API"截然不同。传统插件定义 API 端点供程序调用；而技能是面向 LLM 的"文档"，通过自然语言指导 Agent 行为。这利用了 LLM 的核心优势——理解和遵循自然语言指令。

### 技能 vs 工具

OpenClaw 中的"技能"和"工具"是不同概念：

| 维度 | 技能（Skill） | 工具（Tool） |
|------|-------------|-------------|
| 本质 | Markdown 文档 | 可执行的函数 |
| 消费者 | LLM（通过系统提示词阅读） | LLM（通过 function calling 调用） |
| 扩展方式 | 写一个 `.md` 文件 | 编写 TypeScript 代码并注册 |
| 示例 | weather、github、discord | bash、file_read、memory_search |

技能告诉 Agent **怎么做**，工具给 Agent **能力去做**。一个天气技能告诉 Agent "用 `curl` 调用 wttr.in"，`bash` 工具让 Agent 能执行 `curl` 命令。

---

## 21.1.2 技能类型：Bundled / Managed / Workspace / Extra

OpenClaw 支持四种来源的技能，按优先级从低到高排列：

| 类型 | 目录位置 | 来源标识 | 说明 |
|------|---------|---------|------|
| **Extra** | 配置的额外目录 | `openclaw-extra` | 插件或自定义目录提供的技能 |
| **Bundled** | `<package>/skills/` | `openclaw-bundled` | 随 OpenClaw 安装包分发的内置技能 |
| **Managed** | `~/.openclaw/skills/` | `openclaw-managed` | 通过 ClawHub 安装的托管技能 |
| **Workspace** | `<workspace>/skills/` | `openclaw-workspace` | 项目级别的自定义技能 |

优先级体现为：**同名技能，高优先级覆盖低优先级**。如果项目目录下有一个自定义的 `weather` 技能，它会覆盖内置的 `weather` 技能。

```typescript
// src/agents/skills/workspace.ts（简化）

const merged = new Map<string, Skill>();
// 优先级：extra < bundled < managed < workspace
for (const skill of extraSkills)    merged.set(skill.name, skill);
for (const skill of bundledSkills)  merged.set(skill.name, skill);
for (const skill of managedSkills)  merged.set(skill.name, skill);
for (const skill of workspaceSkills) merged.set(skill.name, skill);

内置技能（Bundled）

OpenClaw 随包附带 52 个内置技能，覆盖开发工具、通信平台、智能家居、媒体处理等领域：

类别	代表性技能	说明
开发工具	github, coding-agent, tmux	Git 操作、子 Agent 编排、终端会话
通信平台	discord, slack, imsg, bluebubbles	聊天平台集成
笔记/知识	obsidian, notion, bear-notes, apple-notes	各类笔记应用
智能家居	openhue, sonoscli	Hue 灯光、Sonos 音响
AI/模型	gemini, oracle, openai-image-gen	模型调用、图像生成
媒体	spotify-player, video-frames, camsnap	音乐、视频、摄像头
工具	weather, summarize, healthcheck	天气、摘要、健康检查
生态	clawhub, skill-creator	技能注册中心、技能创作

内置技能目录解析

resolveBundledSkillsDir 负责定位内置技能的物理目录，支持多种安装场景：

// src/agents/skills/bundled-dir.ts（简化）

export function resolveBundledSkillsDir(): string | undefined {
  // 1. 环境变量覆盖
  const override = process.env.OPENCLAW_BUNDLED_SKILLS_DIR;
  if (override) return override;

  // 2. 编译后二进制文件：查找可执行文件旁边的 skills/ 目录
  const sibling = path.join(path.dirname(process.execPath), "skills");
  if (fs.existsSync(sibling)) return sibling;

  // 3. npm/开发模式：从包根目录查找 skills/
  const packageRoot = resolveOpenClawPackageRootSync();
  if (packageRoot) {
    const candidate = path.join(packageRoot, "skills");
    if (looksLikeSkillsDir(candidate)) return candidate;
  }

  // 4. 向上遍历最多 6 层目录查找
  // ...
  return undefined;
}

looksLikeSkillsDir 通过检查目录中是否存在 .md 文件或包含 SKILL.md 的子目录来判断。

---

21.1.3 技能加载与快照

加载流程

loadSkillEntries 是技能加载的核心函数。它从四个来源加载技能，解析 Front Matter，提取元数据：

// src/agents/skills/workspace.ts（简化）

function loadSkillEntries(workspaceDir, opts?): SkillEntry[] {
  // 1. 从各来源加载原始 Skill 对象
  const bundledSkills  = loadSkillsFromDir({ dir: bundledSkillsDir, source: "openclaw-bundled" });
  const managedSkills  = loadSkillsFromDir({ dir: managedSkillsDir, source: "openclaw-managed" });
  const workspaceSkills = loadSkillsFromDir({ dir: workspaceSkillsDir, source: "openclaw-workspace" });
  const extraSkills    = extraDirs.flatMap(dir => loadSkillsFromDir({ dir, source: "openclaw-extra" }));

  // 2. 按优先级合并（同名覆盖）
  const merged = new Map<string, Skill>();
  // ... extra < bundled < managed < workspace

  // 3. 为每个技能解析 Front Matter 和元数据
  return Array.from(merged.values()).map(skill => {
    const raw = fs.readFileSync(skill.filePath, "utf-8");
    const frontmatter = parseFrontmatter(raw);
    return {
      skill,
      frontmatter,
      metadata: resolveOpenClawMetadata(frontmatter),
      invocation: resolveSkillInvocationPolicy(frontmatter),
    };
  });
}

每个 SkillEntry 包含四个层次的信息：

type SkillEntry = {
  skill: Skill;                        // 基础信息：name, description, filePath, baseDir
  frontmatter: ParsedSkillFrontmatter; // 原始 Front Matter 键值对
  metadata?: OpenClawSkillMetadata;    // 解析后的 OpenClaw 特定元数据
  invocation?: SkillInvocationPolicy;  // 调用策略
};

资格过滤

并非所有加载的技能都会被激活。shouldIncludeSkill 实现了多维度的资格检查：

// src/agents/skills/config.ts（简化）

export function shouldIncludeSkill(params: { entry, config, eligibility }): boolean {
  // 1. 配置禁用检查
  if (skillConfig?.enabled === false) return false;

  // 2. 内置技能白名单检查
  if (!isBundledSkillAllowed(entry, allowBundled)) return false;

  // 3. 操作系统兼容性检查
  if (osList.length > 0 && !osList.includes(process.platform)) return false;

  // 4. always 标记：无条件激活
  if (entry.metadata?.always === true) return true;

  // 5. 必需二进制文件检查（PATH 中是否存在）
  for (const bin of requiredBins) {
    if (!hasBinary(bin)) return false;
  }

  // 6. 任一二进制文件检查（至少有一个）
  if (requiredAnyBins.length > 0 && !requiredAnyBins.some(bin => hasBinary(bin))) return false;

  // 7. 环境变量检查
  for (const envName of requiredEnv) {
    if (!process.env[envName] && !skillConfig?.env?.[envName]) return false;
  }

  // 8. 配置路径检查
  for (const configPath of requiredConfig) {
    if (!isConfigPathTruthy(config, configPath)) return false;
  }

  return true;
}

这就是为什么用户安装 OpenClaw 后，只会看到与其环境匹配的技能——没有安装 gh CLI 的用户不会看到 github 技能，没有配置 Discord Token 的用户不会看到 discord 技能。

技能快照

技能快照（SkillSnapshot）是某一时刻所有激活技能的静态表示，用于注入到 Agent 的系统提示词中：

// src/agents/skills/types.ts

export type SkillSnapshot = {
  prompt: string;                                    // 格式化后的技能提示词
  skills: Array<{ name: string; primaryEnv?: string }>; // 激活的技能列表
  resolvedSkills?: Skill[];                          // 完整的 Skill 对象
  version?: number;                                  // 快照版本（用于缓存）
};

buildWorkspaceSkillSnapshot 构建快照的过程：加载 → 过滤 → 排除 disableModelInvocation 的技能 → 调用 formatSkillsForPrompt 生成提示文本。

技能命令规格

每个技能还可以注册为斜杠命令（/weather、/github），让用户直接调用。buildWorkspaceSkillCommandSpecs 为每个可调用的技能生成命令规格：

// src/agents/skills/workspace.ts（简化）

function buildWorkspaceSkillCommandSpecs(workspaceDir, opts?): SkillCommandSpec[] {
  const eligible = filterSkillEntries(entries, config);
  const userInvocable = eligible.filter(e => e.invocation?.userInvocable !== false);

  return userInvocable.map(entry => ({
    name: sanitizeSkillCommandName(entry.skill.name), // 小写+下划线，≤32字符
    skillName: entry.skill.name,
    description: entry.skill.description,
    dispatch: resolveCommandDispatch(entry),           // 可选的确定性调度
  }));
}

命令名经过 sanitizeSkillCommandName 处理（只保留 [a-z0-9_]），并通过 resolveUniqueSkillCommandName 确保唯一性。技能的 Front Matter 还可以通过 command-dispatch: tool + command-tool: <toolName> 指定确定性调度——即命令不经过 LLM 推理，直接调用指定工具。

---

本节小结

1. 技能本质是 Markdown 文档，通过 Front Matter 声明元数据，正文提供领域知识，注入系统提示词后指导 Agent 行为。

2. 四种来源按优先级排列：Extra < Bundled < Managed < Workspace，同名技能高优先级覆盖低优先级。

3. 资格过滤检查八个维度：配置禁用、白名单、OS 兼容性、always 标记、必需二进制、环境变量、配置路径，确保只激活与当前环境匹配的技能。

4. 技能快照是激活技能的静态表示，formatSkillsForPrompt 将其格式化为系统提示词的一部分。

5. 52 个内置技能覆盖开发、通信、智能家居、媒体等领域，每个技能文件独立自包含，便于理解和扩展。