08-skills-extension.md

第8章 Skills扩展

💡 本章目标：学会使用ClawHub技能市场，掌握必装Skills推荐，学习自定义Skills开发和管理技巧。

🔧 本章内容

• 8.1 ClawHub技能市场
• 8.2 必装Skills推荐
• 8.3 自定义Skills开发
• 8.4 Skills管理技巧

---

8.1 ClawHub技能市场

8.1.1 什么是ClawHub

定义： ClawHub是OpenClaw的官方技能市场（https://clawhub.com），类似于App Store，提供各种扩展功能。

核心价值：

• 🎯 扩展能力：让OpenClaw能做更多事情
• 🚀 快速部署：一键安装，即刻使用
• 🌍 社区驱动：开发者共享优质Skills
• 🔄 持续更新：Skills不断优化升级
• 📦 统一管理：安装、更新、备份一站式

与其他AI的区别：

特性	OpenClaw + Skills	ChatGPT Plugins	Claude
本地执行	✅	❌	❌
系统操作	✅	❌	❌
自定义开发	✅	❌	❌
社区生态	✅	✅	❌
免费使用	✅	部分付费	❌

8.1.2 Skills加载机制

Skills加载位置：

OpenClaw从三个位置加载Skills，优先级从高到低：

1. 工作区Skills：<workspace>/skills（最高优先级）
   - 单智能体专用
   - 项目特定的Skills
   
2. 托管/本地Skills：~/.openclaw/skills
   - 所有智能体共享
   - 用户自定义Skills
   
3. 内置Skills：随安装包发布（最低优先级）
   - OpenClaw官方Skills
   - 基础功能Skills

优先级规则：

如果同名Skills存在于多个位置：
工作区Skills > 托管/本地Skills > 内置Skills

示例：
- 内置Skills：file-search v1.0
- 本地Skills：file-search v1.2（自定义版本）
- 工作区Skills：file-search v2.0（项目专用）

最终加载：工作区的 v2.0 版本

额外Skills目录：

可以通过配置添加额外的Skills文件夹：

{
  "skills": {
    "load": {
      "extraDirs": [
        "/path/to/shared-skills",
        "/path/to/team-skills"
      ]
    }
  }
}

8.1.3 ClawHub使用指南

访问方式：

# 方式1：网页访问（推荐）
https://clawhub.com

# 方式2：命令行工具
clawhub --help

# 方式3：OpenClaw内访问
你：打开ClawHub

常用命令：

# 搜索Skills
clawhub search <关键词>

# 查看Skills详情
clawhub info <skill-slug>

# 安装Skills到工作区
clawhub install <skill-slug>

# 安装到指定目录
clawhub install <skill-slug> --dir /path/to/skills

# 更新单个Skills
clawhub update <skill-slug>

# 更新所有Skills
clawhub update --all

# 同步（扫描+发布更新）
clawhub sync --all

# 列出已安装的Skills
clawhub list

# 卸载Skills
clawhub uninstall <skill-slug>

安装位置说明：

# 默认安装到当前工作目录
clawhub install nano-banana-pro
# 安装到：./skills/nano-banana-pro/

# 如果不在工作目录，回退到配置的工作区
# 安装到：<workspace>/skills/nano-banana-pro/

ClawHub界面布局：

8.1.3 技能分类和搜索

主要分类：

1. 文件管理类

• 文件搜索
• 文件整理
• 批量处理
• 格式转换

2. 知识管理类

• 网页剪藏
• 笔记同步
• 文献管理
• 知识图谱

3. 日程管理类

• 日历同步
• 提醒设置
• 任务管理
• 时间追踪

4. 自动化类

• 定时任务
• 网站监控
• 数据采集
• 流程自动化

5. 工具类

• 截图工具
• 翻译助手
• 计算器
• 单位转换

6. 娱乐休闲类

• 音乐播放
• 天气查询
• 新闻阅读
• 游戏娱乐

搜索技巧：

# 按名称搜索
搜索：file-search

# 按功能搜索
搜索：文件搜索

# 按标签搜索
搜索：#文件管理 #效率工具

# 按作者搜索
搜索：@作者名

# 组合搜索
搜索：文件 #管理 @官方

8.1.4 技能评价体系

评价维度：

维度	说明	权重
⭐ 评分	用户评分（1-5星）	30%
📥 下载量	安装次数	20%
🔄 更新频率	维护活跃度	20%
📝 文档质量	说明完善度	15%
🐛 Bug数量	稳定性	15%

评分标准：

⭐⭐⭐⭐⭐ (5.0) - 完美
- 功能完善
- 文档详细
- 无明显Bug
- 持续更新

⭐⭐⭐⭐ (4.0-4.9) - 优秀
- 功能完整
- 文档清晰
- 偶尔小Bug
- 定期更新

⭐⭐⭐ (3.0-3.9) - 良好
- 基本功能可用
- 文档一般
- 有些Bug
- 更新较慢

⭐⭐ (2.0-2.9) - 一般
- 功能不完整
- 文档缺失
- Bug较多
- 很少更新

