06. 技能系统 (Skills) 完全指南

课程信息

⠀

• 作者：老金

• GitHub：https://github.com/KimYx0207

• 公众号：老金带你玩AI

• X（Twitter）：老金带你玩AI

• 个人博客：https://aiking.dev

• 难度等级：🟡 进阶

• 阅读时间：30 分钟

• 前置知识：已完成快速开始（03-快速开始指南）

⠀

本篇你将学会： 理解技能和工具的区别、管理内置技能、通过 openclaw skills 安装技能、创建自定义技能

⠀

小白速通： 只看前 3 节（"什么是技能"、"Skills vs Tools"、"内置技能一览"），了解概念就够了。等你想教 AI 新能力时再看后面的章节

⠀

先做一个小练习：看见技能如何改变助手行为

技能不是术语表里的概念，它的作用是把一组稳定做法交给 AI。先用一个最小练习建立手感。

⠀

第一步：确认技能命令可用

⠀

openclaw skills search "summarize"

⠀

如果搜索结果里能看到摘要、笔记、文档处理相关技能，说明 skills 入口正常。不同版本和市场索引返回结果可能不同，重点是确认命令能跑通。

⠀

第二步：安装一个低风险技能

⠀

优先选择只处理文本、不需要外部账号授权的技能。例如搜索结果里有 summarize 时：

⠀

openclaw skills install summarize

⠀

如果你的版本里没有这个技能，就先跳过安装，继续看下面的“技能长什么样”。不要为了练习随便安装需要邮箱、网盘、密码管理器授权的技能。

⠀

第三步：在对话里触发它

⠀

回到 Control UI，输入一段长文本，然后要求：

⠀

请把上面这段内容整理成 3 条要点，并保留行动项。

⠀

如果已安装摘要类技能，OpenClaw 会更倾向于按技能里的流程整理内容。即使你的环境没有对应技能，这个练习也能帮你理解：技能的价值不是“多一个按钮”，而是把可复用的处理流程写下来。

⠀

你应该记住

⠀

• 工具负责单个动作。

• 技能负责告诉 AI 如何组合动作。

• 新手先练低风险文本技能，不要一上来接邮箱、云盘、密码管理器。

⠀

什么是技能？

⠀

如果说工具 (Tools) 是 AI 的双手，那技能 (Skills) 就是教 AI 如何组合使用这些工具的教科书。

⠀

一个工具只能做一件事：读文件、发消息、搜索网页。但一个技能可以把多个工具串起来，完成一个完整的任务流程。比如"管理 GitHub Issue"这个技能，背后可能要调用搜索、读取、创建、评论等十几个工具。

⠀

OpenClaw 提供了大量内置与可安装技能，覆盖办公、开发、生活方方面面。你也可以自己创建技能，教 AI 新的能力。

⠀

Skills vs Tools：概念深入对比

⠀

很多人刚接触 OpenClaw 时会搞混技能和工具，这里彻底说清楚。

⠀

本质区别

⠀

工具 (Tools) = 原子操作，做一件具体的事
技能 (Skills) = 编排方案，教 AI 如何组合工具完成复杂任务

⠀

打个比方：

⠀

• 工具就像厨房里的刀、锅、铲子 — 每个都有明确的单一用途

• 技能就像菜谱 — 告诉你先切菜、再热油、然后翻炒、最后调味

⠀

对比表

⠀

维度

工具 (Tools)

技能 (Skills)

粒度

单个动作

多步骤流程

定义方式

TypeScript/Python 函数

Markdown 指令文档

执行方式

直接调用

AI 根据指令编排工具

状态

无状态

可以维护上下文

触发方式

模型自动选择

关键词触发或模型判断

复用性

跨技能共享

通常独立使用

开发难度

需要编程

写 Markdown 就行

⠀

一个具体的例子

⠀

假设你说："帮我把今天的会议纪要发到 Slack 的 #team 频道"。

⠀

AI 需要做这些事：

⠀

1. 搜索今天的日历事件（工具：google_calendar_search）

2. 找到会议纪要文件（工具：file_search）

3. 读取文件内容（工具：file_read）

4. 格式化为 Slack 消息（AI 自己处理）

5. 发送到指定频道（工具：slack_send_message）

⠀

这 5 步里，每一步都是一个工具调用。但 AI 怎么知道要按这个顺序来？答案就是技能。gog 技能和 slack 技能里的指令告诉了 AI 如何组合这些工具。

⠀

技能的加载机制

⠀

技能不是一直驻留在内存里的。OpenClaw 的加载策略很聪明：

⠀

用户消息进来
    ↓
Gateway 分析消息内容
    ↓
匹配相关技能（通过 triggers 关键词或语义匹配）
    ↓
将匹配到的技能指令注入到系统提示词中
    ↓
AI 根据技能指令 + 工具列表来执行任务

⠀

这意味着：

• 不是所有技能都会同时加载（那会撑爆上下文窗口）

• 只有跟当前任务相关的技能才会被激活

• 你可以通过 triggers 字段精确控制技能的触发条件

⠀

常用 Skills 命令

⠀

# 搜索技能
openclaw skills search "gog"

# 安装技能
openclaw skills install gog

# 更新技能
openclaw skills update

⠀

内置技能完整分类

⠀

办公效率类

⠀

技能

功能

使用场景

依赖工具

gog

Google Workspace

邮件、日历、文档管理

Google API MCP

notion

Notion

页面创建、数据库查询

Notion API

trello

Trello

看板管理、任务跟踪

Trello API

slack

Slack

工作区消息管理

Slack API

1password

1Password

密码查询（只读）

1Password CLI

⠀

开发工具类

⠀

技能

功能

使用场景

依赖工具

coding-agent

编程助手

写代码、调试、重构

文件系统 + Shell

github

GitHub

仓库管理、PR、Issue

GitHub CLI (gh)

gh-issues

GitHub Issues

Issue 专项管理

GitHub CLI (gh)

