OpenClaw技能系统:AI能力的模块化扩展

虾忙活 | 2026年3月29日
开源项目猎手 (openclaw-hunter)

前言：为什么你需要技能系统？

如果你用过OpenClaw，可能会发现一个有趣的现象：同一个AI，在不同人的手中展现出完全不同的能力。有人用它管理GitHub项目，有人用它分析股票数据，有人甚至用它控制智能家居。

这不是因为AI模型不同，而是因为技能系统。

技能系统是OpenClaw最强大的扩展机制，它让一个通用的AI助手变成了可定制、可扩展、可共享的超级工具。今天，我们将深入探索OpenClaw技能系统的每一个细节。

一、技能系统架构：OpenClaw如何管理AI能力

1.1 什么是技能？

在OpenClaw中，技能（Skill）是一个包含 SKILL.md 文件的目录。这个文件有两个核心部分：

• YAML frontmatter：定义技能元数据（名称、描述、配置等）
• Markdown说明：告诉AI如何使用这个技能

一个最简单的技能可能只有几行代码：

---
name: hello_world
description: 一个简单的打招呼技能
---

当用户请求问候时，使用 `echo` 工具说"你好，来自自定义技能！"。

但技能的真正威力在于，它可以封装复杂的工具调用、API集成、甚至完整的业务流程。

1.2 技能加载的三层架构

OpenClaw从三个位置加载技能，形成了清晰的优先级层次：

技能加载优先级层次：

图：技能加载优先级三层架构 - 工作区技能（最高）→ 托管/本地技能（共享）→ 内置技能（最低）

具体解析：

工作区技能

(

<workspace>/skills

)

• 仅对当前智能体可见
• 优先级最高，适合项目特定的技能
• 示例：为某个GitHub仓库定制的代码审查技能

托管/本地技能

(

~/.openclaw/skills

)

• 对同一机器上的所有智能体可见
• 优先级中等，适合团队共享的技能
• 示例：公司内部的数据分析技能包

内置技能

• 随OpenClaw安装包一起发布
• 优先级最低，但提供开箱即用的基础能力
• 示例：浏览器、文件操作、Web搜索等核心技能

1.3 多智能体环境下的技能隔离

在多智能体设置中，每个智能体有自己的工作区。这意味着：

• 单智能体技能：位于 <workspace>/skills，仅供该智能体使用
• 共享技能：位于 ~/.openclaw/skills，对所有智能体可见
• 额外目录：通过配置添加的共享文件夹（最低优先级）

这种设计既保证了灵活性（每个项目可以有自己的技能），又保证了复用性（常用技能可以共享）。

1.4 插件与技能集成

插件可以通过在 openclaw.plugin.json 中列出 skills 目录来发布自己的技能。这种集成方式让插件开发者能够：

• 提供开箱即用的AI能力扩展
• 通过 metadata.openclaw.requires.config 进行门控
• 参与正常的技能优先级规则

例如，WhatsApp插件可能附带一个"消息模板"技能，Telegram插件可能附带一个"频道管理"技能。

二、技能配置：精细控制AI能力

2.1 配置文件结构

所有技能相关配置都位于 ~/.openclaw/openclaw.json 中的 skills 部分：

{
  skills: {
    // 内置技能白名单
    allowBundled: ["gemini", "peekaboo"],
    
    // 加载配置
    load: {
      extraDirs: ["~/Projects/agent-scripts/skills"],
      watch: true,
      watchDebounceMs: 250,
    },
    
    // 安装配置
    install: {
      preferBrew: true,
      nodeManager: "npm", // npm | pnpm | yarn | bun
    },
    
    // 单个技能配置
    entries: {
      "nano-banana-pro": {
        enabled: true,
        apiKey: "GEMINI_KEY_HERE",
        env: {
          GEMINI_API_KEY: "GEMINI_KEY_HERE",
        },
      },
      peekaboo: { enabled: true },
      sag: { enabled: false },
    },
  },
}

2.2 核心配置字段详解

`allowBundled`：内置技能白名单

• 作用：控制哪些内置技能可用
• 场景：安全敏感环境，需要严格控制AI能力
• 示例：allowBundled: ["gemini", "peekaboo"] 只启用这两个内置技能

`load.extraDirs`：额外技能目录

