06-技能系统指南

06 技能系统指南 06 技能系统指南 Modified June 10 Code block Plain Text {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 总结。 ⠀ 推荐使用边界： ⠀ ⠀ 如果当前 CLI 暴露了 meeting notes 相关命令，先用只读方式查看帮助和可用 source： ⠀ Code block Plain Text 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. 耦合实现细节而非稳定契约 ⠀ 迁移步骤 ⠀ 旧写法（已移除）： ⠀ Code block Plain Text // 不再支持 api.registerEmbeddedExtensionFactory(async (event) = { return compactToolResult(event); }); ⠀ 新写法： ⠀ Code block Plain Text api.registerAgentToolResultMiddleware(async (event) = { return compactToolResult(event); }, { runtimes: ["pi", "codex"], }); ⠀ 同时更新插件 manifest，声明 contracts： ⠀ Code block Plain Text { "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 驱动的模型行减少提供商依赖激活 ⠀ 这些改进是自动生效的，不需要配置变更。 ⠀ 常见问题 ⠀ 技能安装失败怎么办？ ⠀ Code block Plain Text 检查技能就绪状态 openclaw skills check skill name 带详细输出重试安装 openclaw skills install skill name verbose ⠀ 如何禁用某个技能？ ⠀ 在 /.openclaw/openclaw.json 的 skills.entries 中将其 enabled 设为 false： ⠀ Code block Plain Text { "skills": { "entries": { "voice call": { "enabled": false, }, "camsnap": { "enabled": false, }, }, }, } ⠀ 自定义技能和内置技能冲突怎么办？ ⠀ 工作空间技能优先级最高。如果你在 /.openclaw/workspace/skills/ 下创建了一个跟内置技能同名的技能，你的版本会覆盖内置版本。 ⠀ 如果想恢复内置版本，删除工作空间中的同名技能即可。 ⠀ ⏭️ 小白可跳过 — 这部分面向需要优化技能性能的开发者 ⠀ 技能太多会影响性能吗？ ⠀ 不会。OpenClaw 只会加载跟当前消息相关的技能，不是把所有技能都塞进上下文。但如果你的 triggers 设置得太宽泛，可能会导致不相关的技能被误触发，浪费 token。 ⠀ 建议： • 给每个技能设置精确的 triggers • 在 Agent 配置中用 skills 字符串数组只加载需要的技能 • 定期清理不用的技能 ⠀ 技能可以访问其他 Agent 的数据吗？ ⠀ 默认不能。每个 Agent 的工作空间是隔离的。如果需要跨 Agent 共享数据，可以将技能安装为 managed 类型（通过 ClawHub / 市场），这样多个 Agent 都可以使用同一个技能。 ⠀ ⏭️ 小白可跳过 — 这部分面向插件开发者 ⏭️ 小白可跳过 — 这部分面向插件开发者 ⠀ 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 总结。 ⠀ 推荐使用边界： ⠀ ⠀ 如果当前 CLI 暴露了 meeting notes 相关命令，先用只读方式查看帮助和可用 source： ⠀ ⠀ 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 的捆绑插件作者。 ⚠️ 如果你从未开发过 OpenClaw 捆绑插件，可以跳过本节。 这只影响使用 Tool Result Transforms 的捆绑插件作者。 ⠀ 变更内容 ⠀ v2026.4.24 移除了 Pi 运行时专用的 api.registerEmbeddedExtensionFactory(...) 兼容路径。所有 Tool Result Transforms 必须迁移到 api.registerAgentToolResultMiddleware(...)。 ⠀ 为什么改 ⠀ 旧的 registerEmbeddedExtensionFactory 有三个问题： ⠀ 1. Pi 运行时专用，Codex app server 不支持 2. 直接访问高信任工具输出，安全边界不清晰 3. 耦合实现细节而非稳定契约 ⠀ 迁移步骤 ⠀ 旧写法（已移除）： ⠀ ⠀ 新写法： ⠀ ⠀ 同时更新插件 manifest，声明 contracts： ⠀ ⠀ 迁移清单 ⠀ 1. 删除所有 api.registerEmbeddedExtensionFactory(...) 调用 2. 替换为 api.registerAgentToolResultMiddleware(handler, { runtimes }) 3. 在插件 manifest 中添加 contracts.agentToolResultMiddleware 声明 4. 在所有目标运行时上测试 5. 移除 Pi only 条件逻辑 — 新 API 通过 runtimes 数组处理运行时差异 ⠀ 注意： 外部插件不能注册 tool result middleware，因为它可以在模型看到工具输出之前重写内容。只有捆绑插件可以使用此能力。 注意： 外部插件不能注册 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： ⠀ ⠀ 自定义技能和内置技能冲突怎么办？ ⠀ 工作空间技能优先级最高。如果你在 /.openclaw/workspace/skills/ 下创建了一个跟内置技能同名的技能，你的版本会覆盖内置版本。 ⠀ 如果想恢复内置版本，删除工作空间中的同名技能即可。 ⠀ ⏭️ 小白可跳过 — 这部分面向需要优化技能性能的开发者 ⏭️ 小白可跳过 — 这部分面向需要优化技能性能的开发者 ⠀ 技能太多会影响性能吗？ ⠀ 不会。OpenClaw 只会加载跟当前消息相关的技能，不是把所有技能都塞进上下文。但如果你的 triggers 设置得太宽泛，可能会导致不相关的技能被误触发，浪费 token。 ⠀ 建议： • 给每个技能设置精确的 triggers • 在 Agent 配置中用 skills 字符串数组只加载需要的技能 • 定期清理不用的技能 ⠀ 技能可以访问其他 Agent 的数据吗？ ⠀ 默认不能。每个 Agent 的工作空间是隔离的。如果需要跨 Agent 共享数据，可以将技能安装为 managed 类型（通过 ClawHub / 市场），这样多个 Agent 都可以使用同一个技能。 ⠀ 如何回滚技能更新？ ⠀ ⠀ 技能开发的最佳实践 ⠀ 1. 指令要具体 — 不要写"处理邮件"，要写"搜索今天的未读邮件，按发件人分组，生成摘要" 2. 步骤要编号 — AI 更容易按编号步骤执行 3. 提供示例 — examples/ 目录里的示例能显著提高 AI 的执行准确率 4. 权限最小化 — 只申请真正需要的权限 5. 错误处理 — 在指令中说明异常情况怎么处理（比如"如果找不到文件，提示用户创建"） 6. 保持简洁 — 一个技能做一件事，不要把太多功能塞进一个技能 ⠀ 下一步 ⠀ 技能系统掌握了！去 07. 记忆系统 了解 AI 如何记住你！ 课程信息 ⠀ • 作者：老金 • GitHub：https://github.com/KimYx0207 • 公众号：老金带你玩AI • X（Twitter）：老金带你玩AI • 个人博客：https://aiking.dev • 难度等级：🟡 进阶 • 阅读时间：30 分钟 • 前置知识：已完成快速开始（03 快速开始指南） ⠀ 本篇你将学会： 理解技能和工具的区别、管理内置技能、通过 openclaw skills 安装技能、创建自定义技能 ⠀ 小白速通： 只看前 3 节（"什么是技能"、"Skills vs Tools"、"内置技能一览"），了解概念就够了。等你想教 AI 新能力时再看后面的章节 ⠀ 先做一个小练习：看见技能如何改变助手行为 技能不是术语表里的概念，它的作用是把一组稳定做法交给 AI。先用一个最小练习建立手感。 ⠀ 第一步：确认技能命令可用 ⠀ ⠀ 如果搜索结果里能看到摘要、笔记、文档处理相关技能，说明 skills 入口正常。不同版本和市场索引返回结果可能不同，重点是确认命令能跑通。 ⠀ 第二步：安装一个低风险技能 ⠀ 优先选择只处理文本、不需要外部账号授权的技能。例如搜索结果里有 summarize 时： ⠀ ⠀ 如果你的版本里没有这个技能，就先跳过安装，继续看下面的“技能长什么样”。不要为了练习随便安装需要邮箱、网盘、密码管理器授权的技能。 ⠀ 第三步：在对话里触发它 ⠀ 回到 Control UI，输入一段长文本，然后要求： ⠀ ⠀ 如果已安装摘要类技能，OpenClaw 会更倾向于按技能里的流程整理内容。即使你的环境没有对应技能，这个练习也能帮你理解：技能的价值不是“多一个按钮”，而是把可复用的处理流程写下来。 ⠀ 你应该记住 ⠀ • 工具负责单个动作。 • 技能负责告诉 AI 如何组合动作。 • 新手先练低风险文本技能，不要一上来接邮箱、云盘、密码管理器。 ⠀ 什么是技能？ ⠀ 如果说工具 (Tools) 是 AI 的双手，那技能 (Skills) 就是教 AI 如何组合使用这些工具的教科书。 ⠀ 一个工具只能做一件事：读文件、发消息、搜索网页。但一个技能可以把多个工具串起来，完成一个完整的任务流程。比如"管理 GitHub Issue"这个技能，背后可能要调用搜索、读取、创建、评论等十几个工具。 ⠀ OpenClaw 提供了大量内置与可安装技能，覆盖办公、开发、生活方方面面。你也可以自己创建技能，教 AI 新的能力。 ⠀ Skills vs Tools：概念深入对比 ⠀ 很多人刚接触 OpenClaw 时会搞混技能和工具，这里彻底说清楚。 ⠀ 本质区别 ⠀ ⠀ 打个比方： ⠀ • 工具就像厨房里的刀、锅、铲子 — 每个都有明确的单一用途 • 技能就像菜谱 — 告诉你先切菜、再热油、然后翻炒、最后调味 ⠀ 对比表 ⠀ 维度 工具 (Tools) 技能 (Skills) 粒度 单个动作 多步骤流程 定义方式 TypeScript/Python 函数 Markdown 指令文档 执行方式 直接调用 AI 根据指令编排工具 状态 无状态 可以维护上下文 触发方式 模型自动选择 关键词触发或模型判断 复用性 跨技能共享 通常独立使用 开发难度 需要编程 写 Markdown 就行 维度 维度 工具 (Tools) 工具 (Tools) 技能 (Skills) 技能 (Skills) 粒度 粒度 单个动作 单个动作 多步骤流程 多步骤流程 定义方式 定义方式 TypeScript/Python 函数 TypeScript/Python 函数 Markdown 指令文档 Markdown 指令文档 执行方式 执行方式 直接调用 直接调用 AI 根据指令编排工具 AI 根据指令编排工具 状态 状态 无状态 无状态 可以维护上下文 可以维护上下文 触发方式 触发方式 模型自动选择 模型自动选择 关键词触发或模型判断 关键词触发或模型判断 复用性 复用性 跨技能共享 跨技能共享 通常独立使用 通常独立使用 开发难度 开发难度 需要编程 需要编程 写 Markdown 就行 写 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 的加载策略很聪明： ⠀ ⠀ 这意味着： • 不是所有技能都会同时加载（那会撑爆上下文窗口） • 只有跟当前任务相关的技能才会被激活 • 你可以通过 triggers 字段精确控制技能的触发条件 ⠀ 常用 Skills 命令 ⠀ ⠀ 内置技能完整分类 ⠀ 办公效率类 ⠀ 技能 功能 使用场景 依赖工具 gog Google Workspace 邮件、日历、文档管理 Google API MCP notion Notion 页面创建、数据库查询 Notion API trello Trello 看板管理、任务跟踪 Trello API slack Slack 工作区消息管理 Slack API 1password 1Password 密码查询（只读） 1Password CLI 技能 技能 功能 功能 使用场景 使用场景 依赖工具 依赖工具 gog gog Google Workspace Google Workspace 邮件、日历、文档管理 邮件、日历、文档管理 Google API MCP Google API MCP notion notion Notion Notion 页面创建、数据库查询 页面创建、数据库查询 Notion API Notion API trello trello Trello Trello 看板管理、任务跟踪 看板管理、任务跟踪 Trello API Trello API slack slack Slack Slack 工作区消息管理 工作区消息管理 Slack API Slack API 1password 1password 1Password 1Password 密码查询（只读） 密码查询（只读） 1Password CLI 1Password CLI ⠀ 开发工具类 ⠀ 技能 功能 使用场景 依赖工具 coding agent 编程助手 写代码、调试、重构 文件系统 + Shell github GitHub 仓库管理、PR、Issue GitHub CLI (gh) gh issues GitHub Issues Issue 专项管理 GitHub CLI (gh) tmux 终端会话 管理终端会话 tmux 技能 技能 功能 功能 使用场景 使用场景 依赖工具 依赖工具 coding agent coding agent 编程助手 编程助手 写代码、调试、重构 写代码、调试、重构 文件系统 + Shell 文件系统 + Shell github github GitHub GitHub 仓库管理、PR、Issue 仓库管理、PR、Issue GitHub CLI (gh) GitHub CLI (gh) gh issues gh issues GitHub Issues GitHub Issues Issue 专项管理 Issue 专项管理 GitHub CLI (gh) GitHub CLI (gh) tmux tmux 终端会话 终端会话 管理终端会话 管理终端会话 tmux tmux ⠀ 笔记知识类 ⠀ 技能 功能 使用场景 依赖工具 obsidian Obsidian 笔记管理、知识库 文件系统 apple notes Apple 备忘录 macOS/iOS 备忘录 AppleScript bear notes Bear Bear 笔记管理 Bear X Callback nano pdf PDF 处理 PDF 阅读、摘要 PDF 解析工具 技能 技能 功能 功能 使用场景 使用场景 依赖工具 依赖工具 obsidian obsidian Obsidian Obsidian 笔记管理、知识库 笔记管理、知识库 文件系统 文件系统 apple notes apple notes Apple 备忘录 Apple 备忘录 macOS/iOS 备忘录 macOS/iOS 备忘录 AppleScript AppleScript bear notes bear notes Bear Bear Bear 笔记管理 Bear 笔记管理 Bear X Callback Bear X Callback nano pdf nano pdf PDF 处理 PDF 处理 PDF 阅读、摘要 PDF 阅读、摘要 PDF 解析工具 PDF 解析工具 ⠀ 多媒体类 ⠀ 技能 功能 使用场景 依赖工具 voice call 语音通话 AI 语音对话 音频 I/O spotify player Spotify 音乐播放控制 Spotify API peekaboo 截图 屏幕截图分析 screencapture camsnap 摄像头 拍照识别 imagesnap video frames 视频帧 视频内容分析 ffmpeg songsee 听歌识曲 识别正在播放的音乐 音频采集 技能 技能 功能 功能 使用场景 使用场景 依赖工具 依赖工具 voice call voice call 语音通话 语音通话 AI 语音对话 AI 语音对话 音频 I/O 音频 I/O spotify player spotify player Spotify Spotify 音乐播放控制 音乐播放控制 Spotify API Spotify API peekaboo peekaboo 截图 截图 屏幕截图分析 屏幕截图分析 screencapture screencapture camsnap camsnap 摄像头 摄像头 拍照识别 拍照识别 imagesnap imagesnap video frames video frames 视频帧 视频帧 视频内容分析 视频内容分析 ffmpeg ffmpeg songsee 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 工具 工具 功能 功能 支持的提供商 支持的提供商 运行模式 运行模式 video generate video generate 文本/图片/视频 → 视频 文本/图片/视频 → 视频 xAI (Grok)、Alibaba Wan、Runway、Google Veo、OpenAI Sora、BytePlus Seedance、Qwen xAI (Grok)、Alibaba Wan、Runway、Google Veo、OpenAI Sora、BytePlus See