OpenClaw Find Skills 功能详解

分析时间： 2026-03-02 源码来源： OpenClaw/src/agents/skills/ 功能类型： 技能发现与安装工具

🎯 功能定位

Find Skills 是 OpenClaw 的技能发现、搜索和安装工具，帮助用户：

快速查找所需技能
查看技能状态和依赖
一键安装合适的技能
支持多种安装方式

🔍 技能发现机制

1. 技能来源

来源路径（优先级从高到低）：

1. 工作区技能目录 (workspace/skills/)
2. .agents 技能目录 (~/.agents/skills/)
3. 配置文件指定目录 (skills.load.extraDirs)
4. 插件技能目录 (extensions/*)
5. 全局技能目录 (CONFIG_DIR/skills/)

2. 技能定义

文件： SKILL.md（每个技能目录必须包含）

格式示例：

markdown

---
id: my-skill
kind: node
description: 我的功能性技能
emoji: 🔧
homepage: https://github.com/user/skill
---

# 技能说明
这里写技能的详细说明...

元数据字段：

typescript

type SkillMetadata = {
  id?: string;
  kind: "brew" | "node" | "go" | "uv" | "download";
  label?: string;
  bins?: string[];
  os?: string[];
  install?: SkillInstallSpec[];
  always?: boolean;
  skillKey?: string;
  primaryEnv?: string;
  emoji?: string;
  homepage?: string;
}

3. 技能解析

文件： src/agents/skills/types.ts

解析功能：

Frontmatter 解析（标题、元数据）
技能验证（必需字段检查）
安装规范提取
调用策略配置

📊 技能状态检查

文件： src/agents/skills-status.ts

状态报告结构

typescript

type SkillStatusEntry = {
  name: string;
  description: string;
  source: string;          // openclaw-bundled / workspace / managed
  bundled: boolean;
  filePath: string;
  baseDir: string;
  skillKey: string;
  primaryEnv?: string;
  emoji?: string;
  homepage?: string;
  always?: boolean;
  disabled?: boolean;
  blockedByAllowlist?: boolean;  // 是否被允许列表阻止
  eligible?: boolean;       // 是否可以安装
  requirements: Requirements;     // 依赖需求
  missing: Requirements;          // 缺失的依赖
  configChecks: SkillStatusConfigCheck[];  // 配置检查结果
  install: SkillInstallOption[];       // 可用的安装选项
}

检查维度

1. 依赖需求检查

需求类型	检查方式	示例
Binary	检查 `which <binary>`	`brew`, `go`, `uv`
Env	检查环境变量	`OPENAI_API_KEY`
Config	检查配置文件存在	`~/.config/openclaw/config.json`

2. 配置验证

Bundled Allowlist： 检查技能是否在允许列表中
Platform Eligibility： 检查 OS 匹配（os: ["linux", "darwin"]）
Env Satisfaction： 检查必需环境变量是否已设置

3. 安全扫描

文件： src/security/skill-scanner.ts

扫描内容：

危险代码模式检测
可疑代码模式警告
eval()、child_process.exec() 等 API 使用检查

严重级别：

Critical： 危险代码模式（如 eval() 用户输入）
Warning： 可疑模式（建议人工审查）

🔧 安装选项

文件： src/agents/skills-install.ts

支持的安装方式

| 方式 | kind | 说明 | 示例 | |------|------|------| | Brew | brew | Homebrew formula 安装 | | Node | node | npm/pnpm/yarn/bun 安装 | | Go | go | Go 模块安装 | | UV | uv | Python UV 包管理器 | | Download | download | 通用下载安装 |

安装选择策略

typescript

// 偏好配置（从配置读取）
interface SkillsInstallPreferences {
  preferBrew: boolean;       // 优先使用 brew
  nodeManager: "npm" | "pnpm" | "yarn" | "bun";  // 包管理器
}

// 选择逻辑（优先级）
1. 如果 preferBrew && brew 可用 → 使用 brew
2. 否则按顺序尝试：uv → node → go → download
3. 最后回退到 brew（显示错误信息）

安装命令生成

Brew 安装：

bash

brew install <formula>

Node 安装：

bash

pnpm install <package>      # 如果配置了 pnpm
# 或
npm install <package>
# 或
bun install <package>

Go 安装：

bash

go install <module>@version

UV 安装：

bash

uv tool install <package>

Download 安装：

bash

curl -fsSL <url> -o /tmp/install.sh
bash /tmp/install.sh

🎮 命令行使用

查看技能状态

bash

# 列出所有技能及其状态
openclaw skills

# 查看技能详细信息
openclaw skills --status

# 检查技能依赖
openclaw skills --check

搜索技能

bash

# 按名称搜索
openclaw skills --search <keyword>

# 按类型筛选
openclaw skills --type node

# 按平台筛选
openclaw skills --platform darwin

安装技能

bash

# 自动选择最佳安装方式
openclaw skills install <skill-id>

# 指定安装方式
openclaw skills install <skill-id> --kind brew

# 强制重新安装
openclaw skills install <skill-id> --force

# 从 URL 安装
openclaw skills install <url>

刷新技能

bash

# 重新加载所有技能（热重载）
openclaw skills refresh

🔐 安全机制

1. Bundled Allowlist

目的： 限制某些内置技能的安装/卸载

配置：

typescript

interface BundledAllowlistConfig {
  // 允许卸载的内置技能
  uninstall: string[];
}

2. 代码安全扫描

扫描触发时机：

安装前自动扫描
手动触发：openclaw security audit --deep

检测模式：

危险的 eval() 使用
child_process.exec() 用户输入
任意文件系统访问
硬编码密钥/凭证

3. 环境隔离

安装隔离：

沙箱执行（推荐 Docker）
权限最小化（Capabilities）
临时环境变量作用域

📝 技能开发指南

创建新技能

目录结构：

my-skill/
├── SKILL.md              # 技能定义文件
├── index.ts             # 技能入口
├── package.json         # 依赖配置（如果 kind: node）
├── test/                # 测试文件
└── README.md            # 文档说明

SKILL.md 示例：

markdown

---
id: my-skill
kind: node
description: 我的功能性技能
emoji: 🔧
homepage: https://github.com/user/my-skill
always: true

install:
  - id: npm
    package: my-skill
    label: Install my-skill (pnpm)
    bins: ["my-skill"]

技能类型选择指南

需求	推荐的 kind	原因
纯 Node.js 工具	`node`	直接 npm 安装，无需编译
系统级工具	`brew`	利用 Homebrew 生态，跨平台
Go 工具	`go`	编译型工具，高性能
Python 工具	`uv`	Python UV 包管理器，现代化
通用脚本	`download`	适用于任何语言和环境

🚀 高级特性

1. 技能快照

文件： src/agents/skills/bundle-dir.ts

功能：

缓存所有已解析技能配置
避免重复文件读取
提高启动速度

2. 环境覆盖

文件： src/agents/skills/env-overrides.ts

覆盖类型：

运行时环境变量
配置文件设置
快照环境变量

覆盖优先级：

运行时变量 > 快照变量 > 配置文件 > 默认值

3. 技能过滤

文件： src/agents/skills/filter.ts

过滤选项：

数组形式（白名单）
否定前缀（排除特定技能）
环境变量覆盖
前缀匹配（批量加载）

使用场景：

typescript

// 只加载 AI 相关技能
const filter = ["ai-*", "ml-*"];

// 排除测试技能
const filter = ["-test", "-dev"];

// 前缀匹配
const filter = ["openai", "anthropic"];

💡 最佳实践

1. 技能开发

✅ 清晰的技能 ID - 简短、唯一、易记 ✅ 详细的描述 - 说明技能用途和适用场景 ✅ Emoji 标识 - 提高可读性 ✅ Homepage 链接 - 指向文档或 GitHub 仓库 ✅ 安装验证 - 测试多种平台和安装方式

2. 依赖管理

✅ 最小化依赖 - 只依赖必要的包 ✅ 明确版本 - 指定兼容的版本范围 ✅ 提供替代品 - 支持 brew/node/go 等多种安装方式 ✅ 二进制检查 - 使用前检查系统工具是否已安装

3. 安全开发

✅ 避免 eval() - 不要对用户输入使用 eval ✅ 验证路径 - 防止路径遍历攻击 ✅ 最小权限 - 只请求必要的权限 ✅ 沙箱执行 - 危险操作在隔离环境中运行

4. 用户体验

✅ 安装进度显示 - 提供清晰的安装反馈 ✅ 错误处理 - 友好的错误信息和恢复建议 ✅ 向后兼容 - 支持旧版本技能格式 ✅ 文档完善 - 提供使用示例和故障排除指南

📊 命令速查表

命令	说明
`openclaw skills`	列出所有技能
`openclaw skills --status`	查看技能详细状态
`openclaw skills --check`	检查技能依赖
`openclaw skills --search <term>`	搜索技能
`openclaw skills install <id>`	安装技能
`openclaw skills refresh`	刷新技能缓存
`openclaw skills --type <kind>`	按类型筛选
`openclaw skills --platform <os>`	按平台筛选

🎯 适用场景

场景 1：不确定需要哪种技能

问题： 不知道有什么技能可用

解决：

bash

# 查看所有可用技能
openclaw skills

# 按类型筛选查看
openclaw skills --type node  # 只看 Node.js 技能

场景 2：技能安装失败

问题： 安装时报错或缺少依赖

解决：

bash

# 检查依赖状态
openclaw skills --check <skill-id>

# 查看详细状态
openclaw skills --status <skill-id>

场景 3：技能热重载

问题： 修改了技能配置但未生效

解决：

bash

# 刷新技能缓存
openclaw skills refresh

🔗 相关文件

源码文件：

src/agents/skills.ts - 技能类型定义和导出
src/agents/skills-status.ts - 技能状态检查
src/agents/skills-install.ts - 技能安装逻辑
src/agents/skills/types.ts - 技能类型系统
src/agents/skills/workspace.ts - 工作区技能加载
src/agents/skills/env-overrides.ts - 环境覆盖
src/agents/skills/filter.ts - 技能过滤
src/security/skill-scanner.ts - 安全扫描

测试文件：

src/agents/skills.test.ts - 技能系统单元测试
src/agents/skills-status.test.ts - 状态检查测试
src/agents/skills-install.test.ts - 安装流程测试

💡 新项目借鉴点

1. 插件化架构

推荐实现：

my-project/
├── plugins/
│   ├── core/              # 插件类型定义
│   ├── loader/            # 插件加载器
│   ├── installer/          # 插件安装器
│   └── scanner/           # 插件扫描器
├── config/
│   └── plugins.json       # 插件配置
└── cli/
    └── plugins.ts         # 插件 CLI 命令

2. 多安装方式支持

推荐模式：

typescript

interface PluginInstallSpec {
  id: string;
  kind: "npm" | "brew" | "go" | "python" | "download";
  package?: string;
  formula?: string;
  module?: string;
  url?: string;
  bins?: string[];
  os?: string[];
  install?: PluginInstallSpec[];
}

function resolveBestInstall(
  specs: PluginInstallSpec[],
  prefs: InstallPreferences
): InstallSpec | undefined {
  // 1. 按偏好顺序尝试
  // 2. 检查工具是否可用
  // 3. 验证平台支持
  // 4. 返回最佳选项
}

3. 状态检查机制

推荐实现：

typescript

interface PluginStatus {
  name: string;
  version: string;
  source: string;
  installed: boolean;
  eligible: boolean;
  missing: Dependency[];
  warnings: string[];
  installOptions: InstallOption[];
}

async function checkPluginStatus(
  pluginId: string
): Promise<PluginStatus> {
  // 1. 检查是否已安装
  // 2. 验证依赖
  // 3. 扫描安全问题
  // 4. 生成安装选项
}

4. 安全扫描集成

推荐实现：

typescript

import { scanDirectoryWithSummary } from "./scanner";

async function safePluginInstall(
  pluginDir: string
): Promise<InstallResult> {
  // 安装前扫描
  const scan = await scanDirectoryWithSummary(pluginDir);

  if (scan.critical > 0) {
    return {
      ok: false,
      message: "Plugin contains dangerous code patterns"
    };
  }

  // 继续安装
  return await installPlugin(pluginDir);
}

📈 版本管理

技能版本

文件： src/agents/skills/bundle-dir.ts

版本机制：

全局版本号： 时间戳递增
工作区版本号： Map 结构（skillId → version）
自动检测： 文件变化触发版本更新

版本对比

typescript

function bumpVersion(current: number): number {
  const now = Date.now();
  return now <= current ? current + 1 : now;
}

function needsRefresh(
  currentVersion: number,
  snapshotVersion: number
): boolean {
  return snapshotVersion > currentVersion;
}

🎯 核心价值总结

特性	技术实现	用户价值
技能发现	多路径扫描 + Frontmatter 解析	快速找到所需技能
状态检查	依赖验证 + 安全扫描	安装前预判可行性
多安装方式	brew/node/go/uv/download 支持	适应不同环境
热重载	chokidar 文件监听	无需重启即可更新
安全扫描	危险代码模式检测	防止安装恶意技能
环境覆盖	多层级配置合并	灵活调试和定制

分析结论： OpenClaw 的 Find Skills 功能展示了完善的插件化架构，通过多安装方式支持、智能依赖检查、安全扫描集成和热重载机制，构建了一个既强大又安全的技能管理系统。其设计思想值得在新项目中深入借鉴，特别是在技能类型系统、安装选项选择策略和状态检查机制等方面。

OpenClaw Find Skills 功能详解 ​

🎯 功能定位 ​

🔍 技能发现机制 ​

1. 技能来源 ​

2. 技能定义 ​

3. 技能解析 ​

📊 技能状态检查 ​

状态报告结构 ​

检查维度 ​

1. 依赖需求检查 ​

2. 配置验证 ​

3. 安全扫描 ​

🔧 安装选项 ​

支持的安装方式 ​

安装选择策略 ​

安装命令生成 ​

🎮 命令行使用 ​

查看技能状态 ​

搜索技能 ​

安装技能 ​

刷新技能 ​

🔐 安全机制 ​

1. Bundled Allowlist ​

2. 代码安全扫描 ​

3. 环境隔离 ​

📝 技能开发指南 ​

创建新技能 ​

技能类型选择指南 ​

🚀 高级特性 ​

1. 技能快照 ​

2. 环境覆盖 ​

3. 技能过滤 ​

💡 最佳实践 ​

1. 技能开发 ​

2. 依赖管理 ​

3. 安全开发 ​

4. 用户体验 ​

📊 命令速查表 ​

🎯 适用场景 ​

场景 1：不确定需要哪种技能 ​

场景 2：技能安装失败 ​

场景 3：技能热重载 ​

🔗 相关文件 ​

💡 新项目借鉴点 ​

1. 插件化架构 ​

2. 多安装方式支持 ​

3. 状态检查机制 ​

4. 安全扫描集成 ​

📈 版本管理 ​

技能版本 ​

版本对比 ​

🎯 核心价值总结 ​

OpenClaw Find Skills 功能详解

🎯 功能定位

🔍 技能发现机制

1. 技能来源

2. 技能定义

3. 技能解析

📊 技能状态检查

状态报告结构

检查维度

1. 依赖需求检查

2. 配置验证

3. 安全扫描

🔧 安装选项

支持的安装方式

安装选择策略

安装命令生成

🎮 命令行使用

查看技能状态

搜索技能

安装技能

刷新技能

🔐 安全机制

1. Bundled Allowlist

2. 代码安全扫描

3. 环境隔离

📝 技能开发指南

创建新技能

技能类型选择指南

🚀 高级特性

1. 技能快照

2. 环境覆盖

3. 技能过滤

💡 最佳实践

1. 技能开发

2. 依赖管理

3. 安全开发

4. 用户体验

📊 命令速查表

🎯 适用场景

场景 1：不确定需要哪种技能

场景 2：技能安装失败

场景 3：技能热重载

🔗 相关文件

💡 新项目借鉴点

1. 插件化架构

2. 多安装方式支持

3. 状态检查机制

4. 安全扫描集成

📈 版本管理

技能版本

版本对比

🎯 核心价值总结