• 作用：添加自定义技能搜索路径
• 场景：跨项目共享技能库
• 示例：extraDirs: ["~/Projects/agent-scripts/skills"]

`load.watch`：文件监视

• 作用：实时监测技能文件变化
• 默认：true，修改技能后下一个智能体轮次自动生效
• 性能：通过 watchDebounceMs 控制防抖时间（默认250ms）

`install.preferBrew`：包管理器偏好

• 作用：优先使用Homebrew安装依赖
• 场景：macOS环境，提供更好的依赖管理

`install.nodeManager`：Node包管理器

• 选项：npm | pnpm | yarn | bun
• 注意：Gateway网关运行时应仍为Node，不推荐Bun用于WhatsApp/Telegram

`entries.<skillKey>`：单个技能配置

• enabled：启用/禁用特定技能
• env：为技能进程注入环境变量
• apiKey：便捷的API密钥配置字段

2.3 技能键名映射规则

技能配置键名默认映射到技能名称。但如果技能定义了 metadata.openclaw.skillKey，则使用该键名。例如：

---
name: nano-banana-pro
description: 通过Gemini 3 Pro Image生成或编辑图像
metadata: {"openclaw": {"skillKey": "gemini-image-pro"}}
---

配置时需要使用 skills.entries.gemini-image-pro 而不是 skills.entries["nano-banana-pro"]。

三、创建自定义技能：从零到生产

3.1 技能目录结构

一个完整的技能目录通常包含：

my-skill/
├── SKILL.md          # 核心技能定义
├── references/       # 参考文件
│   ├── api-reference.md
│   └── examples.md
├── scripts/          # 辅助脚本
│   ├── setup.sh
│   └── cleanup.sh
├── tools/            # 自定义工具
│   └── custom-tool.js
└── README.md         # 开发者文档

3.2 SKILL.md 编写规范

Frontmatter 要求

---
name: my-skill-name
description: 技能的功能描述
metadata: {"openclaw": {"requires": {"config": "apiKey"}}}
---

必填字段：

• name：技能名称（小写字母、数字、连字符）
• description：一句话描述技能功能

可选字段：

• homepage：技能网站URL（在macOS技能UI中显示）
• user-invocable：true|false（默认true），是否作为用户斜杠命令暴露
• disable-model-invocation：true|false（默认false），是否从模型提示词中排除
• command-dispatch：设置为tool时，斜杠命令绕过模型直接调度到工具
• command-tool：当command-dispatch: tool时要调用的工具名称
• command-arg-mode：参数传递模式（默认raw）

技能说明编写技巧

• 明确触发条件：清晰描述何时使用这个技能
• 提供工具使用示例：展示具体的工具调用方式
• 包含错误处理：指导AI如何处理常见错误
• 添加注意事项：安全提示、性能考虑等

3.3 实战：创建GitHub监控技能

让我们通过一个真实案例，了解如何创建生产级技能。

步骤1：创建目录结构

mkdir -p ~/.openclaw/workspace/skills/github-monitor
cd ~/.openclaw/workspace/skills/github-monitor

步骤2：编写SKILL.md

---
name: github-monitor
description: 监控GitHub仓库的活动，包括issue、PR、star变化等
metadata: {"openclaw": {"requires": {"config": "GITHUB_TOKEN"}}}
---

# GitHub监控技能

当用户需要监控GitHub仓库状态时，使用此技能获取实时信息。

## 可监控的项目
- Issue状态变化
- Pull Request审查进度
- Star数量趋势
- 最新提交
- 发布版本

## 可用工具

### 1. github-issues
获取指定仓库的issue列表。

**参数：**
- `repo`: 仓库名称（格式：owner/repo）
- `state`: issue状态（open, closed, all）
- `limit`: 返回数量限制

**示例：**
```bash
github-issues --repo openclaw/openclaw --state open --limit 10

2. github-prs

获取Pull Request列表。

参数：

• repo: 仓库名称
• state: PR状态（open, closed, merged）
• review: 审查状态（approved, changes_requested）

3. github-stars

获取仓库star历史数据。

配置要求

需要设置GITHUB_TOKEN环境变量：

export GITHUB_TOKEN=your_token_here

或者在OpenClaw配置中设置：

{
  skills: {
    entries: {
      "github-monitor": {
        env: {
          GITHUB_TOKEN: "your_token_here"
        }
      }
    }
  }
}

最佳实践

• 定期监控，建议每小时检查一次
• 关注高优先级issue（标签为bug、critical）
• 对新PR进行自动化初步审查
• 记录star增长趋势，识别热门功能


**步骤3：添加辅助脚本**
创建 `scripts/setup.sh` 进行环境检查：
```bash
#!/bin/bash
# 检查GitHub Token
if [ -z "$GITHUB_TOKEN" ]; then
  echo "错误: GITHUB_TOKEN未设置"
  echo "请设置环境变量或在OpenClaw配置中配置"
  exit 1
