1. 从一次 Skill 加载失败说起OpenClaw Skill 是赋予 AI 代理专业能力的核心机制——通过编写 SKILL.md 文件你可以让 Agent 学会使用特定工具、遵循特定流程、在特定场景下自动触发。但真正动手写第一个自定义 Skill 时很多人会卡在同一个地方SKILL.md 写完了openclaw skills list里却看不到它或者 Skill 加载成功Agent 却死活不触发。我试过在一个天气查询 Skill 上反复折腾了两小时最后发现是requires.bins里写了一个系统里根本不存在的二进制名门控直接把整个 Skill 拦掉了。这类问题不会报错只会静默跳过对新手极不友好。这篇指南面向 Agent 开发者聚焦 OpenClaw Skill 从 SKILL.md 骨架到 ClawHub 发布的完整链路。你会拿到可复制的 SKILL.md 模板、TaoToken 统一 Key/API 通道的 config.toml 配置骨架以及本地加载与调用验证动作。无论你是 OpenClaw 新手还是想进阶定制化的高级用户都能按步骤跑通自定义技能。2. TaoToken 前置统一 Key 与 API 通道在写 Skill 之前先把模型调用通道配好。OpenClaw 的 Skill 本身不绑定模型供应商但 Agent 执行 Skill 时需要调用大模型做意图理解和结果总结。TaoToken 提供统一的 API 通道一个 Key 可以走多个模型省去在 config.toml 里维护多套凭证的麻烦。2.1 获取 API Key访问 TaoToken 控制台的 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite创建一个新 Key。建议按用途命名比如openclaw-skill-dev方便后续排查。拿到 Key 后不要直接写进 SKILL.md——Skill 文件可能会被发布到 ClawHub凭证泄露风险很高。正确做法是写进 OpenClaw 的 config.toml通过环境变量注入。2.2 config.toml 配置骨架OpenClaw 的配置文件通常位于~/.openclaw/config.toml。下面是一个可复制的骨架把YOUR_TAOTOKEN_KEY替换成你实际的 Key[models] default claude-sonnet-4-20250514 [models.providers.taotoken] base_url https://taotoken.net/api api_key YOUR_TAOTOKEN_KEY models [ claude-sonnet-4-20250514, gpt-4o, deepseek-chat ] [skills] # Skill 根目录支持多个路径 load [ ~/.openclaw/workspace/skills, ~/.openclaw/skills ]这里的关键点base_url用https://taotoken.net/api不要加 UTM 参数那是给网页跳转用的。models数组里列出你计划在 Skill 中调用的模型名OpenClaw 启动时会校验这些模型是否可用。2.3 验证通道连通配置写完后先用一条命令确认通道能通openclaw models test --provider taotoken --model claude-sonnet-4-20250514如果返回模型响应说明 Key 和 base_url 都正确。如果报 401检查 Key 是否复制完整如果报连接超时检查网络和 base_url 拼写。3. SKILL.md 骨架与可复制模板Skill 的核心是 SKILL.md采用 YAML 前置元数据 Markdown 正文的格式。前置元数据定义 Skill 的身份、触发条件和门控规则正文是给 Agent 看的执行指令。3.1 最小可用模板下面是一个可以直接复制修改的 SKILL.md 骨架--- name: my-skill description: One-line description of what this skill does. Use when user mentions keyword1, keyword2, or asks about specific scenario. metadata: openclaw: requires: bins: [python3] env: [MY_SKILL_API_KEY] --- # My Skill When the user asks about scenario, run the following command: bash python3 {baseDir}/scripts/run.py argumentGuidelinesReplaceargumentwith the value extracted from user inputPresent results in a clear, formatted wayIf the command fails, inform the user and suggest retryingError HandlingNetwork timeout: default 10 seconds, suggest checking connectionMissing argument: ask user to clarify这个骨架里name 和 description 是必填字段。description 直接决定 Agent 能否自动触发这个 Skill——写得越具体、触发词越丰富触发率越高。 ### 3.2 门控字段说明 metadata.openclaw.requires 下的门控字段控制 Skill 的加载条件 | 字段 | 说明 | 示例 | |------|------|------| | bins | 所有指定二进制必须在 PATH 中 | [python3, curl] | | anyBins | 至少一个指定二进制存在 | [node, bun] | | env | 每个指定环境变量必须存在 | [MY_API_KEY] | | os | 平台过滤器 | [darwin, linux] | | always | 设为 true 跳过所有门控检查 | true | 门控不满足时Skill 会被静默跳过不会出现在 openclaw skills list 中。这是新手最容易踩的坑——写了一个依赖 jq 的 Skill但系统里没装 jqSkill 就永远加载不了。 ### 3.3 正文编写规范 正文是给 Agent 看的指令需要做到几点明确触发条件、列出具体执行步骤、说明参数含义、给出示例输出、处理错误情况。引用 Skill 目录内的文件时用 {baseDir} 代替硬编码路径 markdown Run the helper script at {baseDir}/scripts/run.sh.{baseDir}会在运行时被替换为 Skill 的实际目录路径保证 Skill 被安装到不同位置时都能正常工作。4. 本地加载与调用验证写完 SKILL.md 后不要急着发布先在本地验证加载和触发。4.1 验证 Skill 是否加载把 Skill 目录放到配置的 skills 根目录下然后运行openclaw skills list如果列表里出现了你的 Skill 名称说明 YAML 解析和门控检查都通过了。如果没有出现按以下顺序排查# 检查文件位置 ls -la ~/.openclaw/workspace/skills/my-skill/SKILL.md # 检查 YAML 语法用 Python 快速验证 python3 -c import yaml; print(yaml.safe_load(open(SKILL.md).read().split(---)[1])) # 检查门控依赖 which python3 echo $MY_SKILL_API_KEY4.2 测试 Skill 触发确认加载后用 Agent 命令行测试触发openclaw agent --message 帮我查一下北京今天的天气如果自动触发失败但斜杠命令成功问题通常出在description字段——Agent 无法从用户消息中匹配到你的 Skill。这时需要优化 description 的触发关键词。4.3 日志排查当 Skill 执行出问题时查看 Gateway 日志是最直接的排查方式# 查看实时日志 openclaw gateway logs # 只看 Skill 相关 openclaw gateway logs | grep -i skill # 查看 Agent 决策日志 openclaw gateway logs | grep -i skill.*trigger日志里能看到 Skill 的加载和注册过程、Agent 选择 Skill 的决策依据、Skill 执行的详细步骤和输出、错误信息和堆栈跟踪。4.4 会话刷新技巧修改 SKILL.md 后如果 Agent 似乎没有使用新版本可能是当前会话使用了缓存的 Skill 列表。在对话中输入/new新建会话或者重启 Gatewayopenclaw gateway restart5. 常见错误排查5.1 Skill 不在列表中最常见的原因是门控条件不满足。检查requires.bins里的二进制是否都在 PATH 中requires.env里的环境变量是否都已设置。如果只是本地测试可以临时设always: true跳过门控但发布前记得改回来。另一个原因是 YAML 格式错误。前置元数据里的缩进必须用空格不能用 Tab。name字段只能用小写字母、数字和连字符。5.2 Skill 不自动触发description 不够明确是主因。对比下面两个写法# 不好的描述——太简短容易漏触发 description: Weather lookup skill # 好的描述——包含功能、触发词和使用场景 description: Get current weather, rain, temperature, and forecasts for locations or travel planning. Use when user mentions weather, temperature, rain, forecast, or asks about travel conditions.好的 description 会列出同义词和触发词、包含隐性场景描述、使用具体动词而非模糊描述。5.3 Skill 触发但执行失败脚本路径错误是最常见的原因。检查 SKILL.md 里是否用了{baseDir}而不是硬编码路径。另外确认脚本有执行权限chmod x scripts/*.sh如果是 Python 脚本确认 shebang 行正确且脚本里没有依赖未安装的第三方库。5.4 修改后未生效OpenClaw 通常会监视 SKILL.md 文件变化并热更新但在某些情况下如编辑器保存事件丢失手动刷新是必要的。用/new新建会话或重启 Gateway 即可。6. 实战天气查询 Skill 完整开发现在动手开发第一个自定义 Skill——天气查询技能。它会调用免费天气 API返回当前天气和 3 天预报。6.1 创建目录和脚本mkdir -p ~/.openclaw/workspace/skills/weather-query/scripts创建scripts/weather.py#!/usr/bin/env python3 Weather query skill script for OpenClaw. import json import sys import urllib.request import urllib.parse def get_weather(city: str) - dict: Fetch weather data from wttr.in API. encoded urllib.parse.quote(city) url fhttps://wttr.in/{encoded}?formatj1 try: req urllib.request.Request(url, headers{User-Agent: curl/7.68.0}) with urllib.request.urlopen(req, timeout10) as resp: return json.loads(resp.read().decode()) except Exception as e: return {error: str(e)} def format_weather(data: dict, city: str) - str: Format weather data into readable output. if error in data: return f查询失败: {data[error]} current data.get(current_condition, [{}])[0] area data.get(nearest_area, [{}])[0] lines [ f城市: {area.get(areaName, [{}])[0].get(value, city)}, f天气: {current.get(weatherDesc, [{}])[0].get(value, N/A)}, f温度: {current.get(temp_C, N/A)}°C (体感 {current.get(FeelsLikeC, N/A)}°C), f湿度: {current.get(humidity, N/A)}%, f风速: {current.get(windspeedKmph, N/A)} km/h, ] for day in data.get(weather, [])[:3]: date day.get(date, N/A) max_t day.get(maxtempC, N/A) min_t day.get(mintempC, N/A) desc day.get(hourly, [{}])[4].get(weatherDesc, [{}])[0].get(value, N/A) lines.append(f{date}: {desc}, {min_t}~{max_t}°C) return \n.join(lines) if __name__ __main__: city .join(sys.argv[1:]) if len(sys.argv) 1 else Beijing data get_weather(city) print(format_weather(data, city))脚本用 Python 标准库实现无需 pip 安装任何依赖。6.2 编写 SKILL.md--- name: weather-query description: Get current weather, temperature, rain forecast for any city. Use when user mentions weather, 天气, 温度, 下雨, forecast, or asks about travel conditions. metadata: openclaw: requires: bins: [python3] --- # Weather Query Skill When the user asks about weather for a location, run the weather script. ## Execution bash python3 {baseDir}/scripts/weather.py city_nameGuidelinesReplacecity_namewith the city the user mentionedSupport both Chinese and English city namesIf user doesnt specify a city, default to their last mentioned locationPresent results in a clear, formatted wayError HandlingIf the API call fails, inform the user and suggest trying againNetwork timeout: default is 10 seconds### 6.3 测试验证 bash # 验证加载 openclaw skills list | grep weather # 命令行测试 openclaw agent --message 上海今天天气怎么样 # 斜杠命令测试 /weather-query 上海预期输出会包含城市名、天气描述、温度、湿度和 3 天预报。7. 发布到 ClawHub 市场当 Skill 在本地验证通过后可以发布到 ClawHub 分享给社区。7.1 发布前检查清单确认 SKILL.md 包含完整的 name 和 description、description 包含触发关键词、门控条件已正确设置、所有脚本有执行权限、已在本地充分测试、不包含敏感信息API 密钥、个人数据。7.2 使用 ClawdHub CLI 发布# 安装 CLI npm i -g clawdhub # 登录 clawdhub login # 验证登录状态 clawdhub whoami # 发布 clawdhub publish ./weather-query \ --slug weather-query \ --name Weather Query \ --version 1.0.0 \ --changelog Initial release版本号遵循语义化版本规范补丁版本修 Bug次版本加功能主版本做破坏性变更。7.3 版本更新流程clawdhub publish ./weather-query \ --slug weather-query \ --name Weather Query \ --version 1.1.0 \ --changelog Added 3-day forecast, fixed timeout issue7.4 发布最佳实践description 是门面花时间打磨它决定了 Skill 能否被发现和正确触发。最简版本先发布后续迭代增加功能。错误处理优先网络超时、API 限流、参数缺失都要处理。纯标准库优先减少用户安装依赖。版本管理用 semver每次发布都写清楚 changelog。8. 语义一致 CTA如果你在配置 TaoToken 通道时遇到问题或者想验证不同模型在 Skill 场景下的表现可以走这几个入口排障与接入先看 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite确认 Key 状态再对照接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite检查 base_url 和参数格式。验证模型效果在模型对话https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite里直接测试 Skill 中要用的模型确认响应质量和延迟。长期编码与 Agent 开发如果你打算持续开发多个 Skill 并跑 Agent 工作流Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite更适合高频调用场景。Skill 开发最有效的学习方式是从修改一个内置 Skill 开始逐步过渡到自己创建新 Skill。当你发现自己反复执行某个操作时就是创建 Skill 的最佳时机。
