这段时间我一直在折腾 OpenClaw把日常智能体的工作流从什么都丢给云端慢慢迁回到本地系统上。OpenClaw 是一个开源的智能体框架定位介于大模型和外部世界之间而 Skills 是它给智能体准备的一套可复用能力包把一段操作流程、一个脚本、一组工具调用打包成独立单元让模型在需要的时候自动发现并调用直接操作你本机的文件、命令和服务。这篇文章不讲虚的就围绕对接本地系统这条主线把 Skills 的机制、完整技能包的写法、以及我踩过的坑全部过一遍。适合已经跑起来 OpenClaw、正想着让它干点真活的人也适合还没上手但想评估这套方案值不值得入局的读者。1. 先搞清楚 OpenClaw 和 Skills 的定位再谈直接对接1.1 OpenClaw 解决的是模型到动作这一段大模型本身只负责生成文字它不碰文件系统不执行命令也摸不到你电脑上的任何服务。真正让智能体动手干活的是外面的那层执行框架。OpenClaw 干的就是这件事它把模型接进一个可以调用外部工具的运行环境里让模型在推理过程中决定下一步要调什么、传什么参数然后由框架去真正执行再把执行结果回传给模型继续判断。很多人一开始接触 OpenClaw 会把它理解成又一个聊天机器人外壳这个理解窄了。它的核心价值在于连接连接模型和工具连接模型和本地系统连接模型和各种外部 API。而所有连接里和本地系统的对接是最能体现掌控感的一环。因为只有本机上的资源是真正属于你的磁盘上的文件、跑在 localhost 的数据库、已经装好的命令行工具这些都不需要上传不需要等第三方服务也没有数据出机的顾虑。OpenClaw 通过 Skills 把这一层连接做得比较干净这也是我花时间研究它的原因。1.2 Skills 到底是什么一份手册加一套工具Skills 翻译过来是技能但在 OpenClaw 的语境里它更像是一个带说明书的工作岗位。一个 Skill 通常包含三部分一份描述文件告诉模型这个技能是干嘛的、什么时候用、怎么用一个或多个可执行脚本真正干活的部分以及可选的配置项比如 API 地址、默认参数、权限白名单。你可以把一个 Skill 理解为餐厅里的招牌菜操作卡卡片上写了这道菜适合什么客人、需要哪些食材、出餐步骤是什么后厨照着卡片就能稳定复现。模型就是那个看卡片的人它不会凭空知道你会写什么样的脚本但你一旦把脚本和说明打包成 Skill 放进 OpenClaw它就能在合适的场景下主动调用。这一点和 IDE 插件、浏览器扩展有本质区别。插件是固定入口用户得自己去点按钮Skills 是模型主动发现的能力清单它读到你这句话里隐含的需求对比自己手头有哪些 Skill 的描述命中之后才触发。也就是说Skill 的触发逻辑不在代码里写死而是靠描述文本去引导模型的判断。这个机制决定了写 Skill 时描述和触发词的设计和脚本本身一样重要。2. Skills 的运行机制从模型决策到本地执行2.1 一次完整调用的链路我在第一次写 Skill 之前最大的困惑是模型到底怎么知道我有这个技能。后来把调用链捋了一遍才明白整个过程是这样的用户提出需求后模型会先做一轮意图判断同时把自己身上挂载的 Skill 列表过一遍。这个列表里每个 Skill 只展露它的名称、描述、触发词这类元信息不会把所有脚本内容都塞进上下文。模型根据描述判断是否命中如果命中它会按照 SKILL.md 里的指引选择要执行的脚本和参数。OpenClaw 框架收到指令后在本地起一个子进程去跑对应的 Python、Shell 或其他可执行文件捕获标准输出和返回码把它作为工具结果交还给模型。模型根据结果组织最终的回复或者决定要不要继续调用下一个 Skill。这里面有一个容易被忽略的点模型本身并不运行脚本它只是下达指令真正在本地执行的是 OpenClaw 框架。这就像调度中心打电话给车间这批订单按 A 方案处理车间工人动手做完回报结果。模型是调度员你的本机是车间Skills 就是车间里那套已经调好的工装夹具。理解了这条链路后面排查问题就顺了技能没触发先看模型有没有读到描述触发了但没执行再看框架有没有找到脚本执行了但结果不对才轮到查脚本本身的逻辑。2.2 Skill 的装载与发现规则社区目前比较通行的做法是把所有 Skill 放在一个统一目录下比如~/.openclaw/skills/每个 Skill 单独一个子目录。OpenClaw 在启动或者执行 reload 操作时会扫描这个目录把每个 Skill 的元信息注册到当前会话里。第三方 Skill 可以通过包管理器或者npx skills add这类命令安装自己写的 Skill 手动放进目录就行不需要额外注册。有几个细节值得注意。第一目录名和 Skill 名最好保持一致且使用英文小写加连字符避免在某些文件系统上出现大小写问题。第二同名 Skill 会互相覆盖如果你手动放了一个download-organizer又用命令装了一个同名的最终生效的是谁取决于扫描顺序这件事非常容易把人绕晕。第三每次新增或修改 Skill 后需要重启 OpenClaw 或触发热加载当前会话里已经构建好的工具列表不会自动刷新。我一开始写完 Skill 直接对话发现模型完全感知不到折腾了半天才意识到是没 reload。3. 实操从零写一个对接本地文件系统的 Skill3.1 场景拆解让智能体整理下载目录理论讲再多不如动手写一个。我选的第一个练手场景是整理下载目录每周我的 Downloads 文件夹都会堆积各种文件截图、安装包、PDF、压缩包混在一起。这个场景适合做第一个 Skill原因有三操作对象是本机文件系统效果肉眼可见脚本逻辑简单不涉及外部依赖风险可控先做只读扫描再加移动归档。需求拆解下来就三条扫描指定目录下的所有文件按扩展名归类到对应的子目录图片、文档、压缩包、可执行文件、其他输出一份归档报告。为了安全我要求脚本默认支持演练模式dry-run只打印将要执行的操作不真正移动文件。这样模型在不确定的时候可以先跑一遍演练确认无误再执行真实归档。3.2 技能包的目录结构我按社区比较通用的结构组织这个 Skill~/.openclaw/skills/ └── download-organizer/ ├── SKILL.md ├── config.yaml └── scripts/ ├── organize.py └── manifest.pySKILL.md是给模型看的说明书config.yaml存放用户自定义配置scripts/下面放真正的执行脚本。这里我特意把生成清单和归档移动拆成两个脚本manifest.py只负责扫描和输出报告是只读操作organize.py负责实际移动文件。拆开的好处是模型可以先生成清单给用户确认再执行修改类操作降低误操作风险。3.3 SKILL.md 的写法SKILL.md 的开头是 YAML 格式的元信息后面是正文说明。我的写法如下--- name: download_organizer description: 扫描并整理本地下载目录按文件类型归档到子目录支持演练模式。适合用户要求整理下载文件清理下载目录时使用。 version: 1.0.0 trigger: 下载, 整理, 归档, 文件分类, 清理文件夹 auto: false ---正文部分我会写清楚三块内容。第一块是使用场景和使用限制只处理配置文件中指定的目录绝不允许操作系统目录第二块是操作步骤指引先运行 manifest.py 生成清单再询问用户是否执行 organize.py第三块是脚本参数说明告诉模型每个脚本支持哪些 flag、输出格式是什么。写完 SKILL.md 之后我才明白这个文件本质上是在教模型怎么用你的脚本。脚本写得再好如果说明文档不清楚模型就可能传错参数、用错顺序。所以写描述时要把自己当成一个完全不懂这个脚本的新人把所有隐含假设都写出来。3.4 背后的 Python 脚本organize.py的核心逻辑不复杂但有几个细节我在写的时候特别注意。第一个是路径安全使用pathlib处理路径而不是字符串拼接第二个是冲突处理目标目录里如果已有同名文件就在文件名后面加时间戳后缀不能直接覆盖第三个是跨目录移动用shutil.move它会自动处理跨文件系统的情况比os.rename稳。脚本主体大概长这样#!/usr/bin/env python3 import argparse import json import shutil import sys from datetime import datetime from pathlib import Path TYPE_RULES { images: {.jpg, .jpeg, .png, .gif, .webp, .svg}, documents: {.pdf, .doc, .docx, .xls, .xlsx, .ppt, .pptx, .md, .txt}, archives: {.zip, .rar, .7z, .tar, .gz}, executables: {.exe, .msi, .dmg, .appimage, .deb}, code: {.py, .js, .ts, .go, .rs, .java, .c, .cpp}, } def classify(path: Path) - str: ext path.suffix.lower() for category, extensions in TYPE_RULES.items(): if ext in extensions: return category return others def organize(target: Path, dry_run: bool True) - dict: if not target.is_dir(): raise ValueError(f目标路径不存在或不是目录: {target}) moved [] skipped [] for item in target.iterdir(): if not item.is_file(): continue category classify(item) dest_dir target / category dest_dir.mkdir(exist_okTrue) dest dest_dir / item.name if dest.exists(): dest dest_dir / f{item.stem}_{datetime.now().strftime(%Y%m%d_%H%M%S)}{item.suffix} if dry_run: moved.append({from: str(item), to: str(dest)}) else: shutil.move(str(item), str(dest)) moved.append({from: str(item), to: str(dest)}) return {dry_run: dry_run, moved_count: len(moved), moved: moved} if __name__ __main__: parser argparse.ArgumentParser(description整理下载目录) parser.add_argument(--target, requiredTrue, help要整理的目录) parser.add_argument(--dry-run, actionstore_true, help演练模式只输出计划不执行) args parser.parse_args() try: result organize(Path(args.target), dry_runargs.dry_run) print(json.dumps(result, ensure_asciiFalse, indent2)) except Exception as exc: print(json.dumps({error: str(exc)}, ensure_asciiFalse), filesys.stderr) sys.exit(1)这里我特意让脚本输出 JSON 结构化数据而不是一段花里胡哨的文字。模型解析 JSON 的可靠性远高于解析散装文本它拿到moved_count和moved列表后可以直接生成清晰的总结。这个习惯我在后面写所有 Skill 时都保留了算是踩了不少坑之后总结出来的最佳实践。manifest.py更简单只负责扫描目录、按分类统计文件数量和大小同样输出 JSON。模型在真正动手之前先看清单和用户确认下载目录里有 12 个文件其中 5 个图片、3 个压缩包要归档吗用户体验会好很多。3.5 本地跑通测试Skill 写完之后不能直接丢给模型先把脚本本身在终端里跑通。我的测试顺序是先用小样本目录做 dry-run确认输出 JSON 正确再检查分类规则有没有漏网之鱼最后在真实目录上先演练、再执行。脚本没问题之后把整个目录放到~/.openclaw/skills/下重启 OpenClaw 让新 Skill 被装载。然后在对话里输入帮我看看下载目录里都有什么模型应该会触发download_organizer并运行manifest.py。如果这一步没有触发优先检查 SKILL.md 里的description和trigger有没有覆盖用户可能的说法。我最初写的是扫描并整理下载目录但实际对话里用户更常说帮我清理一下下载文件夹加了这个说法之后触发率明显提升。4. 本地系统对接的三个高频场景4.1 调用命令行工具文件操作是本地系统对接的入门命令行工具调用则是进阶。很多本机工具干起活来比手写脚本高效得多比如git、ffmpeg、imagemagick。把这类工具包成 Skill 有个好处模型不需要记住复杂的命令行语法它只需要读 SKILL.md 里的参数说明按模型自己的理解去组合。我写过一个小众但特别实用的git_summarySkill核心逻辑就是依次执行git status、git log --oneline -10、git diff --stat把结果汇总成一段简明的工作进度报告。这个 Skill 本身没有太多技术含量但省去了我每天手动敲这三条命令的重复劳动。写这类 Skill 时最需要注意的是返回码处理脚本里要判断subprocess.run的返回码命令失败时把错误输出原样返回给模型而不是让它看到一段 Python 堆栈。模型对英文报错的理解能力远强于对 Python 堆栈的理解能力。4.2 对接本地数据库服务业务开发场景里让智能体直接查本地数据库是刚需。无论是开发环境的 MySQL还是本地跑的 SQLite都可以通过 Skill 暴露给模型。这里我有一条很重要的安全建议默认给 Skill 配置一个只读账号连接配置放在config.yaml里而不是写死在 SKILL.md 的正文中。因为 SKILL.md 是要作为上下文喂给模型的里面出现数据库密码就等于把凭据放进了对话历史这在本地虽然风险可控但一旦你后面把会话同步到其他地方就很可能泄露。我常用的写法是让 Skill 调用一个封装好的查询脚本脚本从config.yaml读取连接信息执行模型生成的 SQL并且默认加LIMIT限制返回行数。模型不像人那样有表可能很大的直觉如果不加限制一条SELECT * FROM orders能把整个内存打爆。脚本里统一加上LIMIT 200既保证了功能又兜住了底线。4.3 批量文件处理与日志分析第三个高频场景是日志分析和批量处理。这类任务的共同特点是数据量大、格式固定、人工做又慢又烦但脚本逻辑往往很简单。我曾经用 OpenClaw 排查过一台开发机的磁盘占用问题Skill 做的事情就是遍历指定目录、统计每个子目录的大小、按大小排序输出前十。模型拿到结果后自动推断出是 node_modules 目录堆积过多整个过程我只负责确认。日志分析类的 Skill 我建议把采样和全量分析分开。第一次调用先跑一个只读的采样脚本输出日志的行数、时间范围、错误关键词统计让模型形成初步判断需要深入时再跑全量解析脚本。这样可以避免模型一上来就试图读完整个 GB 级日志文件既慢又浪费 token。这个思路本质上和数据库查询先看EXPLAIN是一个道理先用最廉价的信号建立判断再决定要不要下重手。5. 常见问题与排查技巧实录5.1 模型压根不触发 Skill这是新手遇到最多的问题也是最容易让人怀疑人生的时刻。我总结下来主要原因有三个。第一Skill 没被正确装载检查目录路径和 reload 操作第二description和trigger写得和用户实际表达差异太大模型对比之后认为没有匹配项第三模型本身的能力设置或者上下文长度限制导致工具列表被截断后面的 Skill 根本看不到。排查时可以按这个顺序来先确认 OpenClaw 的日志里有没有加载 Skill 的记录再在对话里直接问模型你现在有哪些可用技能看它能不能说出你的 Skill 名称如果这一步都过不了问题就出在装载环节。如果模型能说出名称但不主动用问题就出在描述文本上把用户可能的说法尽可能多地写进trigger里。5.2 脚本权限和路径的坑本地系统对接绕不开权限和路径问题。最常见的是脚本没有可执行权限在 Linux 和 macOS 下./script.py会直接报 Permission denied需要chmod x。更隐蔽的是路径问题OpenClaw 可能在任意工作目录下启动你的脚本如果脚本里用了相对路径它操作的可能不是你以为的那个目录。解决的办法是有两条我都用上了第一脚本内部用Path(__file__).resolve().parent定位自己的位置所有资源路径都从那里推导第二在 SKILL.md 里明确要求模型传入绝对路径参数比如--target /Users/me/Downloads而不是--target ~/Downloads。另外提醒一句~这个符号脚本里通常不会自动展开模型如果传了带~的路径十有八九会失败最好在脚本里先做一次expanduser。5.3 输出被截断、编码报错模型能接收的上下文有限脚本如果一次性输出几百行文本后面的内容会被截断导致模型只能看到开头看不到结尾。我的做法是在脚本里做输出裁剪先输出汇总信息明细只保留前 50 条超出部分提示共 N 条已截断。这样模型拿到的一定是最关键的信息。编码问题在 Windows 上尤其常见。Windows 下 Python 默认输出编码可能是 GBK而 OpenClaw 期望的是 UTF-8控制台会报UnicodeEncodeError。这也好解决在脚本开头加两行import sys sys.stdout.reconfigure(encodingutf-8)或者在环境变量里设置PYTHONIOENCODINGutf-8。这个小问题当年让我排查了大半天问题不在逻辑而在编码。5.4 升级 OpenClaw 后 Skill 失效OpenClaw 迭代速度不慢每次升级都有可能调整 Skills 的目录规范、配置格式或者 API。我遇到过几次升级后 Skill 全部消失的情况排查下来通常是两个原因一是新版改了默认的 skills 目录旧目录不再被扫描二是SKILL.md的元信息格式有新的必填字段旧文件校验不通过被静默跳过。升级之后先别急着跑业务第一时间检查两个东西~/.openclaw/下有没有新的配置项日志里有没有关于 skills 的报错。第三方安装的 Skill 升级后尤其容易出现兼容问题因为它们是按旧版接口写的稳妥的做法是升级后重新安装一次同时留意项目仓库的更新说明。下面把常见问题整理成速查表方便以后遇到直接对照现象可能原因排查顺序模型不知道有该技能Skill 未装载或元信息未注册检查目录、reload、直接询问模型可用技能模型知道但不调用描述和触发词与用户表达不匹配扩充 description/trigger加入典型问法脚本报 Permission denied缺少可执行权限chmod x检查脚本 shebang操作了错误的目录相对路径 工作目录不一致脚本内解析绝对路径强制要求传绝对路径输出中文变乱码编码不是 UTF-8设置 PYTHONIOENCODINGutf-8输出内容不完整上下文超限被截断脚本内做汇总优先、明细限长升级后技能消失目录规范或元信息格式变更查看变更说明重新安装或迁移目录最后再分享一点个人体会。把 OpenClaw 接到本地系统之后最大的变化不是终于能用 AI 干活了而是AI 干活的边界由你自己定义。我建议不要一上来就想着写十几个 Skill先挑一个每天都要重复的本地操作比如整理下载目录、解析日志、批量压缩图片把它做成第一个 Skill跑通之后再扩展。我现在手头维护了大概十几个 Skill最常用的反而还是最开始写的那个文件整理器因为它解决的问题足够具体、触发足够稳定。Skills 这件事做得小巧、做得精准比做得庞大、做得花哨要重要得多。
这段时间我一直在折腾 OpenClaw把日常智能体的工作流从什么都丢给云端慢慢迁回到本地系统上。OpenClaw 是一个开源的智能体框架定位介于大模型和外部世界之间而 Skills 是它给智能体准备的一套可复用能力包把一段操作流程、一个脚本、一组工具调用打包成独立单元让模型在需要的时候自动发现并调用直接操作你本机的文件、命令和服务。这篇文章不讲虚的就围绕对接本地系统这条主线把 Skills 的机制、完整技能包的写法、以及我踩过的坑全部过一遍。适合已经跑起来 OpenClaw、正想着让它干点真活的人也适合还没上手但想评估这套方案值不值得入局的读者。1. 先搞清楚 OpenClaw 和 Skills 的定位再谈直接对接1.1 OpenClaw 解决的是模型到动作这一段大模型本身只负责生成文字它不碰文件系统不执行命令也摸不到你电脑上的任何服务。真正让智能体动手干活的是外面的那层执行框架。OpenClaw 干的就是这件事它把模型接进一个可以调用外部工具的运行环境里让模型在推理过程中决定下一步要调什么、传什么参数然后由框架去真正执行再把执行结果回传给模型继续判断。很多人一开始接触 OpenClaw 会把它理解成又一个聊天机器人外壳这个理解窄了。它的核心价值在于连接连接模型和工具连接模型和本地系统连接模型和各种外部 API。而所有连接里和本地系统的对接是最能体现掌控感的一环。因为只有本机上的资源是真正属于你的磁盘上的文件、跑在 localhost 的数据库、已经装好的命令行工具这些都不需要上传不需要等第三方服务也没有数据出机的顾虑。OpenClaw 通过 Skills 把这一层连接做得比较干净这也是我花时间研究它的原因。1.2 Skills 到底是什么一份手册加一套工具Skills 翻译过来是技能但在 OpenClaw 的语境里它更像是一个带说明书的工作岗位。一个 Skill 通常包含三部分一份描述文件告诉模型这个技能是干嘛的、什么时候用、怎么用一个或多个可执行脚本真正干活的部分以及可选的配置项比如 API 地址、默认参数、权限白名单。你可以把一个 Skill 理解为餐厅里的招牌菜操作卡卡片上写了这道菜适合什么客人、需要哪些食材、出餐步骤是什么后厨照着卡片就能稳定复现。模型就是那个看卡片的人它不会凭空知道你会写什么样的脚本但你一旦把脚本和说明打包成 Skill 放进 OpenClaw它就能在合适的场景下主动调用。这一点和 IDE 插件、浏览器扩展有本质区别。插件是固定入口用户得自己去点按钮Skills 是模型主动发现的能力清单它读到你这句话里隐含的需求对比自己手头有哪些 Skill 的描述命中之后才触发。也就是说Skill 的触发逻辑不在代码里写死而是靠描述文本去引导模型的判断。这个机制决定了写 Skill 时描述和触发词的设计和脚本本身一样重要。2. Skills 的运行机制从模型决策到本地执行2.1 一次完整调用的链路我在第一次写 Skill 之前最大的困惑是模型到底怎么知道我有这个技能。后来把调用链捋了一遍才明白整个过程是这样的用户提出需求后模型会先做一轮意图判断同时把自己身上挂载的 Skill 列表过一遍。这个列表里每个 Skill 只展露它的名称、描述、触发词这类元信息不会把所有脚本内容都塞进上下文。模型根据描述判断是否命中如果命中它会按照 SKILL.md 里的指引选择要执行的脚本和参数。OpenClaw 框架收到指令后在本地起一个子进程去跑对应的 Python、Shell 或其他可执行文件捕获标准输出和返回码把它作为工具结果交还给模型。模型根据结果组织最终的回复或者决定要不要继续调用下一个 Skill。这里面有一个容易被忽略的点模型本身并不运行脚本它只是下达指令真正在本地执行的是 OpenClaw 框架。这就像调度中心打电话给车间这批订单按 A 方案处理车间工人动手做完回报结果。模型是调度员你的本机是车间Skills 就是车间里那套已经调好的工装夹具。理解了这条链路后面排查问题就顺了技能没触发先看模型有没有读到描述触发了但没执行再看框架有没有找到脚本执行了但结果不对才轮到查脚本本身的逻辑。2.2 Skill 的装载与发现规则社区目前比较通行的做法是把所有 Skill 放在一个统一目录下比如~/.openclaw/skills/每个 Skill 单独一个子目录。OpenClaw 在启动或者执行 reload 操作时会扫描这个目录把每个 Skill 的元信息注册到当前会话里。第三方 Skill 可以通过包管理器或者npx skills add这类命令安装自己写的 Skill 手动放进目录就行不需要额外注册。有几个细节值得注意。第一目录名和 Skill 名最好保持一致且使用英文小写加连字符避免在某些文件系统上出现大小写问题。第二同名 Skill 会互相覆盖如果你手动放了一个download-organizer又用命令装了一个同名的最终生效的是谁取决于扫描顺序这件事非常容易把人绕晕。第三每次新增或修改 Skill 后需要重启 OpenClaw 或触发热加载当前会话里已经构建好的工具列表不会自动刷新。我一开始写完 Skill 直接对话发现模型完全感知不到折腾了半天才意识到是没 reload。3. 实操从零写一个对接本地文件系统的 Skill3.1 场景拆解让智能体整理下载目录理论讲再多不如动手写一个。我选的第一个练手场景是整理下载目录每周我的 Downloads 文件夹都会堆积各种文件截图、安装包、PDF、压缩包混在一起。这个场景适合做第一个 Skill原因有三操作对象是本机文件系统效果肉眼可见脚本逻辑简单不涉及外部依赖风险可控先做只读扫描再加移动归档。需求拆解下来就三条扫描指定目录下的所有文件按扩展名归类到对应的子目录图片、文档、压缩包、可执行文件、其他输出一份归档报告。为了安全我要求脚本默认支持演练模式dry-run只打印将要执行的操作不真正移动文件。这样模型在不确定的时候可以先跑一遍演练确认无误再执行真实归档。3.2 技能包的目录结构我按社区比较通用的结构组织这个 Skill~/.openclaw/skills/ └── download-organizer/ ├── SKILL.md ├── config.yaml └── scripts/ ├── organize.py └── manifest.pySKILL.md是给模型看的说明书config.yaml存放用户自定义配置scripts/下面放真正的执行脚本。这里我特意把生成清单和归档移动拆成两个脚本manifest.py只负责扫描和输出报告是只读操作organize.py负责实际移动文件。拆开的好处是模型可以先生成清单给用户确认再执行修改类操作降低误操作风险。3.3 SKILL.md 的写法SKILL.md 的开头是 YAML 格式的元信息后面是正文说明。我的写法如下--- name: download_organizer description: 扫描并整理本地下载目录按文件类型归档到子目录支持演练模式。适合用户要求整理下载文件清理下载目录时使用。 version: 1.0.0 trigger: 下载, 整理, 归档, 文件分类, 清理文件夹 auto: false ---正文部分我会写清楚三块内容。第一块是使用场景和使用限制只处理配置文件中指定的目录绝不允许操作系统目录第二块是操作步骤指引先运行 manifest.py 生成清单再询问用户是否执行 organize.py第三块是脚本参数说明告诉模型每个脚本支持哪些 flag、输出格式是什么。写完 SKILL.md 之后我才明白这个文件本质上是在教模型怎么用你的脚本。脚本写得再好如果说明文档不清楚模型就可能传错参数、用错顺序。所以写描述时要把自己当成一个完全不懂这个脚本的新人把所有隐含假设都写出来。3.4 背后的 Python 脚本organize.py的核心逻辑不复杂但有几个细节我在写的时候特别注意。第一个是路径安全使用pathlib处理路径而不是字符串拼接第二个是冲突处理目标目录里如果已有同名文件就在文件名后面加时间戳后缀不能直接覆盖第三个是跨目录移动用shutil.move它会自动处理跨文件系统的情况比os.rename稳。脚本主体大概长这样#!/usr/bin/env python3 import argparse import json import shutil import sys from datetime import datetime from pathlib import Path TYPE_RULES { images: {.jpg, .jpeg, .png, .gif, .webp, .svg}, documents: {.pdf, .doc, .docx, .xls, .xlsx, .ppt, .pptx, .md, .txt}, archives: {.zip, .rar, .7z, .tar, .gz}, executables: {.exe, .msi, .dmg, .appimage, .deb}, code: {.py, .js, .ts, .go, .rs, .java, .c, .cpp}, } def classify(path: Path) - str: ext path.suffix.lower() for category, extensions in TYPE_RULES.items(): if ext in extensions: return category return others def organize(target: Path, dry_run: bool True) - dict: if not target.is_dir(): raise ValueError(f目标路径不存在或不是目录: {target}) moved [] skipped [] for item in target.iterdir(): if not item.is_file(): continue category classify(item) dest_dir target / category dest_dir.mkdir(exist_okTrue) dest dest_dir / item.name if dest.exists(): dest dest_dir / f{item.stem}_{datetime.now().strftime(%Y%m%d_%H%M%S)}{item.suffix} if dry_run: moved.append({from: str(item), to: str(dest)}) else: shutil.move(str(item), str(dest)) moved.append({from: str(item), to: str(dest)}) return {dry_run: dry_run, moved_count: len(moved), moved: moved} if __name__ __main__: parser argparse.ArgumentParser(description整理下载目录) parser.add_argument(--target, requiredTrue, help要整理的目录) parser.add_argument(--dry-run, actionstore_true, help演练模式只输出计划不执行) args parser.parse_args() try: result organize(Path(args.target), dry_runargs.dry_run) print(json.dumps(result, ensure_asciiFalse, indent2)) except Exception as exc: print(json.dumps({error: str(exc)}, ensure_asciiFalse), filesys.stderr) sys.exit(1)这里我特意让脚本输出 JSON 结构化数据而不是一段花里胡哨的文字。模型解析 JSON 的可靠性远高于解析散装文本它拿到moved_count和moved列表后可以直接生成清晰的总结。这个习惯我在后面写所有 Skill 时都保留了算是踩了不少坑之后总结出来的最佳实践。manifest.py更简单只负责扫描目录、按分类统计文件数量和大小同样输出 JSON。模型在真正动手之前先看清单和用户确认下载目录里有 12 个文件其中 5 个图片、3 个压缩包要归档吗用户体验会好很多。3.5 本地跑通测试Skill 写完之后不能直接丢给模型先把脚本本身在终端里跑通。我的测试顺序是先用小样本目录做 dry-run确认输出 JSON 正确再检查分类规则有没有漏网之鱼最后在真实目录上先演练、再执行。脚本没问题之后把整个目录放到~/.openclaw/skills/下重启 OpenClaw 让新 Skill 被装载。然后在对话里输入帮我看看下载目录里都有什么模型应该会触发download_organizer并运行manifest.py。如果这一步没有触发优先检查 SKILL.md 里的description和trigger有没有覆盖用户可能的说法。我最初写的是扫描并整理下载目录但实际对话里用户更常说帮我清理一下下载文件夹加了这个说法之后触发率明显提升。4. 本地系统对接的三个高频场景4.1 调用命令行工具文件操作是本地系统对接的入门命令行工具调用则是进阶。很多本机工具干起活来比手写脚本高效得多比如git、ffmpeg、imagemagick。把这类工具包成 Skill 有个好处模型不需要记住复杂的命令行语法它只需要读 SKILL.md 里的参数说明按模型自己的理解去组合。我写过一个小众但特别实用的git_summarySkill核心逻辑就是依次执行git status、git log --oneline -10、git diff --stat把结果汇总成一段简明的工作进度报告。这个 Skill 本身没有太多技术含量但省去了我每天手动敲这三条命令的重复劳动。写这类 Skill 时最需要注意的是返回码处理脚本里要判断subprocess.run的返回码命令失败时把错误输出原样返回给模型而不是让它看到一段 Python 堆栈。模型对英文报错的理解能力远强于对 Python 堆栈的理解能力。4.2 对接本地数据库服务业务开发场景里让智能体直接查本地数据库是刚需。无论是开发环境的 MySQL还是本地跑的 SQLite都可以通过 Skill 暴露给模型。这里我有一条很重要的安全建议默认给 Skill 配置一个只读账号连接配置放在config.yaml里而不是写死在 SKILL.md 的正文中。因为 SKILL.md 是要作为上下文喂给模型的里面出现数据库密码就等于把凭据放进了对话历史这在本地虽然风险可控但一旦你后面把会话同步到其他地方就很可能泄露。我常用的写法是让 Skill 调用一个封装好的查询脚本脚本从config.yaml读取连接信息执行模型生成的 SQL并且默认加LIMIT限制返回行数。模型不像人那样有表可能很大的直觉如果不加限制一条SELECT * FROM orders能把整个内存打爆。脚本里统一加上LIMIT 200既保证了功能又兜住了底线。4.3 批量文件处理与日志分析第三个高频场景是日志分析和批量处理。这类任务的共同特点是数据量大、格式固定、人工做又慢又烦但脚本逻辑往往很简单。我曾经用 OpenClaw 排查过一台开发机的磁盘占用问题Skill 做的事情就是遍历指定目录、统计每个子目录的大小、按大小排序输出前十。模型拿到结果后自动推断出是 node_modules 目录堆积过多整个过程我只负责确认。日志分析类的 Skill 我建议把采样和全量分析分开。第一次调用先跑一个只读的采样脚本输出日志的行数、时间范围、错误关键词统计让模型形成初步判断需要深入时再跑全量解析脚本。这样可以避免模型一上来就试图读完整个 GB 级日志文件既慢又浪费 token。这个思路本质上和数据库查询先看EXPLAIN是一个道理先用最廉价的信号建立判断再决定要不要下重手。5. 常见问题与排查技巧实录5.1 模型压根不触发 Skill这是新手遇到最多的问题也是最容易让人怀疑人生的时刻。我总结下来主要原因有三个。第一Skill 没被正确装载检查目录路径和 reload 操作第二description和trigger写得和用户实际表达差异太大模型对比之后认为没有匹配项第三模型本身的能力设置或者上下文长度限制导致工具列表被截断后面的 Skill 根本看不到。排查时可以按这个顺序来先确认 OpenClaw 的日志里有没有加载 Skill 的记录再在对话里直接问模型你现在有哪些可用技能看它能不能说出你的 Skill 名称如果这一步都过不了问题就出在装载环节。如果模型能说出名称但不主动用问题就出在描述文本上把用户可能的说法尽可能多地写进trigger里。5.2 脚本权限和路径的坑本地系统对接绕不开权限和路径问题。最常见的是脚本没有可执行权限在 Linux 和 macOS 下./script.py会直接报 Permission denied需要chmod x。更隐蔽的是路径问题OpenClaw 可能在任意工作目录下启动你的脚本如果脚本里用了相对路径它操作的可能不是你以为的那个目录。解决的办法是有两条我都用上了第一脚本内部用Path(__file__).resolve().parent定位自己的位置所有资源路径都从那里推导第二在 SKILL.md 里明确要求模型传入绝对路径参数比如--target /Users/me/Downloads而不是--target ~/Downloads。另外提醒一句~这个符号脚本里通常不会自动展开模型如果传了带~的路径十有八九会失败最好在脚本里先做一次expanduser。5.3 输出被截断、编码报错模型能接收的上下文有限脚本如果一次性输出几百行文本后面的内容会被截断导致模型只能看到开头看不到结尾。我的做法是在脚本里做输出裁剪先输出汇总信息明细只保留前 50 条超出部分提示共 N 条已截断。这样模型拿到的一定是最关键的信息。编码问题在 Windows 上尤其常见。Windows 下 Python 默认输出编码可能是 GBK而 OpenClaw 期望的是 UTF-8控制台会报UnicodeEncodeError。这也好解决在脚本开头加两行import sys sys.stdout.reconfigure(encodingutf-8)或者在环境变量里设置PYTHONIOENCODINGutf-8。这个小问题当年让我排查了大半天问题不在逻辑而在编码。5.4 升级 OpenClaw 后 Skill 失效OpenClaw 迭代速度不慢每次升级都有可能调整 Skills 的目录规范、配置格式或者 API。我遇到过几次升级后 Skill 全部消失的情况排查下来通常是两个原因一是新版改了默认的 skills 目录旧目录不再被扫描二是SKILL.md的元信息格式有新的必填字段旧文件校验不通过被静默跳过。升级之后先别急着跑业务第一时间检查两个东西~/.openclaw/下有没有新的配置项日志里有没有关于 skills 的报错。第三方安装的 Skill 升级后尤其容易出现兼容问题因为它们是按旧版接口写的稳妥的做法是升级后重新安装一次同时留意项目仓库的更新说明。下面把常见问题整理成速查表方便以后遇到直接对照现象可能原因排查顺序模型不知道有该技能Skill 未装载或元信息未注册检查目录、reload、直接询问模型可用技能模型知道但不调用描述和触发词与用户表达不匹配扩充 description/trigger加入典型问法脚本报 Permission denied缺少可执行权限chmod x检查脚本 shebang操作了错误的目录相对路径 工作目录不一致脚本内解析绝对路径强制要求传绝对路径输出中文变乱码编码不是 UTF-8设置 PYTHONIOENCODINGutf-8输出内容不完整上下文超限被截断脚本内做汇总优先、明细限长升级后技能消失目录规范或元信息格式变更查看变更说明重新安装或迁移目录最后再分享一点个人体会。把 OpenClaw 接到本地系统之后最大的变化不是终于能用 AI 干活了而是AI 干活的边界由你自己定义。我建议不要一上来就想着写十几个 Skill先挑一个每天都要重复的本地操作比如整理下载目录、解析日志、批量压缩图片把它做成第一个 Skill跑通之后再扩展。我现在手头维护了大概十几个 Skill最常用的反而还是最开始写的那个文件整理器因为它解决的问题足够具体、触发足够稳定。Skills 这件事做得小巧、做得精准比做得庞大、做得花哨要重要得多。
