课程信息

• 作者：老金

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

• 公众号：老金带你玩AI

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

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

• 难度等级：🟡 进阶

• 阅读时间：30 分钟

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

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

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

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

我讲技能系统时会把触发条件、输出和复盘放在一起，因为技能不是写出来就算完成。

2026-09-13 当前基线（v2026.9.4）：技能侧有两处影响教学组织方式。v2026.9.1 起共享 Gateway 上支持个人技能库——openclaw skills library 可以把自己的技能放在 workspace 技能集旁边，支持从 ZIP 导入，团队 Gateway 上还能按身份分享或发布；培训环境里可以让学员各自建库，不必都写进共享目录。v2026.9.3 起 Skill Workshop 把技能收在一个按 agent 归属、跨 workspace 保留的集合里，可以对比完整技能说明；草稿已经丢失的技能建议，可以用 Doctor 安全清掉。插件侧 v2026.9.4 把捆绑插件和 ClawHub 插件收进统一的 Plugins 工作区，安装、配置和访问控制都在 Control UI 里做。

2026-06-18 技能口径：v2026.6.5 以后 ClawHub 技能安装加强了 resolved API、pinned GitHub commit 和 policy checks；v2026.6.8 继续补强 managed plugin installs 与依赖安全。课堂练习仍选低风险文本技能，安装外部技能前先看来源、固定版本、权限范围和是否需要账号授权。

技能不是术语表里的概念，它的作用是把一组稳定做法交给 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 分析消息内容
    ↓
把可用技能的名称和 description 提供给模型，模型按任务选择并读取对应 SKILL.md
    ↓
将匹配到的技能指令注入到系统提示词中
    ↓
AI 根据技能指令 + 工具列表来执行任务

这意味着：

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

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

• 在 YAML frontmatter 的 description 中写清适用场景；正文补步骤和边界。不要把 triggers 当成 OpenClaw 的强制匹配字段。

常用 Skills 命令

# 搜索技能
openclaw skills search "gog"

# 安装技能
openclaw skills install gog

# 更新技能
openclaw skills update --all

当前工具入口：Tool Search 与 Code Mode

使用 v2026.9.8 时，“已授权的工具”不一定把全部参数说明直接放在模型面前。OpenClaw 的内嵌运行时和 Copilot 在未配置 tools.toolSearch、且 Code Mode 没接管时，默认按需发现工具。先发现，再查看输入说明，最后调用：对应 tool_search、tool_describe、tool_call。这是模型侧工具入口，不是三个 shell 命令，也不能把技能名直接当成 tool ID。

先在当前会话的工具列表确认目标工具已授权，再在聊天中做一个只读练习：

查找这个会话允许使用的文件读取工具，先查看输入说明，再只读取工作区里我提供的 README.md。若工具不可用，请说明缺的是授权、安装还是运行时，不要换成其他方式绕过限制。

检查活动记录：目标工具应来自当前授权目录，路径应是你提供的真实文件；发现工具不等于获得权限。v2026.9.7 已删除旧的 JavaScript 入口 tool_search_code。手动替换程序后遇到旧设置阻止启动，先按维护流程执行 openclaw doctor --fix，再启动核对；需要 JavaScript 编排时改用 Code Mode，不能继续照抄退休工具名。

Code Mode 让模型写一小段 JavaScript，查找、组合工具调用，并等待结果。它不是 Bash，也不同于 Codex 原生的同名功能。OpenClaw 的 exec 接收 { title, code }；其中 code 是 JavaScript，不能塞入 ls、npm 这样的 shell 文本。默认 Node 执行器本身不是安全隔离；实际工具、文件和命令权限仍要按第 10 章配置。

当前版本在 tools.codeMode 未设置时，只对目录中标记为适合的模型自动启用；显式 false 或没有 enabled 的对象保持关闭，Agent/模型级覆盖仍优先。想先保留直接工具说明，合并下面片段并检查 Agent/模型级是否另有覆盖，然后新开对话验证：

{
  tools: {
    toolSearch: false,
    codeMode: false,
  },
}

要尝试 Code Mode，可在 Control UI 的 Code Mode 设置中明确开启，用同一份低风险文件做练习；在活动记录确认实际执行工具与输出，不把缩略预览当成完整数据。点击当前对话 Stop 可以停止本次运行，再关闭设置并新开会话恢复对照。Codex 原生工具入口由它自己的运行时控制，上面两个 OpenClaw 设置不能替它关闭原生 Code Mode 或 Tool Search。详见Tool Search与Code Mode。固定 v2026.9.4 环境按本机工具目录核对，不能倒用 9.7 已迁移后的接口名称。

v2026.9.7 的任务接口退役

