最近一直在折腾 OpenClaw 这个开源智能体框架越用越觉得内置技能只是个起点真正让它从演示玩具变成生产力工具的是自定义技能。OpenClaw 的机制并不复杂把一段能力封装成一个技能目录写好描述文件配好执行脚本大模型通过描述去判断什么时候该调用它。这篇文章把我实际搭技能的过程完整记录了一遍包括 SKILL.md 怎么写、脚本怎么接、依赖怎么装、问题怎么查每一步都有代码和解释。照着做能跑通跑通之后你可以直接拿去改造。适合正在上手 OpenClaw、或者想搞懂 Agent 技能机制的人阅读。1. 为什么自定义技能是 OpenClaw 的扩展核心1.1 技能系统的工作原理模型是怎么看到技能的先把这个最核心的机制讲透。OpenClaw 把技能定义为一个自包含的目录目录里有描述文件SKILL.md和可执行脚本。启动之后所有技能都会被加载进模型上下文相当于给大模型提供了一份工具清单。模型不会真的去读你脚本的每一行代码它只读 SKILL.md 里的描述。当用户提出请求时模型判断当前这个请求是不是匹配某个技能的描述匹配成功就调用那个技能。所以技能描述就是使用说明书说明书的质量直接决定调用准确性。拿生活化类比来说技能就像一个工具箱里贴着标签的扳手模型是工人标签写得太含糊工人就可能拿错工具。我见过不少技能写得代码很漂亮但描述写得一塌糊涂结果模型要么死活不调用要么在错误的场景下调用。这里还有个容易忽略的点OpenClaw 对模型的要求是必须具备工具调用function calling能力。如果没有这个能力技能系统根本转不起来。所以你接模型的时候别只看对话流畅度先确认它支不支持 function calling。1.2 内置技能与自定义技能的分工OpenClaw 自带一些基础技能负责文件读写、shell 命令、网络请求这些通用操作。自定义技能则负责领域专精比如 OCR 文字提取、报表生成、对接内部 API、调私有云服务。这两者不是替代关系而是协作关系。绝大多数自定义技能底层都会依赖内置的技能去完成基础操作。举个实际例子我写一个读取网页正文并总结的技能脚本里做的事情就是先用内置的网络请求技能把页面拉下来再做 HTML 解析最后把文本交给大模型总结。我的经验是在自定义技能里多做一层错误处理别把复杂逻辑全暴露给模型自由发挥。模型能调脚本已经很厉害了但你不要指望它每次都能处理脚本抛出的各种边界异常。脚本内部把参数校验、文件存在性检查、异常捕获全做好模型只需要负责调用和取结果。1.3 三种技能形态怎么选自定义技能主要有三种形态我用一个表格来对比形态典型实现适用场景注意事项命令包装型直接封装已有 CLI 工具系统里已有成熟的命令行工具想直接暴露给模型注意处理命令超时和错误输出脚本型Python / Node 脚本处理数据加工、OCR、文件转换、报表生成依赖管理要处理好否则换个环境就崩API 调用型封装 HTTP 接口对接外部服务、内部系统、云端能力注意凭证管理和接口限流这三种形态不是互斥的很多技能是混合的。我常用的策略是外部有现成 CLI 就选第一种快速需要复杂逻辑处理就选第二种灵活需要对接业务系统就选第三种规范。选型标准只有一个——你手里最不缺的资源和最想省的时间。2. 技能文件结构的底层逻辑与编写要点2.1 技能目录长什么样先看一个标准的技能目录结构skills/ └── ocr-extract/ ├── SKILL.md ├── scripts/ │ └── main.py ├── assets/ │ └── sample.png └── requirements.txt每个技能一个目录目录名就是技能名建议全小写加连字符的 kebab-case 风格比如ocr-extract、pdf-to-markdown。目录名在全局必须唯一如果和其他技能重名加载阶段就会冲突。SKILL.md 必须放在技能目录的根目录下这是约定。scripts 目录放可执行脚本assets 放静态资源文件requirements.txt 放 Python 依赖。OpenClaw 加载技能的时候会扫描目录下的 SKILL.md 来识别技能存在。我在实际使用中还有一个习惯每个技能目录里放一个 README 或者 CHANGELOG记录这个技能的迭代历史。这不是框架要求的但对多人协作和后期自己回顾非常有帮助。技能越做越多之后你会发现这个技能当初为什么这么写比这个技能怎么用更值钱。2.2 SKILL.md 的 YAML frontmatter 怎么写SKILL.md 的核心是文件开头的 YAML frontmatter它定义技能的元信息。一个典型的例子是这样的--- name: ocr-extract description: 从图片中提取文字支持中文和英文。当用户需要识别图片中的文字、从截图提取内容时使用。输入是图片路径输出是识别出的纯文本。 version: 1.0.0 author: your-name license: MIT ---字段说明name技能名称和目录名保持一致。description描述这是最重要的字段模型靠它做意图匹配。version版本号建议做技能包管理时用语义化版本。author、license协作和发布信息单机自用可以不写但分享给别人的时候建议补齐。接下来是正文部分。正文可以写更详细的参数说明、使用示例和注意事项。这套格式的核心价值是把机器可读的元信息和人可读的使用文档放在同一个文件里。描述里有一个常见误区——把技能说得太宏大。比如强大的跨平台文字识别工具基于深度学习的先进 OCR 引擎模型看完根本不知道什么时候调用。正确写法应该是场景化的当用户需要识别图片中的文字、从截图提取内容时使用。模型看到截图提取文字这样的词才会准确触发调用。2.3 参数传递与输出规范OpenClaw 调用技能本质上是执行一条命令。所以参数传递主要靠命令行参数、选项和标准输入。技能脚本要像一个标准命令行工具一样工作接收参数、处理任务、把结果输出到标准输出。为了让模型知道技能接收哪些参数最好在 SKILL.md 里把参数表写清楚--- name: ocr-extract description: 从图片中提取文字。当用户需要识别图片文字、从截图提取内容时使用。输入是图片路径输出是识别出的纯文本。 version: 1.0.0 ---正文部分可以这样描述参数参数 - image_path: 图片文件路径必填 - lang: 识别语言可选默认 chi_simeng可选值eng / chi_simeng - output: 输出格式可选默认 text可选值text / json输出规范上我强烈建议结构化输出。如果技能返回的内容要经过模型理解后再加工尽量用 JSON 格式输出让模型直接解析。如果直接给用户看最终结果输出纯文本就够了。两种各有用处关键是别混。2.4 敏感变量与运行环境管理这是安全里的大坑。很多新手把 API Key、Token 直接硬编码在 SKILL.md 或脚本里结果技能包一分享凭证全泄漏了。正确做法是从环境变量读取import os api_key os.environ.get(MY_OCR_API_KEY)OpenClaw 本身也是支持环境变量注入的可以在启动配置里设置。我自己的习惯是技能涉及的凭证全部通过环境变量注入脚本里不出现任何明文密钥。再配合一个.env.example文件把需要配置的变量名列出来但填上假的示例值。我踩过这个坑。有一次我图省事把某个服务的 Token 直接写进了 SKILL.md 的正文示例里然后整个技能目录推到了 git 仓库。虽然仓库是私有的但后来要发给别人协作时才发现脱敏有多麻烦。从那以后凡是技能目录我都先跑一遍 grep 检查有没有明显的密钥模式再提交。3. 从零构建 OCR 技能完整实操记录3.1 案例选择与前置准备我选的案例是一个 OCR 图片文字提取技能。选它有几个原因需求普遍几乎每个智能体项目都会遇到实现成本低不依赖复杂的服务容易验证拿一张截图就能测。技术选型上我用 pytesseract 作为主力识别引擎。它依赖轻、跨平台但需要单独安装 Tesseract OCR 本体。如果你主要识别中文PaddleOCR 的效果会更好但依赖也重更多。这个案例我用 pytesseract 讲清楚整个流程你后面要换引擎只改脚本内部逻辑就行。环境准备pip install pytesseract pillow然后安装 Tesseract OCR 本体。Ubuntu 上是sudo apt install tesseract-ocr tesseract-ocr-chi-simWindows 上需要下载 Tesseract 的 Windows 安装包并把安装目录加入 PATH。顺手把中文语言包也装了识别中文的时候才够用。3.2 创建技能目录在 OpenClaw 的技能目录下创建基础结构mkdir -p skills/ocr-extract/scripts cd skills/ocr-extract如果你不清楚技能目录该放哪去 OpenClaw 的配置里看skills路径的配置项默认通常会有一个专门的 skills 文件夹。把技能目录放在正确的位置框架才能扫描到。3.3 编写核心脚本 main.py核心脚本用 Python 写接收一个图片路径参数跑 OCR输出结果#!/usr/bin/env python3 import sys import json import argparse from PIL import Image import pytesseract def ocr_image(image_path: str, lang: str chi_simeng, output: str text) - str: 读取图片并通过 Tesseract 执行文字识别。 try: image Image.open(image_path) # 这里可以加图像预处理的逻辑比如灰度化、增强提高识别率 result_text pytesseract.image_to_string(image, langlang) except FileNotFoundError: return json.dumps({error: f图片不存在: {image_path}}, ensure_asciiFalse) except Exception as exc: return json.dumps({error: str(exc)}, ensure_asciiFalse) if output json: # 清洗文本再返回结构化结果 lines [line.strip() for line in result_text.splitlines() if line.strip()] return json.dumps({text: \n.join(lines)}, ensure_asciiFalse) return result_text if __name__ __main__: parser argparse.ArgumentParser(descriptionOCR 文字提取) parser.add_argument(image_path, help图片文件路径) parser.add_argument(--lang, defaultchi_simeng, help识别语言) parser.add_argument(--output, defaulttext, choices[text, json], help输出格式) args parser.parse_args() result ocr_image(args.image_path, args.lang, args.output) print(result)加个执行权限chmod x scripts/main.py脚本里有几个细节值得注意。首先异常处理一定要全面FileNotFoundError 和通用 Exception 都捕获因为模型调用脚本时不会预知文件的真实状态。其次输出编码要处理好在 Windows 环境下 Python 默认的 stdout 编码可能不是 UTF-8中文会乱码建议在脚本里显式声明import sys sys.stdout.reconfigure(encodingutf-8)很多人在本地跑脚本好好的放到 OpenClaw 里调用就乱码十有八九是编码问题。3.4 编写 SKILL.md接下来是最关键的一步写描述文件--- name: ocr-extract description: 从图片中提取文字。当用户需要识别图片中的文字、从截图提取内容、解析扫描件时使用。输入是图片路径输出是识别出的纯文本。 version: 1.0.0 author: your-name --- # ocr-extract 从图片中提取文字支持中文和英文。 ## 参数 - image_path: 图片文件路径必填 - lang: 识别语言可选默认 chi_simeng可选值eng / chi_simeng - output: 输出格式可选默认 text可选值text / json ## 使用示例 bash python3 scripts/main.py /path/to/image.png python3 scripts/main.py /path/to/image.png --output json依赖Python 3.8pytesseractpillowTesseract OCR 本体系统级依赖注意我特意在 description 里写了从截图提取内容、解析扫描件这些触发场景。这样当用户说帮我把这张截图里的文字整理一下模型就能准确匹配到 ocr-extract而不是错误地调用别的技能。这种场景词列表写法是我测试了很多技能后总结出来的非常管用。 ### 3.5 注册与触发调试 写完文件后重启 OpenClaw 或者触发技能重新加载机制让框架扫描到新技能。 然后做验证分两步。第一步手动执行脚本确认孤立环境下能跑通 bash python3 scripts/main.py ~/Desktop/test.png第二步在 OpenClaw 会话里发一条真实请求比如帮我把桌面上的 test.png 里的文字提取出来。这时候观察日志看技能是否被加载、是否被调用、输出有没有正确回传。我自己的调试习惯是每改一次 SKILL.md 或脚本就在全新会话里测。因为模型有上下文记忆同一个会话里如果你之前已经讨论过图片内容模型可能不调用技能而是根据记忆回答这会造成技能没生效的假象。3.6 让技能更实用的进阶扩展上面这个版本能跑通但离好用还差几步。我实际使用中会再加这些能力支持多图片批处理。很多场景下用户一次性截图好几张逐个调用技能效率太低。脚本支持接收多个路径循环识别后合并结果。增加预处理逻辑。截图经常会带噪点、深色背景、旋转角度OCR 识别率会明显下降。在传给 Tesseract 之前先用 Pillow 做灰度化、二值化、对比度增强识别率能提升不少。在做这种步骤的时候要控制好脚本的单次耗时太慢的预处理会让整个交互变迟钝。输出清洗。OCR 结果里经常有大段空白和无关字符脚本里先做一遍清洗去掉空行、特殊符号再给模型模型解析起来轻松很多。这一步对体验提升非常明显。4. 调试与常见问题排查实录4.1 技能根本没被加载这是第一个可能遇到的大坑SKILL.md 写好了目录放好了重启后模型还是看不到新技能。排查顺序按这个来先确认目录位置是否正确。技能文件夹是不是放到了配置指定的 skills 路径下放错位置扫描不到。再查日志。OpenClaw 加载技能时会在日志里打印加载成功或失败的信息。看到 YAML 解析错误基本就是 frontmatter 格式有问题。检查技能名是否和其他技能重复。我遇到过一次之前有个旧技能占了名字新技能加载时静默失败日志里只有一行不显眼的 warning不盯日志根本发现不了。4.2 技能被加载但没被调用技能明明加载成功但用户提出请求时模型就是不调用。这种情况十有八九是描述写得不够好。我之前有个技能描述写的是PDF 文件处理工具用于处理 PDF 相关操作结果模型在提取 PDF 里的表格这种明确场景下都不调用它。后来我改成从 PDF 中提取表格数据支持 PDF 表格识别、Excel 转换。当用户提供 PDF 文件并要求提取表格、转换格式时使用触发率立刻上来了。另外要注意有些模型本身工具调用能力弱或者上下文里技能太多导致拥挤效应。技能数量多的时候描述要更精简否则模型会在选择上犹豫不决。4.3 被调用但脚本执行报错技能被调用了但返回的是错误信息说明脚本执行环节出问题。最常见的几个原因脚本没有执行权限。在 Linux 环境下chmod x忘了做就会出现权限拒绝。shebang 写错。脚本第一行如果写#!/usr/bin/env python3那系统会按这个路径找 Python。如果用的虚拟环境里的 Python这个 shebang 可能找不到最好显式指定解释器路径。环境变量边界。脚本执行时读取不到某些环境变量因为你的 Shell 环境里有的变量OpenClaw 进程里不一定有。解决方案是把依赖的变量写全脚本启动时自己检查缺失并给出明确错误提示。4.4 Windows WSL2 环境下的典型问题OpenClaw 在 Windows 上跑的时候很多底层操作依赖 WSL2。热词里我看到openclaw无法安全验证sl2环境请在powershell中运行wsl -- status这个问题我实际遇到过。现象是启动 OpenClaw 时提示 WSL 环境无法安全验证要求运行wsl -- status。排查步骤用管理员权限打开 PowerShell运行wsl --status看 WSL 状态。如果是内核版本过旧或未更新运行wsl --update更新到最新内核。如果显示虚拟化功能未启用去 Windows 功能里打开适用于 Linux 的 Windows 子系统和虚拟机平台然后重启。运行wsl --version确认 WSL 2 版本已经就绪。这个问题的根源是安全验证机制要求 WSL2 内核必须满足最低版本系统里内核太旧就直接拒绝服务。解决起来不难难的是第一时间想到是这个原因。4.5 输出编码与格式问题在 Windows 环境下脚本输出中文会出现乱码或者模型拿到乱码后的畸形 JSON。原因就是 Python 默认 stdout 编码不是 UTF-8。我的解决办法是双保险。脚本里主动声明 UTF-8sys.stdout.reconfigure(encodingutf-8)同时在 OpenClaw 的环境配置里设置PYTHONIOENCODINGutf-8。如果你发现模型解析 JSON 失败先别怪模型。把技能脚本的输出重定向到文件里看一眼往往能看到 Python 打印了多余的日志信息污染了 JSON 输出。记住一条铁律结构化输出的时候脚本的 stdout 只放结构化数据日志全走 stderr否则模型拿到混合内容解析效率非常低。4.6 常见问题速查表问题现象可能原因解决动作技能没加载目录位置不对 / YAML 解析失败 / 名字冲突检查 skills 路径、frontmatter、日志加载了但不调用描述不具体 / 模型 function calling 弱重写 description换支持工具调用的模型脚本报权限错误没加执行权限 / shebang 有问题chmod x检查解释器路径中文乱码编码 GBK/UTF-8 冲突脚本声明 UTF-8设置 PYTHONIOENCODINGJSON 解析失败stdout 混入日志日志走 stderrstdout 只留结构数据WSL2 验证失败内核过旧 / 虚拟化未启用wsl --update启用相关 Windows 功能5. 从本地到生产部署、分享与模型选型经验5.1 Ubuntu 服务器部署要点本地跑通之后大多数人会想部署到服务器。Ubuntu 上部署 OpenClaw 比 Windows 省心不少但还是有几点经验。第一步装好运行环境Node.js、Python、Git这些都是底层依赖。然后按官方步骤装 OpenClaw 本体配置文件里指定模型接口和 API Key。服务器上跑智能体有一个优化建议用 systemd 或者 pm2 做进程守护。OpenClaw 如果直接跑在终端里SSH 断开就结束了。我用 pm2 管理设置开机自启异常崩溃后自动重启省心很多。还有个容易忽略的点上传大文件时路径处理。本地路径和服务器路径不一致技能脚本里如果写死绝对路径换成服务器环境就出错。建议所有技能脚本都从相对路径或环境变量读取路径。5.2 Windows Companion 配置要点Windows 上使用 OpenClaw 通常还需要配置 Companion 组件。我看到热词里有openclaw windows companion 怎么配置实际配置过程中比较关键的就三个点Companion 的安装路径和 OpenClaw 主进程要保持一致配置里要能互相发现。权限设置很重要Windows 的防火墙有时会拦截本地通信端口需要加放行规则。如果在 WSL2 里跑 OpenClawCompanion 在 Windows 侧就要配置好 WSL 的地址映射两边的网络路径要打通。Windows 环境折腾起来比 Linux 多一些细节但是把端口、防火墙、WSL 地址这三个坑填掉剩下的就和 Linux 环境一样顺了。5.3 技能包的分享与版本管理技能做多了之后管理就成了问题。我的做法是建一个独立的 git 仓库存放所有自定义技能仓库里按目录分技能SKILL.md 里的 version 字段做版本标记。分享技能给别人的时候有几点规范建议不要带自己机器的绝对路径。敏感配置一律用环境变量占位替换。依赖清单写清楚Python 技能给 requirements.txtNode 技能给 package.json。写一个简短的 README 说明适用场景和限制。社区里现在也有不少现成技能包比如网盘操作类、笔记管理类比如 Obsidian 集成、报表生成类。有些人会问类似 WorkBuddy 这类工具是不是参考了 OpenClaw 的技能模式其实这种技能目录 描述驱动调用的设计已经在不少 Agent 工具里出现了。学会了自定义技能的写法这些工具你都能快速上手因为底层的思维是相通的。5.4 本地小模型的接入尝试有热词提到qwen2.5-3b 关联到 openclaw说明不少人是想把本地小模型接进去。这个方向可行但要注意选型的前提条件模型必须支持 function calling 或 tool use。很多参数量太小的模型根本没有稳定的工具调用能力接进去之后技能列表加载了但模型不会正确调用表现就是用户发什么它都直接回答完全不触发技能。如果要用小模型我的建议是技能描述写得极简。小模型的上下文窗口有限技能列表太长描述再长它处理不过来调用准确率会降。把手头技能精简到核心几个description 控制在两句话以内实际效果会改善不少。5.5 大模型选型与技能包搭配建议最后聊一下被问到最多的问题搭建智能体应该选哪个大模型、需要哪些技能包。这个没有标准答案但我提供一个决策框架。选模型看三个指标上下文长度、function calling 稳定性、单次调用成本。上下文长度决定你能挂多少技能、塞多少文档function calling 稳定性决定技能调用准不准这个必须实测成本决定能不能长期跑。技能包搭配看业务场景。做内容处理类的PDF 解析、OCR、网页抓取这些是刚需做办公自动化的表格处理、邮件发送、日程管理优先配做垂直领域的比如电商客服那要把订单查询、商品信息、售后政策这些封装成专属技能。核心原则是先盘点业务流程里重复性高、规则明确的操作再决定技能包清单不要一上来就堆技能。最后说几句个人体会。技能设计真正难的从来不是代码而是让模型一眼看懂什么时候该用你。我做了十几个技能之后才意识到每次调试都应该从模型视角提问而不是从自己已知答案的视角去测。一个技能写完之后问自己一句如果我是第一次看到这段描述我知道该什么时候调用它吗还有一个小技巧我到现在还在用每次新技能上线先跑一遍全新会话测试再跑一遍长时间会话压力测试。前者验证描述准确性后者验证稳定性和输出可解析性。两个都过了技能才算真正可用。