tmux

终端会话

管理终端会话

tmux

⠀

笔记知识类

⠀

技能

功能

使用场景

依赖工具

obsidian

Obsidian

笔记管理、知识库

文件系统

apple-notes

Apple 备忘录

macOS/iOS 备忘录

AppleScript

bear-notes

Bear

Bear 笔记管理

Bear X-Callback

nano-pdf

PDF 处理

PDF 阅读、摘要

PDF 解析工具

⠀

多媒体类

⠀

技能

功能

使用场景

依赖工具

voice-call

语音通话

AI 语音对话

音频 I/O

spotify-player

Spotify

音乐播放控制

Spotify API

peekaboo

截图

屏幕截图分析

screencapture

camsnap

摄像头

拍照识别

imagesnap

video-frames

视频帧

视频内容分析

ffmpeg

songsee

听歌识曲

识别正在播放的音乐

音频采集

⠀

多媒体生成类（v2026.4.5 新增）

⠀

v2026.4.5 起，OpenClaw 内置了三个生成式多媒体工具，不再需要额外安装：

⠀

工具

功能

支持的提供商

运行模式

video_generate

文本/图片/视频 → 视频

xAI (Grok)、Alibaba Wan、Runway、Google Veo、OpenAI Sora、BytePlus Seedance、Qwen

generate / imageToVideo / videoToVideo

music_generate

文本 → 音乐/音频

Google Lyria 3、MiniMax、ComfyUI 工作流

generate（异步任务）

image_generate

文本 → 图片

多提供商 + ComfyUI 工作流

generate

⠀

这些工具全部异步执行：Agent 提交请求后立即返回任务 ID，生成完成后自动将结果推送到原始会话。

⠀

快速配置示例：

⠀

{
  "agents": {
    "defaults": {
      "videoGenerationModel": {
        "primary": "google/veo-3.1-fast-generate-preview",
        "fallbacks": ["runway/gen4.5"],
      },
      "musicGenerationModel": {
        "primary": "google/lyria-3-clip-preview",
        "fallbacks": ["minimax/music-2.6"],
      },
    },
  },
}

⠀

ComfyUI 工作流支持： 如果你有本地 ComfyUI 或 Comfy Cloud 实例，可以通过 comfy 插件将自定义工作流接入 image_generate、video_generate 和 music_generate。设置 COMFY_API_KEY 或 COMFY_CLOUD_API_KEY 环境变量即可。

⠀

生活工具类

⠀

技能

功能

使用场景

依赖工具

weather

天气

天气查询和预报

天气 API

things-mac

Things

任务管理 (macOS)

Things URL Scheme

apple-reminders

提醒事项

Apple 提醒事项

AppleScript

goplaces

地点

地点搜索和导航

地图 API

healthcheck

健康检查

系统状态监控

系统命令

⠀

系统管理类

⠀

技能

功能

使用场景

依赖工具

session-logs

会话日志

查看对话历史

文件系统

model-usage

模型统计

API 使用量统计

内部 API

summarize

摘要

长文本摘要

AI 模型

skill-creator

技能创建器

创建自定义技能

文件系统

⠀

主要技能详细使用教程

⠀

gog — Google Workspace 技能

⠀

gog 是 OpenClaw 最常用的技能之一，让 AI 帮你管理 Gmail、Google Calendar 和 Google Drive。

⠀

前置条件

⠀

1. 在 Google Cloud Console 创建 OAuth 2.0 凭证

2. 启用 Gmail API、Calendar API、Drive API

3. 在 OpenClaw 中完成 Google 认证

⠀

# 认证 Google 账号（通过 models auth 子命令）
openclaw models auth login --provider google

# 浏览器会弹出 Google 登录页面
# 授权后，凭证自动保存到 auth-profiles.json

⠀

邮件管理

⠀

你可以这样跟 AI 说：

⠀

查看我今天收到的邮件

⠀

AI 会调用 gog 技能，执行以下流程：

1. 调用 gmail_search 工具搜索今天的邮件

2. 调用 gmail_read 工具读取邮件内容

3. 整理成摘要返回给你

⠀

更多邮件操作示例：

⠀

帮我回复张三的邮件，告诉他周五可以开会
把所有来自 [email protected] 的邮件标记为已读
搜索上周关于"项目报告"的邮件
帮我写一封邮件给客户，确认下周的交付时间

⠀

日历管理

⠀

今天有什么安排？
帮我在下周三下午 2 点创建一个会议，邀请 [email protected]
取消明天上午的会议
把周五的会议改到下周一

⠀

AI 会自动处理时区、冲突检测、邀请发送等细节。

⠀

Google Drive 操作

⠀

在 Google Drive 里搜索"季度报告"
帮我创建一个新的 Google Doc，标题是"会议纪要 2026-02-25"
把这个文件分享给 [email protected]

⠀

gog 技能的配置选项

⠀

在 ~/.openclaw/openclaw.json（JSON5 格式）中可以微调 gog 技能的行为：

⠀

{
  "skills": {
    "entries": {
      "gog": {
        "config": {
          "defaultCalendar": "primary",
          "emailSignature": "— 发自 OpenClaw AI 助手",
          "maxSearchResults": 20,
          "timezone": "Asia/Shanghai",
          "language": "zh-CN",
        },
      },
    },
  },
}

⠀

github — GitHub 技能

⠀

github 技能让 AI 成为你的 GitHub 助手，管理仓库、PR、Issue、Actions 等。

⠀

前置条件

⠀

# 认证 GitHub（通过 models auth 子命令）
openclaw models auth login --provider github

# 或者手动设置 Token
openclaw config set github.token ghp_xxxxxxxxxxxx

⠀

仓库管理

⠀

列出我的 GitHub 仓库
克隆 username/repo-name 到本地
查看 openclaw/openclaw 仓库的最新动态

⠀

Pull Request 操作

⠀

