1. 为什么你的 OpenClaw 总在重复劳动Skills 自定义技能包到底解决什么问题如果你已经在用 OpenClaw 处理日常开发任务大概率遇到过这种场景每次让它帮你查天气、整理待办、备份目录都得把同一套指令重新描述一遍。今天说“帮我看看北京天气”明天说“查一下上海温度”后天又得解释一遍“用 wttr.in 那个接口format 参数这样写”。重复描述本身就是一种隐性成本而且每次描述方式不同模型给出的结果也不稳定。OpenClaw 的 Skills 机制就是为这类重复操作准备的。你可以把它理解成给 AI 助手装了一个“能力扩展包”一个文件夹里面放一个SKILL.md说明文件OpenClaw 在启动会话时会扫描这些目录把技能的名称、描述、触发条件和执行指令加载进上下文。之后你只要说“北京天气怎么样”它就知道该调用哪个技能、执行哪条命令、按什么格式返回。这套机制适合谁三类人最受益。第一类是每天有固定重复操作的开发者比如定时备份、日志清理、格式转换第二类是把 OpenClaw 当个人助理用的用户希望把“查天气、记待办、整理文件”这类动作固化下来第三类是想把团队内部流程沉淀成可分享技能包的工程师一个SKILL.md就能让同事复用同一套操作规范。我试过把常用的几个操作都写成 Skills最大的感受是模型不再“猜”你要什么而是按你写好的指令稳定执行。这篇文章会从目录结构、SKILL.md字段配置、本地加载验证一直讲到如何通过统一 Key/API 通道完成技能调用链路自检。全程可跟做代码和配置都能直接复制。需要先明确一个概念Skills 不是插件也不是需要编译的代码包。它本质上是“给模型的说明书”模型读到说明书后决定是否调用、怎么调用。所以写SKILL.md的核心不是编程而是把操作步骤写清楚、把触发条件写明确。这一点想通了后面所有配置都会顺理成章。2. TaoToken 前置准备统一 Key/API 通道让技能调用链路可自检在正式写第一个 Skill 之前有一个前置环节值得先处理技能调用链路的统一入口。很多人的 Skills 里会直接写死某个模型的 API 地址和密钥结果换模型、换环境时到处改配置排查问题时也分不清是 Skill 写错了还是通道不通。更稳妥的做法是先把模型调用通道统一起来再让 Skills 通过这个通道发起请求。TaoToken 在这里扮演的就是统一 Key/API 通道的角色。它提供兼容 OpenAI 风格的接口你只需要一个 Base URL 和一个 API Key就能在 Skills 的配置里引用。这样做的直接好处是技能文件里不出现任何硬编码的密钥所有模型调用都走同一个入口出问题时只需要检查一个地方。先拿到访问凭证。打开控制台创建 API Keyhttps://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapi_keys创建完成后你会得到一串以sk-开头的 Key先复制保存。接着确认接口地址TaoToken 的 API 入口是https://taotoken.net/api注意这个地址不带任何查询参数是纯粹的接口根路径。在 OpenClaw 的配置里Base URL 填这个即可具体路径由客户端拼接。如果你还不确定该用哪个模型可以先到模型对话页面测一下连通性确认 Key 有效、模型可调用https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmodel_chat这一步的意义在于先把“通道”验证通过再去写 Skill。否则 Skill 写完后报错你无法判断是 Skill 的SKILL.md格式问题还是 Key 或 Base URL 配错了。把变量分离排障效率会高很多。对于需要长期跑编码任务或 Agent 流程的场景可以考虑 Coding Plan它更适合高频、持续的调用https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcoding_plan接入细节和字段说明可以对照官方文档里面有完整的参数列表https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc把这三样东西准备好——Base URL、API Key、Model ID——后面在 Skills 配置里引用时就不会手忙脚乱。记住一个原则Skill 文件里只写“引用哪个环境变量”不写密钥明文。这样技能包可以安全地分享给同事也不会因为误提交到仓库而泄露。3. 可复制配置SKILL.md 目录结构与字段配置完整示例现在进入核心部分。一个 OpenClaw Skill 的最小结构就是一个文件夹加一个SKILL.md。文件夹名建议用英文小写加连字符比如weather-query、file-backup。SKILL.md分两段顶部是 YAML Frontmatter 元数据下面是用 Markdown 写的指令正文。先看目录结构。最简单的形态my-skill/ └── SKILL.md带脚本和模板的复杂形态my-skill/ ├── SKILL.md ├── scripts/ │ └── process.sh ├── templates/ │ └── report.txt └── config.yaml创建位置有两个选择。工作区级别只对当前工作区生效适合临时试验mkdir -p ~/.openclaw/workspace/skills/hello-world全局级别对所有工作区生效适合长期使用的技能mkdir -p ~/.openclaw/skills/hello-world加载优先级是工作区 Skills 高于全局 Skills高于内置 Skills。重名时高优先级覆盖低优先级。这个规则在排查“为什么我的 Skill 没生效”时非常关键。接下来是SKILL.md的完整字段配置。顶部 Frontmatter 用---包裹必填字段只有两个--- name: weather_query description: 查询任意城市的实时天气和预报 ---name只能用英文、数字、下划线、连字符不能有空格。description用一句话说清楚这个技能做什么模型会读这句话来判断是否触发。可选字段里homepage填技能主页metadata是高级配置。metadata里最常用的是openclaw对象用来声明依赖和展示信息--- name: weather_query description: 查询任意城市的实时天气和预报 homepage: https://wttr.in/ metadata: { openclaw: { emoji: , requires: { bins: [curl], env: [WEATHER_API_KEY], config: [browser.enabled] }, primaryEnv: WEATHER_API_KEY, os: [darwin, linux], always: false } } ---这里每个字段都有实际作用。bins声明需要的命令行工具OpenClaw 启动时会检查缺失就标记为不可用。env声明需要的环境变量primaryEnv指定主变量名。os限制支持的操作系统。always设为true会跳过依赖检查一般不建议除非你确定环境永远满足。Frontmatter 下面是 Markdown 指令正文这是给模型看的操作手册。结构建议包含四块技能说明、什么时候使用、如何使用、示例。以天气查询为例# 天气查询技能 使用 wttr.in 服务查询全球任意城市的天气信息无需 API 密钥。 ## 什么时候使用 当用户提到以下类似表达时使用 - 今天天气怎么样 - 北京会下雨吗 - 上海周末的天气 - 纽约的温度 ## 如何使用 实时天气简洁版 bash curl -s wttr.in/Beijing?format3三天预报curl -s wttr.in/Beijing示例用户北京天气怎么样 助手执行 curl -s wttr.in/Beijing?format3然后解读结果。写指令正文有几个要点。触发条件要写具体把用户可能说的原话列出来模型匹配更准。命令要完整可执行不要写“调用天气接口”这种模糊描述。示例要给出输入和期望输出模型会照着示例的风格回应。 如果技能需要调用模型 API不要在 SKILL.md 里写密钥而是引用环境变量。配置写在 ~/.openclaw/openclaw.json json { skills: { entries: { weather_query: { enabled: true, env: { WEATHER_API_KEY: 你的密钥 } }, my_llm_skill: { enabled: true, apiKey: TAOTOKEN_KEY_HERE, config: { baseUrl: https://taotoken.net/api, model: 你的模型ID, timeout: 30 } } } } }注意baseUrl填https://taotoken.net/apiapiKey填你在控制台创建的 Keymodel填你要用的模型 ID。这三件套——Base URL、Key、Model ID——是任何需要调用模型的 Skill 都必须配齐的。缺一个就会在运行时报错。带脚本的技能在SKILL.md里用{baseDir}引用技能目录## 使用脚本处理 bash bash {baseDir}/scripts/process.sh 参数1 参数2{baseDir} 会被替换成技能的实际路径这样技能包移动到任何位置都能正常工作。脚本记得加执行权限 bash chmod x scripts/process.sh4. 验证请求与成功结果本地加载、依赖检查与调用链路自检配置写完后必须验证。验证分三层技能是否被识别、依赖是否满足、调用链路是否通。三层都过了才算真正可用。第一层检查技能是否被 OpenClaw 识别。用命令行工具列出所有技能openclaw skills list如果只想看当前环境可用的技能openclaw skills list --eligible查看某个技能的详情openclaw skills info weather_query正常输出会显示技能名称、描述、来源路径和依赖状态。如果列表里没有你的技能先检查文件夹位置和SKILL.md文件名大小写。SKILL.md必须全大写写成skill.md或Skill.md都不会被识别。第二层检查依赖。运行openclaw skills check输出类似weather_query - 所有依赖满足 my_llm_skill - 缺少环境变量TAOTOKEN_KEY data_processor - 缺少命令jq看到 就按提示补齐。缺命令就安装缺环境变量就在openclaw.json里补上。这一步能挡掉大部分“技能不生效”的问题。第三层验证调用链路。重启会话让新技能加载/new或者/reset然后在新会话里触发技能。以天气技能为例用户北京天气怎么样如果技能配置正确OpenClaw 会执行curl -s wttr.in/Beijing?format3返回类似Beijing: ☀ 25°C, 西北风 3 级看到这个结果说明技能从加载到执行整条链路是通的。对于需要调用模型 API 的技能验证要更细一层。先单独测通道是否通curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_KEY \ -H Content-Type: application/json \ -d { model: 你的模型ID, messages: [{role: user, content: ping}] }返回里有choices字段且内容正常说明 Base URL、Key、Model ID 三件套没问题。然后再在 OpenClaw 会话里触发技能观察是否正常返回。如果单独测通道通、但技能里报错问题就在SKILL.md的指令写法或配置引用上。验证脚本类技能时先手动跑一遍脚本bash ~/.openclaw/workspace/skills/data-processor/scripts/process.sh 输入 输出确认脚本本身能跑通再让 OpenClaw 调用。这样能把“脚本问题”和“技能加载问题”分开。一个完整的成功验证流程是这样的openclaw skills list能看到技能 →openclaw skills check全部通过 →/new重启 → 会话里触发 → 返回预期结果。四步都过技能就可以投入日常使用了。5. 本篇常见错误排查401、local proxy failed、reading choices、OAuth 报错对照技能开发过程中报错集中在几个固定位置。下面按真实报错逐条对照给出定位思路和修复方法。401 Unauthorized这是最常见的通道类报错。出现位置通常是技能调用模型 API 时。原因有三个Key 没填、Key 填错、Key 已失效。先检查openclaw.json里apiKey字段是否填了正确的 Key再确认这个 Key 在控制台是否还有效。如果 Key 是从环境变量读取的检查变量名是否和SKILL.md里声明的一致。修复后重新/new加载配置。local proxy failed这个报错说明请求根本没发出去卡在本地网络层。常见原因是 Base URL 写错比如多写了路径、少了https://、或者填了带查询参数的地址。正确写法是https://taotoken.net/api不带任何后缀。另一个原因是本地网络环境无法访问该地址先用curl单独测一下通道确认能通再回到技能里排查。reading choices 相关报错这类报错通常表现为解析响应时找不到choices字段。原因是接口返回的不是标准 OpenAI 格式或者返回了错误信息但被当成正常响应解析。先看原始返回内容用curl直接请求一次确认返回结构里有choices数组。如果返回的是错误对象里面会有error字段按错误信息处理。如果返回格式不对检查 Base URL 是否指向了正确的接口根路径。OAuth 相关报错如果技能里涉及需要 OAuth 授权的服务报错通常出现在 token 过期或 scope 不足。检查授权是否完成、token 是否需要刷新、请求的 scope 是否覆盖了当前操作。OAuth 类问题建议先用官方提供的调试工具单独验证授权流程确认 token 有效后再放进技能。技能不生效没有任何报错这种“静默失败”最容易被忽略。排查顺序确认SKILL.md文件名全大写确认文件夹在~/.openclaw/workspace/skills/或~/.openclaw/skills/下确认 Frontmatter 的---是成对的确认name字段没有空格和中文执行/new重启会话。这五步能解决绝大多数“技能不加载”的问题。依赖检查一直不通过openclaw skills check报缺命令或缺环境变量。缺命令就装缺环境变量就在openclaw.json的env里补。如果确认都装了还是报缺检查命令是否在 PATH 里环境变量是否在启动 OpenClaw 的 shell 里可见。必要时用绝对路径声明命令。脚本执行权限不足报错类似Permission denied。执行chmod x scripts/process.sh确认脚本首行有 shebang比如#!/bin/bash。如果脚本里引用了相对路径改成基于{baseDir}的绝对路径。配置改了但没生效OpenClaw 的配置在会话启动时加载改完openclaw.json后必须/new或/reset重启会话。只改文件不重启旧配置还在内存里。这是很多人踩过的坑。把上面这些报错对照表存下来遇到问题时先定位是哪一层通道层401、local proxy failed、响应层reading choices、授权层OAuth、加载层技能不生效、依赖层check 不通过。分层定位比盲目改配置快得多。6. 语义一致 CTA把技能调用链路固定下来之后技能写多了会发现一个规律真正花时间的不是写SKILL.md而是保证每次调用都稳定。稳定的前提是通道统一、配置集中、验证有据。把 Base URL、Key、Model ID 这三件套固定在一个地方所有技能都引用它后面新增技能就是复制模板改指令的事。需要创建或管理 Key 的时候从这里进https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapi_keys接入参数和字段说明对照文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc想先验证模型是否可用到模型对话页面测一下https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmodel_chat如果你的 Skills 要长期跑编码或 Agent 类任务Coding Plan 更适合持续调用https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcoding_plan最后给一个实用建议每写完一个 Skill先跑openclaw skills check再/new再触发一次。三步都过再写下一个。不要攒一堆技能一起测出问题时定位成本会翻倍。技能包的价值在于复用而复用的前提是每个都经过验证。