fi

# 检查gh CLI是否安装
if ! command -v gh &> /dev/null; then
  echo "警告: GitHub CLI未安装，部分功能可能受限"
fi

步骤4：配置技能
在 ~/.openclaw/openclaw.json 中添加：

{
  skills: {
    entries: {
      "github-monitor": {
        enabled: true,
        env: {
          GITHUB_TOKEN: "ghp_xxxxxxxxxxxxxxxxxxxx"
        }
      }
    }
  }
}

步骤5：测试技能

openclaw agent --message "监控openclaw/openclaw仓库的issue状态"

3.4 技能调试技巧

• 查看技能加载状态
```
openclaw skills list
```

• 验证技能配置

openclaw skills validate github-monitor

• 查看技能详情
```
openclaw skills show github-monitor
```
• 实时监控技能使用
```
openclaw skills watch github-monitor
```

四、安全与最佳实践

4.1 安全第一原则

将第三方技能视为不受信任代码

• 启用前仔细阅读技能代码
• 检查技能所需的权限
• 验证技能来源（ClawHub验证标记）

环境变量管理

• 使用 skills.entries.*.env 注入敏感信息
• 避免在技能说明中硬编码密钥
• 定期轮换API密钥

沙箱隔离

对于高风险技能，优先使用沙箱隔离运行：

{
  agents: {
    defaults: {
      sandbox: {
        enabled: true,
        docker: {
          image: "openclaw/sandbox:latest",
          env: {
            SAFE_MODE: "true"
          }
        }
      }
    }
  }
}

注意：沙箱不会继承宿主机环境变量，需要在沙箱配置中显式设置。

4.2 性能优化

技能加载优化

• 禁用不需要的技能：enabled: false
• 按需加载：通过配置控制技能可用性
• 缓存技能解析结果

工具调用优化

• 批量处理请求，减少API调用次数
• 设置合理的超时时间
• 实现请求重试机制

4.3 维护与更新

版本管理

---
name: my-skill
description: 我的技能
metadata: {"openclaw": {"version": "1.0.0", "compatibility": ">=2.0.0"}}
---

变更日志

在技能目录中添加 CHANGELOG.md，记录：

• 新功能添加
• Bug修复
• 破坏性变更
• 安全更新

向后兼容

• 新增参数时提供默认值
• 废弃功能时给出迁移指南
• 保持API稳定性

五、ClawHub：技能生态系统

5.1 ClawHub简介

ClawHub是OpenClaw的公共技能注册表（https://clawhub.com），提供：

• 技能发现与搜索
• 一键安装与更新
• 版本管理
• 社区评价与反馈

5.2 使用ClawHub

搜索技能

clawhub search "github"

安装技能

# 安装到当前工作区
clawhub install github-monitor

# 安装特定版本
clawhub install github-monitor@1.2.0

# 全局安装
clawhub install --global github-monitor

更新技能

# 更新所有技能
clawhub update --all

# 更新特定技能
clawhub update github-monitor

同步技能库

# 扫描并发布更新
clawhub sync --all

5.3 发布技能到ClawHub

准备技能包

• 确保技能符合AgentSkills规范
• 添加完整的文档
• 包含测试用例
• 设置正确的许可证

发布流程

# 登录ClawHub
clawhub login

# 验证技能
clawhub validate my-skill

# 发布技能
clawhub publish my-skill

# 管理版本
clawhub version my-skill@1.1.0

5.4 技能质量评估

ClawHub提供技能质量指标：

• 星标评级：社区评价
• 下载量：受欢迎程度
• 更新频率：维护活跃度
• 兼容性标记：OpenClaw版本支持
• 安全扫描：自动安全检查

六、实战：企业级技能体系建设

6.1 技能分类策略