旧的 Tasks / TaskFlow 面板、命令和 API 已移除，Workboard 与会话 transcript 仍保留。观察委派工作用 subagent 控制；后台命令用 process；定时任务看 Cron run history；需要持久流水线时查 Lobster。它们不是一个能无缝替换所有旧 TaskFlow 的接口。插件作者要按移除接口迁移说明改 SDK，TaskFlow Webhooks 没有等价 HTTP 替代。手动替包后在启动前运行 Doctor 并处理报告的配置冲突；不要把新 Swarm 或新插件接到已退役的 Tasks API 上。

内置技能完整分类

办公效率类

技能

功能

使用场景

依赖工具

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

自行提取视频帧

视频帧

v2026.9.4 已移除内置 video-frames；可以直接使用 ffmpeg，或审查后另装技能

ffmpeg

songsee

听歌识曲

识别正在播放的音乐

音频采集

多媒体生成类（v2026.4.5 补齐）

v2026.4.5 新增了 video_generate 和 music_generate 两个内置工具；image_generate 更早，v2026.3.22 起就已定为核心图片生成工具。三者都不需要额外安装：

工具

功能

支持的提供商

运行模式

video_generate

文本/图片/视频 → 视频

xAI (Grok)、Alibaba Wan、Runway、Google Veo、BytePlus Seedance、Qwen（以安装版本和已配置提供商为准）

generate / imageToVideo / videoToVideo

music_generate

文本 → 音乐/音频

Google Lyria 3、MiniMax、ComfyUI 工作流

generate（异步任务）

image_generate

文本 → 图片

多提供商 + ComfyUI 工作流

generate

媒体生成是否可用，要分别检查对应提供商的插件、凭据、模型和工具权限。任务被接受与生成成功是两回事；按工具返回的状态查看结果。等待超时也不能证明远端任务已取消或停止计费。

升级到 v2026.9.7 及以后时，原来保存的 sora-2 / sora-2-pro 会继续失败，需要你在视频设置中明确选择仍受支持的提供商并配置其凭据；不能只换聊天模型来修复。生成图片同样要核对路线：已有 ChatGPT 登录时，直接走 OpenAI API 的 GPT Image 2.5 仍需明确配置 API key；通过 fal 使用时则用 fal 的凭据和计费。先确认路线、参考图片和输出数量，再决定是否发起实际生成。

快速配置示例：

