最近项目里把 openclaw 从玩具跑成了正式工具刚好写到这个系列的第八章。前七章我们把环境部署、模型接入、基础配置都过了一遍今天聊的是真正的灵魂Skills 扩展。什么是 Skills说人话就是 AI 代理的“外挂工具箱”装上它之后openclaw 不再只是陪你聊天而是可以帮你写论文、画分镜、做前端代码规范检查、整理项目文件甚至把一组复杂的命令行操作封装成一句话指令。这一篇我会先讲清技能机制的底层逻辑再带你把第一个 Skill 跑起来最后把调试过程中踩过的五个坑原封不动交给你。不管你是刚装完 openclaw 的新手还是想帮团队搭技能库的开发者这一章都适用。1. Skills 到底是什么为什么非要搞懂它1.1 从一次性指令到可复用技能最早用 openclaw 的时候我习惯把需求直接打在对话里。比如“帮我写一份前端代码审查报告按性能、可维护性、可访问性三个维度”模型确实能答但每次都要重新描述背景和输出格式烦且不稳定。后来我意识到真正高效的用法是把这类重复需求固化成“技能”一个技能包里面包含三样东西——告诉模型什么时候用、怎么用的说明文档、一段可选的可执行脚本、以及一些辅助资源。模型负责判断“当前该不该启动这个技能、启动哪个”脚本负责处理模型不擅长的精确计算、文件遍历、系统调用。二者一配合原来靠对话反复拉扯的事就变成了一个稳定入口。这个转变的本质是把“指令”升级成了“能力模块”。指令是一次性的技能是可复用的。你可以在任何对话中让 openclaw 直接调用已安装的技能不用每次重新描述。对团队来说更是如此一份合格的技能说明写好后评审一次、沉淀到仓库里以后任何人都能复用不用把时间浪费在重复调 prompt 上。1.2 openclaw 里一个技能是如何被触发的要理解触发逻辑得先看 openclaw 启动时发生了什么。安装和配置好之后openclaw 会扫描固定的技能目录不同平台默认位置略有差异最常见的是~/.openclaw/skills逐个读取目录中的SKILL.md文件解析文件头部的 YAML 元数据再把它注册到模型上下文里。看到这里你就明白SKILL.md是整个技能包的入口它写得好不好直接影响模型能不能在合适的时机想起这个技能。触发过程可以粗略分成两步第一步是“描述匹配”模型看到用户的请求后会拿请求内容和你所有技能的description字段做语义匹配判断哪个技能最相关第二步是“执行调用”模型决定调用后再按照SKILL.md正文里的指引决定是直接输出一段脚本、运行某个命令还是调用技能包里的可执行文件。所以你会发现同样一个技能如果description写得太笼统或太抽象模型就会经常忘记用它如果正文指令写得含糊脚本很容易执行错方向。后面我会单独讲怎么写好这两部分。2. 动手前环境准备与目录规范2.1 先确认你的 openclaw 跑在哪一层开始写技能之前我建议你先花三分钟确认运行环境。 openclaw 在 Windows、Linux、macOS 上都有安装路径很多 Windows 用户是通过 WSL 跑的所以第一个要检查的是 Windows 上的 WSL 状态。如果在 PowerShell 里执行wsl --status提示“无法安全验证”或者要求启用 WSL2不要直接跳过。这个问题通常意味着 Windows 功能没开全或者内核版本过旧后续安装 Node.js、让 openclaw 持续运行都会踩坑。正确做法是先确认系统支持虚拟化然后在管理员 PowerShell 里依次执行wsl --update和wsl --set-default-version 2装完重启。至于 Node.jsopenclaw 基于 Node 生态建议安装当前 LTS 版本千万不要用太老的 12.x 或过于激进的 latest版本不匹配最常见的表现就是启动时报错、技能文件偶尔加载不上。如果你在手机端比如 Termux也可以装 openclaw但要注意技能里若依赖 GUI 或系统服务多半跑不起来后面第 6 章我再细说。2.2 技能包的标准目录结构与 SKILL.md 写法一个标准的技能包其实就是一个独立目录。下面这个是我常用的模板你可以直接抄my-skill/ ├── SKILL.md ├── scripts/ │ ├── analyze.py │ └── helper.sh └── assets/ └── templates/SKILL.md不可缺少它是 openclaw 识别技能的唯一标志scripts/放可执行脚本模型遇到复杂逻辑时会调用它assets/可选放模板、样例数据这些辅助文件。注意整个技能目录的名字最好和技能用途一致比如要做“项目体检”目录就叫project-health-check别叫test1否则你自己都会忘记它是干嘛的。SKILL.md的开头必须写一段 YAML 元数据。我给出一个通用模板--- name: project-health-check description: 检查一个项目的代码健康状况包括文件结构、未使用依赖、TODO标记等。当用户想了解项目代码状态、检查项目结构或清理依赖时使用。 parameters: - name: target_dir description: 要检查的项目根目录 required: true ---元数据下面就是正文用 Markdown 写给模型看。正文里要写清楚这个技能的执行流程、边界条件、注意事项比如“只分析目标目录内的文件不要修改任何代码”“输出报告用表格形式”等等。很多第一次写技能的人只会在正文里写“调用脚本”其实这是不够的。模型并不知道你的脚本长什么样、参数怎么传你要把调用方式一步一步写清楚必要时把脚本里会用到的关键逻辑也贴出来。3. 从零开发一个可以落地的 Skill3.1 选一个好场景定好输入输出理论知识讲完我们直接动手。我建议第一个技能选一个“小而痛”的场景比如我做过的“项目体检”给 openclaw 一个目录它去扫描这个目录里的代码文件统计文件数量、找出 TODO 标记、识别明显的未使用依赖最后生成一份简洁的健康报告。为什么选它因为它正好能把 openclaw 的两种能力都用上模型负责理解和组织输出脚本负责文件遍历、正则匹配这些模型不擅长的精确操作。为了让技能落地先定义输入输出。输入是目标目录路径输出是一份 Markdown 报告包含文件总数、目录结构摘要、TODO/FIXME 出现次数、明显未使用依赖数量仅针对 package.json 这类常见清单文件以及一条综合建议。有了这套契约写脚本就不容易跑偏。3.2 三步创建目录、脚本、注册第一步创建技能目录和脚本。在你的技能目录下建project-health-check然后新建scripts/health_check.py内容可以输成#!/usr/bin/env python3 import os, sys, json, re def main(target_dir: str): todo_count 0 fixme_count 0 total_files 0 report {dir: target_dir, total_files: 0, todos: 0, fixmes: 0} for root, _, files in os.walk(target_dir): for f in files: if f in [.git] or root.startswith(os.path.join(target_dir, .git)): continue total_files 1 path os.path.join(root, f) try: with open(path, r, encodingutf-8, errorsignore) as fh: content fh.read() todo_count len(re.findall(rTODO, content)) fixme_count len(re.findall(rFIXME, content)) except Exception: pass report[total_files] total_files report[todos] todo_count report[fixmes] fixme_count print(json.dumps(report, ensure_asciiFalse, indent2)) if __name__ __main__: if len(sys.argv) ! 2: print(Usage: python health_check.py target_dir, filesys.stderr) sys.exit(1) main(sys.argv[1])这个脚本逻辑很简单但是足够演示标准流程接收一个目录参数遍历文件统计关键词输出 JSON。真正生产环境里你还可以加入依赖分析、大文件检测这些功能这里先求跑通。第二步写SKILL.md。前面已经给了 YAML 片段正文部分我建议写成这样# project-health-check 检查目标目录的健康状况。当用户想评估代码质量、整理旧项目、准备重构时使用此技能。 ## 执行流程 1. 确认用户提供的 target_dir 存在。 2. 运行命令python3 scripts/health_check.py target_dir 3. 将输出的 JSON 结果整理成 Markdown 报告。报告包含文件总数、TODO/FIXME 数量、目录结构摘要。 4. 不要修改目录内任何文件只做只读分析。注意“不要修改任何文件”这句很重要技能一旦涉及文件操作必须明确边界否则模型在自动执行时可能做出危险动作。第三步注册并测试。把整个目录放进~/.openclaw/skills重启 openclaw或者执行你安装版本对应的重载命令确认没有报错。然后打开对话简单说一句“用项目体检技能看一下/workspace/demo”。如果模型回答说找不到这个技能多半是目录位置不对或者SKILL.md里的 metadata 写错回到第 2 章检查。3.3 如何确认 openclaw 真的加载了这个 Skill很多人在这一步卡住所以我单独拿出来讲。加载成功与否最直接的办法是看 openclaw 自己的技能列表命令通常是openclaw skills list它会把当前已注册的技能和对应描述都打印出来。如果你在输出里看到了project-health-check基本就是加载成功了。另一个验证方式是对话测试。你可以在测试时说“我现在不修改文件只想知道这个项目里有多少TODO请帮我看看”如果模型主动选择了project-health-check而不是自己直接数说明技能已经进入它的工具集。如果模型依然在乱猜问题基本出在description写得太宽泛比如只写“检查项目”模型不知道何时该用。把description改成包含典型用户表达和触发条件的句子多测两次就正常了。4. 模型与技能的配合方式4.1 本地模型Ollama/Qwen下技能还能不能用这里要回应一个大家高频问的问题openclaw 是不是只有接 API 才能干活我负责任地告诉你不是。你可以接云端大模型 API也可以把模型部署在本地用 Ollama 跑 Qwen2.5 这类开源模型openclaw 照样能用技能。本地模型的好处是数据不出内网成本可控代价是小参数模型比如 3B 级别对复杂技能的指令理解能力明显弱一些所以技能说明必须写得更直白。我实际用下来Qwen2.5-3B 跑一个简单技能完全没问题但如果你给它三个技能同时摆在面前它选择错误的概率会变高。对策很简单本地模型场景下给每个技能描述加“触发词”比如“当用户提到体检、健康检查、项目状态时”让模型可以靠关键词做粗匹配。另外脚本调用失败时小模型不擅长自己修你最好把常见错误在 SKILL.md 正文里写清楚。4.2 热门场景的 Skills 组合建议社区里现在流行的 Skills 方向五花八门我根据自己用过的经验整理了一张组合表比较适合需要快速落地的团队场景推荐技能方向核心能力前端开发代码审查、组件模板生成、依赖检查快速发现性能隐患、统一代码风格论文写作引用格式整理、章节结构建议、查重预检减少格式返工提高写作效率视频分镜分镜描述生成、镜头语言提示把文案快速转成分镜表格安全测试授权范围内的配置检查、风险点扫描规范化扫描流程输出统一报告这些技能本质上都是同一个套路模型做判断和表达脚本做计算和采集。你完全可以从一个现成技能反向拆解看看它的SKILL.md怎么组织、脚本怎么接参数模仿着改造出你自己的版本。4.3 API 模式与本地算力怎么选回到算力的问题。openclaw 支持多种模型后端接入 API 是最省事的方案不用操心 GPU、显存、量化这些问题适合个人快速体验。但如果你的使用场景涉及敏感数据或者团队希望把工具链内部化本地模型会更稳妥。实际操作中我建议先在 API 模式下把技能全部调通再切换到本地模型做回归测试这样能最快定位到“是技能脚本的问题还是模型理解力的问题”。5. 获取现成 Skills官方市场与第三方平台5.1 上哪找现成技能不想从零写技能的话最适合你的路线是去社区找现成的。常见的渠道包括 openclaw 官方仓库的 skills 子目录那里会维护一批基础技能GitHub 上搜openclaw skill或agent skills也能找到大量个人项目还有一些内容聚合站专门收集各类 AI 技能包。像 superpowers、reasonix 这类名字也在社区里很火搜索时可以加上frontend skills、writing skills等关键词缩小范围。如果你是第一次试水我建议不要贪多。先下载一个和手头工作直接相关的技能比如“前端开发 skills”或“论文写作 skills”装好、测通再慢慢扩充。技能装得太多反而会让模型选择困难想象一下一个工具箱里塞了 50 把形状差不多的螺丝刀你要找的那把永远在底层。5.2 装一个现成技能的完整流程装技能比写技能还简单但有三个细节容易被坑。第一步从可信来源把技能包下载到本地建议手动把压缩包解压到一个临时目录看清楚目录里有没有可疑脚本再继续。第二步把整个技能目录复制到~/.openclaw/skills下注意不要只复制SKILL.md脚本和资源文件都要一起复制。第三步重启或重载 openclaw再用openclaw skills list验证。为什么我特意强调“看清脚本”有人图省事直接在下那个技能目录里运行了安装脚本结果它默默改了一堆全局配置排查了大半天。技能来自第三方时先打开SKILL.md和主脚本扫一眼目的只是确认“它会在你授权范围内执行不会乱动系统”这个习惯值得长期保留。6. 排错实战我遇到过的五个坑6.1 WSL 环境安全检查失败围绕 openclaw 最多的问题就是 Windows 下打开终端准备执行命令时提示“无法安全验证 WSL2 环境。请在 PowerShell 中运行 wsl --status”。我第一次遇到这个以为是 openclaw 的包问题折腾了半天最后发现是笔记本上 Windows 功能没开完整。这个报错的实质是系统检测到 WSL 内核或者虚拟机平台没有正确启用不是 openclaw 本身的事。解决路径是这样的先按 WinR 输入optionalfeatures确认“适用于 Linux 的 Windows 子系统”和“虚拟机平台”两项都已勾选然后以管理员身份打开 PowerShell执行wsl --update再执行wsl --set-default-version 2最后重启电脑重开终端再次wsl --status应该就能看到正常状态。这个坑一旦踩平后面 node 环境和 openclaw 的安装会顺畅很多。6.2 技能放对位置却加载不出来第二种高频问题技能目录在SKILL.md 也在但openclaw skills list里就是看不到。我排查过几次九成原因出在三个地方文件名大小写必须是SKILL.md不是skill.md、YAML 元数据语法比如name带了空格、description分行缩进错误、目录权限服务器上常见当前用户没有读权限。可以用下面这行命令快速检查 YAML 是否合法python3 -c import yaml, pathlib; tpathlib.Path(SKILL.md).read_text().split(---)[1]; yaml.safe_load(t)另一个容易被忽视的原因是重复加载。如果你把一个技能同时放进了全局技能目录和项目级技能目录版本又是两份不同的openclaw 可能会先注册其中一个导致你改完文件却不生效。统一只保留一个来源才能避免混乱。6.3 Node.js 版本不匹配openclaw 跑在 Node 生态里版本不对的时候现象通常是启动后过不了几秒就崩或者技能列表偶尔加载失败。我的建议是直接用 nvm 管理 Node 版本装成 LTS 版然后在项目根目录执行node -v跟官方要求的版本号对比一下。一旦发现版本不匹配nvm install 20这类命令就能切换而不是去改系统全局的 Node。很多初学者急于求成下载完 Node.js 官网最新版就开跑其实“官网最新”不只是版本新它可能是奇数版稳定性反而不如 LTS。openclaw 这种需要长期跑的工具稳定优先。6.4 卸载 openclaw 要清干净问“怎么卸载 openclaw”的人也不少。如果你只是删掉安装目录就会残留配置文件和 PATH 环境变量后续重装时各种奇怪报错。正确做法是分三步先执行官方提供的卸载命令如果有然后把~/.openclaw配置目录整个删除最后检查 shell 的配置文件把安装时写入的 PATH 和 alias 手动移除。因为 openclaw 的技能目录就在~/.openclaw/skills下你积累的技能也会一起删掉删之前记得先备份想要留存的技能。6.5 Termux 手机版跑技能的局限在手机上用 Termux 安装 openclaw 确实可以跑我测试过一次但很快发现它更适合做轻量对话和简单技能比如“生成周报模板”“整理待办清单”这类不涉及系统权限的操作。到了需要访问存储卡、调用小部件、跑 GUI 工具的技能Termux 的权限模型会让它立刻失败。所以我的建议是手机端先安装开箱体验没问题但别把它当成完整替代品如果确实要在移动端用优先选择纯脚本、纯文本输出的技能。7. 把 Skills 变成团队资产的三条经验7.1 命名和描述是最重要的注释写技能写久了我越来越觉得description不是给模型看的技术注释而是整个技能的“入口文案”。结构上最好遵循这个技能能做什么 什么场景下使用 触发它的用户表达例子。我自己的模板是“当用户想做 X、提到 Y 关键词、或需要 Z 结果时使用本技能它可以输出 A、B、C”。听起来啰嗦但模型在语义匹配时确实更准。正文里还要写清楚“不做什么”。比如一个代码审查技能最好明确“不会修改代码不会自动提交”。边界写清楚模型在自动执行时胆子会更稳团队审阅时也更放心。7.2 用 Git 管理技能库技能本质上是一段代码加一份文档天然适合放进 Git 仓库。我们团队的做法是单独建一个skills仓库每个技能一个目录新增或修改都走 PR 评审。评审时关注三件事description是否清晰、脚本是否处理了异常情况、有没有写入危险操作。这样做的好处是技能不会“烂在某个人的本地目录里”任何新成员 clone 下来就能用。7.3 先解决小问题再做大而全这是我最想强调的一条不要一开始就设计一个万能技能。我看到太多人试图做一个“项目智能助理”技能结果里面塞了十几个子命令模型判断不过来最后每个功能都不好用。从“一个具体的、每天都会遇到的痛点”出发先让技能跑通再根据反馈迭代。我的项目体检技能最早只统计 TODO 数量后来才慢慢加了依赖检查和目录结构摘要但这种演进是好用的因为每一步都建立在真实使用基础上。我个人在实际使用中的一个体会是openclaw 的 Skills 扩展真正的难点从来不是写代码而是想清楚“模型负责什么、脚本负责什么”这条分工线。脚本越贴近确定性操作模型越能在它擅长的语义判断上游刃有余。你不需要一次做出完美技能先做一个能用的然后让它替你干几周脏活自然就知道下一个版本该改哪里。最近我的技能目录已经攒了二十多个小技能从项目体检到文件批量改名都有几乎没有哪个是一天写出来的全是用了改、改了用的过程沉淀下来的。希望这一章能帮你把第一个技能顺利跑起来也期待看到你的技能列表越长越顺手。