⭐ (1.0-1.9) - 较差
- 功能有问题
- 无文档
- Bug很多
- 不再维护

如何选择Skills：

✅ 推荐安装：
- 评分 ≥ 4.0
- 下载量 > 1000
- 最近3个月有更新
- 文档完善

⚠️ 谨慎安装：
- 评分 3.0-3.9
- 下载量 < 1000
- 更新不频繁
- 文档不全

❌ 不推荐：
- 评分 < 3.0
- 长期不更新
- 无文档
- Bug多

8.1.5 Skills安装和管理

安装方式：

方式1：通过ClawHub安装

1. 打开ClawHub
2. 搜索Skills
3. 点击"安装"按钮
4. 等待安装完成

方式2：通过命令行安装

# 安装单个Skill
openclaw skill install file-search

# 安装多个Skills
openclaw skill install file-search note-sync calendar-sync

# 从URL安装
openclaw skill install https://github.com/user/skill-name

方式3：通过OpenClaw对话安装

你：帮我安装file-search这个Skill

OpenClaw：好的，我来帮你安装！

正在安装 file-search...
- 下载中... ✅
- 解压中... ✅
- 配置中... ✅
- 测试中... ✅

安装成功！✅

Skill信息：
- 名称：File Search
- 版本：v1.2.0
- 作者：OpenClaw官方
- 功能：智能文件搜索

现在你可以使用文件搜索功能了！

查看已安装Skills：

# 列出所有已安装的Skills
openclaw skill list

# 输出示例：
已安装Skills（12个）：

文件管理类（3个）：
✅ file-search v1.2.0
✅ file-organizer v2.0.1
✅ batch-processor v1.5.0

知识管理类（4个）：
✅ web-clipper v1.8.0
✅ note-sync v2.1.0
✅ github-manager v1.3.0
✅ paper-reader v1.0.5

日程管理类（2个）：
✅ calendar-sync v3.0.0
✅ reminder v1.4.0

工具类（3个）：
✅ screenshot v2.2.0
✅ translator v1.6.0
✅ calculator v1.1.0

更新Skills：

# 检查更新
openclaw skill update --check

# 更新所有Skills
openclaw skill update --all

# 更新指定Skill
openclaw skill update file-search

# 输出示例：
检查更新中...

发现3个可更新的Skills：
1. file-search: v1.2.0 → v1.3.0
2. note-sync: v2.1.0 → v2.2.0
3. calendar-sync: v3.0.0 → v3.1.0

是否更新？[Y/n]

卸载Skills：

# 卸载单个Skill
openclaw skill uninstall file-search

# 卸载多个Skills
openclaw skill uninstall file-search note-sync

# 输出示例：
正在卸载 file-search...
- 停止服务... ✅
- 清理配置... ✅
- 删除文件... ✅

卸载成功！✅

---

8.2 必装Skills推荐

8.2.1 文件管理类Skills

1. file-search（智能文件搜索）

⭐ 评分：5.0/5.0
📥 下载量：50,000+
👤 作者：OpenClaw官方

功能：
- 基于内容的智能搜索
- 支持多种文件格式
- 快速索引和检索
- 模糊匹配

使用示例：
你：搜索包含"发票"的PDF文件

OpenClaw：找到3个匹配文件：
1. 2026年1月发票.pdf
2. 跑步机购买发票.pdf
3. 办公用品发票.pdf

2. file-organizer（文件自动整理）

⭐ 评分：4.8/5.0
📥 下载量：35,000+
👤 作者：OpenClaw官方

功能：
- 智能分类文件
- 批量重命名
- 重复文件检测
- 自动归档

使用示例：
你：整理下载文件夹

OpenClaw：正在整理...
- 图片 → Pictures/Downloads/
- 文档 → Documents/Downloads/
- 视频 → Videos/Downloads/
- 其他 → Others/Downloads/

整理完成！共处理156个文件 ✅

3. batch-processor（批量文件处理）

⭐ 评分：4.7/5.0
📥 下载量：28,000+
👤 作者：社区开发者

功能：
- 批量格式转换
- 批量压缩
- 批量提取信息
- 批量重命名

使用示例：
你：把这个文件夹里的所有PNG转成JPG

OpenClaw：正在转换...
- image1.png → image1.jpg ✅
- image2.png → image2.jpg ✅
- image3.png → image3.jpg ✅
...
共转换25个文件 ✅

8.2.2 知识管理类Skills

4. web-clipper（网页剪藏）

⭐ 评分：4.9/5.0
📥 下载量：45,000+
👤 作者：OpenClaw官方

功能：
- 网页内容抓取
- 智能摘要生成
- 多平台保存（备忘录/Notion/Obsidian）
- 标签管理

使用示例：
你：保存这篇文章到备忘录
https://example.com/article

OpenClaw：已保存！
标题：AI技术发展趋势
摘要：[自动生成的摘要]
标签：#AI #技术 #趋势
位置：备忘录 > AI学习 ✅

5. note-sync（笔记同步）

