1. 从一次技能调用失败说起OpenClaw 的技能机制简单说就是把「一段可复用的能力」打包成文件夹让 Agent 在合适的时机自动调用。它能做什么把查询、抓取、计算、格式化这类重复动作固化成脚本Agent 只负责判断「什么时候用」和「传什么参数」。适合谁想把日常重复操作沉淀成自动化流程的开发者尤其是已经在用 OpenClaw 做 Agent 编排的人。我试过直接让 Agent 现场写脚本跑任务结果每次输出格式都不一样参数名还老变。后来才明白技能的价值不在于「能跑」而在于「稳定地按约定跑」。SKILL.md 就是这个约定的载体——它既是给 Agent 看的提示词也是给脚本传参的契约。这篇按「从零搭一个可运行技能」的路径走先讲清楚技能目录骨架再给出 SKILL.md 的完整配置片段接着串起 Agent 调用与脚本执行最后用逐步验证动作确认它真的生效并排查几个高频报错。全程可复制你跟着敲就能跑通一个自己的技能。2. 前置准备TaoToken 与 OpenClaw 环境在动手写技能之前得先让 Agent 有稳定的模型调用通道。OpenClaw 本身是编排层真正干活的是背后的模型。我用 TaoToken 作为模型接入层原因是它的接口兼容主流协议配置一次就能在 Agent 里反复调用省去来回换 Key 的麻烦。官网入口在这里https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册后在控制台生成 API Key。API 基地址是 https://taotoken.net/api 注意这个地址不带任何查询参数直接填进配置即可。拿到 Key 之后先确认 OpenClaw 能正常调用模型再开始写技能。顺序反了的话技能报错你分不清是 SKILL.md 写错了还是模型通道没通。这一步的验证命令后面第 4 节会给。提示API Key 建议放在环境变量里不要硬编码进 SKILL.md 或脚本。技能文件经常要分享或提交到仓库明文 Key 泄露风险很高。3. 技能目录骨架与 SKILL.md 配置3.1 标准目录结构一个技能就是一个文件夹文件夹名即技能 ID。最小可用结构只需要 SKILL.md但要做成能维护的技能建议按下面这套骨架来my-skill/ ├── SKILL.md # 必须技能定义、触发规则、输入输出契约 ├── scripts/ # 可执行脚本py / sh / js │ └── run.py ├── references/ # 参考文档、API 说明、schema ├── templates/ # 代码或配置模板 ├── assets/ # 静态资源 ├── examples/ # 使用示例 └── tests/ # 测试用例SKILL.md 是入口Agent 先读它再决定是否调用 scripts 里的脚本。references 和 templates 是给脚本或 Agent 补充上下文用的不是必须但技能一复杂就离不开。3.2 SKILL.md 的六类核心信息把 SKILL.md 拆开看它承载六类信息元数据name、description、输入参数、执行流程、外部工具、输出格式、触发规则。其中 name 是唯一标识description 是 Agent 选择技能的最重要依据——写得好不好直接决定 Agent 会不会在该用的时候用上它。下面是一个可直接复制的 SKILL.md 配置片段功能是「按关键词抓取科技新闻标题和链接」--- name: tech-news-fetch version: 1.0.0 description: 按关键词抓取科技媒体新闻标题与链接。当用户查询某关键词的最新资讯、动态、新闻时使用。支持数量限制返回结构化 JSON。 --- # 科技新闻抓取 ## 输入参数 | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | keyword | string | 是 | 新闻关键词如「大语言模型」 | | limit | int | 否 | 返回条数默认 10范围 1-50 | ## 执行流程 1. 向用户确认 keywordlimit 缺省为 10 2. 调用 scripts/run.py传入 keyword 与 limit 3. 脚本抓取并解析结果按相关性排序 4. 截断到 limit 条输出 JSON 数组 ## 输出格式 json [ { title: 新闻标题, url: https://example.com/xxx } ]触发场景「帮我找一下关于 XX 的最新新闻」「XX 最近有什么动态」「查一下 XX 的资讯」注意 frontmatter 里的 description 要写清楚「什么时候用」而不是「这个技能是什么」。Agent 匹配的是场景不是功能名。 ### 3.3 脚本与 SKILL.md 的契约 scripts/run.py 要严格按 SKILL.md 里声明的参数名接收输入。下面是一个最小可运行示例 python import argparse import json def main(): parser argparse.ArgumentParser() parser.add_argument(--keyword, requiredTrue) parser.add_argument(--limit, typeint, default10) args parser.parse_args() # 这里替换成真实的抓取逻辑 results [ {title: f{args.keyword} 相关新闻 {i}, url: fhttps://example.com/{i}} for i in range(1, args.limit 1) ] print(json.dumps(results, ensure_asciiFalse, indent2)) if __name__ __main__: main()参数名、默认值、输出结构必须和 SKILL.md 一致。这是最容易出错的地方SKILL.md 写limit脚本里写成countAgent 传参就会失败。4. 验证请求与成功结果4.1 先验证模型通道在装技能之前先确认 TaoToken 通道正常。用 curl 发一个最小请求curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: 回复 OK}] }返回里有正常的choices字段说明通道通了。这一步不通后面技能报错都别急着改 SKILL.md。4.2 安装并触发技能把技能文件夹放到 OpenClaw 的技能目录然后安装openclaw skill install tech-news-fetch安装后确认状态openclaw skill list看到tech-news-fetch状态为ready即可。接着用自然语言触发帮我找一下关于大语言模型的最新新闻要 5 条Agent 应该自动匹配到 tech-news-fetch调用脚本并返回 5 条 JSON。成功结果长这样[ { title: 大语言模型 相关新闻 1, url: https://example.com/1 }, { title: 大语言模型 相关新闻 2, url: https://example.com/2 } ]4.3 直接验证脚本如果 Agent 没触发先绕过 Agent 直接跑脚本确认脚本本身没问题python scripts/run.py --keyword 大语言模型 --limit 5脚本能正常输出问题就在 SKILL.md 的 description 或触发规则脚本报错问题在脚本本身。这个二分法能省掉大量排查时间。5. 常见报错排查5.1 技能装了但 Agent 不调用最常见的原因是 description 写得太泛比如只写「查询新闻」。Agent 匹配不到具体场景就不会调用。改成「当用户查询某关键词的最新资讯、动态、新闻时使用」命中率立刻上来。另一个原因是技能名和已有技能冲突openclaw skill list里看有没有重名。5.2 参数传递失败报错通常是unexpected argument或missing required argument。对照 SKILL.md 的参数表和脚本的 argparse 定义逐字核对参数名。keyword和key_word在 Agent 眼里是两个东西。5.3 脚本执行权限或路径问题chmod x scripts/run.py如果脚本里用了相对路径读 references 或 templates注意工作目录。建议在脚本里用os.path.dirname(__file__)定位别依赖当前目录。5.4 输出格式不符合预期Agent 拿到脚本输出后可能再加工。如果 SKILL.md 里声明输出是 JSON 数组脚本就必须只打印 JSON不要混入日志。调试信息走 stderr别走 stdout。注意技能目录里不要放 API Key、数据库密码这类敏感信息。技能文件经常要跨环境复制凭据走环境变量或独立的密钥管理。6. 继续往下走技能跑通之后下一步是把它用起来。如果你主要在验证模型输出和调试提示词可以直接在模型对话里试https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 先生成 Key 再进对话页。如果你要把技能接进长期的编码或 Agent 工作流建议走 Coding Plan配置一次就能持续调用https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。接入细节和参数说明看文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。控制台里可以管理所有 Keyhttps://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。最后留一个实用习惯每写完一个技能先在 tests/ 里放一个最小调用用例改 SKILL.md 或脚本后先跑测试再装进 Agent。技能一多这个习惯能帮你挡住大部分「改了 A 坏了 B」的问题。