1. 从“工具调用”到“技能学习”OpenClaw的进化瓶颈如果你最近在折腾AI智能体尤其是那些能帮你操作电脑、调用各种API的“数字员工”那你大概率听说过OpenClaw。它本质上是一个开源的AI智能体框架核心能力是让一个大语言模型比如GPT-4、Claude或者本地部署的Llama能够“动手操作”——打开浏览器、点击按钮、填写表单、调用某个Web API诸如此类。传统的实现方式是开发者预先在代码里写好一堆“工具函数”然后告诉模型“嘿这是你能用的所有工具名字叫open_browser参数是url你自己看着办。”这种方式在初期很有效但很快就暴露了它的天花板工具集是静态的、封闭的。每次想给智能体增加一个新能力比如让它学会用一个新的内部系统或者接入一个刚发布的API你都得去修改框架的源代码重新定义工具函数然后重新部署。这根本不是“智能体”该有的样子更像是一个功能固定的自动化脚本。真正的智能体应该能“学习”。就像一个新员工入职你给他一份操作手册他读一遍就能上手新设备。OpenClaw社区里很多开发者都在问“能不能让我的OpenClaw智能体自己去学用新工具” 这个需求催生了一个非常巧妙的解决方案SKILL.md。它不是一个复杂的插件系统而是一个简单到极致的理念——用Markdown文档来定义一项技能。简单来说SKILL.md就是一份写给AI看的“工具说明书”。你不需要写一行代码去“注册”工具只需要按照约定的格式在一个Markdown文件里描述清楚这个工具叫什么、是干什么的、怎么用、输入输出是什么。然后把这份文档“喂”给OpenClaw它就能理解并尝试调用这个新工具。这实现了从“硬编码集成”到“文档即接口”的范式转变。我最初看到这个设计时觉得它既大胆又优雅大胆在于它完全信任模型的自然语言理解能力优雅在于它用最通用的文档格式解决了最棘手的扩展性问题。2. SKILL.md 文档解构一份AI能读懂的“工具说明书”一份标准的SKILL.md文档其结构之清晰目的之明确堪称典范。它完全遵循了“说人话”的原则因为它的读者既是人类开发者更是AI模型。下面我们拆解一个为“获取天气”功能编写的SKILL.md示例看看每一部分是如何起作用的。2.1 核心元数据定义技能的“身份证”文档的开头通常用YAML Front Matter被---包裹的部分或一级标题来声明最核心的元数据。这是AI快速检索和匹配技能的索引。# get_weather **技能名称**: get_weather **描述**: 根据提供的城市名称查询该城市当前的天气情况包括温度、天气状况、湿度和风速。 **调用方式**: HTTP GET **权限**: 公开技能名称 (get_weather): 必须简洁、唯一使用蛇形命名法snake_case。这是AI在思考时内部调用的“函数名”。一个好的名字应该能望文生义。描述: 用一两句话清晰说明这个技能的核心功能。这是最重要的部分模型主要靠这段描述来理解“该在什么时候调用这个技能”。描述应避免歧义例如“处理数据”就太模糊“将CSV文件转换为JSON格式”就明确得多。调用方式: 指明技能的实现类型。常见的有HTTP GET/POST: 表示这是一个Web API调用。SHELL: 表示需要执行一个命令行指令。PYTHON: 表示需要运行一段Python代码需在安全沙箱内。UI_AUTOMATION: 表示需要进行图形界面自动化操作如通过Playwright控制浏览器。权限: 说明该技能所需的权限级别例如“公开”、“需要用户授权”、“需要管理员权限”。这有助于框架进行基本的权限控制和安全检查。2.2 参数详解手把手教AI“填表格”这是技能定义中最需要细致入微的部分。你需要像教一个极其认真但缺乏背景知识的新手一样定义每一个输入参数。## 参数 | 参数名 | 类型 | 是否必需 | 描述 | 示例 | | :--- | :--- | :--- | :--- | :--- | | city | string | 是 | 要查询天气的城市名称支持中文或英文。请尽可能提供完整的城市名避免使用缩写。 | 北京, New York | | unit | string | 否 | 温度单位。默认为 metric摄氏度。可选 imperial华氏度。 | metric |注意参数描述是AI理解如何生成参数值的关键。避免使用“目标对象”、“输入数据”这类泛泛之词。应该描述这个参数在真实世界中的意义和约束例如“用户的电子邮件地址必须符合标准邮箱格式”、“文件的完整路径必须是当前系统可访问的”。类型 (Type): 定义参数的数据类型如string,number,boolean,array,object。这能帮助AI在生成调用请求时进行正确的格式转换。是否必需 (Required): 明确告诉AI哪些参数是必须提供的哪些可以省略或有默认值。示例 (Example): 提供一个或多个典型值。这对于AI理解参数的格式和范围有奇效。例如对于date参数写示例2023-10-27比单纯说“日期字符串”要清晰得多。2.3 调用示例与响应展示“成功的样子”AI需要看到正确调用的模板和预期的结果以此来验证自己的理解并解析返回数据。## 调用示例 **请求**: json { “skill”: “get_weather”, “params”: { “city”: “上海”, “unit”: “metric” } }响应:{ “success”: true, “data”: { “city”: “上海”, “temperature”: 22, “condition”: “晴”, “humidity”: 65, “wind_speed”: 12, “unit”: “°C” }, “error”: null }* **请求示例**: 展示了技能被调用时的完整数据结构。这相当于给AI一个填空模板。 * **响应示例**: 展示了技能成功执行后返回的数据结构。AI在收到真实响应后会以此结构为参考来提取信息并组织成自然语言回复给用户。**务必包含一个success字段和error字段**这是健壮性设计的关键让AI能明确知道调用是成功还是失败。 ### 2.4 错误处理与备注预见“可能出的错” 一份好的说明书会包含故障排除指南。SKILL.md也不例外。 markdown ## 错误处理 如果调用失败响应中 success 将为 falseerror 字段会包含错误信息。 常见错误 - city not found: 提供的城市名称无法识别。请检查城市名拼写。 - network error: 网络请求失败。请检查网络连接或稍后重试。 - service unavailable: 天气服务暂时不可用。 ## 备注 - 该技能依赖于外部的天气API可能存在调用频率限制。 - 温度单位参数 unit 如果未提供将始终使用摄氏度(metric)。 - 建议在调用前对城市名进行基本的有效性检查如非空字符串。错误处理: 列出常见的错误类型和可能的原因。这能极大地提升AI在遇到问题时的应对能力让它不仅能报告“出错了”还能给出“可能是什么原因”的提示甚至尝试修复如提示用户检查城市名。备注: 放置任何额外的、重要的信息。例如依赖项、性能警告、使用限制、最佳实践等。这部分信息能帮助AI更“聪明”地使用该技能避免滥用或误用。通过以上四个部分的组合一份SKILL.md就构成了一份对AI足够友好的完整契约。它不像代码接口那样严格却通过自然语言提供了更丰富的上下文这正是大语言模型所擅长的。3. OpenClaw 如何“阅读”并“掌握”SKILL.md那么OpenClaw框架是如何利用这份Markdown文档的呢这个过程并非魔法而是一套设计精巧的流程我们可以称之为“技能注入工作流”。下面我结合自己的部署和调试经验来拆解这个工作流的关键环节。3.1 技能文档的加载与索引首先OpenClaw需要知道去哪里找SKILL.md文件。通常你会在配置中指定一个或多个技能目录例如./skills/。启动时框架会扫描这些目录读取所有.md文件。关键步骤与避坑目录结构建议按领域对技能进行分类。例如skills/ ├── web/ │ ├── search_web.md │ └── scrape_page.md ├── data/ │ ├── csv_to_json.md │ └── plot_chart.md └── system/ ├── get_file_list.md └── execute_shell.md这本身就在为AI提供分类上下文。文档解析框架会解析每个Markdown文件提取出我们上一章提到的那些结构化信息技能名、描述、参数列表等。这里一个常见的坑是Markdown格式不规范。如果YAML Front Matter格式错误或者表格使用了非标准语法解析就会失败。务必使用标准的GFMGitHub Flavored Markdown语法。向量化与索引这是核心步骤。仅仅把文档读进内存是不够的当用户说“帮我查一下北京的天气”时OpenClaw需要从几十个技能中快速找到最相关的get_weather。实现这一点通常依靠向量数据库。将每个技能的描述和参数名等关键文本通过嵌入模型Embedding Model转换为一个高维向量即一组数字。将这些向量存储到向量数据库如Chroma、Qdrant中建立索引。当用户请求到来时将用户的查询“查北京天气”也转换为向量然后在向量数据库中进行相似度搜索找到最匹配的几个技能。实操心得技能描述的撰写质量直接决定了向量搜索的准确性。get_weather的描述如果只写“获取天气”可能也会被“查询气候”匹配到。但如果描述写成“根据城市名查询实时温度、湿度和风力”那么与用户查询的语义匹配度会高得多检索结果也更精准。3.2 动态上下文构建与函数调用当AI通过检索确定了要使用的技能比如get_weather后下一步就是“调用”。这里OpenClaw扮演了一个“翻译官”和“调度员”的角色。上下文构建OpenClaw不会把原始的SKILL.md全文都塞给大模型那样会浪费大量令牌Token。相反它会动态地构建一个精简的“工具列表”上下文。这个列表可能只包含技能名和一行描述例如[ {“name”: “get_weather”, “description”: “根据城市名称查询当前天气情况。”}, {“name”: “search_web”, “description”: “使用搜索引擎在互联网上查找信息。”}, // ... 其他技能 ]将这个列表作为系统提示词System Prompt的一部分注入到大模型的对话上下文中。这相当于告诉模型“你现在拥有以下能力。”模型决策与参数生成当用户说“上海今天热吗”大模型结合上下文中的工具列表会“思考”“用户问上海天气我有个get_weather技能可以用。” 然后它会根据SKILL.md中对参数的描述自动生成一个结构化的调用请求。在OpenAI的Function Calling或类似机制下这个请求格式是固定的{ “function”: “get_weather”, “arguments”: { “city”: “上海”, “unit”: “metric” } }这里的关键在于模型生成arguments时依赖的是SKILL.md中参数描述的自然语言理解。它读懂了“城市名称”这个描述并把“上海”映射到了city参数上。请求转发与执行OpenClaw收到模型返回的结构化调用请求后会根据技能定义中的“调用方式”将请求分发给对应的执行器Executor。如果是HTTP GET就构造URL并发起网络请求。如果是SHELL就在安全的子进程中执行命令。如果是PYTHON就在沙箱环境中运行代码。 这个过程对模型是透明的它只关心“调用什么”和“传递什么参数”。3.3 结果解析与回复生成执行器拿到结果无论是API返回的JSON还是命令行的输出后会将其封装成一个标准格式返回给OpenClaw核心。结果标准化OpenClaw会尝试将各种形态的结果统一到SKILL.md中定义的“响应示例”结构。例如将天气API返回的原始数据组装成{“success”: true, “data”: {…}}的格式。如果执行出错如网络超时则组装成{“success”: false, “error”: “network timeout”}。上下文回馈与最终回复这个标准化后的结果会连同最初的技能描述再次作为上下文提供给大模型。模型此时的任务是“基于你刚才调用get_weather技能得到的结果组织一段通顺的自然语言回复用户。” 于是模型可能会生成“上海今天天气晴朗当前气温22摄氏度湿度65%风力3级感觉比较舒适。”至此一个完整的“技能学习-调用-回复”闭环就完成了。整个过程开发者没有写一句胶水代码只是提供了一份详尽的Markdown文档。OpenClaw框架和底层大模型协同工作完成了从自然语言理解到工具调用的全过程。4. 实战从零创建一个“图片处理”技能并集成理论说得再多不如动手做一遍。假设我们现在需要一个新技能convert_image功能是将用户上传的图片从一种格式转换为另一种格式如PNG转JPG。我们将完整走一遍流程。4.1 编写convert_image.md技能文档首先在OpenClaw的技能目录例如./skills/下创建文件convert_image.md。# convert_image **技能名称**: convert_image **描述**: 将一张图片从源格式转换为目标格式并调整其图片质量。支持常见格式如PNG, JPG/JPEG, WEBP, GIF之间的转换。 **调用方式**: PYTHON **权限**: 公开 (注意涉及文件操作需确保路径安全) ## 参数 | 参数名 | 类型 | 是否必需 | 描述 | 示例 | | :--- | :--- | :--- | :--- | :--- | | source_path | string | 是 | 源图片文件的完整路径。文件必须存在且可读。 | /tmp/uploaded_image.png | | target_format | string | 是 | 需要转换的目标图片格式。不区分大小写。可选值: png, jpg, jpeg, webp, gif。 | jpg | | quality | integer | 否 | 输出图片的质量仅对JPG/JPEG和WEBP格式有效。范围1-100数值越高质量越好文件越大。默认为85。 | 90 | | output_dir | string | 否 | 输出图片的目录。如果未指定则保存在源文件所在目录。 | /tmp/converted/ | ## 调用示例 **请求**: json { “skill”: “convert_image”, “params”: { “source_path”: “/home/user/pictures/photo.png”, “target_format”: “jpg”, “quality”: 90 } }响应 (成功):{ “success”: true, “data”: { “message”: “图片转换成功。”, “original_path”: “/home/user/pictures/photo.png”, “output_path”: “/home/user/pictures/photo.jpg”, “format”: “JPEG”, “size_kb”: 245 }, “error”: null }响应 (失败):{ “success”: false, “data”: null, “error”: { “code”: “FILE_NOT_FOUND”, “message”: “源图片文件不存在: /home/user/pictures/photo.png” } }错误处理FILE_NOT_FOUND: 提供的source_path不存在或不可读。UNSUPPORTED_FORMAT:target_format参数值不被支持。CONVERSION_ERROR: 图片转换过程中出错可能是损坏的源文件或不兼容的格式。PERMISSION_DENIED: 对输出目录没有写入权限。备注该技能依赖于Python的PIL库Pillow。确保运行环境已安装pillow包 (pip install pillow)。转换GIF图片时请注意动态GIF转换为静态格式如JPG将只保留第一帧。出于安全考虑框架应限制source_path和output_dir的可访问范围防止路径遍历攻击。这份文档已经非常详细但它是“声明式”的只告诉了AI“做什么”和“用什么做”还没定义“怎么做”。对于 PYTHON 调用方式我们还需要实现具体的执行逻辑。 ### 4.2 实现Python执行器逻辑 OpenClaw需要知道当调用方式为 PYTHON 时如何执行这段逻辑。这通常通过一个“Python技能执行器”来完成。我们需要在框架的相应位置或通过插件机制注册一个处理器。 以下是一个简化的处理器示例展示了如何解析参数并调用Pillow库 python # 假设在某个技能执行器注册文件中 from PIL import Image import os import json def execute_python_skill(skill_name: str, params: dict) - dict: “”“执行Python类型的技能”“” if skill_name “convert_image”: return convert_image(params) # ... 处理其他Python技能 def convert_image(params: dict) - dict: “”“具体的图片转换逻辑”“” try: source_path params.get(“source_path”) target_format params.get(“target_format”).upper() # 转为大写如 JPG - JPEG quality params.get(“quality”, 85) output_dir params.get(“output_dir”) # 1. 参数验证与安全校验 if not os.path.exists(source_path): return {“success”: False, “error”: {“code”: “FILE_NOT_FOUND”, “message”: f“源文件不存在: {source_path}”}} # 这里应添加路径安全校验防止路径遍历攻击 allowed_formats [‘PNG’, ‘JPEG’, ‘JPG’, ‘WEBP’, ‘GIF’] if target_format not in allowed_formats: return {“success”: False, “error”: {“code”: “UNSUPPORTED_FORMAT”, “message”: f“不支持的目标格式: {target_format}”}} # 2. 准备输出路径 if output_dir: os.makedirs(output_dir, exist_okTrue) filename os.path.basename(source_path) name_without_ext os.path.splitext(filename)[0] output_path os.path.join(output_dir, f“{name_without_ext}.{target_format.lower()}”) else: dir_name os.path.dirname(source_path) name_without_ext os.path.splitext(os.path.basename(source_path))[0] output_path os.path.join(dir_name, f“{name_without_ext}.{target_format.lower()}”) # 3. 执行转换 with Image.open(source_path) as img: # 处理RGBA转RGB的情况如PNG转JPG if target_format in [‘JPEG’, ‘JPG’] and img.mode in (‘RGBA’, ‘LA’, ‘P’): background Image.new(‘RGB’, img.size, (255, 255, 255)) if img.mode ‘P’: img img.convert(‘RGBA’) background.paste(img, maskimg.split()[-1] if img.mode ‘RGBA’ else None) img background elif img.mode ‘P’: img img.convert(‘RGB’) save_kwargs {‘format’: target_format} if target_format in [‘JPEG’, ‘JPG’, ‘WEBP’]: save_kwargs[‘quality’] quality elif target_format ‘PNG’: save_kwargs[‘compress_level’] 9 - round(quality / 100.0 * 9) # 将质量映射到压缩级别 img.save(output_path, **save_kwargs) # 4. 返回标准化结果 size_kb os.path.getsize(output_path) // 1024 return { “success”: True, “data”: { “message”: “图片转换成功。”, “original_path”: source_path, “output_path”: output_path, “format”: target_format, “size_kb”: size_kb } } except Exception as e: # 捕获所有未预见的异常 return {“success”: False, “error”: {“code”: “CONVERSION_ERROR”, “message”: str(e)}}踩坑点图片格式转换中有很多细节坑。比如PNG可能带有透明通道RGBA模式而JPG不支持透明直接转换会报错或产生黑底。上面的代码演示了如何处理这种常见情况——创建一个白色背景进行合并。这类“领域知识”是编写健壮技能的关键最好在SKILL.md的“备注”部分也稍作提示。4.3 测试与验证技能文档写好了代码也实现了下一步就是测试。重启你的OpenClaw服务它会自动加载新的convert_image.md技能。向量索引验证首先你可以通过OpenClaw的管理接口或日志查看新技能是否被成功加载和索引。通常会有日志显示Loaded skill: convert_image。模拟调用测试不通过AI直接构造一个请求发给OpenClaw的技能调用端点测试执行器是否正常工作。curl -X POST http://localhost:8000/execute \ -H “Content-Type: application/json” \ -d ‘{ “skill”: “convert_image”, “params”: { “source_path”: “/tmp/test.png”, “target_format”: “jpg” } }’检查返回的JSON是否符合SKILL.md中定义的响应格式。端到端AI测试这才是真正的考验。在OpenClaw的聊天界面里直接对AI说“帮我把/tmp/test.png转换成JPG格式质量要高一点。”理想情况AI能正确理解意图调用convert_image技能并生成参数{“source_path”: “/tmp/test.png”, “target_format”: “jpg”, “quality”: 90}最终执行成功并告诉你输出路径。常见问题技能不匹配AI可能调用了其他技能比如search_web。这说明技能描述不够精准或者向量检索相似度不高。需要优化convert_image.md中的描述文本。参数错误AI可能漏掉了quality参数或者把“质量高一点”错误映射为quality: “high”。这说明参数描述需要更明确比如可以加上“参数值为1到100的整数”。路径问题AI可能无法正确处理文件路径的上下文。如果用户只说“转换我的图片”AI需要有能力通过多轮对话追问“请提供源图片的路径”。这涉及到更复杂的对话状态管理超出了基础技能调用的范围但一个好的技能描述可以引导AI例如在描述中强调“必须提供源图片文件的完整路径”。通过这样从文档编写、代码实现到完整测试的流程一个全新的技能就被成功地“教授”给了OpenClaw。整个过程核心工作就是撰写一份清晰的Markdown文档其余的“理解”和“调度”工作都交给了框架和AI模型。5. 高级技巧与最佳实践让技能更“聪明”更可靠当你创建了几个技能后你会发现仅仅让AI“能用”还不够我们还需要它“用得巧”、“用得稳”。下面分享一些在实战中总结出来的高级技巧和避坑指南。5.1 撰写高质量技能描述的“心法”技能描述是AI理解技能的窗口其质量直接决定技能被正确调用的概率。使用场景化描述不要只写“做什么”要写“在什么情况下做什么”。欠佳“发送电子邮件。”优秀“当用户需要向指定的收件人发送一封包含主题和正文的电子邮件时使用此技能。适用于通知、报告等场景。”明确输入输出的边界在描述中暗示参数的“味道”。对于date参数描述可以写“日期格式为 YYYY-MM-DD例如 2023-10-27”。对于email参数可以写“有效的电子邮件地址”。利用关键词在描述中自然地融入可能被用户提及的同义词或相关词。对于get_weather描述中可以加入“天气、气温、气候、预报”等词提高向量检索的召回率。区分相似技能如果你有search_internal_doc和search_web两个技能描述必须突出其区别。search_internal_doc: “在公司内部的文档知识库中根据关键词搜索相关的技术文档、会议纪要和产品手册。”search_web: “在公开的互联网上使用搜索引擎查找最新的新闻、百科知识和公开资料。”5.2 复杂技能的设计模式对于需要多个步骤或决策的技能单一的SKILL.md可能不够。这时可以考虑两种模式技能编排Orchestration创建一个“主”技能它的逻辑是调用其他几个“子”技能。例如一个analyze_sentiment_report技能内部可以依次调用scrape_news-extract_text-call_sentiment_api-generate_chart。在主技能的描述中需要清晰说明这个复合过程。不过这要求OpenClaw框架支持技能间的链式调用。参数依赖与条件逻辑在SKILL.md的“备注”部分明确写出参数之间的依赖关系或条件。## 备注 - 当 format 参数为 pdf 时resolution 参数才有效。 - 如果 auto_crop 设置为 true则技能会先尝试检测并裁剪图片主体区域。虽然AI不一定能完全理解这些逻辑但这份文档对人类维护者和未来更高级的模型是有价值的。5.3 安全性与错误处理强化让AI操作真实系统安全是第一要务。输入验证与净化在执行器代码中必须对source_path、output_dir等参数进行严格的验证。检查路径遍历确保路径不包含..等符号防止访问系统敏感文件。限制文件操作范围最好配置一个白名单目录所有文件操作只能在该目录及其子目录下进行。参数类型与范围检查即使SKILL.md中定义了类型在执行代码中也要再次校验防止恶意构造的请求。资源限制对于可能消耗大量资源CPU、内存、时间的技能如视频转码、大规模文件处理必须在执行器中设置超时和资源限制。详细的错误反馈错误信息不要只返回“执行失败”。像前面示例那样提供错误码 (FILE_NOT_FOUND) 和可读的信息。这能极大帮助AI和用户理解问题所在甚至让AI能尝试修复比如提示用户“您提供的文件路径不存在请检查路径是否正确”。技能权限分级在SKILL.md的权限字段做文章。框架可以设计一个简单的权限模型比如public任何请求都可执行、user_confirm执行前需用户确认、admin仅管理员可用。在执行前进行权限校验。5.4 技能的管理与维护当技能数量增长到几十上百个时管理就变得重要。版本控制将skills/目录纳入Git版本控制。每次修改SKILL.md文件都有清晰的提交历史便于回滚和协作。技能目录与分类如前所述良好的目录结构就是最好的分类。你还可以在SKILL.md中增加category: [‘web’, ‘data’]这样的标签便于前端展示和过滤。技能测试套件为关键技能编写自动化测试脚本定期验证技能是否按预期工作。这尤其适用于依赖外部API的技能可以及时发现API变更或服务中断。技能使用监控与分析记录每个技能被调用的频率、成功率、耗时。这些数据能告诉你哪些技能最有用哪些技能最容易出错为优化提供数据支持。SKILL.md模式的美妙之处在于它将技能的“接口定义”文档和“实现细节”代码进行了松耦合的关联。开发者可以独立地更新文档来描述行为变更也可以优化后端代码来提升性能或修复Bug只要契约输入输出格式保持不变AI侧就能无缝适应。这种以文档为中心的、人机均可读的契约正是构建可进化AI智能体系统的基石。