1. Skills 在 OpenClaw 里的定位先搞懂它到底解决了什么问题接触 OpenClaw 的朋友应该都有这种感觉默认装好之后它确实能聊天、能总结、能写代码但真要它去操作点实际的东西——比如帮你批量重命名一整个目录的文件、定时抓某个网页的更新、把散落的笔记按规则归档——它就有点“有劲使不出”。这不是模型不行而是 LLM 本质上只是一个文本生成引擎它不会真的去执行命令、读写文件、调用外部服务。Skills 这套机制存在的全部意义就是把这层“只会说不会做”的窗户纸捅破。我在第一次看到 OpenClaw 的 Skills 设计时印象最深的一点是它没有把技能做成一堆散落的函数库也没有做成一个巨大的插件框架而是把每个技能都定义成一个“目录 元数据 可执行方法”的自治单元。这种设计的好处是极其直观的——你给 AI 添加一项能力和你在命令行里安装一个工具的行为模式完全一致把东西放到该放的位置声明清楚它是什么、什么时候用、怎么用剩下的交给系统去加载。如果你只是想给 OpenClaw 加一个“帮我查天气”的小功能你完全可以不用理解底层实现照着目录结构往里填内容就行。但如果你想把它用扎实——比如给自己的项目定制一套自动化工作流、让多个技能之间互相调用、控制技能的触发条件和权限边界——那就必须把它的技术架构吃透。这篇内容我把 Skills 从目录规范、元数据设计到执行流程、常见坑全部过一遍适合已经被 OpenClaw 的基本使用勾起了兴趣、准备深度定制自己技能包的开发者参考。2. Skills 的整体设计思路拆解为什么是“目录即技能”2.1 LLM 的能力边界与技能系统的补位逻辑要理解 Skills 的架构得先回到 AI 助手的运行本质上。OpenClaw 的核心引擎是一个对话循环用户输入 → 模型判断意图 → 生成回复 → 可能需要调用工具 → 拿到结果继续生成。在这个循环里模型自身的能力只覆盖了前两步后面真正产生实际效果的步骤必须要靠外部代码来补位。Skills 系统就是这块“外部代码”的统一封装层。它把原本散落在各种地方的工具调用逻辑——比如写死的 Python 脚本、shell 命令、HTTP 请求——全部收纳进一个标准化的技能目录里并告诉模型你面前有这些能力可用每一项能力何时适用、需要什么参数、会返回什么结果。这样模型就不需要“凭空想象”怎么操作一个文件系统它只需要学会“选择技能 填对参数”具体的脏活累活交给技能的底层实现去完成。从整体架构上看OpenClaw 把技能系统分成了四个层面技能定义层描述技能是什么、何时用、方法实现层实际执行的代码逻辑、调度层模型决定调用哪个技能、传什么参数、执行层在隔离环境里跑方法并返回结果。四个层面各司其职互不侵入。这个分层好处在后期维护时特别明显你要改一个技能的底层实现逻辑完全不用动元数据描述你想调整某个技能的触发条件也不需要碰它的代码。2.2 技能注册表与“按需加载”的取舍很多人刚开始会有一个直觉既然要给模型暴露技能那把全部技能的所有信息一股脑塞进上下文不就行了这个想法在技能数量少时没问题但一旦你攒了十几个甚至几十个技能对上下文的浪费是致命的。OpenClaw 的做法是维护一张技能注册表。系统在启动时扫描技能目录把每个技能的名字、功能描述、适用场景这些“摘要信息”汇总成一张清单注入到模型上下文中。模型看到的是类似“当前可用 12 项技能文件批量重命名操作文件系统、网页内容抓取获取 URL 内容、定时任务管理创建/查询定时任务……”这样的索引。只有当模型判断某个技能确实适用时完整的方法参数定义和调用约定才会被加载。这就像餐厅只会把菜单递给你而不是把后厨所有食材的采购记录、切配流程全摆在你面前。你根据菜单点菜后厨才会开始处理具体食材。我实际用下来这种“按需加载”对 token 占用的控制效果非常显著。刚开始我只有五六个技能时感觉不明显后来把技能扩展到二十多个上下文压缩的优势才真正体现出来——模型在复杂对话场景下很少因为技能描述过长而“忘记”用户的原始指令。2.3 为什么强调“技能自治”OpenClaw 对技能的最基本原则是一个技能目录就是一个完整的、自包含的功能模块。你在目录里放进元数据、方法代码、依赖清单、示例说明这个技能就能在任意一台部署了 OpenClaw 的机器上运行——不需要额外手动注册也不用往别处再填一份配置。这个设计直接带来的好处有两个。第一是可移植性我在本机调试好的技能包直接拷贝到另一台服务器上重启后就能被识别和调用这大大降低了技能的分发成本让人可以像分享开源工具一样分享自己写好的技能包。第二是可测试性因为每个技能都是独立的你可以在不启动整个 AI 对话引擎的情况下单独跑一个技能的方法入口来验证逻辑正确性调试效率提升非常明显尤其是技能里带了复杂的文件操作或网络请求逻辑时。3. Skills 的目录结构与元数据规范3.1 一个标准技能目录长什么样OpenClaw 里每个技能都以一个独立的子目录形式存放在skills/根目录下。我自己在建技能时使用的标准结构是这样的skills/ └── my_skill/ ├── SKILL.md ├── methods/ │ ├── __init__.py │ ├── main.py │ └── helper.py ├── assets/ │ └── templates/ ├── requirements.txt └── README.md其中SKILL.md是整个技能的门面承载了所有模型需要知道的元数据methods/目录放实际的 Python 方法实现assets/目录放技能运行所需的静态资源requirements.txt声明依赖。这四个部分各司其职缺一不可。有一点要提醒目录名就是技能名。命名时尽量用全小写加下划线不要用空格和奇怪的符号。我在调试时踩过坑给一个技能起名叫My Web Fetcher结果系统在扫描时因为目录名里的空格导致解析异常技能一直无法被识别。最后老老实实改成my_web_fetcher才正常。OpenClaw 对技能目录名的解析规则不算严格但空格和中文这类字符建议避免否则后续你在技能索引里看到的名称也可能显示异常。3.2 SKILL.md 元数据逐项拆解SKILL.md是技能系统里最核心的配置文件格式上采用 YAML frontmatter 加 Markdown 正文的组合。我整理了一份最常用的元数据字段表按必需程度排列如下字段含义必需性name技能唯一标识一般与目录名保持一致必需description一句话描述技能功能模型靠它判断是否适用必需trigger_keywords触发关键词列表辅助模型在对话中识别调用时机推荐overrides覆盖默认模型行为的指令定义“何时绝对不要调用”可选require_env需要的环境变量或凭据名称列表按需permission技能运行所需的权限级别如sandboxed/admin推荐description这个字段我建议认真打磨因为它直接决定了模型“看不看得懂”你的技能。写的时候不要用太笼统的话比如“处理文件”这种就没法让模型判断具体怎么用。比较好的格式是动作 对象 适用场景。例如description: 批量重命名指定目录下的所有文件支持前后缀添加、扩展名替换、正则表达式匹配适用于需要整理下载目录或日志文件的场景。trigger_keywords也不是摆设。虽然如今模型的意图识别能力已经很强但在技能数量庞大的情况下给几个高频关键词能显著提升触发准确率。比如你的技能是抓取网页内容加抓取、网页内容、爬取、读取页面这些词模型在用户说“帮我看看这个网页里写了什么”时就能更快联想到调用这个技能。3.3 方法注册与参数声明让你的函数能被模型“看见”元数据描述解决了“什么时候用”的问题方法注册则解决“怎么用”的问题。一个技能可以在methods/目录里定义多个方法每个方法都对应一段独立的可调用逻辑。以 Python 技能为例每个方法本质上就是一个普通的 Python 函数但你需要通过一个统一入口暴露给系统。OpenClaw 的约定是在methods/__init__.py里维护一个METHODS字典把方法名映射到对应的处理函数上。系统只会加载这个字典里显式声明的方法没注册的私有函数不会被暴露这给了开发者很大的自由度——你可以在辅助模块里写一堆内部函数但只要不注册模型就不会碰它们也不用担心暴露多余的调用面。参数声明方面我建议使用类型注解并给出默认值。这不仅是为了代码规范而是实打实地有好处模型在生成调用参数时会参考你的函数签名类型注解可以帮助它生成更精确的 JSON 参数。如果你的函数需要一个directory参数写成directory: str和写成不带注解的directory模型在两种情况下传错类型的概率有明显差异。安全的经验是每个方法都写成接收一个参数字典的函数而不是写成一个参数跟一个位置实参的普通函数。这样当模型生成调用时你可以在函数内部对参数做统一校验和兜底处理某个参数缺失也不会让整个技能直接崩溃。我在自己的技能包里给每个方法都加了一段这样的开头逻辑大幅提升了调用的健壮性。4. Skills 的执行流程与触发机制深入4.1 从系统启动到技能调用全链路时序搞清楚一个技能从被扫描到被执行的完整过程是理解整个架构的关键。我按实际运行时的先后顺序梳理了这条链路上的核心环节扫描阶段OpenClaw 启动时遍历skills/根目录识别每个包含SKILL.md的子目录。解析阶段读取SKILL.md的 frontmatter校验必填字段是否齐全将技能名、描述、关键词等摘要信息写入注册表。注入阶段注册表里的技能摘要被拼接进系统提示词作为模型可见的“可用技能列表”。触发决策阶段用户在对话中提出请求模型根据当前上下文和技能摘要判断是否调用某个技能、调用哪个方法、传入什么参数。调用执行阶段模型发出函数调用请求OpenClaw 解析请求、校验参数、找到对应方法在目标权限环境下执行。结果回填阶段方法执行结果被转换为文本重新注入对话上下文模型基于结果生成最终回复。这四个步骤里最容易出问题的是第 4 步——模型的决策环节。其他步骤都是确定性代码流程出问题基本在参数上唯独触发决策是概率性的同一个请求可能每次的调用结果都不一样。所以我后面会说为了让技能稳定触发你需要在元数据描述和权限配置上多做功课。4.2 显式调用 vs. 隐式触发OpenClaw 的 Skills 触发策略大致分为两种模式显式调用和隐式触发。理解它们的区别能帮助你针对不同技能选择正确的配置方式。显式调用是最高可控的模式。在技能元数据中如果你明确声明了这个技能只应在用户提到特定语法时使用比如设置了override指令“只有用户输入/search开头的内容时才调用本技能”那么模型几乎不会误触发它。这种模式适合那些“宁可不调不能乱调”的技能——比如删除文件、修改配置、发送消息这类有副作用的操作我强烈建议用显式调用约束住。隐式触发则依赖模型在自然对话中对用户意图的理解。比如你有个“总结网页内容”的技能用户说“这篇新闻太长了帮我精简一下核心观点”模型可能不会自觉去调用技能——因为用户没提“网页”也没提“抓取”。这种情况下你需要在trigger_keywords里覆盖语义宽度足够的词比如新闻、文章、网页、内容太多、精简。我个人的建议是把两者结合核心操作技能设置为显式调用保证安全边界辅助提效技能设置为隐式触发让使用体验更自然。而且 OpenClaw 支持在对话中间动态提醒用户有哪些可用技能相当于隐式触发的一个兜底——即使模型没识别出来你可以用一句话把它点醒。4.3 上下文注入与 Token 预算分配策略技能摘要注入到上下文里这听起来简单但实际操作时需要精心控制信息量。每个技能的描述、关键词、权限声明都要占 token 预算技能一多这块累积起来非常可观。为了避免上下文爆炸OpenClaw 会为每个技能生成一段精简的索引项而不是把全文都塞进去。我在使用中发现技能描述写得越精炼模型在决策时越果断。写得很啰嗦的描述反而会导致模型“看不过来”在技能多的时候经常出现选择困难甚至把两个相似技能搞混。我自己控制 token 预算的经验是每个技能的描述控制在 60~100 字左右关键词控制在 5 个左右。超过这个量收益就开始递减。另外一个实用技巧是在技能描述里主动说明“本技能不适用于什么场景”这种负例描述虽然会多花一点点 token但能显著减少误调用。比如一个只处理本地文件的技能加上“仅处理本机文件不适用于网络资源”模型在用户提出 URL 请求时就不会错误地选它。4.4 权限隔离与沙箱机制为什么技能不能想干嘛就干嘛OpenClaw 的 Skills 技术架构里最值得借鉴的设计是它的权限分级与沙箱隔离。每个技能在元数据里可以声明自己需要的权限级别级别不同执行环境的边界也不同。我目前用过的权限模式有三种纯沙箱模式方法运行在受限环境里不能访问文件系统只能通过专门的 API 完成少数操作。适合纯计算、文本处理类技能。有限文件访问模式可以读写特定目录如~/openclaw/workspace/下的子目录但被限制在固定的工作目录里不能满盘乱跑。适合大多数文件操作类技能。宿主模式全权限运行可以执行任意命令、访问任意目录。适合系统管理类技能但风险也最高。我强烈建议哪怕是本地单机使用的 OpenClaw也要认真思考每个技能的权限边界。很多人一开始图省事把所有技能都配成宿主模式觉得反正都是自己机器。但技能多了以后你可能会从社区下载别人分享的技能包那些代码你根本没逐行读过。有一次我下载了一个“生成项目周报”的技能运行后发现它在assets/目录里藏了一段收集系统信息并上传的代码。虽然可能是无意的数据统计但这种行为如果发生在全权限模式下风险非常大。配好权限级别才是对“技能自治”这个理念最好的补充。5. 实操从零编写一个自定义 Skill 的完整过程5.1 先定场景再写代码写技能最忌讳一上来就开始撸代码。我先分享自己惯用的流程先明确用户会在什么场景下说出一句什么样的话、期望得到一个什么样的结果再倒推技能该拆成几个方法、需要哪些参数。举个例子。我想给 OpenClaw 加一个“整理下载目录”的技能。用户的诉求可能是“把下载文件夹里最近一周的安装包整理到按软件名分好的子目录里”。这个场景就非常清晰技能名organize_downloads功能描述扫描指定下载目录按扩展名/来源/日期分类文件移动到对应子目录需要的方法scan_directory扫描并统计文件类型、move_files按规则移动文件、dry_run预演模式下只输出整理计划不真正移动这个拆分的好处是dry_run方法相当于给整个技能加了一层安全网用户在真实执行前可以先预览整理计划确认无误后再真正动手。我在技能里加了这个方法之后误删文件的焦虑基本消失了推荐你也这样做。5.2 目录初始化与元数据编写实例场景定好之后我开始搭目录。以organize_downloads为例完整步骤如下cd ~/openclaw/skills mkdir organize_downloads cd organize_downloads mkdir methods assets touch SKILL.md requirements.txt然后我写SKILL.md内容如下--- name: organize_downloads description: 扫描指定目录并按文件扩展名、修改日期或文件名关键词将文件分类移动到子目录适用于整理下载文件夹、日志目录、临时文件目录等场景。仅处理本机文件不适用于网络资源。 trigger_keywords: - 整理下载 - 分类文件 - 归档 - 移动文件 permission: sandboxed --- # organize_downloads 按规则整理指定目录中的文件支持三种分类模式 1. 按扩展名分类 2. 按修改日期分类如 2024-01/ 3. 按文件名关键词分类 所有移动操作前必须先调用 dry_run 预览计划。注意这里我声明了permission: sandboxed并把移动操作限定在指定工作目录内防止它满盘乱跑。trigger_keywords里覆盖了用户最可能说出的几种说法模型看到“整理下载文件夹”这种请求时大概率会联想到这个技能。5.3 方法实现与返回值设计接下来是核心代码。methods/main.py里我实现一个公开入口函数它接收参数字典并完成调度organize_downloads 技能方法实现 import os import shutil from datetime import datetime from typing import Dict, Any def _normalize_path(path: str) - str: 统一路径格式避免传入参数带尾斜杠导致比较出错 return os.path.abspath(os.path.expanduser(path)) def scan_directory(params: Dict[str, Any]) - Dict[str, Any]: 扫描目录返回文件类型统计与文件清单 target_dir _normalize_path(params.get(directory, .)) if not os.path.isdir(target_dir): return {success: False, error: f目录不存在: {target_dir}} file_list [] type_stats {} for root, dirs, files in os.walk(target_dir): # 跳过以 . 开头的隐藏目录 dirs[:] [d for d in dirs if not d.startswith(.)] for fname in files: fpath os.path.join(root, fname) ext os.path.splitext(fname)[1].lower() or [无扩展名] type_stats[ext] type_stats.get(ext, 0) 1 file_list.append({ path: fpath, name: fname, ext: ext, size: os.path.getsize(fpath), }) return {success: True, total_files: len(file_list), type_stats: type_stats, files: file_list[:100]}返回值的设计很有讲究。我在技能里做一件事时会坚持让返回结果包含三层信息是否成功、简洁的统计摘要、必要时附上的详情数据。这样模型拿到返回结果后不需要在长列表里反复找重点可以直接基于摘要生成回复。如果直接把上百条文件清单全抛给模型不仅费 token还可能让模型的回复变得冗长且抓不住重点。move_files方法的实现也类似区别在于它在移动前会做一次目录创建和路径冲突检查def move_files(params: Dict[str, Any]) - Dict[str, Any]: 按规则移动文件支持 dry_run 预演 target_dir _normalize_path(params.get(directory, .)) mode params.get(mode, extension) # extension | date | keyword dry_run params.get(dry_run, False) keyword params.get(keyword, ) if not os.path.isdir(target_dir): return {success: False, error: f目录不存在: {target_dir}} scan_result scan_directory({directory: target_dir}) if not scan_result[success]: return scan_result moved_count 0 plan [] for item in scan_result[files]: if mode extension: dest_dir os.path.join(target_dir, item[ext].lstrip(.) or no_ext) elif mode date: mtime os.path.getmtime(item[path]) date_str datetime.fromtimestamp(mtime).strftime(%Y-%m) dest_dir os.path.join(target_dir, date_str) elif mode keyword: if keyword not in item[name]: continue dest_dir os.path.join(target_dir, keyword) else: return {success: False, error: f不支持的分类模式: {mode}} dest_file os.path.join(dest_dir, item[name]) plan.append({from: item[path], to: dest_file}) if not dry_run and item[path] ! dest_file: os.makedirs(dest_dir, exist_okTrue) shutil.move(item[path], dest_file) moved_count 1 return {success: True, dry_run: dry_run, planned: len(plan), moved: moved_count, plan: plan[:50]}在methods/__init__.py里注册from .main import scan_directory, move_files METHODS { scan_directory: scan_directory, move_files: move_files, }这样模型就能看到两个可调用的方法。我不把_normalize_path这种辅助函数注册进去因为模型没有必要直接调用它暴露最小可用面是维护可调用接口的好习惯。5.4 本地验证与效果调优写完之后不要急着启动完整的对话引擎去测试我推荐先用一个简单的本地验证脚本直接调用技能方法cd ~/openclaw/skills/organize_downloads python -c from methods import METHODS; print(METHODS[scan_directory]({directory: /tmp/test_downloads}))先用dry_run模式跑一遍计划预览确认分类逻辑符合预期再真正执行移动操作。我在第一次写这个技能时就发现按扩展名分类时把临时文件.tmp也单独归了一类这些其实应该直接忽略。所以我在move_files里加了个忽略列表IGNORE_EXTS {.tmp, .crdownload, .part}这一小步对实际体验的提升很大——用户不会希望整理完文件夹后看到一堆没用的临时文件垃圾。技能的调优是一个持续的过程建议你每用一段时间就看看它的执行结果从失败案例里反推元数据描述或代码逻辑哪里需要修正。6. 常见问题与排查技巧实录6.1 技能注册了但模型就是不调用它这是最频繁遇到的问题。技能被扫描成功了可对话时模型总是“无视”它。我的排查顺序是在注册表里确认技能摘要确实被注入可以通过 OpenClaw 的诊断命令查看当前加载了哪些技能如果这项技能根本不在列表里那就是扫描/解析阶段出了问题。检查description是否写得足够具体描述模糊是模型不调用的头号原因。“处理文件”和“扫描并整理目录把文件按扩展名/日期移动到子目录”在模型眼中的可用性是两个量级。检查有没有其他技能在描述上“抢占”了这个场景两个技能描述重叠时模型可能会优先选择描述更详细的那个。在对话里明确提到技能名看模型是否还是不用。如果明确提到都不用那基本可以断定是权限或注入环节出问题了。我遇到过最隐蔽的一次是某个技能的元数据被我误写成了permission: admin而当前运行的 OpenClaw 进程是沙箱模式系统直接把该技能标记为“不可用”。这种权限不对称的坑不做全量排查很难发现。6.2 模型的调用参数总是传错当模型把字符串传给了整型参数或者漏掉了必填参数时先别急着骂模型笨。大概率是你的函数签名写得不够“有引导性”。我举一个真实改进过的例子。原来我写的方法是def move_files(params): mode params.get(mode, extension)参数说明完全缺失模型只能猜。改成这样之后调用准确率大幅上升def move_files(params: Dict[str, Any]) - Dict[str, Any]: mode 可选值: extension|date|keyword directory: 要整理的目录绝对路径 dry_run: 是否只预览不执行布尔值 keyword: 当 modekeyword 时必填 原因很简单模型在生成调用时会参考函数签名和 docstring 中的信息。你给的信息越结构化它传参就越准确。我还建议在函数开头加一段参数校验逻辑而不是直接假设参数都合法mode params.get(mode, extension) if mode not in (extension, date, keyword): return {success: False, error: fmode 必须是 extension/date/keyword收到: {mode}}一旦传参错误至少能得到一个明确的失败原因而不是在运行到一半时抛异常或者更糟——静默地执行了错误的操作。6.3 技能执行超时或卡死技能执行超时通常有两种原因一是方法本身做了耗时很长的操作比如递归扫描一个庞大的目录树、访问网络接口迟迟不返回二是死循环或等待用户输入。处理超时问题我的经验是给技能方法设计明确的“最大扫描量”或超时阈值。比如我的scan_directory只返回前 100 个文件详情并且用total_files作为总量估计而不是把几万个文件的所有信息都计算一遍。对网络请求类技能我会显式传入超时参数requests.get(url, timeout10)别小看这行代码。有一次我写抓网页的技能时忘了加超时某个站点响应极慢整个技能卡了两分多钟期间对话完全被阻塞。加上超时后即使某个网站无法访问技能也会在 10 秒内返回错误信息对话体验不会中断。另一个思路是把重操作拆成多个轻量方法。用户先调用scan_directory拿到文件清单再调用move_files执行移动而不是把一个“全自动整理”塞进一个方法里。这样每个方法的执行时间都在可接受范围模型也更容易中途介入确认而不是被动等待一个黑盒任务跑完。6.4 上下文污染技能返回结果把对话带偏技能执行完了返回结果也进上下文了但模型的后续回复质量急剧下降——比如开始用文件的绝对路径来回复用户或者在无关话题里反复提到刚才处理的文件名。这就是上下文污染。控制上下文污染有几个实用技巧第一精简返回结果的大小。scan_directory返回前 100 个文件的详情是我故意限制的——因为超过这个量模型大概率不会用反而会被无意义的长列表干扰。你可以在摘要里放关键统计数字文件总数、类型分布、目录大小把大数据量结果以文件形式落盘并在返回结果里附上文件路径让模型知道“完整清单在那边”。第二返回结果里加上“此结果仅供操作参考不要在回复中逐条罗列”这类指令。OpenClaw 支持在技能返回文本中附带面向模型的指令相当于给结果“贴个标签”明确告诉模型应该怎么使用这些信息。这个技巧对抑制“倒豆子式回复”非常有效。第三技能完成后主动收尾。在任务执行链的最后一步调用一个类似于“任务完成状态确认”的轻量方法返回一个干净的结论文本覆盖掉此前可能堆积的大量过程信息。就像 6.2 里的参数校验失败返回也会输出干净的 error 信息而不是让模型面对一个异常堆栈自己想办法。写到这里我想起一个常在 OpenClaw 社区里被讨论的现象很多开发者过早地去学习大规模技能编排、多技能协同、动态装载这些进阶概念结果反而在基础技能触发、参数传递这类环节反复受挫。Skills 系统真正的学习路径是先把一个技能做扎实——从场景定义、元数据描述、方法实现到执行验证跑通一遍有了这个完整的感知后面的扩展都会水到渠成。我自己也是被“技能不触发”折磨了几天之后才开始意识到元数据描述和权限声明这些看似简单的字段才是整个架构里决定成败的细节。