很多人第一次把 OpenClaw 跑起来的时候都会有类似的疑惑它能对话、能写代码、能查资料看起来啥都能干可真要让它按行业习惯批量处理文件、按照团队模板生成报告、或者盯住某个特定流程它立刻就露怯了。不是它笨而是它缺了一个针对你具体场景的 Skill。OpenClaw 的 Skill 机制本质上就是给通用 Agent 装上专业插件的方式。一个 Skill 可以是一段 Markdown 指令可以是一个 Python/Shell 脚本也可以是指令加脚本的组合。你把某个领域的处理流程封装进去之后对 OpenClaw 说一句用 XX 技能处理一下它就能按你写好的规则一步步执行。这篇文章我会从环境准备开始讲清楚 Skill 的目录结构、SKILL.md 的编写规范、调试排错思路以及接入本地模型和 Teams 的进阶玩法。整个过程以一份文件自动整理 Skill为主线你可以直接照着抄。1. 为什么 OpenClaw 需要自定义 Skill从开箱即用到专属能力的最后一公里1.1 通用 Agent 的瓶颈在哪里装好 OpenClaw 之后它默认具备的能力其实是通用对话 基础工具调用。它能读懂问题能调起一些内置工具但它不知道你所在行业的具体术语、不知道你们团队的模板、不知道你电脑里那些文件应该按什么规则归档。这就好比招了一个名校毕业生基础素质很好但没经过岗前培训没法直接让他上手处理专业业务。Skill 起的作用就是岗前培训。它不是简单把一堆提示词塞给模型而是把一整套可执行的知识沉淀成标准文件遇到什么情况触发、按什么步骤处理、每一步调用什么脚本、输出什么格式全部白纸黑字写清楚。模型拿到 Skill 之后等于拿到了一本带练习册的岗位手册。所以那些觉得OpenClaw 不够懂行的人我第一反应往往是先问他你的 Skill 库里装了什么如果还是空的那问题多半出在你自己身上而不在 Agent 身上。1.2 Skill 的组成一个目录三样东西在我目前用的 OpenClaw 版本里一个 Skill 就是一个目录放在skills/下面。目录里核心是三样东西SKILL.md技能的说明文件和操作手册Agent 首先读它。scripts/可选放 Python、Shell、Node.js 脚本负责真正执行文件操作、数据处理等任务。resources/可选放模板、参考文档、示例配置。举个例子一个周报生成 Skill的目录结构是这样skills/ └── weekly-report/ ├── SKILL.md ├── scripts/ │ ├── collect_git_log.py │ └── render_report.py └── resources/ └── report_template.mdAgent 在运行这个 Skill 时先读SKILL.md理解任务流程再按需调用scripts/里的脚本完成计算和渲染最后根据resources/里的模板输出成品。这种结构的好处是知识Markdown和逻辑脚本分离模型负责判断和调度脚本负责精确执行。两条线各干各的最终汇合成一个可靠的结果。1.3 Skill 与插件、工具的关系有朋友问过OpenClaw 的 Skill 跟插件、Tool工具有什么区别我梳理下来是这么理解的Tool工具Agent 可以调用的原子能力比如读文件写文件发请求通常由系统内置。插件Plugin外部服务或运行时能力的集成比如接入某个数据库、某个 API 网关。Skill技能一套在什么场景下按什么顺序把哪些 Tool 和脚本组合起来完成任务的完整流程定义。一句话概括Tool 是零件Skill 是工艺规程。工艺规程告诉你什么时候用哪个零件、怎么装配最终产出一个合格产品。所以如果你觉得 OpenClaw不专业别急着换更强的模型先检查一下自己的 Skill 库是不是太单薄了。市面上那些热门讨论里无论是 Codex、Cursor 还是 WorkBuddy 里的 Skill基本都遵循同样的分层逻辑想通这一点工具换来换去也不会慌。2. 部署与目录结构先把 OpenClaw 跑起来再说 Skill 开发2.1 Windows 与 Ubuntu 的安装选择开发 Skill 的前提是先把 OpenClaw 跑通。我在 Ubuntu 和 Windows 两种环境下都部署过经验是如果手头是 Windows强烈建议走 WSL2而不是直接在 Windows 上硬跑。原因有两个一是 OpenClaw 的很多 Skill 脚本是 Shell/Python 写的在 Linux 子系统的行为更一致二是路径、权限、换行符这些坑在 WSL2 里会明显少很多。Ubuntu 下的安装相对直白先装 Node.js建议 LTS 版本然后用 npm 全局安装 OpenClaw 的命令行工具初始化配置目录。Windows 下则是先启用 WSL2装好 Ubuntu 发行版之后所有操作都在 WSL 的终端里完成。至于网上问得多的node.js 官网下载 OpenClaw其实是两步操作Node.js 从官网下载安装OpenClaw 再用 npm 安装两者不是一回事。提示无论哪种方式安装完成后先跑一次openclaw doctor或等价的诊断命令检查环境把 Node 版本、技能目录路径、模型连接状态都确认一遍再开始开发。2.2 排查无法安全验证 WSL2 环境从 wsl -- status 开始在 Windows 上部署的人大概率见过这么一条提示OpenClaw 无法安全验证 WSL2 环境请在 PowerShell 中运行wsl -- status。我第一次遇到时也愣了一下后来发现绝大多数情况是两类问题。第一类是 WSL 版本不对。有些机器默认跑的是 WSL1或者系统里同时存在新旧两个发行版。在 PowerShell 里执行wsl --status看输出如果显示默认版本是 1就执行wsl --set-default-version 2切换。如果发行版本身是 v1需要wsl --set-version 发行版名 2做一次转换。第二类是 PowerShell 和 WSL 的环境变量互相干扰。OpenClaw 在 Windows 上启动时会通过 WSL 调用内部命令如果 PATH 里有特殊字符、中文字符或者说引号没有转义校验就会失败。我处理过一例最后发现是 Windows 用户名包含中文导致 WSL 的 HOME 路径中带着中文目录Node.js 在解析配置文件时直接报错。解决方法是在 WSL 里把工作目录切换到纯英文路径或者新建一个英文用户目录。注意这类环境问题跟 Skill 本身没有关系但如果不解决后面开发 Skill 时会一直报各种莫名其妙的问题。我的建议是花十分钟先把地基夯实不要急着写技能。2.3 认识 Skills 目录与内置 Skill 示例OpenClaw 的配置目录一般位于~/.openclaw/Skills 目录在~/.openclaw/skills/。如果是项目级使用也可以在项目根目录建skills/这样这个项目独有的技能就不会污染全局配置。新装好的 OpenClaw 通常带几个内置 Skill我建议别急着删先逐个读一遍它们的SKILL.md。我自己的习惯是把内置 Skill 当成官方教科书。里面会展示元数据的标准写法、指令描述的语气、脚本的接入方式。开发初期最稳妥的路子就是模仿把其中一个 Skill 完整复制一份改成自己的只改 name 和 description这样最不容易踩格式坑。等理解透了再去设计复杂的执行链路。3. SKILL.md 的编写规范一个 Skill 的说明书该怎么写3.1 frontmatter 元数据name、description、triggers、versionSKILL.md的开头是 YAML 格式的 frontmatter相当于给这个技能贴的标签。OpenClaw 的模型调度逻辑很大程度上依赖这段元数据来决定什么时候调起这个 Skill。一段典型的 frontmatter 长这样--- name: file-organizer description: 根据文件类型和命名规则把混乱目录整理成带日期归档结构适合下载目录、桌面清理等场景。 triggers: - 整理文件 - 目录太乱 - 归档 version: 1.0.0 author: yourname dependencies: - python3 ---这里最需要注意的是description和triggers。模型在看到用户请求时会先扫描所有 Skill 的描述和触发词判断当前请求是否和这个 Skill 匹配。所以描述要写清楚两件事这个 Skill 是干什么的适合在什么场景下用。避免只写文件整理工具这种笼统描述而是写把下载目录里的安装包、图片、文档按扩展名分类并移动到以月份命名的子目录适合临时文件堆积的清理场景。触发词尽量贴近用户真实口语比如桌面太乱了帮我归档一下这些都比整理两个字容易被命中。3.2 正文指令的写作技巧给 Agent 看的操作手册frontmatter 下面的正文是给 Agent 看的操作手册。这里很多人会把一个错误把正文写成给人类看的 README介绍来龙去脉、设计理念。Agent 真正需要的不是理念而是步骤清单、判断规则、边界条件。我的经验是正文越像给实习生写的 check list执行效果越好。我打磨过几个 Skill 之后总结出的正文结构一般是四段任务目标一句话说清这个技能要产出什么。输入来源数据从哪里来比如用户提供的路径、某个目录下的文件、或者脚本的输出。执行步骤按顺序列出每一步尽量具体比如先列出目录下所有扩展名按类型分组再把 .zip 和 .exe 移动到 archives/当前月份 目录。约束与回退什么情况不要做比如不要移动正在被占用的文件找不到匹配类型时停留在原地并报告。另外一个小技巧是在正文里给出一个完整的输入-输出示例。模型对示例的模仿能力非常强一个具体例子比十句抽象描述管用。比如你希望在收到整理下载目录时把图片移动到images/2025-04/就把这个映射关系写进示例里。这样即便模型在某些步骤上犯迷糊也能依照示例的路径风格走下去。3.3 什么场景适合用脚本什么场景只写 Markdown不是所有 Skill 都要带脚本。我自己的划分标准是如果任务只需要判断 搜索 按已有规则回答比如帮我按团队模板写一份项目复盘那纯 Markdown 就够了如果任务涉及批量操作、复杂计算、调用外部 API就一定要写脚本。原因是模型的强项是语义理解和生成弱项是精确执行。让模型逐个处理一千个文件的命名它既慢又容易出错但让 Python 脚本去跑毫秒级完成且结果稳定。Skill 的架构就是让两者各干各的模型负责理解意图、编排步骤、处理例外情况脚本负责确定性较强的那部分工作。我在实际项目中踩过一回当时想做一个批量压缩图片的 Skill一开始只写了 Markdown 指令让 Agent 自己用内置工具去压缩。结果二十张图它压了十分钟还漏了两张。改成调用scripts/compress_images.py之后整个过程几秒钟而且每一步都有日志输出。从此之后凡涉及批量文件操作的我必然写脚本。4. 实战开发从零写一个文件整理 Skill完整可抄作业4.1 需求拆解与设计下面进入正题我们做一个能实际跑起来的 Skill文件自动整理器。需求定成三条扫描用户指定的目录按扩展名把文件分组。图片、文档、压缩包、安装包各归入对应分类目录。目录按月归档比如2025-04并将结果输出为一份清单。为什么选这个例子因为它综合了 Markdown 指令、Python 脚本、文件系统操作、结果反馈这几个环节麻雀虽小五脏俱全。做完之后你就完全清楚一个完整 Skill 是怎么从零到一跑起来的。4.2 创建 Skill 目录和 SKILL.md先建目录mkdir -p ~/.openclaw/skills/file-organizer/{scripts,resources}然后写SKILL.md--- name: file-organizer description: 按扩展名和月份归档指定目录中的文件生成整理报告适合清理下载、桌面、临时目录。 triggers: - 整理文件 - 清理目录 - 归档文件 version: 1.0.0 dependencies: - python3 --- # 任务目标 将指定目录下散乱的文件按类型分组并移动到以月份命名的归档目录中最后输出整理报告。 # 输入来源 - 用户提供目录路径如果没有提供默认使用当前工作目录。 # 执行步骤 1. 调用 scripts/file_organizer.py传入目录路径作为第一个参数。 2. 脚本会读取目录下所有普通文件不递归子目录。 3. 按扩展名映射到分类图片(images)、文档(docs)、压缩包(archives)、安装包(installers)、其他(misc)。 4. 目标目录为 原路径/分类/YYYY-MM/移动完成后输出 JSON 格式的报告。 5. 将报告中的文件数量、占用空间、移动明细整理成自然语言回复给用户。 # 约束与回退 - 不处理目录、隐藏文件、符号链接。 - 如果目标路径已存在同名文件不覆盖保留源文件并记录到报告。 - 没有任何可移动文件时直接回复目录已经很干净了。 # 示例 用户说整理一下 ~/Downloads 应执行 python3 ~/.openclaw/skills/file-organizer/scripts/file_organizer.py ~/Downloads 然后回复 已将 12 个文件归档到 images/2025-045个、docs/2025-044个、archives/2025-043个共释放空间约 350MB。你可能会注意到SKILL.md里把脚本调用方式写得非常明确甚至连命令都写出来了。这是因为 Agent 在执行 Skill 时更喜欢照葫芦画瓢而不是自己发挥。写得越具体执行偏差越小。4.3 编写辅助脚本接着创建scripts/file_organizer.py实现文件移动和统计逻辑#!/usr/bin/env python3 import json, os, shutil, sys from collections import defaultdict from datetime import datetime CATEGORY_MAP { images: [.jpg, .jpeg, .png, .gif, .webp, .svg], docs: [.pdf, .docx, .doc, .txt, .md, .xlsx, .pptx], archives:[.zip, .tar, .gz, .rar, .7z], installers:[.exe, .msi, .dmg, .AppImage, .deb], } def categorize(ext: str) - str: for cat, exts in CATEGORY_MAP.items(): if ext.lower() in exts: return cat return misc def main(): root sys.argv[1] if len(sys.argv) 1 else os.getcwd() month datetime.now().strftime(%Y-%m) report {moved: [], skipped: [], total_moved: 0, total_size_mb: 0.0} for entry in os.scandir(root): if not entry.is_file() or entry.name.startswith(.): continue if os.path.islink(entry.path): continue cat categorize(os.path.splitext(entry.name)[1]) dest_dir os.path.join(root, cat, month) os.makedirs(dest_dir, exist_okTrue) dest_path os.path.join(dest_dir, entry.name) if os.path.exists(dest_path): report[skipped].append({file: entry.name, reason: 目标文件已存在}) continue size entry.stat().st_size / (1024 * 1024) shutil.move(entry.path, dest_path) report[moved].append({file: entry.name, category: cat, dest: dest_path}) report[total_moved] 1 report[total_size_mb] size print(json.dumps(report, ensure_asciiFalse, indent2)) if __name__ __main__: main()这里有几个细节值得说明。第一ensure_asciiFalse是为了让中文文件名在 JSON 里可读避免 Agent 拿到一堆转义序列后一脸茫然。第二不覆盖同名文件是安全底线宁可让报告里多一个 skipped也不能把用户的重要文件弄丢。第三脚本只输出 JSON不做任何多余的提示因为它的下游是 AgentAgent 会负责把 JSON 翻译成自然语言回复。4.4 测试 Skill 的完整流程写完之后先别急着重启 OpenClaw建议先在终端里验证脚本python3 ~/.openclaw/skills/file-organizer/scripts/file_organizer.py ~/Downloads如果输出结果是合法的 JSON再在 OpenClaw 里测试完整链路。我习惯的做法是开一个新的会话明确说使用 file-organizer 技能整理路径 /tmp/test_dir然后观察它是否调起了这个 Skill、是否按SKILL.md的步骤执行、回复格式是否符合预期。第一次跑的时候如果 Agent 干脆不调用这个 Skill最可能的原因是触发词和描述写得不够明确。把用户的习惯说法补充到triggers里比如把下载文件夹弄干净然后重试。如果 Agent 调用了但是脚本报错那就复制终端里的错误信息通常问题出在路径权限或依赖缺失上。测试通过之后再拉到真实目录里跑一遍确认没有意外情况。5. 调试链路与常见报错编码 247、WSL 校验失败这类问题的根因5.1 把 Skill 跑挂的三类原因开发 Skill 过程中遇到的报错我总结下来无非三类环境类、编码类、逻辑类。环境类报错的典型代表是WSL2 环境无法安全验证以及 Python/Node 依赖没装好编码类报错的典型代表是脚本文件本身编码不对Windows 下特别容易触发逻辑类报错则是脚本自身 bug比如路径判断出错、正则匹配错误。这三类问题有一个共性它们往往跟 Skill 的内容无关而跟运行环境和文件格式有关。所以排查时先别怀疑业务逻辑先把环境变量、换行符、编码格式这几个基础项检查一遍。我见过太多人一出问题就去翻 Agent 的提示词实际上问题出在记事本把文件存成了带 BOM 的 UTF-8。5.2 一个真实的退出码 247排查过程有个朋友在群里贴过一次报错说他的 Skill 脚本在 Ubuntu 上跑得好好的换到 Windows WSL2 环境就失败错误信息只有一个冷冰冰的退出码 247。他一度以为是 OpenClaw 的问题甚至打算重装整个环境。我让他做的第一件事是直接在 WSL 终端里手动运行那个脚本。结果发现脚本单独跑完全正常。这就说明问题不在业务逻辑而在 OpenClaw 调用脚本的环节。接着我让他看SKILL.md里写的调用命令发现命令里用了 Windows 风格的绝对路径比如C:\Users\...。在 WSL 里这个路径是不存在的正确写法应该是/mnt/c/Users/...或者直接写 WSL 内的路径。这就导致脚本找不到文件退出码变成 247。当时我们的解决方案很简单全部改用相对路径让脚本在 Skill 目录的上下文里执行或者用环境变量传入 HOME 路径。我后来在处理 OpenClaw 配置时也养成了一个习惯所有 Skill 脚本都不要硬编码绝对路径统一从参数、环境变量或配置文件中读取路径。这样同一个 Skill 换一台机器照样能跑。5.3 建议的调试工作流我自己现在调试 Skill 的流程基本固定为四步独立验证脚本在 Shell 里手动执行确认脚本本身没问题。查看详细日志OpenClaw 一般有--verbose或-d参数打开后能看到 Agent 到底调了哪个 Skill、传了什么参数、脚本输出是什么。拆掉 Markdown 的自动化人工模拟假装自己是 Agent按照SKILL.md的步骤手动操作一遍通常能发现指令描述不清的地方。逐字对比编码与换行在 Windows 下尤其注意脚本和 Markdown 一律保存为 UTF-8 无 BOM换行符用 LF。Windows 自带记事本的默认编码和 CRLF 经常是元凶。这里展开说一下编码问题。Git Bash 和 WSL 对 UTF-8 带 BOM 的文件容忍度还行但 Node.js 的某些解析器会把 BOM 当成不可见字符混入内容导致 frontmatter 解析失败或脚本首行出现意外字符。在 Ubuntu 上用file命令可以快速查看编码file SKILL.md如果输出里有 with BOM 字样就说明多了三个字节的文件头。用dos2unix SKILL.md可以顺便把换行符一起转成 LF。5.4 防止同类问题给文件做一次体检为了避免同一个问题反复出现我给自己定了一个文件体检清单每次写完 Skill 都过一遍检查项正确状态错误典型文本编码UTF-8 无 BOMUTF-8 with BOM换行符LFCRLF路径风格与运行环境一致Windows 路径写进 WSL脚本权限可执行或通过 python3 调用没有权限依赖声明frontmatter 中声明运行时报 ModuleNotFoundError这些检查项看起来琐碎但确实能省掉后面大量调试时间。尤其是当你准备把 Skill 分享给同事或开源出去的时候文件的编码和换行直接决定了别人拿过去能不能跑。6. 进阶玩法接入 Qwen 模型、Teams 通知与多 Skill 编排6.1 给 Skill 绑定本地模型以 qwen2.5-3b 为例很多用户关心 OpenClaw 能不能用开源模型尤其是把 Skill 跑在本地、保护数据隐私的场景。在我的使用经验里OpenClaw 的模型层是可以通过配置切换的。如果你手头资源有限又想让 Skill 在低延迟环境下工作可以在配置文件中把模型提供方指向一个兼容接口并指定qwen2.5-3b这样的轻量模型。基础配置类似这样model: provider: openai-compatible base_url: http://127.0.0.1:8000/v1 name: qwen2.5-3b技能本身不会因为换了模型就失效因为 Skill 的逻辑主要靠SKILL.md和脚本驱动。但要注意轻量模型对指令的遵循能力弱一些。如果你的 Skill 步骤特别复杂、约束特别多小模型可能漏步骤。我的建议是给纯 Markdown 类 Skill 准备一个精简版描述把关键步骤压缩成三条以内而带脚本的 Skill 则不用太担心因为重活都在脚本里模型只负责传参和读结果。6.2 把 Skill 暴露到 Microsoft Teams团队协作场景如果你需要让整个团队用上你写的 Skill接入 Microsoft Teams 是一个很实用的路径。OpenClaw 支持配置机器人应用让成员在 Teams 聊天里直接 机器人来调用 Skill。大致需要三步在 Teams 开发者后台注册一个机器人应用拿到 App ID 和密码。在 OpenClaw 配置里启用 Teams 通道填入机器人的凭据。运行 OpenClaw 时指定通道类型启动后机器人自动在 Teams 中上线。接入之后团队成员的对话会被送到 OpenClaw由它根据对话内容匹配 Skill。比如大家习惯在群里发机器人 把销售群里的周报归档一下如果模型判断这个请求命中了file-organizer或者weekly-report的触发词它就会把对应 Skill 跑起来再把结果贴回到群里。这样做的好处是Skill 的开发调试可以集中在一台机器上完成但价值能被整个团队共享。我个人的体会是这一步对非技术团队尤其友好。成员不需要装客户端、不需要配环境只会在聊天框里喊一声帮我归档就行。技术细节全部隐藏在 Skill 内部。如果你觉得自己的 Skill 只给自己用有点可惜Teams 通道是最值得折腾的一个方向。6.3 用多个 Skill 组合完成复杂任务最后一个进阶思路是组合。单个 Skill 能做的事有限但把几个 Skill 串起来就能完成一个跨步骤的完整业务流。比如我做过一个项目周报自动生成的流程它拆成三个 Skillgit-log读取指定仓库的提交记录输出结构化 JSON。report-render把 JSON 填进周报模板生成 Markdown。team-notify把 Markdown 发送到 Teams 频道。这三个 Skill 可以独立运行也可以由一个编排 Skill 来调用它们。编排 Skill 的SKILL.md里会写明先运行 git-log 拿到数据再传给 report-render 生成草稿最后调用 team-notify 发布。OpenClaw 在运行编排 Skill 时会自己完成 Skill 间的数据传递。这种组合思路的价值在于复用。下次遇到一个新场景不需要从零写一个巨型 Skill而是看看已有的 Skill 库能不能拼出答案。就像搭积木一样一个负责取数、一个负责渲染、一个负责通知按需组合即可。写到这里我发现很多来找我咨询的人其实不是卡在技术细节上而是卡在不敢动手上。总担心写出来的 SKILL.md 格式不标准、脚本不够高效于是一直在看教程。我的建议是先做一个哪怕只有十行脚本的 Skill跑通整个创建目录 - 编写说明 - 调用脚本 - 看到结果的循环。这个循环打通之后后面所有 Skill 的开发都只是往同一条流水线上加新工序而已。我自己在 WorkBuddy、Codex 这类同样支持 Skill 概念的工具里也做过迁移发现只要掌握了这套元数据 操作手册 脚本的组合思路换个平台成本很低。所以别把这篇当成 OpenClaw 的专属教程它更像是一套 Agent 技能工程的通用方法论。你完全可以照着这个思路把你手头重复做了无数遍的流程一个接一个地变成可复用的 Skill然后让 Agent 从啥都能聊变成真能干活。