⭐ 评分：4.8/5.0
📥 下载量：32,000+
👤 作者：OpenClaw官方

功能：
- 多平台笔记同步
- 实时备份
- 版本控制
- 冲突解决

支持平台：
- Mac备忘录
- Notion
- Obsidian
- Evernote

6. github-manager（GitHub项目管理）

⭐ 评分：4.6/5.0
📥 下载量：25,000+
👤 作者：社区开发者

功能：
- 项目信息分析
- README总结
- 代码结构理解
- Star/Fork追踪

使用示例：
你：分析这个GitHub项目
https://github.com/user/project

OpenClaw：分析完成！
项目：Awesome Project
Stars：15.3k
语言：TypeScript
核心功能：[详细分析]
推荐指数：⭐⭐⭐⭐⭐

8.2.3 日程管理类Skills

7. calendar-sync（日历同步）

⭐ 评分：5.0/5.0
📥 下载量：60,000+
👤 作者：OpenClaw官方

功能：
- Mac日历集成
- 自动创建事件
- 智能提醒
- 跨设备同步

使用示例：
你：明天下午3点，会议室A开会

OpenClaw：已创建日历事件！
标题：会议
时间：2026-02-12 15:00-16:00
地点：会议室A
提醒：提前15分钟 ✅

8. reminder（智能提醒）

⭐ 评分：4.7/5.0
📥 下载量：38,000+
👤 作者：OpenClaw官方

功能：
- 多级提醒设置
- 智能提醒策略
- 位置提醒
- 重复提醒

使用示例：
你：每天早上8点提醒我喝水

OpenClaw：已设置提醒！
内容：该喝水了💧
时间：每天 08:00
方式：飞书消息 ✅

8.2.4 自动化类Skills

9. scheduler（任务调度）

⭐ 评分：4.9/5.0
📥 下载量：42,000+
👤 作者：OpenClaw官方

功能：
- 定时任务设置
- Cron表达式支持
- 任务依赖管理
- 错误重试

使用示例：
你：每天早上8点推送AI日报

OpenClaw：已设置定时任务！
任务：AI日报推送
时间：每天 08:00
Cron：0 8 * * *
状态：已启用 ✅

10. monitor（网站监控）

⭐ 评分：4.6/5.0
📥 下载量：28,000+
👤 作者：社区开发者

功能：
- 网站变化检测
- 价格监控
- 内容更新提醒
- RSS订阅

使用示例：
你：监控这个博客的更新
https://example-blog.com

OpenClaw：已设置监控！
网站：Example Blog
频率：每天2次
通知：飞书消息 ✅

8.2.5 工具类Skills

11. screenshot（截图工具）

⭐ 评分：4.8/5.0
📥 下载量：35,000+
👤 作者：OpenClaw官方

功能：
- 全屏截图
- 窗口截图
- 区域截图
- OCR识别

使用示例：
你：截图当前屏幕

OpenClaw：已截图！
[发送截图]
是否需要OCR识别文字？

12. translator（翻译助手）

⭐ 评分：4.7/5.0
📥 下载量：30,000+
👤 作者：社区开发者

功能：
- 多语言翻译
- 实时翻译
- 文档翻译
- 术语库管理

使用示例：
你：把这段话翻译成英文
"人工智能正在改变世界"

OpenClaw：翻译结果：
"Artificial Intelligence is changing the world"

8.2.6 Skills推荐总结

必装Top 10：

排名	Skill	分类	评分	推荐理由
1	calendar-sync	日程管理	5.0	日历集成必备
2	file-search	文件管理	5.0	文件搜索神器
3	web-clipper	知识管理	4.9	知识收集利器
4	scheduler	自动化	4.9	定时任务必备
5	note-sync	知识管理	4.8	笔记同步工具
6	file-organizer	文件管理	4.8	文件整理助手
7	screenshot	工具	4.8	截图OCR工具
8	reminder	日程管理	4.7	智能提醒系统
9	batch-processor	文件管理	4.7	批量处理工具
10	translator	工具	4.7	翻译助手

安装建议：

# 基础套装（必装）
openclaw skill install calendar-sync file-search web-clipper

# 进阶套装（推荐）
openclaw skill install scheduler note-sync file-organizer

# 完整套装（全能）
openclaw skill install calendar-sync file-search web-clipper \
  scheduler note-sync file-organizer screenshot reminder \
  batch-processor translator

---

8.3 自定义Skills开发

8.3.1 Skills开发基础

为什么要开发Skills：

1. 满足个性化需求

   • 官方Skills无法满足
   • 特定业务场景
   • 企业内部工具

2. 学习和成长

   • 深入理解OpenClaw
   • 提升编程能力
   • 贡献开源社区

3. 商业价值

   • 开发付费Skills
   • 提供定制服务
   • 建立个人品牌

开发前准备：

# 1. 安装开发工具
npm install -g openclaw-cli

# 2. 创建开发环境
openclaw dev init

# 3. 学习文档
openclaw docs

# 4. 查看示例
openclaw examples

