一、引言在 AI Agent 领域能力的可扩展性决定了框架的生命力。OpenClaw 作为一款设计精良的 Agent 框架其技能系统允许用户通过编写技能Skill来扩展框架能力边界实现从简单脚本到复杂工作流的任意功能。技能系统不仅是 OpenClaw 与其他 Agent 框架差异化竞争的核心优势更是构建开放生态的技术基石。本文将系统性地介绍 OpenClaw 技能系统的三大核心模块技能加载机制、门控检查与市场集成。技能加载决定了系统如何发现、解析和优先级排序来自不同来源的技能门控机制确保只有满足运行条件的技能才会被激活保障系统安全与稳定而 ClawHub 市场则提供了技能分发与更新的完整工作流形成闭环的技能生态。本文覆盖范围与阅读指南本文面向有一定编程基础的开发者和技术架构师将从源码实现角度深入讲解各个模块的设计理念与实现细节。读者可以根据自身需求选择性阅读如果你关心技能从哪里来、如何被加载请重点阅读第二章「技能加载优先级机制」如果你想了解技能如何被触发与执行请重点阅读第三章「SKILL.md 规范解析」如果你关注技能运行时的安全检查请重点阅读第四章「技能门控机制」如果你想参与技能生态建设请重点阅读第五章「ClawHub 技能市场集成」与第六章「自定义技能开发实战」技能系统三层架构概览从宏观角度看OpenClaw 技能系统可以划分为三个层次加载层负责从四个不同来源收集技能定义门控层在技能被触发前进行多维度检查执行层则负责加载技能内容并运行相关脚本。接下来我们将逐层展开详细分析。二、技能加载优先级机制技能加载是整个系统运作的起点。OpenClaw 的技能加载机制设计精巧它从四个不同来源收集技能定义并通过优先级策略解决冲突同时保证安全性。2.1 四大技能来源OpenClaw 的技能可以来自以下四个位置按照优先级从低到高排列来源常量名称默认路径说明内置技能bundledSkillsskills/目录随框架一同分发的预装技能管理技能managedSkills~/.openclaw/skills/用户通过包管理器安装的技能项目技能agentSkills.agents/skills/特定项目/仓库的本地技能工作区技能workspaceSkillsworkspaceDir/skills/当前工作区的技能2.2 优先级合并策略技能加载的核心函数loadSkillEntries()使用 JavaScript 的Map数据结构来实现去重和优先级覆盖。其合并逻辑如下// 伪代码展示核心逻辑 function loadSkillEntries() { const merged new Map(); // 1. 首先加载内置技能优先级最低 for (const skill of bundledSkills) { merged.set(skill.name, skill); } // 2. 管理技能覆盖内置技能 for (const skill of managedSkills) { merged.set(skill.name, skill); } // 3. 项目技能覆盖管理技能 for (const skill of agentSkills) { merged.set(skill.name, skill); } // 4. 工作区技能优先级最高最终覆盖 for (const skill of workspaceSkills) { merged.set(skill.name, skill); } return Array.from(merged.values()); }这种设计意味着如果同一个技能名称同时存在于多个来源工作区技能将最终生效。这为开发者提供了极大的灵活性——既可以「继承」框架提供的默认技能又可以通过本地覆盖来定制行为。2.3 目录解析机制各技能目录的解析规则如下内置技能bundledSkillsresolveBundledSkillsDir() → 环境变量 OPENCLAW_BUNDLED_SKILLS_DIR → 可执行文件同级 skills/ → 包根目录 skills/管理技能managedSkills~/.openclaw/skills/ 即CONFIG_DIR skills工作区技能workspaceSkillsworkspaceDir/skills/2.4 安全防护机制为了防止恶意技能通过符号链接逃逸出预期目录OpenClaw 实现了多重路径验证isPathInside()— 基本路径验证确保技能目录在允许范围内isPathInsideWithRealpath()— 符号链接解析后的路径验证bundled-symlink-escape— 特殊安全规则拒绝 bundled 目录中的符号链接逃逸这套机制确保了即使攻击者试图通过符号链接将技能目录指向系统敏感位置OpenClaw 也能有效拦截。路径安全检查的时序技能加载时系统首先解析目录结构获取所有候选技能目录。对于每个候选目录readSkillFileSync()使用openVerifiedFileSync()打开文件并验证路径安全性。只有当文件实际路径在允许范围内时才读取内容。这种先验证后读取的模式是纵深防御策略的体现。此外技能目录扫描会跳过以.开头的隐藏目录和node_modules目录避免意外加载无关内容。候选目录按字母顺序排序确保加载结果的可预测性。三、SKILL.md 规范解析技能的核心定义文件是SKILL.md。OpenClaw 设计了一套渐进式内容披露机制既保证触发时的快速响应又支持触发后的完整内容加载。3.1 三级渐进式披露设计为了平衡性能与功能OpenClaw 采用三级加载策略Level 1 - Metadata只有name和description字段会在技能被扫描时加载。这两个字段约 100 词是技能能否被触发的决定因素。Level 2 - SKILL.md Body只有当技能被实际触发时系统才会加载完整的SKILL.md内容。这部分内容限制在 5000 词以内确保上下文不会过度膨胀。Level 3 - Bundled Resourcesscripts/、references/、assets/等资源目录仅在需要时才加载避免无谓的 I/O 开销。3.2 Frontmatter 规范每个技能的SKILL.md文件必须以 YAML frontmatter 开始--- name: skill-name description: 触发描述这是核心触发机制 ---其中 -name— 技能唯一标识符 -description— 触发描述必须清晰说明「这个技能做什么」以及「何时触发」description 是整个技能系统的触发核心。系统会根据用户输入与各技能的 description 进行匹配从而决定调用哪个技能。3.3 资源目录结构一个完整的技能包结构如下skill-name/ ├── SKILL.md (required) │ ├── YAML frontmatter (name description) │ └── Markdown instructions (技能使用指南) └── Bundled Resources (optional) ├── scripts/ # 可执行代码Python/Bash/JS ├── references/ # 文档参考按需加载到上下文 └── assets/ # 输出资源模板、图片、字体scripts/— 存放技能执行时需要调用的脚本文件。这些脚本是供 AI Agent 在执行技能时参考和调用的工具需要在 SKILL.md 中明确说明使用方式而非系统自动执行。references/— 存放较大的参考文档。这些文件默认不会加载到 AI 上下文中但如果技能需要更多背景信息可以通过 SKILL.md 中的链接引用。assets/— 存放技能可能需要的静态资源如模板文件、图片、字体等。3.4 命名规范技能名称必须遵守以下规则仅使用小写字母、数字、连字符长度不超过 64 个字符建议采用工具命名空间方式如gh-address-comments、pdf-processor3.5 渐进式披露模式在编写 SKILL.md 时OpenClaw 推荐三种内容组织模式Pattern 1: 高层指南 references 链接## 使用指南 本技能用于处理 PDF 文档。详细参数说明请参阅 [references/pdf-guide.md](./references/pdf-guide.md) ## 快速开始 1. 配置 API 密钥 2. 运行处理脚本Pattern 2: 按领域组织skills/ ├── SKILL.md # 总览 入口 ├── references/ │ ├── finance.md # 金融领域参考 │ ├── sales.md # 销售领域参考 │ └── marketing.md # 营销领域参考Pattern 3: 条件细节## 基础用法 [基础内容...] ## 高级用法 如需使用高级功能请参阅 [references/advanced.md](./references/advanced.md)3.6 关键约束SKILL.md body不超过 500 行references 文件超过100 行需包含目录TOC禁止深层嵌套引用仅支持一级深度3.7 解析函数系统使用以下函数解析 SKILL.mdparseFrontmatter()— 提取 YAML frontmatter 中的 name 和 descriptionresolveSkillInvocationPolicy()— 解析技能的调用策略是否允许自动调用、是否需要确认等解析流程从loadSingleSkillDirectory()开始该函数读取SKILL.md文件调用parseFrontmatter()提取元数据。如果name或description为空技能将被忽略。当目录根目录下直接存在SKILL.md文件时如weather/SKILL.md系统将其视为单个技能否则系统会遍历子目录将每个包含SKILL.md的子目录解析为独立技能。3.8 上下文窗口优化上下文窗口是共享资源技能元数据、系统提示、对话历史和其他技能元数据共同占用这一空间。因此 OpenClaw 坚持以下设计原则简洁优先默认假设 AI 模型已经足够智能只在技能中添加模型不知道的程序性知识。每一条信息都应该被质疑AI 真的需要这段解释吗和这段话是否值得它的 token 开销自由度匹配根据任务的脆弱性和可变性设置适当的自由度。高风险操作如数据库迁移需要具体步骤和参数限制低风险操作如文件搜索允许更多灵活性。避免重复信息不应同时出现在 SKILL.md 和 references 文件中。将详细内容放入 references 文件SKILL.md 只保留核心流程指引这样既保持了可发现性又减少了上下文膨胀。这些原则确保了技能系统的高效运行同时最大化了 AI 模型的有效上下文空间。四、技能门控机制当技能被触发后、实际执行前OpenClaw 会进行全面的门控检查。这套机制确保技能只在满足运行条件时才会被执行防止因环境缺失导致的失败或安全问题。4.1 四维门控检查体系门控检查由核心函数evaluateEntryRequirementsForCurrentPlatform()发起检查四个维度4.2 OS 门控OS 门控检查技能的metadata.os数组确保技能仅在支持的平台上运行// 伪代码 function resolveMissingOs(metadata, currentPlatform) { if (!metadata.os || metadata.os.length 0) { return []; // 无 OS 限制 } const supported metadata.os; const remotePlatforms metadata.remotePlatforms || []; const allSupported [...supported, ...remotePlatforms]; if (!allSupported.includes(currentPlatform)) { return [currentPlatform]; // 返回缺失的平台 } return []; // 无缺失 }支持的平台值包括linux、darwinmacOS、win32Windows。值得注意的是remotePlatforms允许指定远程平台也能满足条件。例如一个标记为remotePlatforms: [linux]的技能即使在 macOS 本地无法运行但如果存在远程 Linux 节点则仍可调度执行。4.3 Bins 门控Bins 门控检查技能的二进制依赖function checkBins(requiresBins) { for (const bin of requiresBins) { if (hasBinary(bin.name)) { return true; // 任一满足 } } return false; }hasBinary()— 检查本地 PATH 中是否存在指定二进制hasRemoteBin— 远程节点的二进制检查待验证anyBins— 配置选项允许「任一满足」模式4.4 Env 门控Env 门控验证必需的环境变量// 环境变量优先级 const envPriority [ process.env, // 系统环境变量 skillConfig.env, // 技能配置文件中的 env skillConfig.apiKey // primaryEnvAPI 密钥专用 ];环境变量注入机制确保技能运行时有正确的配置// 技能环境变量覆盖 for (const [rawKey, envValue] of Object.entries(skillConfig.env)) { if (!hasExternallyManagedValue(rawKey)) { pendingOverrides[envKey] envValue; } }恢复机制技能执行完毕后系统会恢复原始环境变量值确保不影响后续操作。4.5 Config 门控Config 门控检查配置文件路径的有效性function isConfigPathTruthy(configPath) { try { const value getConfigValue(configPath); return !!value; // 转换为布尔值 } catch { return false; } }这允许技能指定「仅在特定配置存在时可用」的条件。4.6 安全拦截机制OpenClaw 实现了多层安全防护SKILL_ALWAYS_BLOCKED_ENV_PATTERNS— 正则表达式列表匹配永久阻止的环境变量isDangerousHostEnvVarName()— 检测危险的主机环境变量名isDangerousHostEnvOverrideVarName()— 检测危险的覆盖变量名这些机制防止恶意技能窃取敏感系统信息或覆盖关键配置。4.7 Allowlist 机制内置技能的可 用性可以通过配置控制// 配置项 skills: allowBundled: true/false // 检查函数 function isBundledSkillAllowed(skillName) { if (!config.skills.allowBundled) { return false; // 完全禁用内置技能 } return true; }4.8 最终门控决策综合所有检查技能是否可用的最终判定如下const eligible !disabled // 未被禁用 !blockedByAllowlist // 未被 Allowlist 拦截 requirementsSatisfied; // 所有门控检查通过五、ClawHub 技能市场集成ClawHub 是 OpenClaw 的官方技能市场提供技能的搜索、安装、更新与发布功能。它构成了 OpenClaw 技能生态的闭环。5.1 CLI 命令集ClawHub 通过命令行工具提供服务命令功能示例clawhub search搜索技能clawhub search pdfclawhub install安装技能clawhub install pdf-processorclawhub install --version指定版本安装clawhub install pdf-processor --version 1.2.3clawhub update更新技能clawhub update pdf-processorclawhub update --all批量更新clawhub update --allclawhub update --force强制更新clawhub update pdf-processor --forceclawhub list列出已安装clawhub listclawhub publish发布技能clawhub publish ./my-skill --slug my-skill --name My Skill --version 1.2.05.2 注册中心配置ClawHub 默认连接官方注册中心https://clawhub.com。可以通过以下方式自定义# 环境变量 export CLAWHUB_REGISTRYhttps://custom.registry.com # CLI 参数 clawhub install my-skill --registry https://custom.registry.com5.3 更新机制技能更新采用hash 比对策略更新流程 1. 计算本地技能文件的 hash 值 2. 与注册中心记录的最新版本比对 3. 如果不一致下载并安装新版本 4. 使用--force可强制重新下载安装5.4 安全模型ClawHub 的.skill文件本质上是ZIP 压缩包重命名后缀关键安全限制拒绝符号链接在打包和安装过程中系统会拒绝包含符号链接的技能包防止「符号链接逃逸」攻击。5.5 认证流程# 登录 clawhub login # 查看当前用户 clawhub whoami认证信息用于发布技能和安装私有技能。六、自定义技能开发实战本节通过创建一个pdf-processor技能展示从初始化到发布的完整流程。6.1 项目初始化# 初始化技能项目 scripts/init_skill.py pdf-processor --path skills --resources scripts,references这将创建以下结构skills/ └── pdf-processor/ ├── SKILL.md ├── scripts/ │ └── process.py └── references/ └── guide.md6.2 SKILL.md 完整示例--- name: pdf-processor description: 处理 PDF 文档包括转换、合并、拆分和提取文本。当用户需要处理 PDF 文件时触发。 --- # PDF 处理技能 ## 功能概述 本技能提供 PDF 文档的完整处理能力 - **格式转换** — PDF 转 Word、Excel、图片 - **文档合并** — 多个 PDF 合并为一个 - **页面拆分** — 按页面或范围拆分 PDF - **文本提取** — 提取 PDF 中的文本内容 ## 使用要求 ### 环境依赖 - Python 3.8 - pypdf 库 - pdf2image 库用于图片转换 ### 配置 在 OpenClaw 配置文件中添加 yaml skills: pdf-processor: default_dpi: 150 ocr_enabled: false快速开始# 转换 PDF 为图片 python scripts/process.py convert input.pdf output_dir # 合并 PDF python scripts/process.py merge file1.pdf file2.pdf -o merged.pdf详细文档更多用法请参阅 references/guide.md。### 6.3 脚本示例 python #!/usr/bin/env python3 PDF 处理脚本 import argparse import sys from pathlib import Path def convert_pdf(input_path: str, output_dir: str, dpi: int 150): 将 PDF 转换为图片 # 实现转换逻辑 print(fConverting {input_path} to images at {dpi} DPI...) def merge_pdfs(input_files: list, output_file: str): 合并多个 PDF print(fMerging {len(input_files)} PDF files to {output_file}...) def main(): parser argparse.ArgumentParser(descriptionPDF Processor) subparsers parser.add_subparsers(destcommand) # convert 子命令 convert_parser subparsers.add_parser(convert) convert_parser.add_argument(input, helpInput PDF file) convert_parser.add_argument(output, helpOutput directory) convert_parser.add_argument(--dpi, typeint, default150) # merge 子命令 merge_parser subparsers.add_parser(merge) merge_parser.add_argument(inputs, nargs, helpInput PDF files) merge_parser.add_argument(-o, --output, requiredTrue, helpOutput file) args parser.parse_args() if args.command convert: convert_pdf(args.input, args.output, args.dpi) elif args.command merge: merge_pdfs(args.inputs, args.output) else: parser.print_help() sys.exit(1) if __name__ __main__: main()6.4 打包发布# 打包技能 scripts/package_skill.py skills/pdf-processor ./dist # 发布到 ClawHub clawhub publish ./dist/pdf-processor.skill \ --slug pdf-processor \ --name PDF Processor \ --version 1.0.0打包脚本会自动执行验证流程确保技能满足所有要求YAML frontmatter 验证— 检查 name 和 description 字段是否存在且格式正确命名规范验证— 验证技能名称符合小写 连字符规范长度 64 字符目录结构验证— 确保文件组织合理资源引用路径正确安全验证— 拒绝包含符号链接的技能包只有验证通过后才会生成.skill文件。.skill文件本质上是 ZIP 压缩包包含技能目录的完整结构。6.5 迭代优化技能发布后应根据实际使用情况进行迭代收集反馈— 观察用户如何使用技能记录使用中的问题识别痛点— 注意技能执行失败或不高效的场景针对性改进— 更新 SKILL.md 或补充资源文件重新发布— 打包新版本并推送到 ClawHub迭代过程中特别注意 description 字段的优化因为这是技能能否被正确触发的关键。模糊或过于宽泛的描述可能导致技能无法匹配用户的实际需求。七、总结与展望本文系统性地介绍了 OpenClaw 技能系统的三大核心架构技能加载优先级机制通过四层来源的 Map 合并实现了灵活而安全的技能发现SKILL.md 规范设计了一套渐进式披露机制平衡了触发速度与功能深度四维门控检查从 OS、Bins、Env、Config 四个维度确保技能在满足条件时才被执行ClawHub 市场则提供了完整的技能分发与更新闭环。这套架构的设计理念体现了几个关键原则分层解耦— 加载、门控、执行分离各司其职安全优先— 多层防护机制确保系统稳健开发者友好— 清晰的结构规范与完整的工具链生态开放— 通过 ClawHub 实现技能的开放流通