1. 为什么你的 AI 助手需要一份 SKILL.mdOpenClaw 的 Skills 机制本质上是给 AI 助手装上一本“专业操作手册”。你可以把它理解成助手本身很聪明但它不知道你公司数据库叫什么、不知道你部署流程走哪几步、不知道你习惯用哪个命令行工具。SKILL.md 就是把这些“私有知识”和“固定动作”写成一份结构化文档让助手在合适的时机自动加载并执行。这套机制能做什么简单说三件事第一把重复性操作固化下来比如“查天气”“发版检查”“生成接口文档”第二让助手在特定领域表现得像专家比如你写清楚数据库表结构它就能直接生成正确的 SQL第三通过分层加载控制上下文占用名称和简介常驻正文按需加载详细文档再按需读取不会一上来就把窗口塞满。适合谁适合已经在用 OpenClaw 做自动化、想让助手接入内部工具链的开发者也适合刚接触 Skills、想从零写一个可运行技能模块的新手。这篇会从 SKILL.md 结构设计讲到 TaoToken 统一 Key 配置再给出技能加载与调用的验证步骤最后把常见报错逐个拆开。你跟着做能拿到一个可复制、可运行、可排查的技能模块骨架。2. TaoToken 前置统一 Key 与 API 通道在写技能之前先把模型调用通道理顺。OpenClaw 的技能模块在执行时往往需要调用大模型做意图判断或内容生成如果每个技能各自配一套 Key维护成本会很高。TaoToken 的作用就是提供统一的 API 入口你只需要在配置里写一次 Key 和 base_url所有技能共享同一条通道。先拿到你的 API Key。打开 TaoToken 控制台进入 API Keys 页面创建一个新 Key复制保存。注意不要把它硬编码进 SKILL.md而是放在项目级配置文件里技能通过环境变量或配置读取。TaoToken 的 API 地址是https://taotoken.net/api这个地址不加任何查询参数直接作为 base_url 使用。模型对话、Coding Plan、控制台、API Keys、接入文档、ClaudeCodeAnthropic 这些入口都在官网导航里能找到按需跳转即可。注意Key 只存在于服务端配置文件或环境变量中不要提交到 Git 仓库也不要在 SKILL.md 正文里明文写出来。3. 可复制配置SKILL.md 骨架与 config.toml 片段3.1 SKILL.md 最小可用骨架一个技能就是一个文件夹核心是 SKILL.md。下面这份骨架你可以直接复制改掉 name、description 和命令示例就能用。--- name: weather-query description: 查询实时天气和未来三天预报。适用于用户问天气、温度、是否下雨。不适用于历史气象数据、气候分析。触发语句今天天气怎么样、北京多少度、会下雨吗。 homepage: https://wttr.in/:help metadata: { openclaw: { emoji: ☔, requires: { bins: [curl] } } } --- # 天气查询 获取指定城市的实时天气和未来三天预报。 ## 何时使用 适用场景 - 用户询问当前天气、温度、湿度 - 用户询问未来几天是否下雨 - 用户询问某城市天气状况 不适用场景 - 历史天气数据查询 - 气候趋势分析 - 航空气象专业数据 ## 常用命令 ### 查询当前天气 bash curl wttr.in/Beijing?format3查询三天预报curl wttr.in/Beijing格式代码说明代码含义%c天气图标%t温度%w风速%h湿度注意事项无需申请接口密钥直接调用有请求频率限制不要高频轮询城市名支持中文和拼音这份骨架的关键点description 必须写清楚“做什么 什么时候用 什么时候不用 触发语句”这是决定技能会不会被调用的最重要字段。正文控制在 500 行以内详细文档放 references 目录。 ### 3.2 config.toml 统一通道配置 在 OpenClaw 项目根目录创建或编辑 config.toml把 TaoToken 的 Key 和 base_url 写进去。技能模块通过读取这个配置来调用模型不需要每个技能单独配。 toml [llm] provider taotoken base_url https://taotoken.net/api api_key sk-你的TaoToken密钥 model claude-sonnet-4-20250514 timeout 60 [skills] enabled true skill_dir skills/ auto_load true max_context_tokens 8000 [skills.weather-query] enabled true priority 10如果你不想把 Key 写死在文件里可以用环境变量覆盖export TAOTOKEN_API_KEYsk-你的TaoToken密钥然后在 config.toml 里写api_key ${TAOTOKEN_API_KEY}OpenClaw 启动时会自动读取环境变量。3.3 带脚本的技能目录结构当技能需要执行复杂逻辑时加一个 scripts 目录weather-query/ ├── SKILL.md ├── scripts/ │ └── get_weather.py └── references/ └── api-reference.mdscripts/get_weather.py示例#!/usr/bin/env python3 获取城市天气输出 JSON 格式 import sys import json import urllib.request def get_weather(city): url fhttps://wttr.in/{city}?formatj1 with urllib.request.urlopen(url, timeout10) as response: data json.loads(response.read()) return data[current_condition][0] if __name__ __main__: city sys.argv[1] if len(sys.argv) 1 else Beijing weather get_weather(city) print(json.dumps({ city: city, temp_C: weather[temp_C], desc: weather[weatherDesc][0][value], humidity: weather[humidity] }, ensure_asciiFalse))在 SKILL.md 里引用脚本## 高级用法 需要结构化输出时调用脚本 bash python scripts/get_weather.py Beijing## 4. 验证请求技能加载与调用 配置写完后先验证技能能不能被正确加载再验证模型调用通道是否通。 ### 4.1 验证技能结构 OpenClaw 通常自带校验脚本运行 bash python skills/skill-creator/scripts/quick_validate.py skills/weather-query如果输出Validation passed说明 SKILL.md 的元数据格式、目录结构都没问题。如果报错重点检查 description 是否用了双引号包裹、metadata 的 JSON 是否合法。4.2 验证 TaoToken 通道用 curl 直接测一下 API 通道是否可达curl -X POST https://taotoken.net/api/v1/messages \ -H Content-Type: application/json \ -H x-api-key: sk-你的TaoToken密钥 \ -H anthropic-version: 2023-06-01 \ -d { model: claude-sonnet-4-20250514, max_tokens: 100, messages: [{role: user, content: 回复 OK}] }返回里包含content字段且文本为OK说明通道正常。如果返回 401检查 Key 是否复制完整返回 404检查 base_url 是否写成了https://taotoken.net/api而不是带其他路径。4.3 验证技能触发启动 OpenClaw 后在对话里输入今天北京天气怎么样观察助手是否调用了 weather-query 技能。如果触发了你会看到它执行curl wttr.in/Beijing?format3并返回天气结果。如果没有触发回到第 5 节排查 description 问题。4.4 打包与分享确认技能可用后打包成.skill文件python skills/skill-creator/scripts/package_skill.py skills/weather-query生成的.skill文件可以直接分享给团队成员对方解压到 skills 目录即可使用。5. 本篇常见错排查5.1 技能没有被触发最常见的原因是 description 写得太模糊。比如只写“管理 GitHub 问题”助手不知道什么时候该用。改成description: 通过 gh 命令管理 GitHub 项目的问题、合并请求、构建状态。适用于用户提到问题、合并请求、构建检查。触发语句查看合并请求状态、列出问题、查看构建日志。不适用于本地 git 操作、克隆仓库。把功能、触发条件、边界、示例语句都写进去触发率会明显提升。5.2 技能加载报 YAML 解析错误SKILL.md 开头的元数据是 YAML 格式常见错误有三种description 里用了冒号但没加引号metadata 的 JSON 少了大括号name 里用了大写字母或下划线。name 只能用小写字母、数字、连字符不超过 64 个字符。5.3 TaoToken 返回 401 或 403先确认 Key 是否有效在控制台 API Keys 页面检查状态。然后确认请求头字段是否正确Anthropic 格式用x-api-keyOpenAI 兼容格式用Authorization: Bearer。如果 config.toml 里用了环境变量确认环境变量已 export 且当前 shell 能读到。5.4 技能执行命令失败检查三件事metadata.openclaw.requires.bins 里声明的工具是否已安装命令在当前操作系统上是否可用文件路径是相对路径还是绝对路径脚本引用建议用相对于技能目录的路径。比如python scripts/get_weather.py而不是python /absolute/path/...。5.5 上下文超限如果 SKILL.md 正文超过 500 行助手加载后可能挤占其他内容的空间。把详细文档移到 references 目录在 SKILL.md 里用一行引用详细接口文档请参考 references/api-reference.md。这样只有真正需要时才会加载详细文档。6. 继续接入与长期使用技能模块跑通之后下一步是把模型调用通道固定下来。如果你只是偶尔验证模型效果可以直接用模型对话页面测试如果要把技能接入到日常编码或 Agent 工作流里建议用 Coding Plan 统一管理调用额度如果还需要创建新的 Key 或查看调用记录去 API Keys 和接入文档页面操作。TaoToken 的入口都在官网导航里按你的使用场景选对应的 deep link 即可。技能开发本身是一个迭代过程先跑通最小骨架再根据实际触发情况优化 description最后把详细文档拆到 references。这样你的 AI 助手会越来越懂你的工作方式。