如果你最近在折腾 OpenClaw一定绕不开 Clawhub 这个词。它相当于 OpenClaw 生态里的技能市场不用再为每个小能力手动写提示词、配 API、搭脚本直接在 Clawhub 里搜一个 skills 装进去agent 就会了。我这次拿最典型的 weather 技能做了个完整测试从搜索到安装再到真的问出杭州明天会不会下雨整个过程并不像文档里写的那么一帆风顺中间踩了几个坑也顺便把 Clawhub 的技能加载机制摸清了。这篇文章就把完整过程写出来适合正在部署 OpenClaw、准备给 agent 扩展技能库的朋友参考尤其是第一次接触 skills 机制的人。1. 为什么 OpenClaw 需要一套技能市场Clawhub 的思路1.1 从聊天框到技能化 Agent先说清楚 OpenClaw 到底在解决什么问题。它和常见的聊天机器人不一样你可以把它理解成一个本地优先的 AI 代理框架你把任务用自然语言丢给它它自己会决定调用什么工具、执行什么脚本、最后把结果整理好给你。和 Claude Code 这类工具类似OpenClaw 的生命力在于能干活而不是能聊天。但能干活这件事有个瓶颈每个新能力如果都要靠手动写脚本、配置模型提示词、处理参数解析成本太高了。比如最简单的天气查询如果不用 skills 机制我得先写一个 Python 脚本请求天气接口再在 OpenClaw 的配置文件里注册这个工具还得把用户问天气时应该调用这个脚本的语义关系通过提示词告诉模型。这套流程每加一个功能就要重复一遍非常劝退。Skills 机制的出现就是为了解决这个问题。它把一项能力打包成一个标准化的独立单元里面包含这个技能是干什么的、什么时候该触发、需要哪些参数、具体怎么执行。OpenClaw 启动时会自动扫描技能目录把每个技能是什么、何时用的信息注入到模型的上下文中。用户一旦提出相关请求模型就能从技能列表里选中匹配的那个再把参数解析好交给技能里的脚本执行。1.2 Skills 和 MCP、普通插件到底有什么区别我在社区里看到很多人把 MCP、插件、skills 混为一谈实际区别挺大的。MCPModel Context Protocol解决的是模型如何与外部工具通信这个协议层面的问题它定义了一套标准化的工具调用接口相当于给模型配了一个插座。而 skill 是一个更高层的东西它不只包含工具调用还包含了触发条件、参数模板、执行脚本、甚至是多步骤的提示词编排。你可以理解为MCP 是插座协议skill 是插在这个插座上的电器整机。对比维度MCP 工具OpenClaw Skill核心内容工具接口定义完整能力包含触发描述、参数、脚本谁来维护开发者手动注册从 Clawhub 一键安装触发方式显式调用模型根据语义自动匹配可分发性需自行搭建服务标准化打包可直接发布共享典型场景连数据库、连外部 API天气查询、网页抓取、文档处理等综合任务拿我这个天气测试举例用 MCP 的方式我需要自己去定义一个get_weather(city)工具并注册用 skills 的方式我从 Clawhub 装一下OpenClaw 就知道用户聊到天气、气温、下雨、风力时应该调这个技能连触发判断都一并解决了。对于大多数普通用户来说skills 的门槛明显更低。1.3 Clawhub 解决了社区分发的什么痛点Clawhub 是 OpenClaw 官方的技能分发仓库你可以把它想象成 npm 或者 Homebrew 的 AI 技能版。在它出现之前社区分享技能基本靠两件事把目录打包成 zip 传到网盘或者直接贴 GitHub 仓库链接。用户拿回来后要手动解压、放到正确的目录、检查依赖、确认版本。这套流程有几个明显的麻烦放置位置经常搞错技能装了却加载不到不知道技能是否需要 API key装完才发现环境变量没配版本没法管理作者更新了你还用着旧版技能之间的命名冲突全靠自觉装重名了也不知道。Clawhub 把这些全标准化了搜索在统一索引里完成安装命令自动把技能放到正确目录元数据里写清楚依赖和环境变量要求还支持指定版本号锁定。说白了技能分发的体验从上世纪手动下载软件包进化到了像用手机应用商店一样装技能。这也是我把这次测试重点放在 Clawhub 上的原因——它才是 OpenClaw 技能生态真正的地基。2. 部署 OpenClaw 和准备 Clawhub 环境的几个要点2.1 三种部署方式怎么选我在 Ubuntu 22.04 的机器上部署了两个版本做对比加上平时帮朋友看问题时的经验主流部署方式就三种选择取决于你的使用场景。部署方式适合场景我的评价官方一键脚本个人本机快速体验最省事自动处理依赖和目录推荐新手Docker 容器服务端长期运行、需要隔离环境干净但挂载配置目录时容易踩权限坑源码构建二次开发、想改核心逻辑灵活但需要 Node 环境且编译耗时较长如果你只是想在本地给 agent 加技能、跑通流程我建议直接走一键脚本。脚本会自动检查 Node 版本、创建~/.openclaw目录、装好核心依赖整个过程大概几分钟。我用 Docker 也跑过一次优势是卸载干净缺点是挂载~/.openclaw目录后容器内外的用户 ID 不一致经常导致技能目录不可写排查起来比较绕。源码构建适合想改 OpenClaw 本身逻辑的人普通用户没必要自己编译。2.2 初始化配置模型接入和 skills 目录安装完成之后第一件事是写配置文件~/.openclaw/config.yml。OpenClaw 本身不绑定某个固定模型你既可以用云端模型 API也可以接本地模型。我这里用的是本地 Ollama 服务配置长这样# ~/.openclaw/config.yml model: provider: openai-compatible base_url: http://127.0.0.1:11434/v1 api_key: ollama model: qwen2.5:14b skills: dir: ~/.openclaw/skills clawhub: registry: https://hub.openclaw.dev注意skills.dir这个字段它决定了你安装的技能放在哪里默认是~/.openclaw/skills。如果你把配置放在项目目录里想改成项目级技能目录也可以指向.claw/skills。我个人建议保持全局默认路径因为 Clawhub 安装技能时默认就往这个目录写改来改去反而容易混乱。启动之前最好先验证一下模型接口通不通。我当时图省事直接启动结果模型没接上agent 一直报连接错误后来才发现是base_url的端口写错了。这个坑在部署阶段很容易被忽略强烈建议启动前先curl一下模型服务的地址。2.3 首次连接 Clawhub 的检查配置文件写好后启动 OpenClaw 之前先快速检查 Clawhub 是否能连通。我用的是这样的命令序列# 确认版本 openclaw --version # 查看 clawhub 子命令帮助 openclaw clawhub --help不同版本的命令组织方式略有差异我用的这个版本里技能操作统一挂在openclaw clawhub下面。有些旧版本用的是openclaw skills install如果你敲命令报错可以先跑到openclaw clawhub --help里确认一下当前版本的子命令结构别照搬网上教程硬敲。这里的核心思路是把 Clawhub 当成一个远程仓库源先确认客户端能访问源再去做安装操作。否则你后面执行install时卡在超时上会误以为是技能的锅其实是网络根本没通。3. 从 Clawhub 安装 Weather Skill命令、参数和它装完后发生了什么3.1 先搜索再确认避免装错同名技能技能市场和应用商店一样有重名问题。我这次想装天气查询直接search weather出来的结果有好几个有的叫weather有的叫weather-cli还有叫daily-weather的功能侧重点完全不同。正确姿势是先搜索再用info查看详情确认作者、描述、依赖要求都符合预期后再装# 搜索包含 weather 的技能 openclaw clawhub search weather # 查看某个技能的详细信息 openclaw clawhub info weatherinfo返回的信息里我最关注三个字段Description 是否和我想要的场景匹配、Dependencies 里有没有额外要求、Environment variables 里有没有要求配置 API key。这三个字段直接决定了装完之后能不能用。我选的这个weather技能使用的是 wttr.in 数据源不需要额外申请 API key依赖只有一个 Python 3 标准库非常适合第一轮测试因为环境变量和第三方依赖这两个最容易出问题的变量直接排除了。3.2 执行安装具体命令和版本参数确认没问题后直接安装openclaw clawhub install weather安装过程会显示进度下载技能包、解压到~/.openclaw/skills/weather、校验文件完整性。整个过程不到十秒。这里有几个参数我建议大家了解一下后面排错时很有用--version 1.2.0指定版本安装。我平时习惯只装指定版本避免某天作者推了个有 bug 的新版本把我环境搞崩--force强制覆盖安装。技能目录里已经有同名技能时可以强制重装--no-deps不自动安装依赖。如果你发现自己手动管理依赖可以用这个参数跳过自动装依赖的环节。装完以后用openclaw clawhub list确认一下输出里能看到 weather 技能已经在列表中说明注册成功。我当时看到列表里出现了 weather以为万事大吉直接就去问天气结果 agent 完全不理会这个技能。这个问题我放在第 5 章详细讲先继续看技能包本身的结构。3.3 装完之后看看 skills 目录一个 skill 包到底有什么安装完成后我习惯性打开目录看一眼这个习惯救了我很多次。一个标准的 skill 包长这样~/.openclaw/skills/weather/ ├── SKILL.md ├── fetch_weather.py ├── requirements.txt └── assets/ └── icon.png最核心的是SKILL.md它是整个技能的大脑。文件头部是 YAML frontmatterOpenClaw 靠它来理解这个技能--- name: weather description: 查询全球主要城市的实时天气、未来 1-3 天预报、降雨概率、风速和空气质量。当用户询问任何关于天气、气温、下雨、下雪、风力、空气质量的问题时使用这个技能。 arguments: - name: city description: 城市名称支持中文、拼音和英文例如“杭州”、“hangzhou”、“Hangzhou” required: true - name: days description: 预报天数取值 1 到 3默认 1 required: false ---这段 frontmatter 里的description是 OpenClaw 触发技能的关键。启动时OpenClaw 会把每个技能的name和description拼装成一份可用技能清单注入到模型上下文里。模型判断用户问题该调用哪个技能靠的就是这段描述是否命中用户意图。我后来反复排查技能不触发的问题最后十次里有八次都是因为description写得不够清楚模型根本没意识到该用它。fetch_weather.py是实际的执行脚本。OpenClaw 的约定是把解析好的参数以 JSON 字符串形式作为第一个命令行参数传给脚本脚本执行后把结果以 JSON 格式打印到标准输出OpenClaw 再把它返回给模型整理。核心逻辑大致是这样的#!/usr/bin/env python3 import json import sys import urllib.request url_template https://wttr.in/{city}?formatj1 def main(): args json.loads(sys.argv[1]) city args.get(city, ).strip() days int(args.get(days, 1)) url url_template.format(cityurllib.parse.quote(city)) data json.loads(urllib.request.urlopen(url).read()) result extract_weather(data, days) # 提取温度、湿度、风力、预报等字段 print(json.dumps(result, ensure_asciiFalse)) if __name__ __main__: main()我自己测试时也手动执行过这个脚本确认数据源返回正常再回到 OpenClaw 里测试。这个习惯避免了大量无效排查——先确认脚本本身没问题再去查 agent 调度层面的问题。4. 实测让 OpenClaw 用天气技能完成一次真实查询4.1 交互式会话完整演示安装完成、脚本验证通过后进入实际测试环节。启动 OpenClaw 交互模式直接问天气$ openclaw 帮我看看杭州明天会不会下雨 [openclaw] 检测到用户请求与 weather 技能匹配正在调用... [skill:weather] 参数解析: {city: 杭州, days: 2} [skill:weather] 执行: python3 ~/.openclaw/skills/weather/fetch_weather.py {city: 杭州, days: 2} 杭州Hangzhou未来 2 天预报 明天小雨转多云 气温18°C ~ 24°C 降雨概率70% 风速东北风 3 级 湿度82%这个结果说明整条链路是通的模型理解了明天会不会下雨这个语义匹配到了 weather 技能把杭州解析成了city参数脚本成功从数据源拉取并整理了预报信息最终以自然语言形式返回给用户。整个调用过程我没有写一行代码这就是 skills 机制带来的效率和体验。这里我特意用了明天会不会下雨这种问法而不是干巴巴地说查杭州天气。因为前者更接近真实使用场景也更能测试技能的语义触发能力。一个设计良好的 skill应该能通过 description 里的触发词覆盖各种口语化问法。4.2 观察 agent 调用 skill 的决策过程如果你想知道模型到底是怎么决定调用这个技能的把日志级别调到 debug 再跑一次就能看到细节openclaw --debug日志里会出现类似这样的关键行[11:02:33] match skill: weather (score0.86) [11:02:33] prepare arguments: {city: 杭州, days: 2} [11:02:34] exec: python3 /home/user/.openclaw/skills/weather/fetch_weather.py {city: 杭州, days: 2} [11:02:35] skill output: {city: 杭州, days: 2, current_temp: 22, ...}match skill: weather (score0.86)这行最有价值。它告诉你模型在技能清单里计算了匹配度得分最高的会被选中。days参数为什么是 2因为用户问了明天模型根据日期推算发生在两天内于是自动把days设为了 2。这说明技能 frontmatter 里arguments的参数描述对模型的推理有直接影响。你在自研技能时参数描述写得越具体模型解析参数的准确率就越高。另外注意一个细节脚本返回原始 JSON 后OpenClaw 还有一步翻译成自然语言的流程。这一步由模型完成所以即便脚本只返回结构化字段用户看到的依然是一段通顺的中文天气播报。这也是很多第一次接触 skills 的人会疑惑的地方——怎么脚本只输出 JSON用户却看到的是完整句子因为中间隔了一层大模型的总结。4.3 多城市多轮查询验证技能的边界单次查询通过后我又做了几轮测试目的是摸清技能的边界在哪里。先是多城市连续查询。同一会话里依次问北京、上海、广州、成都每次都能正确切换城市说明模型在长对话中不会把上一轮的城市参数串到下一轮去。这个点其实很关键因为很多自研技能在单轮测试里跑得通一进多轮对话就暴露参数残留问题。接着测试了英文城市名和拼音。问Tokyo weather时模型把Tokyo传给脚本后返回东京天气数据源也对中文做了拼音兼容说明这个技能在参数解析上做得比较规范。然后我故意问了一个不存在的城市帮我查一下亚特兰蒂斯今天的天气。结果是技能正常触发参数也正常解析但脚本返回的数据源异常导致输出变成了警告信息OpenClaw 随后回复暂时无法获取该地区的天气数据。这个表现是可接受的——它没有胡编乱造一个天气数据而是诚实地告诉了用户查询失败。我在不少自研技能里见过模型强行编数据的现象这个技能在失败处理上算是合格的。5. 装好不等于能用三个高频坑的完整排查链路5.1 技能装了却从不触发先查描述再查注册我第一次装完 weather问今天天气怎么样agent 直接回复我没有这个能力。技能明明在列表里为什么没触发我把排查链路完整走了一遍这里按顺序写出来供大家直接复现排查思路第一步确认技能确实在列表里openclaw skills list如果列表里没有说明安装有问题回到第 3 章重新走安装流程。如果列表里有进入第二步。第二步查看SKILL.md的description是否覆盖了你的问法cat ~/.openclaw/skills/weather/SKILL.md我那次的问题就在这里某个版本里 description 写的是查询当前温度、湿度、风速没有提下雨和预报所以我问会不会下雨时模型在技能清单里扫描后认为 weather 技能不太相关就放弃了调用。把 description 改成覆盖天气全场景的宽口径描述后触发率显著提升。第三步如果 description 没问题检查 model 是否支持函数调用。我本地接的 qwen 模型是支持 tool calling 的但有些量化版模型会丢弃工具调用能力这种情况只能换模型。第四步重启 OpenClaw 让技能重新注册。技能加载发生在启动阶段如果会话已经开启再装新技能需要重启才能生效。这个坑非常常见尤其是在测试阶段频繁装技能的时候。5.2 报 401 或者调用失败十有八九是 API Key 没接上community 里有不少 weather 类技能默认走的是 OpenWeatherMap 之类的商业 API需要申请 API key。装完这类技能直接问脚本会报 401 或者 quota exceeded。这时候先别急着怪技能检查路径是这样的# 查看技能包要求哪些环境变量 cat ~/.openclaw/skills/weather/.env.example # 把 key 写入全局环境变量文件 echo WEATHER_API_KEY你的key ~/.openclaw/.envOpenClaw 启动时会读取~/.openclaw/.env并注入到技能脚本的执行环境里。注意两点一是 key 名字必须和技能要求的完全一致大小写都不能错二是改完.env要重启 OpenClaw 才生效。我见过不少人是把 key 写在了技能目录下的.env里但 OpenClaw 默认不读那个位置导致怎么配都不对。如果不想申请 API key选择基于 wttr.in 的 weather 技能是最省事的方案完全免 key。缺点是数据源免费所以有一定访问频率限制个人使用完全足够。5.3 脚本缺依赖Python 环境隔离问题如果技能脚本依赖第三方库比如 requests、pandas装完直接跑大概率会遇到底层报错ModuleNotFoundError: No module named requests这个问题的根源在于OpenClaw 默认用系统 Python 直接执行技能脚本不会自动创建虚拟环境。所以技能声明的依赖得你自己手动装pip install -r ~/.openclaw/skills/weather/requirements.txt在全局环境里装依赖省事但不同技能之间可能依赖冲突。我的习惯是直接用 venv 做隔离python3 -m venv ~/.openclaw/.venv ~/.openclaw/.venv/bin/pip install -r ~/.openclaw/skills/weather/requirements.txt然后在配置里把技能的 Python 解释器指向虚拟环境的python。如果你只是实验性质地玩一下直接全局安装也不是不行但养成隔离的习惯等到技能多了以后会少很多麻烦。另外不管用哪种方式装完依赖后建议手动跑一遍技能脚本确认能输出 JSON再回到 OpenClaw 测试。5.4 拉不到 Clawhub 索引时的检查顺序openclaw clawhub search weather卡住、超时、或者提示无法获取索引时按这个顺序排查先确认openclaw --version是不是太旧旧版本的 registry 地址可能已经变更直接更新 OpenClaw 通常能解决再查看当前配置的 registry 地址openclaw clawhub registry show确认地址没被改动过且当前网络环境可以访问。如果是在受限网络环境里需要让网络策略放行 Clawhub 的域名这是很多内网部署用户容易踩的点最后检查~/.openclaw/config.yml里的clawhub.registry字段是否被错误覆盖。我见过有人跟着老教程配置了一个失效的镜像地址结果所有 clawhub 命令全部失败改回默认地址后恢复正常。这一整套排查链路的关键是先把能不能访问源和技能本身有没有问题分开看不要混在一起排查否则很容易浪费时间。6. 天气技能装完之后Clawhub 还能给你什么6.1 值得试的几类 skillsweather 只是最基础的入门技能。装完它、跑通机制之后我强烈建议去 Clawhub 上逛一圈有几类技能是社区里评价比较高的superpowers这是一个组合包里面包含了很多通用任务增强能力比如代码审查、需求拆解、长文本分析等。装一个能同时获得多个技能适合想快速丰富 agent 能力的用户obsidian 系列把本地 Obsidian 笔记库接入 OpenClawagent 可以基于你的笔记内容回答问题。对于知识管理重度用户来说价值很高microsoft teams 接入类让 OpenClaw 把运行结果推送到 Teams 频道适合把 agent 部署成团队机器人每天自动汇总报告、推送监控信息前端开发辅助类生成网页、调试 CSS、审查响应式布局这类技能对做前端的人帮助很大。安装方式和 weather 完全一样搜到、看 info、install、测试四步走。唯一要注意的是前几个技能体积大、依赖多装之前建议仔细看 Dependencies 字段别一股脑全装否则环境会被依赖冲突搅成一锅粥。6.2 自己开发一个 skill 的最小结构用顺手之后你会发现公共技能库不一定能满足所有需求自己写一个 skill 其实没有想象中复杂。最小结构只需要两个文件一个SKILL.md描述能力一个脚本干实事。举个例子我给自己写了一个查汇率的简单技能--- name: exchange-rate description: 查询指定货币对的最新汇率例如人民币兑美元、欧元兑日元。当用户询问汇率、兑换、多少钱时可以调用这个技能。 arguments: - name: from description: 基础货币代码如 CNY、USD、EUR required: true - name: to description: 目标货币代码如 CNY、USD、EUR required: true ---然后配一个十行左右的 Python 脚本请求免费汇率接口把结果返回。把这两个文件放进~/.openclaw/skills/exchange-rate/目录重启 OpenClaw技能就注册成功了。开发时最大的经验教训是description 要站在模型怎么理解用户意图的角度来写而不是站在我这个功能是什么的角度写。技术指标写再准确模型识别不到适用场景也白搭。多想想用户会怎么问话把这些问法揉进 description 里触发成功率会高一个量级。6.3 把 skills 变成团队资产当你积累了一批自研技能之后单机使用就有点浪费了。~/.openclaw/skills目录天然就是一个普通文件夹完全可以用 git 管理起来。我的做法是建一个私有仓库把整个 skills 目录推上去团队里其他人的 OpenClaw 配置里把skills.dir指向 clone 下来的目录就能共享同一套技能。更进一步Clawhub 支持私有 registry 的配置方式团队可以搭一个内部技能仓库把自研技能发到内部源里成员直接用openclaw clawhub install安装。这样连手动 clone 都省了。发布公共技能也很简单参照 Clawhub 的提交流程把技能包按要求整理好提交审核审核通过后全网用户都能搜索安装。有一次我在内部仓库里发布了新版 exchange-rate结果发现某台服务器上的版本还是旧的后来才意识到当时没锁定版本号直接装的是latest本地没问题但服务器索引缓存了旧版本。后来我统一改成指定版本安装openclaw clawhub install exchange-rate1.3.0并且把版本号写进团队文档里这个问题再也没有出现过。最后分享一个我自己的习惯装完任何带脚本的技能后我不会立刻在 OpenClaw 里测试而是先手动跑一遍脚本确认数据源响应正常、输出明天是一个合法 JSON再回到 OpenClaw 里问一遍。这样如果出问题能直接分清是技能本身的问题还是 agent 调度的问题。这个习惯帮我省了无数排错时间也推荐给你试试。