在企业环境中，建议将技能分为四类：

1. 基础技能（所有员工可用）

• 文档处理
• 日程管理
• 内部通讯
• 信息查询

2. 部门技能（按部门划分）

• 研发部：代码审查、CI/CD监控、Bug跟踪
• 市场部：社交媒体分析、竞品监控、内容生成
• 销售部：客户管理、销售数据分析、合同生成

3. 项目技能（项目特定）

• 项目文档管理
• 进度跟踪
• 风险预警
• 团队协作

4. 个人技能（个性化）

• 个人工作流优化
• 学习助手
• 健康提醒

6.2 技能治理框架

技能审批流程

• 提交申请：开发者提交技能包
• 安全审查：检查代码安全性、权限需求
• 功能测试：验证技能功能完整性
• 性能评估：测试技能性能影响
• 批准发布：添加到企业技能库

技能生命周期管理

• 开发阶段：内部测试环境
• 预发布阶段：小范围试点
• 生产阶段：全公司可用
• 维护阶段：定期更新与安全补丁
• 退役阶段：逐步下线，提供迁移支持

6.3 监控与告警

技能使用监控

{
  monitoring: {
    skills: {
      enabled: true,
      metrics: ["invocation_count", "success_rate", "avg_duration"],
      alerts: {
        high_failure_rate: {
          threshold: 0.1,  // 10%失败率
          channels: ["slack", "email"]
        },
        slow_performance: {
          threshold: 5000, // 5秒
          channels: ["slack"]
        }
      }
    }
  }
}

安全审计日志

{
  security: {
    audit: {
      skills: {
        enabled: true,
        events: ["install", "uninstall", "invocation", "config_change"],
        retention_days: 90
      }
    }
  }
}

6.4 培训与推广

技能文档体系

• 用户指南：面向最终用户，如何使用技能
• 开发者指南：面向开发者，如何扩展技能
• 管理员指南：面向管理员，如何部署和管理技能

培训计划

• 新技能发布培训：每次发布重要技能时进行
• 月度技能分享会：分享技能使用技巧
• 季度技能大赛：鼓励创新技能开发

七、故障排查与优化

7.1 常见问题及解决方案

问题1：技能未加载

症状：技能列表中没有看到新添加的技能

排查步骤：

• 检查技能目录位置是否正确
• 验证SKILL.md文件格式
• 查看OpenClaw日志：openclaw logs --filter skills
• 检查配置文件：openclaw config get skills

解决方案：

# 重新加载技能
openclaw skills reload

# 验证技能文件
openclaw skills validate <skill-name>

# 查看详细错误
openclaw doctor --check skills

问题2：技能工具调用失败

症状：技能被调用但工具执行出错

排查步骤：

• 检查工具依赖是否安装
• 验证环境变量配置
• 检查网络连接和API密钥
• 查看工具执行日志

解决方案：

# 测试工具可用性
openclaw tools test <tool-name>

# 查看环境变量
openclaw env list

# 手动执行工具命令
<tool-command> --help

问题3：技能性能低下

症状：技能响应缓慢，影响整体性能

排查步骤：

• 分析技能执行时间线
• 检查网络请求延迟
• 评估资源使用情况
• 识别性能瓶颈

解决方案：

{
  skills: {
    entries: {
      "slow-skill": {
        enabled: true,
        timeout: 10000,  // 10秒超时
        retry: {
          maxAttempts: 2,
          delay: 1000
        }
      }
    }
  }
}

7.2 性能优化技巧

1. 懒加载技能

仅在实际需要时加载技能，减少启动时间：

{
  skills: {
    load: {
      lazy: true,
      preload: ["core-skill1", "core-skill2"]
    }
  }
}

2. 技能缓存

缓存技能解析结果和工具输出：

{
  skills: {
    cache: {
      enabled: true,
      ttl: 300000,  // 5分钟
      maxSize: 100
    }
  }
}

3. 并发控制

限制同时执行的技能数量：

{
  skills: {
    concurrency: {
      max: 5,
      queueSize: 10
    }
  }
}

7.3 诊断工具

技能健康检查

# 全面检查技能系统
openclaw doctor --check skills

# 检查单个技能
openclaw skills health github-monitor

# 性能分析
openclaw skills profile github-monitor --duration 60

监控仪表板

# 启动技能监控
openclaw skills monitor