8.3.2 Skills文件格式（AgentSkills兼容）

基本格式：

OpenClaw使用兼容AgentSkills的Skills文件夹。每个Skills是一个包含SKILL.md的目录。

最小示例：

---
name: nano-banana-pro
description: Generate or edit images via Gemini 3 Pro Image
---

# Nano Banana Pro

这个Skills可以生成和编辑图片。

## 使用方法

发送：画一只可爱的猫

完整示例：

---
name: gemini
description: Use Gemini CLI for coding assistance and Google search lookups.
homepage: https://github.com/example/gemini-skill
user-invocable: true
disable-model-invocation: false
metadata: {
  "openclaw": {
    "emoji": "♊️",
    "requires": {
      "bins": ["gemini"],
      "env": ["GEMINI_API_KEY"]
    },
    "primaryEnv": "GEMINI_API_KEY",
    "install": [
      {
        "id": "brew",
        "kind": "brew",
        "formula": "gemini-cli",
        "bins": ["gemini"],
        "label": "Install Gemini CLI (brew)"
      }
    ]
  }
}
---

# Gemini Skills

使用Gemini CLI进行编程辅助和Google搜索。

## 功能

- 代码生成
- 问题解答
- 网络搜索

## 使用方法

发送：用Gemini搜索最新的AI新闻

Frontmatter字段说明：

字段	必填	说明
name	✅	Skills名称（唯一标识）
description	✅	Skills描述
homepage	❌	项目主页URL
user-invocable	❌	是否作为斜杠命令暴露（默认true）
disable-model-invocation	❌	是否从模型提示词中排除（默认false）
command-dispatch	❌	命令调度模式（tool=直接调度到工具）
command-tool	❌	要调用的工具名称
command-arg-mode	❌	参数模式（raw=原始字符串）
metadata	❌	元数据（单行JSON对象）

注意事项：

⚠️ 重要：
1. 内嵌智能体的解析器仅支持单行frontmatter键
2. metadata必须是单行JSON对象
3. 在说明中使用{baseDir}引用Skills文件夹路径

8.3.3 Skills门控（加载时过滤）

什么是门控：

门控是指在加载时根据条件过滤Skills，只加载满足条件的Skills。

门控配置：

通过metadata.openclaw配置门控条件：

---
name: nano-banana-pro
description: Generate or edit images
metadata: {
  "openclaw": {
    "requires": {
      "bins": ["uv"],
      "env": ["GEMINI_API_KEY"],
      "config": ["browser.enabled"]
    },
    "primaryEnv": "GEMINI_API_KEY",
    "os": ["darwin", "linux"]
  }
}
---

门控字段说明：

字段	说明	示例
always	始终包含（跳过其他门控）	"always": true
os	限制操作系统	"os": ["darwin", "linux"]
requires.bins	必需的二进制文件（全部）	"bins": ["uv", "python"]
requires.anyBins	必需的二进制文件（任一）	"anyBins": ["npm", "yarn"]
requires.env	必需的环境变量	"env": ["API_KEY"]
requires.config	必需的配置项	"config": ["browser.enabled"]
primaryEnv	主要环境变量名	"primaryEnv": "GEMINI_API_KEY"

门控示例：

# 示例1：仅macOS可用
metadata: {
  "openclaw": {
    "os": ["darwin"]
  }
}

# 示例2：需要特定工具
metadata: {
  "openclaw": {
    "requires": {
      "bins": ["ffmpeg", "imagemagick"]
    }
  }
}

# 示例3：需要API密钥
metadata: {
  "openclaw": {
    "requires": {
      "env": ["OPENAI_API_KEY"]
    },
    "primaryEnv": "OPENAI_API_KEY"
  }
}

# 示例4：需要配置启用
metadata: {
  "openclaw": {
    "requires": {
      "config": ["features.experimental"]
    }
  }
}

8.3.4 Skills安装器配置

什么是安装器：

安装器定义了如何安装Skills所需的依赖（二进制文件、包等）。

支持的安装器类型：

1. Homebrew（macOS/Linux）
2. Node包管理器（npm/pnpm/yarn/bun）
3. Go
4. UV（Python）
5. Download（直接下载）

安装器示例：

---
name: gemini
metadata: {
  "openclaw": {
    "install": [
      {
        "id": "brew",
        "kind": "brew",
        "formula": "gemini-cli",
        "bins": ["gemini"],
        "label": "Install Gemini CLI (brew)",
        "os": ["darwin", "linux"]
      },
      {
        "id": "npm",
        "kind": "node",
        "package": "gemini-cli",
        "bins": ["gemini"],
        "label": "Install Gemini CLI (npm)",
        "global": true
      }
    ]
  }
}
---

安装器字段说明：

字段	说明
id	安装器唯一标识
kind	安装器类型（brew/node/go/uv/download）
formula	Homebrew formula名称
package	npm包名称
bins	安装后的二进制文件列表
label	显示给用户的标签
os	支持的操作系统
global	是否全局安装（Node）

Download安装器：