查看 openclaw/openclaw 仓库的待审 PR
帮我创建一个 PR，从 feature/new-skill 合并到 main
审查 PR #123 的代码变更
合并 PR #456

⠀

AI 处理 PR 的流程：

1. 调用 gh_pr_list 获取 PR 列表

2. 调用 gh_pr_diff 查看代码变更

3. 分析代码质量、潜在问题

4. 生成审查意见或执行合并

⠀

Issue 管理

⠀

查看 openclaw/openclaw 仓库的 open issues
创建一个新 Issue：标题是"技能系统文档需要更新"
给 Issue #789 添加评论
关闭 Issue #101，标记为已解决
给 Issue #202 打上 bug 标签

⠀

GitHub Actions

⠀

查看最近的 CI/CD 运行状态
重新运行失败的 workflow
查看 workflow run #12345 的日志

⠀

github 技能的配置选项

⠀

{
  "skills": {
    "entries": {
      "github": {
        "config": {
          "defaultOrg": "openclaw",
          "defaultRepo": "openclaw",
          "autoLabel": true,
          "prTemplate": "workspace/templates/pr-template.md",
        },
      },
    },
  },
}

⠀

coding-agent — 编程助手技能

⠀

coding-agent 是开发者最爱的技能，让 AI 帮你写代码、调试、重构。

⠀

工作原理

⠀

coding-agent 技能跟其他技能不太一样。它不是简单地调用几个工具，而是启动一个完整的编程工作流：

⠀

用户请求 → 分析需求 → 读取相关代码 → 制定方案 → 编写代码 → 验证结果

⠀

常用场景

⠀

写新代码：

⠀

帮我写一个 TypeScript 函数，把 CSV 文件转换成 JSON
在 src/utils/ 下创建一个日期格式化工具

⠀

调试：

⠀

这段代码报错了，帮我看看：[粘贴错误信息]
为什么这个 API 返回 500？帮我排查

⠀

重构：

⠀

把 src/services/user.ts 重构一下，太长了
这个函数的圈复杂度太高，帮我拆分

⠀

代码审查：

⠀

审查一下 src/api/routes.ts 的代码质量
检查这个文件有没有安全漏洞

⠀

coding-agent 的特殊能力

⠀

1. 文件系统访问 — 可以读写项目文件

2. Shell 命令执行 — 可以运行构建、测试命令

3. 上下文感知 — 会自动读取相关文件来理解代码结构

4. 多文件编辑 — 可以同时修改多个文件

⠀

安全限制

⠀

coding-agent 默认运行在沙箱中：

⠀

• 文件操作限制在工作空间目录内

• Shell 命令需要用户确认（除非配置了自动批准）

• 不能访问系统敏感目录

⠀

{
  "skills": {
    "entries": {
      "coding-agent": {
        "config": {
          "workDir": "~/projects/my-app",
          "allowedCommands": ["npm", "node", "git", "tsc"],
          "autoApprove": false,
          "maxFileSize": "1MB",
        },
      },
    },
  },
}

⠀

browser-automation — 浏览器自动化技能（v2026.4.24 更新）

⠀

browser-automation 是 OpenClaw 内置的浏览器自动化技能，让 AI 操控一个隔离的 Chrome/Brave/Edge 浏览器实例。v2026.4.24 对此技能做了重要增强。

⠀

核心能力

⠀

• 坐标点击（v2026.4.24 新增） — 支持 click-coords 直接按视口坐标点击，不需要快照中的元素引用

• 60 秒操作预算 — 默认 actionTimeoutMs 从旧值提升到 60000ms（60 秒），给复杂页面交互更多时间

• 按配置覆盖 headless 模式 — 每个浏览器 profile 可以独立设置 headless 选项

• 快照 → 操作 → 重快照 → 恢复 — 内置的多步骤循环，带过期引用自动恢复

⠀

配置示例

⠀

{
  "browser": {
    "enabled": true,
    "defaultProfile": "openclaw",
    "actionTimeoutMs": 60000,
    "headless": false,
    "profiles": {
      "openclaw": { "cdpPort": 18800 },
      "work": {
        "cdpPort": 18801,
        "headless": true,
      },
    },
  },
}

⠀

诊断命令

⠀

# 检查浏览器插件、进程、CDP 连接状态
openclaw browser --browser-profile openclaw doctor

⠀

obsidian — Obsidian 笔记技能

⠀

obsidian 技能让 AI 帮你管理 Obsidian 知识库。

⠀

前置条件

⠀

需要告诉 OpenClaw 你的 Obsidian Vault 路径：

⠀

{
  "skills": {
    "entries": {
      "obsidian": {
        "config": {
          "vaultPath": "~/Documents/MyVault",
          "dailyNotesFolder": "Daily",
          "templatesFolder": "Templates",
        },
      },
    },
  },
}

⠀

笔记管理

⠀

在 Obsidian 里创建一篇笔记，标题是"TypeScript 泛型学习笔记"
搜索我的 Obsidian 笔记中关于"设计模式"的内容
帮我整理今天的日记
把这段内容添加到"项目计划"笔记里

⠀

知识库操作

⠀

列出 Obsidian 里所有带 #todo 标签的笔记
查看"读书笔记"文件夹下的所有文件
帮我创建一个 MOC（Map of Content）页面，整理所有编程相关笔记
更新"学习路线图"笔记，添加新的学习目标

⠀

双向链接

⠀

obsidian 技能理解 Obsidian 的双向链接语法：

⠀

创建一篇笔记"React Hooks"，并链接到已有的"React 基础"笔记
查找所有链接到"项目 A"的笔记

⠀

AI 会自动使用 [[双向链接]] 语法，保持你的知识图谱完整。

⠀

技能配置文件详解

⠀

每个技能的行为都可以通过配置文件来调整。

⠀

全局技能配置

⠀

在 ~/.openclaw/openclaw.json 中的 skills 字段：

⠀

