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

课程信息
难度等级：🟡 进阶
阅读时间：30 分钟
前置知识：已完成快速开始（03-快速开始指南）
本篇你将学会： 理解技能和工具的区别、管理内置技能、通过 openclaw skills 安装技能、创建自定义技能
小白速通： 只看前 3 节（"什么是技能"、"Skills vs Tools"、"内置技能一览"），了解概念就够了。等你想教 AI 新能力时再看后面的章节

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

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

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

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

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

优先选择只处理文本、不需要外部账号授权的技能。例如搜索结果里有 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 需要做这些事：

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

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

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

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

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

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

技能的加载机制

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

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

这意味着：

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

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

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

常用 Skills 命令

内置技能完整分类

办公效率类

技能	功能	使用场景	依赖工具
`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。

前置条件

在 Google Cloud Console 创建 OAuth 2.0 凭证

启用 Gmail API、Calendar API、Drive API

在 OpenClaw 中完成 Google 认证

邮件管理

你可以这样跟 AI 说：

查看我今天收到的邮件

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

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

调用 gmail_read 工具读取邮件内容

整理成摘要返回给你

更多邮件操作示例：

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

日历管理

今天有什么安排？
帮我在下周三下午 2 点创建一个会议，邀请 alice@example.com
取消明天上午的会议
把周五的会议改到下周一

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

Google Drive 操作

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

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 仓库
克隆 username/repo-name 到本地
查看 openclaw/openclaw 仓库的最新动态

Pull Request 操作

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

AI 处理 PR 的流程：

调用 gh_pr_list 获取 PR 列表

调用 gh_pr_diff 查看代码变更

分析代码质量、潜在问题

生成审查意见或执行合并

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 的特殊能力

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

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

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

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

安全限制

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,
      },
    },
  },
}

诊断命令

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 的结构：

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

文件	用途
`AGENTS.md`	Agent 角色和行为定义
`SOUL.md`	AI 人格和沟通风格
`TOOLS.md`	可用工具列表和使用说明

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

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

自定义技能开发完整教程

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

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

直接告诉 AI：

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

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

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

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

第一步：创建技能目录

目录结构：

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

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

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

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

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

创建 tools/reading-stats.ts：

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

创建 examples/example.md：

第五步：测试技能

然后在对话中测试：

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

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

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

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

技能的类型与作用域

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 中声明需要的权限：

权限审批策略

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

权限控制的实际机制：

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

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

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

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

运行时权限检查

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

阻止操作

通知用户

记录安全日志

[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。

技能链式调用

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

条件分支

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

技能市场和社区技能

ClawHub 技能市场

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

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

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

一键安装技能到本地

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

安装社区技能

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

浏览技能市场

发布你的技能

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

发布前的检查清单：

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

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

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

没有硬编码的路径或凭证

管理已安装技能

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

技能调试和测试

调试模式

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

在 ~/.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

技能验证工具

常见调试技巧

技能没有被触发？

检查 triggers 关键词是否匹配

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

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

技能执行出错？

开启 debug 日志级别

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

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

技能指令被 AI 误解？

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

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

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

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

高级技能开发模式

多步骤交互技能

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

带状态的技能

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

技能与 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 提供的工具：

技能模板系统

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

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

在 SKILL.md 中引用模板：

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

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

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

变更内容

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

为什么改

旧的 registerEmbeddedExtensionFactory 有三个问题：

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

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

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

迁移步骤

旧写法（已移除）：

新写法：

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

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

迁移清单

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

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

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

在所有目标运行时上测试

移除 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/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 都可以使用同一个技能。

如何回滚技能更新？

技能开发的最佳实践

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

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

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

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

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

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

下一步

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

06-技能系统指南

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

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

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

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

第三步：在对话里触发它#

你应该记住#

什么是技能？#

Skills vs Tools：概念深入对比#

本质区别#

对比表#

一个具体的例子#

技能的加载机制#

常用 Skills 命令#

内置技能完整分类#

办公效率类#

开发工具类#

笔记知识类#

多媒体类#

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

生活工具类#

系统管理类#

主要技能详细使用教程#

gog — Google Workspace 技能#

前置条件#

邮件管理#

日历管理#

Google Drive 操作#

gog 技能的配置选项#

github — GitHub 技能#

前置条件#

仓库管理#

Pull Request 操作#

Issue 管理#

GitHub Actions#

github 技能的配置选项#

coding-agent — 编程助手技能#

工作原理#

常用场景#

coding-agent 的特殊能力#

安全限制#

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

核心能力#

配置示例#

诊断命令#

obsidian — Obsidian 笔记技能#

前置条件#

笔记管理#

知识库操作#

双向链接#

技能配置文件详解#

全局技能配置#

配置字段说明#

Agent 级别的技能配置#

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

自定义技能开发完整教程#

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

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

第一步：创建技能目录#

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

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

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

第五步：测试技能#

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

技能的类型与作用域#

技能的权限管理#

权限类型#

权限声明#

权限审批策略#

运行时权限检查#

技能组合和工作流编排#

自然语言编排#

定时任务编排#

技能链式调用#

条件分支#

技能市场和社区技能#

ClawHub 技能市场#

安装社区技能#

浏览技能市场#

发布你的技能#

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

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

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

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

第三步：在对话里触发它

你应该记住

什么是技能？

Skills vs Tools：概念深入对比

本质区别

对比表

一个具体的例子

技能的加载机制

常用 Skills 命令

内置技能完整分类

办公效率类

开发工具类

笔记知识类

多媒体类

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

生活工具类

系统管理类

主要技能详细使用教程

gog — Google Workspace 技能

前置条件

邮件管理

日历管理

Google Drive 操作

gog 技能的配置选项

github — GitHub 技能

前置条件

仓库管理

Pull Request 操作

Issue 管理

GitHub Actions

github 技能的配置选项

coding-agent — 编程助手技能

工作原理

常用场景

coding-agent 的特殊能力

安全限制

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

核心能力

配置示例

诊断命令

obsidian — Obsidian 笔记技能

前置条件

笔记管理

知识库操作

双向链接

技能配置文件详解

全局技能配置

配置字段说明

Agent 级别的技能配置

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

自定义技能开发完整教程

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

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

第一步：创建技能目录

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

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

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

第五步：测试技能

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

技能的类型与作用域

技能的权限管理

权限类型

权限声明

权限审批策略

运行时权限检查

技能组合和工作流编排

自然语言编排

定时任务编排

技能链式调用

条件分支

技能市场和社区技能

ClawHub 技能市场

安装社区技能

浏览技能市场

发布你的技能

管理已安装技能