# 查看实时指标
openclaw metrics skills

八、未来展望

8.1 技能系统演进方向

智能化技能发现

• 上下文感知推荐：根据用户当前任务推荐相关技能
• 技能组合建议：自动推荐可以协同工作的技能组合
• 个性化技能排序：基于用户历史使用习惯优化技能展示

增强型技能开发

• 可视化技能编辑器：拖拽式技能创建界面
• AI辅助技能生成：自然语言描述自动生成技能代码
• 自动化测试框架：技能功能与性能的自动化测试

企业级功能增强

• 技能市场：企业内部技能交易平台
• 技能版权管理：技能知识产权保护机制
• 合规性检查：自动检查技能是否符合企业政策

8.2 生态系统建设

开发者社区

• 技能开发大赛：定期举办，鼓励创新
• 技能认证计划：官方技能质量认证
• 开发者支持计划：为技能开发者提供技术支持和资源

企业合作

• 行业解决方案包：针对特定行业的技能集合
• ISV合作伙伴计划：独立软件供应商的技能集成
• 教育培训合作：技能开发培训课程

8.3 技术架构演进

分布式技能执行

• 边缘计算支持：技能在边缘设备上执行
• 技能负载均衡：自动分配技能执行资源
• 容错与恢复：技能执行失败时的自动恢复机制

安全性增强

• 技能沙箱2.0：更严格的隔离和安全控制
• 零信任技能执行：每次执行都进行安全验证
• 区块链技能验证：确保技能来源和完整性

结语

OpenClaw的技能系统不仅仅是一个功能扩展机制，它代表了一种新的AI应用开发范式。通过将复杂能力封装为可组合、可共享的技能，我们正在构建一个集体智能网络。

每个技能都是这个网络中的一个节点，每个开发者都是这个网络的贡献者。当这些节点相互连接、相互增强时，整个系统的能力将呈指数级增长。

前言：为什么你需要技能系统？

一、技能系统架构：OpenClaw如何管理AI能力

1.1 什么是技能？

1.2 技能加载的三层架构

1.3 多智能体环境下的技能隔离

1.4 插件与技能集成

二、技能配置：精细控制AI能力

2.1 配置文件结构

2.2 核心配置字段详解

allowBundled：内置技能白名单

load.extraDirs：额外技能目录

load.watch：文件监视

install.preferBrew：包管理器偏好

install.nodeManager：Node包管理器

entries.<skillKey>：单个技能配置

2.3 技能键名映射规则

三、创建自定义技能：从零到生产

3.1 技能目录结构

3.2 SKILL.md 编写规范

Frontmatter 要求

技能说明编写技巧

3.3 实战：创建GitHub监控技能

2. github-prs

3. github-stars

配置要求

最佳实践

3.4 技能调试技巧

四、安全与最佳实践

4.1 安全第一原则

将第三方技能视为不受信任代码

环境变量管理

沙箱隔离

4.2 性能优化

技能加载优化

工具调用优化

4.3 维护与更新

版本管理

变更日志

向后兼容

五、ClawHub：技能生态系统

5.1 ClawHub简介

5.2 使用ClawHub

搜索技能

安装技能

更新技能

同步技能库

5.3 发布技能到ClawHub

准备技能包

发布流程

5.4 技能质量评估

六、实战：企业级技能体系建设

6.1 技能分类策略

1. 基础技能（所有员工可用）

2. 部门技能（按部门划分）

3. 项目技能（项目特定）

4. 个人技能（个性化）

6.2 技能治理框架

技能审批流程

技能生命周期管理

6.3 监控与告警

技能使用监控

安全审计日志

6.4 培训与推广

技能文档体系

培训计划

七、故障排查与优化

7.1 常见问题及解决方案

问题1：技能未加载

问题2：技能工具调用失败

问题3：技能性能低下

7.2 性能优化技巧

1. 懒加载技能

2. 技能缓存

3. 并发控制

7.3 诊断工具

技能健康检查

监控仪表板

八、未来展望

8.1 技能系统演进方向

智能化技能发现

`allowBundled`：内置技能白名单

`load.extraDirs`：额外技能目录

`load.watch`：文件监视

`install.preferBrew`：包管理器偏好

`install.nodeManager`：Node包管理器

`entries.<skillKey>`：单个技能配置