{
  "skills": {
    // 是否加载 OpenClaw 内置技能（默认 true）
    "allowBundled": true,
    // 从指定路径加载额外技能
    "load": ["~/.openclaw/workspace/skills/*"],
    // 各技能的独立配置
    "entries": {
      "gog": {
        "enabled": true,
        "config": {
          "timezone": "Asia/Shanghai"
        }
      },
      "github": {
        "enabled": true,
        "config": {
          "defaultOrg": "my-org"
        }
      },
      "voice-call": {
        "enabled": false
      }
    }
  }
}

⠀

配置字段说明

⠀

字段

类型

说明

allowBundled

boolean

是否加载内置技能（默认 true）

load

string[]

额外技能的加载路径

install

object

从 ClawHub 安装技能的配置

limits

object

技能执行的限制配置

entries

object

各技能的独立配置（enabled、apiKey、env、config）

⠀

要禁用某个技能，在 entries 中将其 enabled 设为 false。技能的自定义参数放在 config 子对象中。

⠀

Agent 级别的技能配置

⠀

每个 Agent 可以有自己的技能配置，覆盖全局设置：

⠀

{
  "agents": {
    "list": [
      {
        "id": "coding",
        "workspace": "~/.openclaw/workspace-coding",
        // Agent 级别的 skills 是一个简单的字符串数组
        "skills": ["coding-agent", "github", "gh-issues", "tmux"],
      },
      {
        "id": "office",
        "workspace": "~/.openclaw/workspace-office",
        "skills": ["gog", "slack", "notion", "trello", "summarize"],
      },
    ],
  },

  // 技能的详细配置放在顶层 skills.entries 中
  "skills": {
    "entries": {
      "coding-agent": {
        "config": {
          "workDir": "~/projects",
          "autoApprove": true,
        },
      },
      "gog": {
        "config": {
          "timezone": "Asia/Shanghai",
        },
      },
    },
  },
}

⠀

这样，编程 Agent 只加载开发相关技能，办公 Agent 只加载办公相关技能，互不干扰。注意 Agent 级别的 skills 是一个简单的字符串数组，而技能的详细配置（如自定义参数）放在顶层 skills.entries 中。

⠀

技能的 SKILL.md（技能的定义文件，用 Markdown 格式编写）文件格式

⠀

每个技能目录下的核心文件是 SKILL.md（注意大写）。这是一个 Markdown 文件，AI 会读取它来理解如何执行任务。

⠀

SKILL.md 的结构：

⠀

# 技能名称

技能的描述和用途说明。

## 触发条件

描述什么情况下应该激活这个技能。

## 执行步骤

1. 第一步操作
2. 第二步操作
3. ...

## 依赖工具

列出技能需要调用的工具。

## 注意事项

执行时需要注意的约束和边界条件。

⠀

OpenClaw 还会自动注入以下 prompt 文件到技能上下文中：

⠀

文件

用途

AGENTS.md

Agent 角色和行为定义

SOUL.md

AI 人格和沟通风格

TOOLS.md

可用工具列表和使用说明

⠀

这些文件与 SKILL.md 配合，让 AI 在执行技能时拥有完整的上下文。

⠀

⏭️ 小白可跳过 — 这部分面向想创建自定义技能的开发者

⠀

自定义技能开发完整教程

⠀

这是 OpenClaw 最强大的功能之一。你可以教 AI 新的能力，而且不需要写复杂的代码 — 大部分情况下写 Markdown 就够了。

⠀

方法一：用 skill-creator 技能（最简单）

⠀

直接告诉 AI：

⠀

帮我创建一个技能，用来管理我的读书笔记。
每次我说"记录读书笔记"，就创建一个新的 Markdown 文件，
包含书名、作者、日期、关键摘录和我的感想。

⠀

AI 会自动使用 skill-creator 技能帮你生成完整的技能文件。

⠀

方法二：手动创建（完全控制）

⠀

下面我们从零开始创建一个完整的自定义技能：读书笔记管理器。

⠀

第一步：创建技能目录

⠀

mkdir -p ~/.openclaw/workspace/skills/reading-notes
mkdir -p ~/.openclaw/workspace/skills/reading-notes/tools
mkdir -p ~/.openclaw/workspace/skills/reading-notes/examples

⠀

目录结构：

⠀

~/.openclaw/workspace/skills/reading-notes/
├── SKILL.md          # 技能描述和指令（核心文件）
├── tools/            # 自定义工具（可选）
│   └── reading-stats.ts
└── examples/         # 使用示例（可选）
    └── example.md

⠀

第二步：编写 SKILL.md（核心文件）

⠀

这是技能的灵魂。AI 会读取这个文件来理解如何执行任务。

⠀

# 读书笔记管理

你是一个读书笔记助手。当用户要求记录读书笔记时，按以下流程操作。

## 触发条件

当用户提到以下关键词时激活：记录读书笔记、读书笔记、我读了一本书、阅读记录、读书

## 依赖工具

- file_read
- file_write
- file_search

## 创建新笔记

1. 询问用户以下信息（如果用户没有主动提供）：
   - 书名
   - 作者
   - 评分（1-5 星）
2. 在 `workspace/reading-notes/` 目录下创建 Markdown 文件
3. 文件名格式：`YYYY-MM-DD-书名.md`
4. 使用以下模板：

### 笔记模板

⠀

• 作者：{作者}
• 阅读日期：{日期}
• 评分：{星级}

⠀

关键摘录

⠀

（用户提供的摘录内容）

⠀

个人感想

⠀

（用户的感想）

⠀

行动项

⠀

• （从书中获得的待办事项）

5. 更新 `workspace/reading-notes/INDEX.md` 索引文件
6. 索引文件按评分降序排列

## 查看阅读统计

当用户问"我读了多少书"或"阅读统计"时：

1. 扫描 `workspace/reading-notes/` 目录
2. 统计总数、平均评分、按月分布
3. 返回格式化的统计信息

## 搜索笔记

当用户搜索读书笔记时：

