1. 先搞清楚 OpenClaw skills 到底是什么能解决什么问题OpenClaw skills 是 OpenClaw 这个开源 AI 智能体框架里最核心的扩展机制。你可以把它理解成给智能体装的一个个“插件包”每个 skill 用一份 SKILL.md 描述“我能干什么、什么时候该调用我、需要哪些权限”再配上一段可选的执行代码OpenClaw 在运行时就会根据用户输入自动匹配并调用对应的 skill。它适合谁适合刚接触 OpenClaw、想给自己或团队定制专属能力的开发者——比如让智能体自动统计目录文件、查询内部接口、生成报表这些都不是模型原生能力而是靠 skill 补上的。我一开始也以为 skill 就是个普通的函数注册后来发现它的关键在 SKILL.md 这份“说明书”上。OpenClaw 不是靠硬编码去路由的而是让模型读你的自然语言描述来决定要不要触发。所以描述写得准不准直接决定 skill 会不会被误调用或者根本调不起来。这也是为什么很多人写完 skill 发现“模型压根不理我”八成是 SKILL.md 的触发场景写得太模糊。整条链路其实分两段第一段是把 SKILL.md 的骨架和字段写对第二段是通过 ClawHub 把 skill 装进本地环境并跑通。而这两段之间还夹着一个容易被忽略的环节——模型通道的配置。因为 skill 执行时往往要调用外部模型或 API如果你的 Key 和 Base URL 没统一好skill 装上了也跑不动。这篇就按“写骨架 → 装 skill → 配通道 → 验证 → 排错”的顺序把每一步都落到可复制的命令和配置上。先明确一个概念边界SKILL.md 是给模型看的代码文件是给运行时执行的两者职责不同。SKILL.md 决定“调不调”代码决定“怎么执行”。很多人把逻辑全塞进 SKILL.md 的描述里结果模型理解偏差也有人 SKILL.md 写得极简代码却依赖一堆没声明的权限运行时直接报权限错误。正确的做法是描述归描述、执行归执行权限在元数据里显式声明。2. 写 SKILL.md 骨架前先把 TaoToken 通道配好在动手写 skill 之前我建议你先把模型通道统一掉否则后面每装一个 skill 都要单独配一次 Key非常乱。TaoToken 在这里的作用就是提供一个统一的 API 通道你只需要一个 Key 和一个 Base URL就能让 OpenClaw 以及它调用的各个 skill 走同一条模型请求链路。官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 注意 API 这个地址不带 UTM 参数配置时直接填这个就行。为什么要在写 skill 之前配因为 SKILL.md 里如果声明了需要调用模型的能力比如“总结文件内容”运行时就会走 OpenClaw 的模型通道。如果通道没配好你写完 skill 测试时会看到一堆连接错误根本分不清是 skill 写错了还是通道没通。先把通道打通后面排错范围就小很多。具体操作上你需要先拿到一个 API Key。进入控制台创建 Key 的页面在这里https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。创建完复制出来注意 Key 只显示一次丢了就得重建。然后打开 OpenClaw 的配置文件 settings.json把通道信息填进去。这个文件通常在 ~/.openclaw/settings.json如果你用的是 Molili 这类封装版路径可能在工作空间的 .openclaw 目录下用“打开工作空间”就能找到。配置的核心就三个字段Base URL、API Key、Model ID。Base URL 填 https://taotoken.net/api Key 填你刚创建的Model ID 填你要用的模型标识。这里要提醒一句Base URL 结尾不要多加斜杠也不要填成带 /v1 的路径OpenClaw 会自己拼接。填错的话典型报错是 404 或者 local proxy failed后面排错章节会细讲。配好之后先别急着写 skill用模型对话功能验证一下通道是否生效。打开 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 随便发一句“你好”能正常返回就说明 Key 和 Base URL 没问题。这一步花两分钟能省掉后面半小时的瞎猜。3. 可复制的 SKILL.md 骨架与 settings.json 配置片段现在进入正题先看 SKILL.md 的骨架。一个标准的 skill 目录长这样顶层是 skill 文件夹里面必须有 SKILL.md可选的还有 agent.py 或 index.ts 这类执行脚本以及 requirements.txt 之类的依赖声明。SKILL.md 用 YAML front matter 开头下面接自然语言描述。下面这份是我实测能跑通的骨架你可以直接复制改--- name: file-report-skill description: 统计指定目录下的文件类型与数量并生成 Markdown 报表 version: 1.0.0 permissions: [file.read, file.write] --- ## 触发场景 当用户提出“统计目录文件”“生成文件报表”“看看这个文件夹里都有什么类型”这类请求时调用本技能。 ## 执行逻辑 1. 读取用户指定的目录路径若未指定则默认当前工作目录。 2. 遍历目录按扩展名归类统计每类文件数量。 3. 生成 Markdown 表格写入 report.md。 ## 异常处理 - 目录不存在返回“目录不存在请检查路径”。 - 无读取权限返回“缺少文件读取权限”。 - 目录为空返回“目录为空无文件可统计”。字段说明上name 是技能唯一标识建议用英文小写加连字符description 一句话说清能力模型靠它做初筛version 用语义化版本permissions 是权限白名单只申请真正需要的比如这个 skill 只读文件就不该申请网络权限。下面的自然语言部分才是模型判断“调不调”的主要依据触发场景要写得像用户会说的话执行逻辑要分步骤异常处理要给出结构化返回。写完 SKILL.md把执行代码放进同目录。如果逻辑简单其实可以只靠 SKILL.md 让模型自己规划但涉及文件遍历这种确定性操作建议写个 agent.py避免模型自由发挥出错。代码里记得捕获异常并返回结构化信息和 SKILL.md 里声明的异常处理对应上。接着是 settings.json 的配置片段。这份配置决定了 OpenClaw 走哪条模型通道也是 skill 执行时依赖的底座{ model: { baseUrl: https://taotoken.net/api, apiKey: sk-你的Key, modelId: 你的模型ID }, skills: { directory: ~/.openclaw/skills, autoLoad: true } }注意 baseUrl 就是 https://taotoken.net/api 不要加 /v1也不要加结尾斜杠。apiKey 填控制台创建的那串。modelId 填你要用的模型标识具体可用的模型可以在模型对话页面确认。skills.directory 指向你的 skill 存放目录autoLoad 设为 true 后 OpenClaw 启动时会自动扫描加载。这份配置改完保存重启 OpenClaw 生效。如果你用的是 Claude Code 这类工具做 skill 开发辅助配置逻辑类似Base URL、Key、Model ID 三件套一个都不能少。Cline 的 MCP 配置也是同样思路把通道指向 TaoToken 的 API 地址即可。核心原则就一条所有走模型请求的地方统一用同一个 Base URL 和 Key避免多套凭证互相干扰。4. 通过 ClawHub 安装 skill 并验证通道生效骨架写好了接下来把它装进 OpenClaw。手动安装的方式是把整个 skill 文件夹复制到 ~/.openclaw/skills/ 目录下然后重启。但更推荐用 ClawHub CLI因为它会自动解析依赖、处理目录结构省去手动拷贝的麻烦。先安装 ClawHub 工具npx clawhublatest install这条命令会拉取 ClawHub 的最新版本并进入交互式安装流程。工具会列出可用的 skill 列表你选择目标技能后它会自动下载并复制到 ~/.openclaw/skills/ 目录同时完成基础配置。如果你要装的是自己写的本地 skill也可以直接用文件路径安装npx clawhublatest install ./my-skill安装完成后用下面这条命令查看已安装的技能列表openclaw skills list正常的话你会看到刚装的 skill 出现在列表里状态是 enabled。如果列表里没有先检查 skills.directory 路径对不对再确认 SKILL.md 的 front matter 格式有没有写错——YAML 对缩进敏感多一个空格都可能解析失败。接下来是关键的验证动作调用一次 skill确认通道生效。启动 OpenClaw 后输入一句会触发该 skill 的话比如“帮我统计一下当前目录的文件类型”。如果 skill 被正确调用你会看到它读取目录、生成报表的完整过程最后输出 report.md。这一步同时验证了两件事skill 的触发描述是否准确以及模型通道是否通畅。因为 skill 执行时如果需要模型参与规划请求会走 settings.json 里配的 TaoToken 通道通道不通的话这里就会卡住或报错。验证通过后你可以进一步测试边界情况给一个不存在的目录看是否返回“目录不存在”给一个空目录看是否返回“目录为空”。这些异常路径能跑通说明 SKILL.md 里的异常处理和代码里的捕获逻辑对上了。如果异常没被正确处理模型可能会自己编一个结果返回这种“看起来成功实际错误”的情况最危险一定要用边界用例测出来。对于长期做 skill 开发和 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 里面有各工具的详细配置说明遇到不确定的字段可以对照查。5. 常见报错排查401、local proxy failed、reading choices、OAuthskill 装完跑不通报错信息往往指向不同环节。下面这几个是我踩过的坑按报错对照排查能省不少时间。401 Unauthorized 是最常见的基本就是 Key 的问题。先确认 settings.json 里的 apiKey 有没有填错、有没有多余空格再去控制台确认这个 Key 是否被删除或过期。还有一种情况是 Key 填对了但 Base URL 写成了带 /v1 的路径导致请求打到了错误端点也会返回 401。记住 Base URL 就是 https://taotoken.net/api 不要自作主张加后缀。local proxy failed 通常出现在 OpenClaw 启动阶段说明本地代理层没起来。先检查 settings.json 的 JSON 格式是否合法一个多余的逗号就会导致整个配置解析失败。可以用在线 JSON 校验工具过一遍。如果格式没问题再看 skills.directory 指向的目录是否存在目录不存在时某些版本会连带代理启动失败。另外确认没有多个 OpenClaw 实例同时占用端口。reading choices 这类报错一般出现在模型返回阶段意思是响应体里没有预期的 choices 字段。原因可能是 Model ID 填错了请求打到了一个不存在的模型也可能是通道返回了错误信息但被当成了正常响应解析。先确认 modelId 在模型对话页面能正常调用再检查请求是否真的走了 TaoToken 通道。如果同时配了多个通道确认没有互相覆盖。OAuth 相关报错多出现在用 Claude Code 或类似工具做 skill 开发辅助时。这类工具默认走 OAuth 登录流程如果你要改成 API Key 模式需要在配置里显式指定 Base URL 和 Key把 OAuth 那套关掉。Claude Code 的配置入口在 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里面有 Anthropic 兼容通道的配置说明。核心还是三件套Base URL 填 https://taotoken.net/api Key 填控制台创建的Model ID 填对应模型。还有一个隐蔽的坑skill 的 permissions 声明了 file.write 但实际运行时没有写权限报错信息可能被模型吞掉表现为“执行成功但没生成文件”。这种时候去看 OpenClaw 的运行日志而不是只看对话输出。日志里会有真实的权限拒绝记录。排查 skill 问题时日志永远比对话界面可靠。如果排查完还是不通建议回到最小验证先用模型对话功能确认通道本身没问题再单独测 skill 的触发最后测 skill 的执行。把问题范围一层层缩小比对着报错瞎改配置高效得多。接入文档里有各环节的验证方法对照着走一遍基本能定位到具体是哪一层出的问题。6. 把 skill 开发流程固定下来后续迭代就快了走到这里你已经完成了从 SKILL.md 骨架编写、ClawHub 安装、TaoToken 通道配置到调用验证的完整链路。我自己的习惯是把这套流程固化成模板新建一个 skill 文件夹复制 SKILL.md 骨架改 name 和 description写执行代码然后用 clawhub install 本地路径装进去最后跑一遍正常用例和边界用例。整个过程熟练之后十分钟以内能搞定一个简单 skill。几个实用技巧SKILL.md 的 description 尽量包含用户可能说的原话这样模型匹配率更高permissions 从最小集开始跑通了再按需加每次改完 SKILL.md 记得重启 OpenClaw因为技能描述是在启动时加载的。另外把 settings.json 纳入版本管理但 Key 用环境变量注入别直接提交到仓库。后续如果要开发更复杂的 skill比如需要调用多个外部接口的建议把执行逻辑拆成独立模块SKILL.md 只负责描述和权限声明。这样模型理解成本低代码也好维护。通道这边保持统一所有 skill 共用一套 TaoToken 配置新增 skill 时不用再动 settings.json直接装直接跑。