metadata: {
  "openclaw": {
    "install": [
      {
        "id": "download-mac",
        "kind": "download",
        "url": "https://example.com/tool-mac.tar.gz",
        "archive": "tar.gz",
        "extract": true,
        "stripComponents": 1,
        "targetDir": "~/.openclaw/tools/my-tool",
        "bins": ["my-tool"],
        "label": "Download for macOS",
        "os": ["darwin"]
      }
    ]
  }
}

安装器选择逻辑：

1. 如果列出多个安装器，Gateway会选择首选选项：
   - 优先选择brew（如果可用）
   - 其次选择node
   - 最后选择其他

2. 如果所有安装器都是download类型：
   - OpenClaw会列出每个条目
   - 让用户选择适合的构件

3. Node安装遵循配置：
   - skills.install.nodeManager（默认npm）
   - 选项：npm/pnpm/yarn/bun

8.3.5 项目结构

标准Skills目录结构：

my-skill/
├── SKILL.md              # Skills定义（必需）
├── README.md             # 说明文档
├── tools/                # 工具脚本
│   ├── setup.sh         # 安装脚本
│   └── cleanup.sh       # 清理脚本
├── examples/             # 示例
│   └── example.md
└── assets/               # 资源文件
    └── icon.png

SKILL.md引用文件：

在SKILL.md中可以使用{baseDir}引用Skills文件夹路径：

---
name: my-skill
description: My custom skill
---

# My Skill

## 安装

运行安装脚本：
```bash
bash {baseDir}/tools/setup.sh

示例

查看示例：{baseDir}/examples/example.md

由于内容较长，让我先提交当前进度，然后继续完成剩余章节。

<function_calls>
<invoke name="executeBash">
<parameter name="command">git add .


**实战案例1：开发一个简单的Skills**

```typescript
// src/index.ts
import { Skill, SkillConfig } from '@openclaw/sdk';

export default class HelloSkill extends Skill {
  config: SkillConfig = {
    name: 'hello-skill',
    version: '1.0.0',
    description: '一个简单的问候Skills',
    author: '你的名字',
    keywords: ['问候', '示例'],
    permissions: []
  };

  async onMessage(message: string) {
    // 检测是否包含"你好"
    if (message.includes('你好')) {
      return '你好！我是Hello Skill，很高兴认识你！😊';
    }
    
    // 检测是否包含"再见"
    if (message.includes('再见')) {
      return '再见！期待下次见面！👋';
    }
    
    return null; // 不处理其他消息
  }
}

测试Skills：

# 启动开发服务器
npm run dev

# 在OpenClaw中测试
你：你好

OpenClaw：你好！我是Hello Skill，很高兴认识你！😊

实战案例2：封装第三方API

// src/index.ts
import { Skill, SkillConfig } from '@openclaw/sdk';
import axios from 'axios';

export default class WeatherSkill extends Skill {
  config: SkillConfig = {
    name: 'weather-skill',
    version: '1.0.0',
    description: '天气查询Skills',
    author: '你的名字',
    keywords: ['天气', 'API'],
    permissions: ['network']
  };

  private apiKey = 'your-api-key';
  private apiUrl = 'https://api.weather.com';

  async onMessage(message: string) {
    // 检测是否是天气查询
    const match = message.match(/(.+)的天气/);
    if (!match) return null;

    const city = match[1];
    
    try {
      // 调用天气API
      const response = await axios.get(`${this.apiUrl}/weather`, {
        params: {
          city: city,
          key: this.apiKey
        }
      });

      const weather = response.data;
      
      return `${city}的天气：
🌡️ 温度：${weather.temp}°C
☁️ 天气：${weather.condition}
💨 风力：${weather.wind}
💧 湿度：${weather.humidity}%`;
      
    } catch (error) {
      return `抱歉，查询${city}的天气失败了。`;
    }
  }
}

实战案例3：复杂Skills开发

// src/index.ts
import { Skill, SkillConfig } from '@openclaw/sdk';
import { FileManager } from './utils/file';
import { NotionAPI } from './utils/notion';

export default class NoteSkill extends Skill {
  config: SkillConfig = {
    name: 'note-skill',
    version: '1.0.0',
    description: '笔记管理Skills',
    author: '你的名字',
    keywords: ['笔记', 'Notion'],
    permissions: ['file:read', 'file:write', 'network']
  };

  private fileManager: FileManager;
  private notionAPI: NotionAPI;

  async onInit() {
    // 初始化文件管理器
    this.fileManager = new FileManager();
    
    // 初始化Notion API
    this.notionAPI = new NotionAPI({
      token: process.env.NOTION_TOKEN
    });
  }

  async onMessage(message: string) {
    // 保存笔记
    if (message.startsWith('保存笔记：')) {
      const content = message.replace('保存笔记：', '');
      return await this.saveNote(content);
    }

    // 搜索笔记
    if (message.startsWith('搜索笔记：')) {
      const keyword = message.replace('搜索笔记：', '');
      return await this.searchNote(keyword);
    }

    // 同步到Notion
    if (message === '同步到Notion') {
      return await this.syncToNotion();
    }

    return null;
  }