1. 在 `workspace/reading-notes/` 目录中搜索
2. 支持按书名、作者、关键词搜索
3. 返回匹配的笔记列表和摘要

⠀

第三步：添加自定义工具（可选）

⠀

如果你的技能需要超出内置工具能力的功能，可以写自定义工具。

⠀

创建 tools/reading-stats.ts：

⠀

import { Tool, ToolInput, ToolOutput } from "@openclaw/sdk";
import * as fs from "fs/promises";
import * as path from "path";

interface StatsInput extends ToolInput {
  notesDir: string;
}

interface BookStats {
  totalBooks: number;
  averageRating: number;
  booksByMonth: Record<string, number>;
  topRated: Array<{ title: string; rating: number }>;
}

export const readingStats: Tool<StatsInput, BookStats> = {
  name: "reading_stats",
  description: "统计读书笔记数据",

  parameters: {
    type: "object",
    properties: {
      notesDir: {
        type: "string",
        description: "读书笔记目录路径",
      },
    },
    required: ["notesDir"],
  },

  async execute(input: StatsInput): Promise<ToolOutput<BookStats>> {
    const { notesDir } = input;

    const files = await fs.readdir(notesDir);
    const mdFiles = files.filter(
      (f) => f.endsWith(".md") && f !== "INDEX.md"
    );

    let totalRating = 0;
    const booksByMonth: Record<string, number> = {};
    const topRated: Array<{ title: string; rating: number }> = [];

    for (const file of mdFiles) {
      const content = await fs.readFile(
        path.join(notesDir, file),
        "utf-8"
      );

      const ratingMatch = content.match(/\*\*评分\*\*：(\d)/);
      const rating = ratingMatch ? parseInt(ratingMatch[1]) : 0;
      totalRating += rating;

      const dateMatch = file.match(/^(\d{4}-\d{2})/);
      if (dateMatch) {
        const month = dateMatch[1];
        booksByMonth[month] = (booksByMonth[month] || 0) + 1;
      }

      const titleMatch = content.match(/# 《(.+?)》/);
      if (titleMatch) {
        topRated.push({ title: titleMatch[1], rating });
      }
    }

    topRated.sort((a, b) => b.rating - a.rating);

    return {
      success: true,
      data: {
        totalBooks: mdFiles.length,
        averageRating:
          mdFiles.length > 0 ? totalRating / mdFiles.length : 0,
        booksByMonth,
        topRated: topRated.slice(0, 10),
      },
    };
  },
};

⠀

第四步：添加使用示例（可选但推荐）

⠀

创建 examples/example.md：

⠀

# 读书笔记技能使用示例

## 示例 1：记录新书

用户：我刚读完《深入理解计算机系统》，作者是 Randal Bryant，给 5 星。
关键摘录："程序员需要理解计算机系统的全貌，才能写出高效的代码。"
感想：这本书让我对底层原理有了全新的认识。

AI 操作：
1. 创建 workspace/reading-notes/2026-02-25-深入理解计算机系统.md
2. 填入模板内容
3. 更新 INDEX.md

## 示例 2：查看统计

用户：我今年读了多少书？

AI 操作：
1. 扫描 reading-notes 目录
2. 筛选今年的文件
3. 返回统计数据

⠀

第五步：测试技能

⠀

# 检查技能是否被正确识别
openclaw skills list

# 查看技能详情
openclaw skills info reading-notes

# 检查技能就绪状态
openclaw skills check reading-notes

⠀

然后在对话中测试：

⠀

记录读书笔记：《代码整洁之道》，作者 Robert C. Martin，5 星

⠀

方法三：基于现有技能扩展

⠀

你可以复制一个现有技能，然后修改它：

⠀

# 复制 obsidian 技能作为模板
cp -r ~/.openclaw/workspace/skills/obsidian ~/.openclaw/workspace/skills/my-notes

# 编辑 SKILL.md，修改为你的需求

⠀

工作空间技能会覆盖同名的共享技能，所以你可以用这种方式"魔改"内置技能。

⠀

技能的类型与作用域

⠀

OpenClaw 的技能分为三种类型：

⠀

类型

说明

来源

bundled（内置）

随 OpenClaw 安装的技能，不可修改

安装目录

managed（托管）

从 ClawHub（OpenClaw 的官方技能市场，类似于手机的应用商店）安装的社区技能，可更新

ClawHub

workspace（工作区）

用户自己创建的技能

~/.openclaw/workspace/skills/

⠀

所有用户可编辑的技能都存放在 ~/.openclaw/workspace/skills/<skill-name>/ 目录下，核心文件为 SKILL.md。

⠀

优先级：workspace 技能 > managed 技能 > bundled 技能

⠀

技能的权限管理

⠀

技能的权限控制是安全的关键。你不会希望一个天气查询技能能删除你的文件。

⠀

权限类型

⠀

权限

说明

风险等级

file_read

读取文件

低

file_write

写入文件

中

file_delete

删除文件

高

shell_exec

执行 Shell 命令

高

network

网络访问

中

auth_access

访问认证凭证

高

memory_write

写入记忆文件

低

memory_read

读取记忆文件

低

⠀

权限声明

⠀

在 SKILL.md 中声明需要的权限：

⠀

## 所需权限

- file_read
- file_write

⠀

权限审批策略

⠀

OpenClaw 通过沙箱系统和审批机制管理工具权限，而不是通过配置文件中的权限字段。

⠀

权限控制的实际机制：

⠀

• 沙箱隔离 — 通过 sandbox 配置限制 Agent 的执行环境（详见 10-安全配置指南）

• 审批系统 — 通过 openclaw approvals CLI 管理工具调用的审批策略

• 安全审计 — 通过 openclaw security audit 检查权限配置是否安全

⠀

# 查看当前审批策略
openclaw approvals get

# 安全审计
openclaw security audit

⠀

权限管理的核心思路：在 SKILL.md 中声明所需权限（如上一节所示），然后通过沙箱和审批系统在运行时控制实际授权。

⠀

运行时权限检查

⠀

当技能尝试执行超出声明权限的操作时，OpenClaw 会：

⠀

1. 阻止操作

2. 通知用户

3. 记录安全日志

⠀

[WARNING] 技能 "weather" 尝试执行 file_write 操作，但未声明该权限。
操作已被阻止。如需授权，请在技能配置中添加 file_write 权限。

⠀

技能组合和工作流编排

⠀

单个技能已经很强大了，但真正的魔法在于把多个技能组合起来。

⠀

自然语言编排

⠀

最简单的方式是直接用自然语言描述你想要的工作流：

⠀

每天早上 9 点：
1. 用 gog 技能查看今天的日历安排
2. 用 gog 技能检查未读邮件
3. 用 github 技能查看我负责的 PR 和 Issue
4. 把以上信息整理成一份"今日简报"
5. 用 slack 技能发送到 #daily-standup 频道

⠀

AI 会自动调用多个技能来完成这个工作流。

⠀

定时任务编排

⠀

通过 openclaw.json 的 cron 字段配置定时任务：

⠀

// ~/.openclaw/openclaw.json
{
  "cron": {
    // 启用定时任务
    "enabled": true,
    // 定时任务的存储后端
    "store": "file",
    // 最大并发运行数
    "maxConcurrentRuns": 2,
  },
}

⠀

注意：cron 是一个配置对象（包含 enabled、store、maxConcurrentRuns、retry 等字段），不是任务数组。具体的定时任务通过 CLI 命令管理：openclaw cron list、openclaw cron add、openclaw cron rm。

⠀

v2026.5.22 后，定时任务还要关注两个细节：

⠀

• 输出语言：cron prompt 里写清输出语言和格式，否则后台任务可能按模型默认语言回复。

• HEARTBEAT 处理：需要持续检查的任务要明确“什么情况下继续、什么情况下停止”，避免后台 heartbeat 一直追加无效上下文。

⠀

技能链式调用

⠀

你可以在自定义技能的 SKILL.md 中引用其他技能：

⠀

# 项目周报生成器

当用户要求生成项目周报时，按以下步骤执行。

## 触发条件

当用户提到以下关键词时激活：项目周报、生成周报

## 依赖技能

- github
- gog
- obsidian

1. **收集 GitHub 数据**（使用 github 技能）
   - 本周合并的 PR 列表
   - 本周关闭的 Issue 列表
   - 本周的代码提交统计

2. **收集日历数据**（使用 gog 技能）
   - 本周的会议列表
   - 重要邮件摘要

3. **生成报告**
   - 整合以上数据
   - 按"完成项 / 进行中 / 下周计划"分类
   - 生成 Markdown 格式的周报

4. **保存报告**（使用 obsidian 技能）
   - 保存到 Obsidian 的"周报"文件夹
   - 文件名：YYYY-WXX-周报.md

⠀

条件分支

⠀

技能指令中可以包含条件逻辑：

⠀

## 处理邮件

当收到新邮件时：

- 如果是会议邀请 → 检查日历冲突，自动回复接受或建议其他时间
- 如果是 GitHub 通知 → 提取 PR/Issue 信息，更新项目看板
- 如果是客户邮件 → 标记为重要，生成回复草稿等待确认
- 其他邮件 → 分类归档

⠀

技能市场和社区技能

⠀

ClawHub 技能市场

⠀

ClawHub（clawhub.ai）是 OpenClaw 的官方技能注册表和市场。截至 2026 年 4 月，平台上已有 52,700+ 工具（含技能和插件）、180k 用户、1200 万次下载。你可以在上面：

⠀

• 浏览和搜索社区发布的技能

• 查看技能的详细说明、评分和使用量

• 一键安装技能到本地

• 发布自己创建的技能供他人使用

⠀

安装社区技能

⠀

从 ClawHub 安装的技能属于 managed（托管）类型，会被安装到 ~/.openclaw/workspace/skills/ 目录下。

⠀

# 从 ClawHub/市场安装（推荐用 openclaw skills）
openclaw skills install skill-name

# 从 GitHub 安装
openclaw skills install github:username/skill-name

# 从本地文件安装
openclaw skills install /path/to/skill-directory

# 安装特定版本
openclaw skills install [email protected]

⠀

浏览技能市场

⠀

# 搜索技能
openclaw skills search "jira"

# 按分类浏览
openclaw skills search --category dev
openclaw skills search --category office

# 查看热门技能
openclaw skills search --sort popular

⠀

发布你的技能

⠀

如果你创建了一个好用的技能，可以分享给社区：

⠀

# 登录 ClawHub（发布前需要认证）
clawhub login

# 发布到 ClawHub
clawhub publish ./my-skill --slug my-skill --name "My Skill"

⠀

发布前的检查清单：

⠀

• SKILL.md 有完整的技能描述（名称、用途、触发条件、执行步骤）

• 包含使用示例（examples/ 目录）

• 权限声明准确（不要申请不需要的权限）

• 没有硬编码的路径或凭证

⠀

管理已安装技能

⠀

# 更新技能
openclaw skills update

# 查看详情 / 其他管理能力
# 以 `openclaw skills --help` 和当前 CLI 文档为准

⠀

⏭️ 小白可跳过 — 这部分面向需要排查技能问题的开发者

⠀

技能调试和测试

⠀

调试模式

⠀

开发技能时，开启调试模式可以看到详细的执行过程。

⠀

在 ~/.openclaw/openclaw.json 中开启日志调试：

⠀

{
  "logging": {
    "level": "debug",
  },
}

⠀

开启后，你会在日志中看到：

⠀

[SKILL] Matching triggers for message: "记录读书笔记"
[SKILL] Matched skill: reading-notes (trigger: "记录读书笔记")
[SKILL] Loading skill instructions: workspace/skills/reading-notes/SKILL.md
[SKILL] Injecting skill into system prompt (tokens: 450)
[SKILL] Tool call: file_write -> workspace/reading-notes/2026-02-25-代码整洁之道.md
[SKILL] Tool call: file_read -> workspace/reading-notes/INDEX.md
[SKILL] Tool call: file_write -> workspace/reading-notes/INDEX.md
[SKILL] Skill execution complete

⠀

技能验证工具

⠀

# 查看技能是否被正确识别
openclaw skills list

# 查看技能详情
openclaw skills info my-skill

# 检查技能就绪状态（依赖工具是否可用等）
openclaw skills check my-skill

⠀

常见调试技巧

⠀

技能没有被触发？

⠀

1. 检查 triggers 关键词是否匹配

2. 确认技能的 enabled 没有被设为 false（在 skills.entries 中检查）

3. 查看是否有更高优先级的技能抢先匹配

⠀

# 查看技能详情，确认触发条件
openclaw skills info reading-notes

⠀

技能执行出错？

⠀

1. 开启 debug 日志级别

2. 检查工具权限是否正确声明

3. 确认依赖的外部工具已安装（如 gh、ffmpeg）

⠀

技能指令被 AI 误解？

⠀

1. 在 SKILL.md 中使用更明确的指令

2. 添加更多示例（examples/ 目录）

3. 使用编号步骤而不是模糊描述

⠀

⏭️ 小白可跳过 — 这部分面向想开发复杂技能的高级用户

⠀

高级技能开发模式

⠀

多步骤交互技能

⠀

有些技能需要跟用户多轮对话才能完成任务：

⠀

# 旅行规划助手

当用户提到"规划旅行"或"旅行计划"时激活。

## 信息收集阶段

按以下顺序收集信息（如果用户没有一次性提供）：

1. **目的地** — "你想去哪里？"
2. **日期** — "什么时候出发？玩几天？"
3. **预算** — "大概预算多少？"
4. **偏好** — "喜欢什么类型的活动？（美食/文化/自然/购物）"

## 规划阶段

收集完信息后：

1. 搜索目的地的热门景点和活动
2. 根据天数安排每日行程
3. 考虑交通和距离，优化路线
4. 根据预算推荐住宿和餐厅

## 输出格式

生成一份完整的旅行计划，包含：
- 每日行程（时间 + 地点 + 活动）
- 预估费用明细
- 实用贴士（天气、交通、注意事项）
- 保存到 workspace/travel-plans/ 目录

⠀

带状态的技能

⠀

有些技能需要在多次对话之间保持状态：

⠀

# 习惯追踪器

当用户提到"打卡"、"习惯追踪"或"今天完成了"时激活。

## 状态文件

使用 `workspace/habits/tracker.json` 存储追踪数据。

## 打卡流程

1. 读取 `tracker.json` 获取当前习惯列表
2. 如果用户说"打卡 [习惯名]"，更新对应习惯的今日状态
3. 计算连续天数
4. 返回鼓励信息和统计

## 数据格式

tracker.json 结构：

{
  "habits": [
    {
      "name": "早起",
      "created": "2026-01-01",
      "records": {
        "2026-02-24": true,
        "2026-02-25": true
      },
      "streak": 2
    }
  ]
}

## 统计报告

当用户问"习惯统计"时，生成：
- 每个习惯的完成率
- 最长连续天数
- 本周/本月完成情况

⠀

技能与 MCP 服务器集成

⠀

如果你的技能需要访问外部 API，可以通过 MCP 服务器来实现：

⠀

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["-y", "@openclaw/mcp-jira"],
      "env": {
        "JIRA_URL": "https://your-company.atlassian.net",
        "JIRA_TOKEN": "${JIRA_TOKEN}"
      }
    }
  }
}