{
  "agents": {
    "defaults": {
      "mediaModels": {
        "video": {
          "primary": "google/veo-3.1-fast-generate-preview",
          "fallbacks": [
            "runway/gen4.5"
          ]
        },
        "music": {
          "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 认证

# 先按该技能说明安装 gog，并使用自己的 OAuth client 文件
gog auth credentials /path/to/client_secret.json
gog auth add [email protected] --services gmail,calendar,drive,contacts,docs,sheets
gog auth list

Google 模型认证和 Google Workspace 授权不是同一件事。models auth --provider google 不会为 gog 授权 Gmail 或 Calendar。凭据由 gog 管理；具体服务权限按实际需求选择。

邮件管理

你可以这样跟 AI 说：

查看我今天收到的邮件

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

1. 按 gog 技能说明执行 gog gmail 的搜索或读取命令

2. 只读取任务所需邮件，整理摘要并说明来源

3. 回复或修改邮件前核对用户授权

更多邮件操作示例：

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

日历管理

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

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

Google Drive 操作

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

gog 技能使用的配置来源

gog 技能依赖 gog CLI 和 Google OAuth 授权；账户与服务范围按 gog 的认证流程配置。skills.entries.gog.config 虽然可以存自定义数据，官方技能并不读取 defaultCalendar、emailSignature、maxSearchResults 或 language 来改变行为。

例如可通过 GOG_ACCOUNT 选择默认账户，查询数量和日历范围则放在实际 gog 命令参数中。先让助手读取当前 gog 的 SKILL.md，并确认 gog auth list 展示了所需服务。官方说明支持 Docs 的导出、查看与复制；原地修改 Google Docs 需要额外的 Docs API 客户端，不能仅凭装了 gog 就承诺完成。发送邮件、邀请或共享文件仍须有明确授权。

github — GitHub 技能

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

前置条件

# GitHub 技能使用 gh CLI 的认证，与 models auth 分开
gh auth login
gh auth status

仓库管理

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

Pull Request 操作

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

AI 处理 PR 的流程：

1. 通过 exec 运行 gh pr list --repo <owner/repo> 获取 PR 列表

2. 用 gh pr diff <number> --repo <owner/repo> 查看代码变更

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

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

Issue 管理

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

GitHub Actions

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

github 技能使用的配置来源

官方 github 技能使用 gh CLI。认证由 gh auth login / gh auth status 管理；目标仓库在请求或命令中明确指定，例如 gh pr list --repo openclaw/openclaw。官方技能不读取 skills.entries.github.config 中的 defaultOrg、defaultRepo、autoLabel 或 prTemplate。需要团队默认仓库与 PR 模板时，把规则写进自己的技能或仓库模板，并明确让助手使用；自动加标签等写操作还需要对应权限与授权。

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 是调用 Claude Code、Codex、OpenCode 等外部编程 CLI 的技能，需显式启用，并安装和认证所选 CLI。OpenClaw 的 sandbox 默认关闭，外部 CLI 的权限也要单独核对；不能仅凭技能名认定命令已被隔离或逐条询问。

{
  skills: { entries: { "coding-agent": { enabled: true } } },
}

skills.entries.coding-agent.config.allowedCommands 和 autoApprove 不构成通用执行策略。工作目录在实际任务和 CLI 启动参数中指定；文件、命令和网络权限分别按 OpenClaw 工具策略、sandbox 和外部 CLI 的配置落实。

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

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

核心能力

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

• 操作超时 — 按实际 browser 工具支持的参数设置；v2026.9.4 的 browser 配置没有 actionTimeoutMs 字段。

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

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

配置示例

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

诊断命令

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

浏览器实际跑在哪台机器也要先确认。v2026.9.5 起自动路由优先用运行 Gateway 的电脑上所选浏览器；显式目标或 gateway.nodes.browser.node 固定节点优先，只有 Gateway 无浏览器能力且只有一个合格节点时才自动转给它。失败不会在另一台机器重放。先核对目标和登录会话，再让 Agent 登录或提交表单。

想连接已有 Chrome 时，v2026.9.6 起先运行 openclaw browser extension setup --action inspect，按检查结果完成扩展安装与 Chrome 批准，再用同一路径的 verify 动作确认认证连接。通过 SSH 运行检查的是远程主机；远程 Gateway 要操作你电脑上的 Chrome，还需要该电脑的 browser node。安装成功不等于浏览器已连接。Windows 还需兼容的独立 BrowserBootstrap，具体条件见官方扩展设置。

网页搜索是独立路线。进入 Settings → Search，先查看目标 Agent 和模型会走哪个提供商；管理员才修改托管提供商或发起真实测试，真实测试按账号正常计费。native/external 路线的 Test in chat 只打开未发送草稿，仍需你发送才查询。已填 key 不代表路线正常；Parallel Search Free 要明确选择，不能把检测到付费 Parallel key 当免费。Gemini 搜索默认3.6 Flash按查询计费，也不会替换聊天模型。详见搜索设置。

obsidian — Obsidian 笔记技能

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

前置条件

官方技能依赖 Obsidian 1.12.7 或更新版本中的官方 obsidian CLI：在 Obsidian 设置的 General 中启用命令行接口，保证可在 PATH 中找到该命令，并保持桌面应用运行。

obsidian version
obsidian help

多 Vault 时按 CLI 的 vault 参数选择目标，并在请求中明确 Vault 名称。skills.entries.obsidian.config 的 vaultPath、dailyNotesFolder、templatesFolder 并不会被官方技能读取；日记与模板仍按实际 Vault 和 Obsidian 设置处理。完成这些前置条件后，才测试读取一篇已有笔记和在获授权的位置写入一篇测试笔记。

笔记管理

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

知识库操作

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

双向链接

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

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

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

技能配置文件详解

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

全局技能配置

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

{
  "skills": {
    // 只允许所列 bundled 技能；未设置时不通过此列表筛选
    "allowBundled": ["weather", "summarize", "github"],
    // workspace/skills 会自动扫描；额外目录填目录路径，不填通配符
    "load": { "extraDirs": ["~/my-extra-skills"], "watch": true },
    // 各技能的独立配置
    "entries": {
      "gog": {
        "enabled": true,
        "config": {
          // 此处只放所用技能明确读取的自定义字段；gog 的时区按 gog CLI 说明配置
        }
      },
      "github": {
        "enabled": true,
        "config": {
          // GitHub 技能使用 gh CLI；组织或仓库在实际 gh 命令中指定
        }
      },
      "voice-call": {
        "enabled": false
      }
    }
  }
}

配置字段说明

字段

类型

说明

allowBundled

string[]

可选的内置技能允许列表；省略时不额外限制，只影响 bundled skills

load

object

extraDirs 指定额外目录，watch 控制变更监听

install

object

从 ClawHub 安装技能的配置

limits

object

限制技能发现数量、文件大小和提示预算；不控制工具执行权限

workshop

object

Skill Workshop 的生成与审核设置

entries

object

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

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

Agent 级别的技能配置

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

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

  // 技能的详细配置放在顶层 skills.entries 中
  "skills": {
    "entries": {
      "coding-agent": {
        "config": {
          // 官方技能不读取workDir/autoApprove；工作目录与审批在实际CLI和tools策略中指定
        },
      },
      "gog": {
        "config": {
          // 此处只放所用技能明确读取的自定义字段；gog 的时区按 gog CLI 说明配置,
        },
      },
    },
  },
}

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

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

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

SKILL.md 的结构：

---
name: my-skill
description: 写清这项技能适合处理什么任务。
---

# 技能名称

技能的描述和用途说明。

## 触发条件

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

## 执行步骤

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

## 依赖工具

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

## 注意事项

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

技能会使用当前会话允许读取的工作区指令，但普通会话与子 Agent 的注入范围不同，不能把所有工作区文件都当成技能必然拥有的上下文。

文件

用途

AGENTS.md

Agent 工作规则，以及需要长期保留的工具使用笔记

SOUL.md

AI 人格和沟通风格；是否注入取决于会话和运行时

TOOLS.md

本教程 v2026.9.4 参考版本使用的旧工具笔记文件

使用 v2026.9.7 或更新版本时，不要继续把新规则只写进 TOOLS.md。 官方发布记录已确认它退役，Agent 启动时不再读取。升级前保存原文件，按维护流程运行 openclaw doctor --fix，把工具笔记迁入 AGENTS.md，然后检查合并结果。如果 Doctor 无法安全保留 POSIX 权限，它会告警并留下两份原文件；先修正权限或人工合并，再验证下一次对话能读取新规则。迁移工作区说明不等于授予工具权限，实际权限仍由配置和审批控制。

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

自定义技能开发完整教程

这是 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 会读取这个文件来理解如何执行任务。

---
name: reading-notes
description: 记录、整理或搜索读书笔记时使用，保存书名、作者、日期和用户提供的内容。
---

# 读书笔记管理

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

## 触发条件

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

## 依赖工具

- read：读取笔记和索引
- write / edit：创建或更新笔记
- exec：确实需要批量列出文件时使用；要先核对工具策略

## 创建新笔记

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. 返回匹配的笔记列表和摘要

第三步：添加辅助脚本或工具（可选）

仅把 TypeScript 文件放进 Skill 的 tools/ 目录，不会自动注册成模型工具。读书统计先使用已有的 read 工具读取笔记并汇总即可。需要可重复的计算时，可以在 scripts/ 放一个经过审查的脚本，并在技能中说明如何执行；执行仍受 exec 和沙箱策略限制。

需要真正增加模型工具时，按 官方工具插件开发说明注册插件工具，或连接已有 MCP server。不要照抄未经验证的 @openclaw/sdk Tool 接口。

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

创建 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

然后在对话中测试：

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

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

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

# 先用 skills info 确认源目录；bundled 技能通常不在 workspace/skills
openclaw skills info obsidian
# 将输出中的真实技能目录替换到下一行；不要直接修改安装目录
cp -R <actual-obsidian-skill-directory> ~/.openclaw/workspace/skills/my-notes

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

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

技能的类型与作用域

OpenClaw 的技能分为三种类型：

类型

说明

来源

bundled（内置）

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

安装目录

managed（托管）

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

ClawHub

workspace（工作区）

用户自己创建的技能

~/.openclaw/workspace/skills/

Workspace 技能位于当前 Agent 的 <workspace>/skills/<skill-name>/SKILL.md；共享 managed 技能通常位于 ~/.openclaw/skills/，额外目录由 skills.load.extraDirs 配置。

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

技能的权限管理

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

权限类型

权限

说明

风险等级

file_read

读取文件

低

file_write

写入文件

中

file_delete

删除文件

高

shell_exec

执行 Shell 命令

高

network

网络访问

中

auth_access

访问认证凭证

高

memory_write

写入记忆文件

低

memory_read

读取记忆文件

低

权限声明

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

## 操作范围说明

这个任务需要读取和写入笔记。这里是任务说明，实际是否允许由 Agent 的 tools 策略和 sandbox 配置决定。

权限审批策略

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

权限控制的实际机制：

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

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

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

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

# 安全审计
openclaw security audit

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

运行时权限检查

SKILL.md 里的“所需权限”是给模型和读者看的说明，不会生成运行时权限。真正的授权由工具 allow/deny、exec 执行审批和 sandbox 设置控制。技能使用的工具会经过同样的策略检查；不存在“未在 Skill 中声明 file_write 就自动拦截”的机制。

只读技能应配合实际工具限制，例如在该 Agent 的 tools.deny 中禁止 write、edit 和 exec，再核查其他外部写入工具。技能正文中的禁止事项可以辅助模型判断，但不能代替这些配置。

技能组合和工作流编排

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

自然语言编排

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

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

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

定时任务编排

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

// ~/.openclaw/openclaw.json
{
  "cron": {
    // 启用定时任务
    "enabled": true,
  },
}

注意：cron 是一个配置对象（包含 enabled、sessionRetention、failureAlert 等字段），不是任务数组。具体的定时任务通过 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 万次下载。你可以在上面：

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

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

• 一键安装技能到本地

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

安装社区技能

openclaw skills install 默认写到当前 Agent 的 <workspace>/skills/，属于 workspace 路径；需要共享 managed 根目录时显式加 --global，写到当前状态目录的 skills/。两个路径的可见范围和覆盖优先级不同。

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

# 从 GitHub 安装
openclaw skills install git:username/skill-name@<reviewed-ref>

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

# 安装特定版本
openclaw skills install skill-name --version 1.2.0

浏览技能市场

# 搜索技能
openclaw skills search "jira"

# 按分类浏览
openclaw skills search "development"
openclaw skills search "office"

# 查看热门技能
openclaw skills search --limit 10

发布你的技能

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

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

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

发布前的检查清单：

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

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

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

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

管理已安装技能

# 更新技能
openclaw skills update --all

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

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

技能调试和测试

调试模式

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

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

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

开启后，查看模型是否读取了预期的 SKILL.md，以及后续工具调用和报错。日志内容随运行时和版本变化；OpenClaw 不保证输出固定的 [SKILL] Matching triggers 或 Matched skill 行，也不会按 frontmatter 的 triggers 强制匹配关键词。

技能验证工具

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

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

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

常见调试技巧

技能没有被触发？

1. 检查 frontmatter 的 name/description、技能就绪状态和当前 Agent 的技能可见范围，再在新对话中测试。

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

3. 检查多个技能的 description 是否重叠；技能目录优先级解决同名覆盖，不是关键词抢占。

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

技能执行出错？

1. 开启 debug 日志级别

2. 检查实际 tools 策略、exec 审批与 sandbox；Skill 正文列权限不会授权

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

技能指令被 AI 误解？

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

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

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

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

高级技能开发模式

多步骤交互技能

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

---
name: travel-planner
description: 用户要求规划旅行时使用，先确认日期、预算、目的地和偏好。
---

# 旅行规划助手

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

## 信息收集阶段

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

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

## 规划阶段

收集完信息后：

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

## 输出格式

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

带状态的技能

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

---
name: habit-tracker
description: 用户要求打卡、记录习惯或统计进展时使用。
---

# 习惯追踪器

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

## 状态文件

使用 `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 服务器集成

需要外部工具时，先选择真实存在且已审查的 MCP server。v2026.9.4 已支持内建 MCP client，配置位于 mcp.servers：

{
  mcp: {
    servers: {
      "team-docs": {
        url: "https://mcp.example.com/mcp",
        transport: "streamable-http",
        enabled: true,
        toolFilter: { include: ["search", "read_*"] },
      },
    },
  },
}

这是结构示例。把 URL 和工具名替换成你的真实服务；不要直接请求 example.com。连接后用 openclaw mcp doctor team-docs --probe 检查实际能力，再检查工具策略。上面的过滤只暴露所列工具，不自动为 Jira、Gmail 或其他服务完成授权。

技能模板系统

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

~/.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 与 Skill Workshop 兼容补充（v2026.6.8）

v2026.6.8 之后，排查技能和插件要同时看 Plugin SDK、Skill Workshop 和运行时索引。v2026.5.27 的 plugin compatibility diagnostics、approval action metadata、display metadata、tool-search catalog 和 metadata fingerprint 仍然有用；v2026.6.x 又补充了 Skill Workshop 的 proposal / review / rollback 流程、ClawHub pinned commit / policy checks、插件安装索引 SQLite 持久化、managed plugin installs、disabled skill stale snapshot 处理和更清楚的 loader failure 提示。排查“技能/插件没被搜到”时，先看 compatibility diagnostics、metadata cache、Skill Workshop 状态和 disabled snapshot，而不是立刻怀疑触发词写错。

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

• 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 驱动的模型行减少提供商依赖激活

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

工坊：把一个重复工作写成可维护技能

很多人第一次写 Skill，会从“我想让 AI 更懂我”开始。这个想法太大，最后容易写成一段很长的系统提示词。更稳的做法是从一个重复动作开始：你已经做过三次、步骤相对固定、结果格式也相对固定的事情，就适合做成 Skill。

下面用“消息分拣摘要”做一个完整练习。假设你经常从 Telegram、Discord 或 WebChat 收到一批用户反馈，希望 OpenClaw 帮你按 bug、需求、疑问、噪音分组，并把可跟进项写成 Markdown 文件。

先不要急着写 SKILL.md。先把这个工作拆成四句话：

问题

本例答案

什么时候触发？

用户说“整理反馈”“分拣消息”“生成反馈摘要”

输入是什么？

一段聊天记录、若干消息链接，或用户直接粘贴的文本

输出是什么？

一个 Markdown 摘要，包含分类、优先级、跟进动作

不做什么？

不自动回复用户，不直接创建外部工单，不写入敏感信息

创建目录：

mkdir -p ~/.openclaw/workspace/skills/feedback-triage/examples

写入技能定义：

---
name: feedback-triage
description: 用户要求整理反馈、分拣消息或生成反馈摘要时使用。
---

# feedback-triage

当用户要求“整理反馈”“分拣消息”“生成反馈摘要”“把这些消息分类”时激活。

## 工作流程

1. 先确认用户提供了消息内容；如果没有，询问消息来源或让用户粘贴文本。
2. 逐条阅读消息，保留原始含义，不替用户扩写投诉。
3. 按 bug、需求、疑问、表扬、噪音分类。
4. 对 bug 和需求提取可跟进动作。
5. 如果消息里出现 token、手机号、邮箱、订单号等敏感信息，输出时做脱敏。
6. 生成 Markdown 摘要，保存到 `workspace/feedback/YYYY-MM-DD-feedback.md`。

## 输出格式

- 今日概览
- 分类列表
- 需要跟进的事项
- 需要人工确认的信息
- 原始消息引用位置

## 边界

- 不自动向消息平台发送回复。
- 不创建 GitHub Issue 或外部工单，除非用户再次明确要求。
- 不保存未脱敏的敏感信息。

再补一个例子，让模型知道你要的颗粒度：

# examples/telegram-feedback.md

用户输入：

请整理这些反馈：
- 登录后一直转圈
- 能不能支持 Slack？
- 我觉得新版本速度快了
- sk-proj-xxxx 这个 key 是不是错了？

期望输出：

## 今日概览

共 4 条反馈，其中 bug 1 条、需求 1 条、表扬 1 条、敏感信息 1 条。

## 需要跟进的事项

1. 登录后一直转圈
   - 类型：bug
   - 需要补充：系统、浏览器、OpenClaw 版本、日志片段

2. 支持 Slack
   - 类型：需求
   - 需要确认：是消息接入、通知推送，还是团队协作频道

## 需要人工确认的信息

- 第 4 条包含疑似 API Key，输出中已脱敏，不写入长期记忆。

检查技能是否被 OpenClaw 识别：

openclaw skills list
openclaw skills check

然后在 WebChat 或 CLI 里发一句真实请求：

帮我整理这些反馈：登录失败、希望支持 Slack、文档里 Docker 部署看不懂。

如果输出太散，先改 输出格式、步骤和示例。description 帮模型选择技能，正文说明如何执行；它不是引擎逐词匹配的触发规则。测试时明确引用 $feedback-triage，并观察模型是否读取了 SKILL.md，再检查实际文件产物。

技能生命周期：从临时提示词到团队资产

一个好技能通常不是一次写成的。它会经历几个阶段：

阶段

典型形态

适合做什么

临时提示词

用户在对话里写一段步骤

验证这个流程是否真的重复出现

本地 Skill

workspace/skills/<name>/SKILL.md

固化个人工作习惯

Agent 绑定 Skill

在某个 Agent 配置中启用

让客服、开发、运维等工作线各自拥有专属能力

Managed Skill

通过市场或团队统一安装

多个 Agent / 多台机器复用同一版本

归档 Skill

禁用但保留历史

流程过时、外部工具停用、权限变更

判断一个临时提示词是否值得升级成 Skill，可以看三个信号：

1. 你已经复制粘贴同一段提示词超过三次。

2. 输出格式开始影响后续工作，比如会被提交到仓库、发到群里或进入周报。

3. 流程里出现了工具调用、文件写入、消息读取或敏感信息处理。

升级时不要把所有细节塞进一章。建议把 Skill 拆成四个小文件：

feedback-triage/
├── SKILL.md              # 触发条件、流程、边界
├── examples/
│   ├── short-feedback.md
│   └── noisy-thread.md
├── templates/
│   └── feedback-report.md
└── README.md             # 给人看的维护说明

SKILL.md 面向 Agent，应该短、清楚、可执行。README.md 面向人，记录这个技能为什么存在、适合什么场景、维护时要注意什么。两者不要混在一起，否则 Skill 会越来越像项目文档，模型真正需要执行的步骤反而被淹没。

触发失败排查：为什么技能没有被加载

技能没有被使用时，先查 name/description、技能可见范围、同名目录覆盖和依赖。不同名字的技能不会按关键词优先级抢占；模型会按描述与任务选择，显式 $skill-name 可以帮助验证加载。

先看列表：

openclaw skills list

如果技能不在列表里，检查目录名和文件名：

~/.openclaw/workspace/skills/feedback-triage/SKILL.md

如果技能在列表里，但没有响应，查看详情：

openclaw skills info feedback-triage

重点看三件事：

现象

可能原因

调整方式

没有被选中

description 没写清任务，或技能不可见

先检查 skills info，再明确引用 $feedback-triage

被用于不合适的任务

description 范围过宽

说明适用任务和边界，避免只写“总结”“处理”

触发了但做错

流程不清楚

把步骤拆成编号动作

做到一半失败

缺工具或缺权限

用 openclaw skills check 看依赖

另一个技能抢先响应

技能边界重叠

调整名称、触发词和 Agent 作用域

开启详细日志后，再复现一次：

openclaw gateway --verbose

先确认技能出现在当前 Agent 的可用目录中，再看模型是否读取其正文。没读取时检查 description 和技能可见范围；读取后调用失败，检查依赖、工具策略及具体报错；调用成功但结果不对，再检查步骤和示例。不要用虚构的 Matching/Matched 日志判断触发词。

权限边界：让技能刚好够用

Skill 最容易被写坏的地方，是一开始就给太多能力。一个整理反馈的技能，不需要发布消息；一个读书笔记技能，不需要访问 GitHub；一个截图技能，不需要读取整个 home 目录。

给技能设计权限时，按这个顺序想：

1. 这个技能需要读哪些输入？

2. 它需要写到哪里？

3. 它会不会触达外部平台？

4. 它有没有机会看到 token、私聊、订单、客户资料？

5. 如果模型误解了用户意图，最坏会发生什么？

以 feedback-triage 为例，更稳的边界是：

## 边界

- 可以读取用户提供的消息文本。
- 可以写入 `workspace/feedback/`。
- 不主动读取私聊历史，除非用户提供消息内容或链接。
- 不向 Telegram、Discord、Slack 自动发送回复。
- 不创建外部 issue，不修改项目代码。
- 发现敏感信息时，只输出脱敏摘要。

如果某个 Skill 需要调用外部工具，把外部动作拆成“生成草稿”和“执行提交”两步。第一步让 Agent 起草，第二步由用户确认后再调用工具。这样既保留效率，也避免技能在错误上下文里直接把结果发出去。

更新事故恢复：技能变差时怎么退回来

技能不是越改越好。有时你加了很多规则，模型反而变得犹豫；有时你把触发词写宽，结果普通对话也被技能接管。遇到这种情况，先止损，再慢慢查。

临时禁用：

{
  "skills": {
    "entries": {
      "feedback-triage": {
        "enabled": false,
      },
    },
  },
}

如果是市场安装的版本，可以搜索并安装旧版本：

openclaw skills search "feedback-triage"
openclaw skills install feedback-triage --version 1.0.0

如果是本地 Skill，最简单的保护方式是把技能目录纳入 Git：

cd ~/.openclaw/workspace/skills
git init
git add feedback-triage
git commit -m "skill: feedback triage baseline"

以后每次大改之前提交一次。出问题时，你不用凭感觉回忆改了什么，可以直接对比：

git diff HEAD~1 -- feedback-triage/SKILL.md

恢复后，再用三条真实消息重跑一次：一条正常触发、一条边界情况、一条不应该触发的普通对话。你要看的不是"模型是否听话"，而是这个技能有没有把任务范围收住。

三个可直接复用的技能蓝图

下面三个蓝图都适合照着改成本地 Skill。它们覆盖了 OpenClaw 里最常见的三类使用：整理信息、生成工作产物、保护边界。

蓝图一：Issue 分拣助手

适合开源项目、内部工具、客服反馈。

---
name: issue-triage
description: 用户要求把提供的 issue 和 bug 反馈分类并生成摘要时使用。
---

# issue-triage

当用户要求“整理 issue”“分拣反馈”“把这些 bug 分类”时激活。

## 工作流程

1. 读取用户提供的 issue 标题、正文和评论。
2. 判断类型：bug、feature、question、docs、duplicate、invalid。
3. 提取复现步骤、期望行为、实际行为、环境信息。
4. 如果信息不足，列出需要补充的问题。
5. 生成 Markdown 摘要，不直接关闭 issue。

## 输出

- 分类
- 严重程度
- 缺失信息
- 建议下一步

蓝图二：版本发布笔记助手

适合把 commit、PR、手写更新记录整理成 changelog。

---
name: release-notes
description: 用户要求把已提供的变更列表整理为发布说明时使用。
---

# release-notes

当用户要求“生成发布说明”“整理 changelog”“总结本周更新”时激活。

## 工作流程

1. 收集用户提供的变更列表。
2. 按 Added、Changed、Fixed、Security 分类。
3. 把内部实现细节改写成用户能理解的语言。
4. 保留破坏性变更和迁移提醒。
5. 输出 Markdown，不自动发布。

## 边界

- 不编造版本号。
- 不声称某功能已经发布，除非输入中明确出现。
- 不删除安全提醒。

蓝图三：会议纪要整理助手

适合 Meeting Notes / transcript 场景，也适合手动粘贴会议记录。

---
name: meeting-summary
description: 用户提供会议记录并要求整理纪要、决定或待办时使用。
---

# meeting-summary

当用户提供会议记录并要求“整理纪要”“提取待办”“总结会议”时激活。

## 工作流程

1. 识别会议主题、时间、参与方。
2. 提取已达成的决定。
3. 提取待办事项，保留负责人原文；如果负责人不明确，标记为“待确认”。
4. 提取风险和未解决问题。
5. 输出一份可复制到文档中的 Markdown。

## 边界

- 不替参会人补承诺。
- 不把未确认讨论写成最终决定。
- 不输出完整逐字稿，除非用户要求。

这三个蓝图都故意把“外部动作”留在用户确认之后。Skill 的第一价值是把重复判断变成稳定流程，不是把所有事情都自动化。

查找技能，再决定是否安装

从 v2026.9.4 起，Control UI 的 Plugins → Skills 可以在一个搜索框里查找已安装技能和 ClawHub 技能。先选要使用技能的 Agent，再输入用途关键词，查看卡片的来源、就绪状态和缺少的设置。已安装但未就绪的技能应先处理它列出的依赖或凭据；市场结果要先读技能说明和脚本，再按界面安装，回来确认该 Agent 能看到它。没有搜索词时显示的热门技能也不代表已经安装。

Agent 的 skills_search 是另一条路径：它只搜索当前可用的已安装技能，不会替你搜索 ClawHub、安装市场技能或授予工具权限。知道技能名称时，可以直接要求 Agent 读取相应技能说明后执行。详见技能发现说明。

Skill Workshop 和个人技能库：什么时候用哪条路径

文件型 Skill 适合你维护自己的 workspace。Workshop 用于把重复工作中的经验整理成可复用技能。想从已有工作中总结一次，进入 Plugins → Workshop → Learn from past conversations，选择目标 Agent 和模式：Propose 留下待审提案，Auto 允许直接应用改进。教学时先用 Propose，确认它选取的会话、改动对象和脚本范围，再决定是否应用。

这个入口会打开普通可见会话，使用该 Agent 的模型、已允许的工具和有权读取的历史；你可以在会话里追加要求、纠正或停止。它按正常模型路线计费，停止也不会撤销已经完成的编辑。手动学习一次不会开启自动自学习；想只总结当前工作，可在当前会话输入 /learn。这条路径不会自动应用结果，即使全局设为 Auto 也一样；先查看它对已有技能或提案的修订，再决定是否应用。旧的未完成批量扫描不能继续接着扫，已有技能和提案仍保留。

自动自学习是单独的设置。现行默认 skills.workshop.autonomous.mode 为 auto，可以在较长的一轮工作结束并空闲后复盘，也会做每周维护；它可能使用会话模型上下文并产生额外模型请求。希望先审后改时，将下面片段合并到配置；受管只读配置请按02章交给配置维护方修改：

{
  skills: {
    workshop: {
      autonomous: { mode: "propose" },
      approvalPolicy: "pending",
    },
  },
}

propose 把自动改进留为提案，approvalPolicy: "pending" 则要求批准 Agent 发起的 apply/reject/quarantine；两项作用不同。把 mode 改为 off 可关闭自主捕获。Incognito 回合不参与自动复盘；其他运行时是否支持复盘，还取决于它能否报告实际模型和 Workshop 工具。Auto 的后台直接编辑没有整个技能集的自动回滚，已有编辑遇到失败也可能保留，启用前保存需要的技能备份。详见自学习模式与批准设置和自学习的费用与隐私。

先看提案和差异，再决定是否应用：

openclaw skills workshop list --agent main
openclaw skills workshop inspect <proposal-id> --agent main

确认提案确实有用、脚本和权限范围也合适后，再运行 openclaw skills workshop apply <proposal-id> --agent main。它写入该 Agent 自己的 workshop-skills，不会自动发布到其他 Agent；拒绝或隔离提案的命令见 Workshop 文档。

共享 Gateway 上，有独立登录身份的操作者可以在 Plugins → Skills 创建或导入个人技能，再选择是否 Share with team。共享 token 不等于个人身份。库保存完整的不可变修订；旧会话仍保留选中的旧修订，需要显式 attach/refresh 才在下一轮使用新版。分享、转移所有权和工具权限是不同的事，库所有者不能借此获得宿主机或凭据访问。不要直接编辑 skill-library/ 内部文件。详见 个人技能库。

常见问题

Q1：技能安装失败怎么办？

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

# 带详细输出重试安装
openclaw skills info skill-name
openclaw skills check

Q2：如何禁用某个技能？

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

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

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

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

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

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

Q4：技能太多会影响性能吗？

可用技能的名称、description 等目录信息会占用上下文；通常由模型按需要读取具体 SKILL.md，正文不会全部预先展开。技能越多，目录本身也越大，应把 description 写清楚，并限制当前 Agent 可见的技能。

建议：

• 给每个技能写准确的 description，明确什么任务适合使用

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

• 定期清理不用的技能

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

技能默认从各 Agent 的 workspace 和共享根目录加载。把技能放进 shared managed 根目录可以共享技能说明和脚本，但不会自动共享业务数据、外部账号或文件权限；这些仍需按实际工具和运行环境单独配置。

Q6：如何回滚技能更新？

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

# 安装特定版本（回滚）
openclaw skills install skill-name --version 1.0.0

Q7：技能开发的最佳实践是什么？

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

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

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

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

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

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

下一步

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

---