  private async saveNote(content: string) {
    try {
      // 保存到本地
      await this.fileManager.save('notes.md', content);
      return '笔记已保存到本地 ✅';
    } catch (error) {
      return '保存失败 ❌';
    }
  }

  private async searchNote(keyword: string) {
    try {
      // 搜索本地笔记
      const results = await this.fileManager.search(keyword);
      return `找到${results.length}条笔记：\n${results.join('\n')}`;
    } catch (error) {
      return '搜索失败 ❌';
    }
  }

  private async syncToNotion() {
    try {
      // 读取本地笔记
      const notes = await this.fileManager.readAll();
      
      // 同步到Notion
      for (const note of notes) {
        await this.notionAPI.createPage({
          title: note.title,
          content: note.content
        });
      }
      
      return `已同步${notes.length}条笔记到Notion ✅`;
    } catch (error) {
      return '同步失败 ❌';
    }
  }
}

8.3.4 调试和测试技巧

调试方法：

1. 使用console.log

async onMessage(message: string) {
  console.log('收到消息：', message);
  
  // 你的逻辑
  const result = await this.process(message);
  console.log('处理结果：', result);
  
  return result;
}

2. 使用调试器

# 启动调试模式
npm run dev:debug

# 在VSCode中设置断点
# 按F5开始调试

3. 单元测试

// tests/index.test.ts
import { describe, it, expect } from 'vitest';
import HelloSkill from '../src/index';

describe('HelloSkill', () => {
  it('should respond to hello', async () => {
    const skill = new HelloSkill();
    const response = await skill.onMessage('你好');
    expect(response).toContain('你好');
  });

  it('should respond to goodbye', async () => {
    const skill = new HelloSkill();
    const response = await skill.onMessage('再见');
    expect(response).toContain('再见');
  });
});

运行测试：

# 运行所有测试
npm test

# 运行单个测试
npm test -- index.test.ts

# 查看测试覆盖率
npm run test:coverage

8.3.5 发布到ClawHub

发布前检查：

# 1. 运行测试
npm test

# 2. 检查代码规范
npm run lint

# 3. 构建生产版本
npm run build

# 4. 检查包大小
npm run size

发布步骤：

# 1. 登录ClawHub
openclaw login

# 2. 发布Skills
openclaw skill publish

# 输出示例：
正在发布 hello-skill...
- 检查配置... ✅
- 运行测试... ✅
- 构建代码... ✅
- 上传文件... ✅
- 生成文档... ✅

发布成功！✅

Skill信息：
- 名称：hello-skill
- 版本：v1.0.0
- 链接：https://clawhub.com/skills/hello-skill

现在其他用户可以安装你的Skill了！

发布后维护：

# 更新Skills
openclaw skill update

# 查看下载统计
openclaw skill stats

# 查看用户反馈
openclaw skill feedback

---

8.4 Skills管理技巧

8.4.1 配置覆盖（~/.openclaw/openclaw.json）

配置Skills：

内置/托管Skills可以通过配置文件进行切换和配置：

{
  "skills": {
    "entries": {
      "nano-banana-pro": {
        "enabled": true,
        "apiKey": "GEMINI_KEY_HERE",
        "env": {
          "GEMINI_API_KEY": "GEMINI_KEY_HERE"
        },
        "config": {
          "endpoint": "https://example.invalid",
          "model": "nano-pro"
        }
      },
      "peekaboo": {
        "enabled": true
      },
      "sag": {
        "enabled": false
      }
    }
  }
}

配置规则：

1. 配置键默认匹配Skills名称
2. 如果Skills名称包含连字符，用引号括起键名
3. 如果Skills定义了metadata.openclaw.skillKey，使用该键

示例：
- Skills名称：file-search
- 配置键："file-search"（需要引号）

配置字段说明：

字段	说明	示例
enabled	启用/禁用Skills	true / false
apiKey	API密钥（便捷字段）	"your-api-key"
env	环境变量	{"KEY": "value"}
config	自定义配置	{"model": "gpt-4"}

环境变量注入规则：

1. env中的变量仅在进程中尚未设置时注入
2. apiKey为声明primaryEnv的Skills提供便捷配置
3. config用于自定义单Skills字段
4. 环境变量在智能体运行时注入，运行结束后恢复

示例配置：

{
  "skills": {
    "entries": {
      // 配置Gemini Skills
      "gemini": {
        "enabled": true,
        "apiKey": "your-gemini-key",
        "config": {
          "model": "gemini-pro",
          "temperature": 0.7
        }
      },
      
      // 配置Banana绘图
      "nano-banana-pro": {
        "enabled": true,
        "env": {
          "GEMINI_API_KEY": "your-key",
          "BANANA_ENDPOINT": "https://api.banana.dev"
        }
      },
      
      // 禁用某个Skills
      "unwanted-skill": {
        "enabled": false
      }
    },
    
    // 仅允许特定内置Skills（可选）
    "allowBundled": [
      "file-search",
      "calendar-sync",
      "web-clipper"
    ]
  }
}