⠀

然后在技能的 SKILL.md 中引用 MCP 提供的工具：

⠀

## 依赖工具

- jira_search
- jira_create_issue
- jira_update_issue

⠀

技能模板系统

⠀

对于需要生成固定格式输出的技能，可以使用模板：

⠀

~/.openclaw/workspace/skills/my-skill/
├── SKILL.md
└── templates/
    ├── daily-report.md
    ├── weekly-report.md
    └── meeting-notes.md

⠀

在 SKILL.md 中引用模板：

⠀

## 生成日报

使用 `templates/daily-report.md` 模板，填入以下变量：
- {date} — 当前日期
- {tasks} — 今日完成的任务
- {blockers} — 遇到的阻碍
- {tomorrow} — 明日计划

⠀

⏭️ 小白可跳过 — 这部分面向插件开发者

⠀

Meeting Notes / Transcripts 外部插件（v2026.5.27）

⠀

v2026.5.22 首先把 Meeting Notes 外部插件带入语音会议场景；v2026.5.26 / v2026.5.27 又把 transcript 路径做成更核心的能力：会议摘要、source-provider chunks、清洗后的用户轮次、媒体 provenance、Codex mirrors、WebChat replies 和 CLI/TUI replay 都会更依赖同一套 transcript-backed 数据。写技能时不要只抓聊天窗口最后一条回复，会议、语音、WebChat 和 Codex mirror 场景都应优先找 transcript / source-provider 证据。

