1. 为什么 OpenClaw Skill 值得你花一个下午搞懂OpenClaw Skill 是一份写给 AI 看的 Markdown 执行说明书它让模型从“会聊天”变成“会干活”。你不需要写后端服务不需要部署运行时只要在~/.openclaw/workspace/skills/下建一个文件夹、放一份SKILL.md重启网关就能被识别。适合谁适合想把重复操作抓数据、整理文件、生成日报交给 AI 的开发者也适合完全没写过插件、但会写 Markdown 的产品和运营同学。我最初也以为 Skill 就是插件换了个名字直到把一份 40 行的SKILL.md丢进目录、重启网关看着它自己调curl抓天气、拉热帖、按我定义的格式输出早报才意识到区别在哪传统插件是“我写代码替 AI 做”Skill 是“我写步骤教 AI 做”。前者要处理 API 鉴权、错误重试、后台常驻后者只描述意图和命令执行交给 Agent Loop。这个认知转变直接决定了开发成本——一个能跑的 Skill从建目录到验证成功熟练后 10 分钟足够。这篇指南按真实开发顺序走先讲清SKILL.md的结构和字段语义再给一份可直接复制的模板然后接上 TaoToken 的统一 Key/API 通道做调用测试最后把本地调试、ClawHub 发布、常见报错排查串起来。全程命令可复制路径与字段名保持和 OpenClaw 实际约定一致。你跟着敲一遍就能拿到属于自己的第一个 AI 技能。2. SKILL.md 结构拆解与 ClawHub 发布前的目录规范SKILL.md是整个 Skill 的核心它由 frontmatter头部元数据和正文两部分组成。frontmatter 用 YAML 写至少包含name和description正文则用自然语言加命令描述执行流程。很多人第一次写会把它当成 README堆一堆介绍性文字结果 AI 读完不知道先干什么。正确做法是frontmatter 负责“什么时候用我”正文负责“具体怎么干”。先看目录结构。最小可用形态只有一个文件skills/ └── daily-brief/ └── SKILL.md默认存放路径是~/.openclaw/workspace/skills/。当 Skill 需要脚本或参考资料时再扩展成skills/ └── trend-scout/ ├── SKILL.md ├── scripts/ │ └── analyze.py └── references/ └── source.mdscripts/放可执行脚本references/放静态资料。注意脚本路径在SKILL.md里要写绝对路径或基于技能目录的相对路径否则 Agent 执行时找不到文件。frontmatter 里最容易被忽略的是description中的否定条件。只写“用于生成简报”不够AI 可能在用户问“帮我写篇长文”时也触发它。加上NOT for能显著降低误触发--- name: daily-brief description: 每日早报上海天气 V2EX 热帖。 Use when: 用户需要简报或早上 8 点定时执行。 NOT for: 专业气象预报、长内容新闻。 ---正文部分建议固定四个小节When to Run、Workflow、Output Format、Error Handling。When to Run写触发条件可以是关键词也可以是 cron 表达式Workflow写具体命令原则是“写命令不写意图”——不要写“查询天气”要写curl https://wttr.in/Shanghai?format3Output Format定义输出模板AI 会严格遵守Error Handling写失败时的兜底动作比如命令超时后重试一次或返回提示。ClawHub 发布前目录名要和 frontmatter 的name一致否则clawhub publish会报名称不匹配。发布命令是clawhub publish daily-brief发布后可以在 ClawHub 技能商店被检索到。这里必须提醒一句ClawHub 上曾出现过包含恶意命令的 Skill下载他人技能时先读SKILL.md里的命令确认没有涉及敏感文件读取或外发数据的操作再决定是否启用。3. 可复制配置SKILL.md 模板与 TaoToken 统一通道接入这一节给一份完整可复制的SKILL.md模板同时把 TaoToken 的 Base URL、Key、Model ID 三件套接进来让 Skill 在调用模型时走统一通道。先建目录mkdir -p ~/.openclaw/workspace/skills/daily-brief touch ~/.openclaw/workspace/skills/daily-brief/SKILL.md然后把下面内容写进SKILL.md--- name: daily-brief description: 每日早报上海天气 V2EX 热帖。 Use when: 用户说“今日简报”“今天热点”“早上好”或早上 8 点定时执行。 NOT for: 专业气象预报、长内容新闻、需要登录的私有数据。 --- # Daily Brief 每日早报 ## When to Run - 每天 8:00 AM 自动执行 - 用户说“今日简报”“今天热点”“早上好” - 用户需要快速了解今日热点时 ## Workflow 1. 获取上海天气 curl https://wttr.in/Shanghai?format3 2. 拉取 V2EX 热门帖子 curl https://www.v2ex.com/api/topics/hot.json 3. 从返回结果中提取前 5 条帖子的标题和节点名称 4. 按 Output Format 整理信息 ## Output Format 今日简报 - {当前日期} 上海天气{天气结果} V2EX 今日热帖 1. {标题1}{节点1} 2. {标题2}{节点2} 3. {标题3}{节点3} 4. {标题4}{节点4} 5. {标题5}{节点5} ## Error Handling - 天气接口超时重试一次仍失败则输出“天气获取失败” - V2EX 接口返回非 200跳过热帖部分只输出天气接下来配置模型通道。OpenClaw 的模型配置通常放在~/.openclaw/config.json或项目级settings.json中把 TaoToken 作为 provider 写入。Base URL 用https://taotoken.net/apiKey 从控制台创建Model ID 按你实际使用的模型填写{ models: { default: { provider: taotoken, baseUrl: https://taotoken.net/api, apiKey: sk-你的TaoTokenKey, model: 你的ModelID } }, skills: { daily-brief: { allowNetwork: true, allowFileSystem: false, allowExec: [curl, python3] } } }三件套缺一不可Base URL 决定请求打到哪Key 决定能不能过鉴权Model ID 决定用哪个模型。只填 Key 不填 Base URL请求会打到默认地址只填 Base URL 不填 Model ID会报模型不存在。配置改完重启网关openclaw gateway restart如果你用的是 Claude Code 类环境配置写在~/.claude/settings.json的env段里字段名对应ANTHROPIC_BASE_URL和ANTHROPIC_API_KEYModel ID 通过ANTHROPIC_MODEL指定。Cline MCP 场景则在 MCP server 配置里填 Base URL 和 KeyModel ID 在 Cline 的模型选择里指定。Codex 的auth.json里对应base_url、api_key、model三个字段。不管哪个客户端逻辑一致地址、密钥、模型三者对齐。4. 验证请求从本地调试到成功拿到早报输出配置写完必须验证否则你不知道是 Skill 没被识别还是模型通道没通。第一步先确认 Skill 被加载openclaw skills list如果输出里能看到daily-brief说明目录和 frontmatter 没问题。看不到就检查目录名与name是否一致、文件是否叫SKILL.md大小写敏感。第二步单独测命令排除网络问题curl https://wttr.in/Shanghai?format3 curl https://www.v2ex.com/api/topics/hot.json | head -c 500两条命令都能返回内容再进 Skill 测试。第三步触发执行openclaw chat --prompt 使用daily-brief生成今日简报正常情况你会看到按Output Format排版的早报天气一行、热帖五条。如果输出格式乱了多半是Output Format写得不够明确把模板里的占位符补全即可。第四步验证模型通道是否真的走了 TaoToken。在请求日志里看 Base URLopenclaw logs --skill daily-brief --tail 50日志里出现https://taotoken.net/api说明通道生效。如果看到的是其他地址回去检查config.json里baseUrl字段有没有写错或者有没有被环境变量覆盖。第五步设置定时任务让 Skill 每天自动跑openclaw cron add daily-brief 0 8 * * * --skill daily-brief0 8 * * *是标准 cron 表达式表示每天 8 点。加完后用openclaw cron list确认任务已注册。到这里一个从零创建的 Skill 就完整跑通了目录建好、模板写好、通道接通、命令验证、定时生效。5. 常见报错排查401、local proxy failed 与 reading choices开发过程中最容易卡住的不是写 Markdown而是各种报错。下面按真实遇到的频率排一下。401 UnauthorizedKey 无效或没带上。先确认config.json里apiKey字段填的是完整 Key没有多余空格再确认请求确实走了配置的 Base URL。如果 Key 是从控制台复制的注意不要漏掉前缀。排查命令curl -H Authorization: Bearer sk-你的Key https://taotoken.net/api/v1/models返回模型列表说明 Key 有效返回 401 说明 Key 本身有问题去控制台重新创建一个。local proxy failed本地代理配置冲突。常见于环境变量里残留了HTTP_PROXY或HTTPS_PROXY导致请求被转发到不可达地址。检查env | grep -i proxy有输出就临时清掉再试unset HTTP_PROXY HTTPS_PROXY然后重启网关重新触发 Skill。reading choices 报错通常是模型返回结构不符合预期比如返回了错误对象而不是choices数组。原因可能是 Model ID 填错或者 Base URL 指向了不兼容的端点。确认model字段和 TaoToken 控制台里可用的 Model ID 完全一致Base URL 用https://taotoken.net/api不要多加/v1或漏掉路径。OAuth 相关报错出现在 Claude Code 类客户端里说明它还在走 OAuth 登录流程而不是 API Key。检查settings.json里是否同时存在 OAuth 配置和 API Key 配置两者冲突时以 OAuth 优先。把 OAuth 相关字段移除只保留ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY。Skill 不触发When to Run关键词太少。把用户可能说的原话都列进去比如“早报”“简报”“今天有什么热点”。执行结果不符合预期Workflow步骤太粗。把“获取天气”改成具体curl命令把“提取前 5 条”改成明确的字段名。输出格式混乱Output Format里占位符和实际数据对不上。用固定模板不要留模糊描述。排查顺序建议先看日志定位是 Skill 层还是模型层再用curl单独测接口最后回查配置文件字段。大部分问题出在 Base URL、Key、Model ID 三者没对齐。6. 把 Skill 用起来从本地验证到长期编码工作流Skill 跑通之后真正的价值在于把它接进日常流程。本地验证只是第一步接下来可以考虑三件事把常用 Skill 沉淀成个人技能库、把需要长期运行的编码类任务交给 Coding Plan、把模型调用统一收敛到 TaoToken 通道。如果你主要做的是编码辅助类 Skill比如自动生成 commit message、批量重构、代码审查这类任务调用频繁、上下文长适合用 Coding Plan 来承载避免每次单独配 Key。配置入口在控制台的 Coding Plan 页面开通后把对应的 Base URL 和 Key 写进客户端配置即可。如果你只是想先验证某个模型在 Skill 里的表现可以直接用模型对话页面快速试不用改本地配置。确认效果后再落到SKILL.md和config.json里。接入文档里有各客户端的完整配置示例包括 Claude Code、Cline、Codex 的字段对照。遇到配置字段不确定时先查文档再改本地文件比反复重启网关快得多。API Key 管理在控制台的 API Keys 页面建议按用途分 Key一个用于本地调试一个用于定时任务方便出问题时快速定位和吊销。Key 不要写进会提交到 Git 的文件里用环境变量或本地配置文件承载。最后回到 Skill 本身它的门槛低到会写 Markdown 就能上手但上限取决于你把 Workflow 写得多具体。命令越明确、错误处理越完整、输出格式越固定AI 执行就越稳定。先从一个每天跑的小 Skill 开始跑顺了再往上叠脚本和定时任务这条路比一上来就写复杂插件要稳得多。