allowBundled白名单：

{
  "skills": {
    "allowBundled": [
      "file-search",
      "note-sync"
    ]
  }
}

说明：

• 如果设置了allowBundled，只有列表中的内置Skills才有资格
• 托管/工作区Skills不受影响
• 用于限制内置Skills的加载

8.4.2 Skills监视器（自动刷新）

什么是Skills监视器：

Skills监视器会监视Skills文件夹，当SKILL.md文件更改时自动更新Skills快照。

配置监视器：

{
  "skills": {
    "load": {
      "watch": true,              // 启用监视器（默认true）
      "watchDebounceMs": 250      // 防抖延迟（毫秒）
    }
  }
}

工作原理：

1. OpenClaw在会话开始时对有资格的Skills进行快照
2. 监视器监视Skills文件夹的变化
3. 当SKILL.md更改时，刷新Skills列表
4. 刷新后的列表在下一个智能体轮次生效

使用场景：

✅ 开发Skills时实时测试
✅ 修改Skills配置后立即生效
✅ 添加新Skills后自动加载

8.4.3 安全注意事项

⚠️ 重要安全提醒：

1. 将第三方Skills视为不受信任的代码
2. 启用前请仔细阅读Skills内容
3. 对于不受信任的输入和高风险工具，使用沙箱隔离
4. 保护API密钥，不要泄露到日志中

安全最佳实践：

1. 审查Skills代码

# 安装前查看Skills内容
cat ~/.openclaw/skills/my-skill/SKILL.md

# 检查Skills权限要求
grep "requires" ~/.openclaw/skills/my-skill/SKILL.md

2. 使用沙箱隔离

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

3. 保护API密钥

{
  "skills": {
    "entries": {
      "my-skill": {
        "apiKey": "your-secret-key",  // ✅ 通过配置文件
        "env": {
          "API_KEY": "your-key"       // ✅ 通过环境变量
        }
      }
    }
  }
}

❌ 不要：

---
name: my-skill
description: My skill with API key: sk-1234567890  # ❌ 不要在SKILL.md中暴露密钥
---

4. 限制Skills权限

{
  "skills": {
    "entries": {
      "untrusted-skill": {
        "enabled": true,
        "config": {
          "allowedPaths": ["/safe/path"],  // 限制文件访问
          "allowedCommands": ["ls", "cat"]  // 限制命令执行
        }
      }
    }
  }
}

5. 定期审计

# 列出所有已安装的Skills
openclaw skill list

# 检查Skills配置
cat ~/.openclaw/openclaw.json | grep -A 10 "skills"

# 查看Skills日志
openclaw logs --skill my-skill

8.4.4 性能优化

Token影响（Skills列表）：

当Skills有资格时，OpenClaw将可用Skills的紧凑XML列表注入到系统提示词中。

成本计算：

基础开销（仅当≥1个Skills时）：195字符

每个Skills：97字符 + XML转义的字段长度
- name（转义后）
- description（转义后）
- location（转义后）

公式：
total = 195 + Σ (97 + len(name) + len(description) + len(location))

Token估算（OpenAI风格）：
~4字符/token，所以每个Skills ≈ 24 token + 字段长度

优化建议：

1. 保持Skills描述简洁
   ❌ 差：This is a very detailed and comprehensive skill that can do many things including...
   ✅ 好：Generate images via Gemini API

2. 使用简短的Skills名称
   ❌ 差：super-advanced-image-generation-tool
   ✅ 好：nano-banana-pro

3. 禁用不需要的Skills
   {
     "skills": {
       "entries": {
         "unused-skill": { "enabled": false }
       }
     }
   }

4. 使用allowBundled限制内置Skills
   {
     "skills": {
       "allowBundled": ["file-search", "calendar-sync"]
     }
   }

性能监控：

# 查看Skills加载时间
openclaw skill perf

# 输出示例：
Skills加载统计：
- 总Skills数：15
- 加载时间：120ms
- Token消耗：约450 tokens
- 内存占用：2.3MB

8.4.5 多智能体Skills管理

单智能体 vs 共享Skills：

单智能体Skills：
- 位置：<workspace>/skills
- 作用域：仅该智能体可用
- 用途：项目特定功能

共享Skills：
- 位置：~/.openclaw/skills
- 作用域：所有智能体可见
- 用途：通用功能

多智能体配置示例：

{
  "agents": {
    "list": [
      {
        "id": "main",
        "workspace": "/home/user/main-agent",
        "skills": {
          "entries": {
            "file-search": { "enabled": true }
          }
        }
      },
      {
        "id": "assistant",
        "workspace": "/home/user/assistant-agent",
        "skills": {
          "entries": {
            "calendar-sync": { "enabled": true }
          }
        }
      }
    ]
  }
}

共享Skills文件夹：

{
  "skills": {
    "load": {
      "extraDirs": [
        "/shared/team-skills",      // 团队共享
        "/shared/company-skills"    // 公司共享
      ]
    }
  }
}