⠀

Meeting Notes 是这一轮更新里更适合“会议 → 纪要 → 后续动作”的外部插件路径。它和普通技能不同：它更偏 source-only 工作流，先接收 live source 或 transcript，再把内容交给 Agent 总结。

⠀

推荐使用边界：

⠀

场景

建议

Discord voice live source

先确认频道授权和参会人同意

手动导入 transcript

标注来源、时间和会议主题

生成纪要

输出待办、决策、风险，而不是直接代替人工发布

写入文档或消息平台

需要人工确认后再提交

⠀

如果当前 CLI 暴露了 meeting-notes 相关命令，先用只读方式查看帮助和可用 source：

⠀

openclaw meeting-notes --help

⠀

Plugin SDK 兼容补充（v2026.5.27）

⠀

v2026.5.27 对 Plugin SDK 和工具搜索也有几处值得记住的变化：内存专用 embedding provider registration 被标为兼容层；非 bundled 用法会在 plugin compatibility diagnostics 中提示；plugin approval action metadata 对外暴露；plugin display metadata 让 ClawHub / package listing 更干净；tool-search catalog 和 plugin metadata fingerprint 会更积极复用缓存。排查“技能/插件没被搜到”时，先看 compatibility diagnostics 和 metadata cache，而不是立刻怀疑触发词写错。