8.4.6 远程macOS节点（Linux Gateway）

跨平台Skills支持：

如果Gateway运行在Linux上但连接了macOS节点，OpenClaw可以将仅限macOS的Skills视为有资格。

配置示例：

{
  "nodes": {
    "macos-node": {
      "host": "192.168.1.100",
      "platform": "darwin",
      "allowSystemRun": true
    }
  }
}

工作原理：

1. Linux Gateway检测到macOS节点
2. 检查节点上的二进制文件
3. 将macOS专用Skills标记为可用
4. 通过nodes工具执行Skills

注意事项：

⚠️ 如果macOS节点离线：
- Skills仍然可见
- 调用可能失败
- 直到节点重新连接

8.4.7 Skills备份和恢复

备份Skills：

# 备份所有Skills
openclaw skill backup

# 备份到指定位置
openclaw skill backup --output ~/backups/skills.zip

# 输出示例：
正在备份Skills...
- file-search ✅
- note-sync ✅
- calendar-sync ✅

备份完成！
文件：~/backups/skills-2026-02-11.zip
大小：15.3MB

恢复Skills：

# 从备份恢复
openclaw skill restore ~/backups/skills-2026-02-11.zip

# 输出示例：
正在恢复Skills...
- file-search ✅
- note-sync ✅
- calendar-sync ✅

恢复完成！
共恢复3个Skills

手动备份：

# 备份Skills文件夹
cp -r ~/.openclaw/skills ~/backups/skills-$(date +%Y%m%d)

# 备份配置文件
cp ~/.openclaw/openclaw.json ~/backups/openclaw-$(date +%Y%m%d).json

8.4.8 常见问题排查

问题1：Skill无法加载

症状：Skill安装成功但无法使用

排查步骤：
1. 检查Skill是否启用
   openclaw skill status file-search

2. 查看错误日志
   openclaw skill logs file-search

3. 检查门控条件
   cat ~/.openclaw/skills/file-search/SKILL.md | grep "requires"

4. 重新安装
   openclaw skill reinstall file-search

问题2：Skill响应慢

症状：Skill执行时间过长

排查步骤：
1. 查看性能报告
   openclaw skill perf file-search

2. 检查网络连接
   ping api.example.com

3. 清理缓存
   openclaw skill cache clear file-search

4. 检查依赖
   which uv python

问题3：Skill配置错误

症状：Skill功能异常

排查步骤：
1. 检查配置文件
   openclaw skill config show file-search

2. 验证环境变量
   echo $GEMINI_API_KEY

3. 重置配置
   openclaw skill config reset file-search

4. 查看文档
   openclaw skill docs file-search

问题4：Skills冲突

症状：多个Skills响应同一命令

排查步骤：
1. 检测冲突
   openclaw skill check

2. 查看优先级
   openclaw skill priority

3. 禁用冲突的Skills
   openclaw config set skills.entries.conflicting-skill.enabled false

4. 修改命令关键词
   编辑SKILL.md，修改触发词

---

📝 本章小结

本章学习了OpenClaw的Skills扩展功能：

核心内容

1. ClawHub技能市场

   • ClawHub介绍
   • 技能分类和搜索
   • 技能评价体系
   • Skills安装和管理

2. 必装Skills推荐

   • 文件管理类（3个）
   • 知识管理类（3个）
   • 日程管理类（2个）
   • 自动化类（2个）
   • 工具类（2个）

3. 自定义Skills开发

   • Skills开发基础
   • 开发环境搭建
   • Skills结构详解
   • API接口设计
   • 调试和测试
   • 发布到ClawHub

4. Skills管理技巧

   • 安装和卸载
   • 配置管理
   • 冲突解决
   • 性能优化
   • 备份和恢复
   • 问题排查

实战技巧

• ✅ 选择高质量Skills
• ✅ 合理配置Skills
• ✅ 定期更新Skills
• ✅ 监控Skills性能
• ✅ 及时备份配置

下一步

• 学习第9章：多平台集成
• 掌握企微、钉钉、飞书、QQ接入
• 构建多平台AI助手

---

🎯 实战练习

练习1：安装必备Skills

1. 安装file-search、calendar-sync、web-clipper
2. 配置Skills参数
3. 测试Skills功能

练习2：开发简单Skills

1. 创建一个问候Skills
2. 实现基本功能
3. 测试和调试

练习3：Skills性能优化

1. 监控Skills性能
2. 找出性能瓶颈
3. 优化和改进

---

💡 常见问题

Q1：如何选择合适的Skills？ A：看评分、下载量、更新频率和文档质量。

Q2：Skills冲突怎么办？ A：使用openclaw skill check检测并自动修复。

Q3：如何开发自己的Skills？ A：参考官方文档和示例代码，从简单开始。

Q4：Skills性能差怎么办？ A：查看性能报告，优化代码，清理缓存。

Q5：Skills数据如何备份？ A：使用openclaw skill backup定期备份。

---

下一章预告：第9章将学习多平台集成，包括企业微信、钉钉、飞书、QQ Bot配置等内容。