⠀

开发插件时不要只看 “能不能加载”。这一轮还需要检查：

⠀

• allowlist imports 是否按 SDK 要求声明，避免运行时隐式依赖。

• plugin fallback override 是否只作用在目标插件，不要改变全局模型策略。

• embeddingProviders capability contract 是否在 manifest 中声明，避免向量检索能力在不同运行时表现不一致。

⠀

Plugin SDK 迁移：Tool-Result Transforms（v2026.4.24 破坏性变更）

⠀

⚠️ 如果你从未开发过 OpenClaw 捆绑插件，可以跳过本节。 这只影响使用 Tool-Result Transforms 的捆绑插件作者。

⠀

变更内容

⠀

v2026.4.24 移除了 Pi 运行时专用的 api.registerEmbeddedExtensionFactory(...) 兼容路径。所有 Tool-Result Transforms 必须迁移到 api.registerAgentToolResultMiddleware(...)。

⠀

为什么改

⠀

旧的 registerEmbeddedExtensionFactory 有三个问题：

⠀

1. Pi 运行时专用，Codex app-server 不支持

2. 直接访问高信任工具输出，安全边界不清晰

3. 耦合实现细节而非稳定契约

⠀

迁移步骤

⠀

旧写法（已移除）：

⠀

// 不再支持
api.registerEmbeddedExtensionFactory(async (event) => {
  return compactToolResult(event);
});

⠀

新写法：

⠀

api.registerAgentToolResultMiddleware(async (event) => {
  return compactToolResult(event);
}, {
  runtimes: ["pi", "codex"],
});

⠀

同时更新插件 manifest，声明 contracts：

⠀

{
  "contracts": {
    "agentToolResultMiddleware": ["pi", "codex"]
  }
}

⠀

迁移清单

⠀

1. 删除所有 api.registerEmbeddedExtensionFactory(...) 调用

2. 替换为 api.registerAgentToolResultMiddleware(handler, { runtimes })

3. 在插件 manifest 中添加 contracts.agentToolResultMiddleware 声明

4. 在所有目标运行时上测试

5. 移除 Pi-only 条件逻辑 — 新 API 通过 runtimes 数组处理运行时差异

⠀

注意： 外部插件不能注册 tool-result middleware，因为它可以在模型看到工具输出之前重写内容。只有捆绑插件可以使用此能力。

⠀

插件启动性能优化（v2026.4.22）

⠀

v2026.4.22 引入了原生 Jiti 加载机制，捆绑插件的启动加载时间减少了 82-90%。

⠀

主要优化：

⠀

• 捆绑插件优先使用预编译的 dist 模块，而非运行时 TypeScript 转换

• 预规范化的 Jiti 别名映射，消除每插件的启动规范化开销

• 惰性加载 doctor 插件路径，doctor --non-interactive 运行时间减少约 74%

• 静态模型目录取代运行时加载，manifest 驱动的模型行减少提供商依赖激活

⠀

这些改进是自动生效的，不需要配置变更。

⠀

常见问题

⠀

技能安装失败怎么办？

⠀

# 检查技能就绪状态
openclaw skills check skill-name

# 带详细输出重试安装
openclaw skills install skill-name --verbose

⠀

如何禁用某个技能？

⠀

在 ~/.openclaw/openclaw.json 的 skills.entries 中将其 enabled 设为 false：

⠀

{
  "skills": {
    "entries": {
      "voice-call": {
        "enabled": false,
      },
      "camsnap": {
        "enabled": false,
      },
    },
  },
}

⠀

自定义技能和内置技能冲突怎么办？

⠀

工作空间技能优先级最高。如果你在 ~/.openclaw/workspace/skills/ 下创建了一个跟内置技能同名的技能，你的版本会覆盖内置版本。

⠀

如果想恢复内置版本，删除工作空间中的同名技能即可。

⠀

⏭️ 小白可跳过 — 这部分面向需要优化技能性能的开发者

⠀

技能太多会影响性能吗？

⠀

不会。OpenClaw 只会加载跟当前消息相关的技能，不是把所有技能都塞进上下文。但如果你的 triggers 设置得太宽泛，可能会导致不相关的技能被误触发，浪费 token。

⠀

建议：

• 给每个技能设置精确的 triggers

• 在 Agent 配置中用 skills 字符串数组只加载需要的技能

• 定期清理不用的技能

⠀

技能可以访问其他 Agent 的数据吗？

⠀

默认不能。每个 Agent 的工作空间是隔离的。如果需要跨 Agent 共享数据，可以将技能安装为 managed 类型（通过 ClawHub / 市场），这样多个 Agent 都可以使用同一个技能。

⠀

如何回滚技能更新？

⠀

# 先搜索技能名称
openclaw skills search "skill-name"

# 安装特定版本（回滚）
openclaw skills install [email protected]

⠀

技能开发的最佳实践

⠀

1. 指令要具体 — 不要写"处理邮件"，要写"搜索今天的未读邮件，按发件人分组，生成摘要"

2. 步骤要编号 — AI 更容易按编号步骤执行

3. 提供示例 — examples/ 目录里的示例能显著提高 AI 的执行准确率

4. 权限最小化 — 只申请真正需要的权限

5. 错误处理 — 在指令中说明异常情况怎么处理（比如"如果找不到文件，提示用户创建"）

6. 保持简洁 — 一个技能做一件事，不要把太多功能塞进一个技能

⠀

下一步

⠀

技能系统掌握了！去 07. 记忆系统 了解 AI 如何记住你！

---