1. 为什么你的 OpenClaw skill 总是加载失败从零开发自定义技能的真实场景你写了一个 SKILL.md放进 skills 目录重启 OpenClaw然后在对话里说“帮我用那个技能处理一下”结果 AI 一脸茫然好像根本没看到你的文件。这种场景我遇到过不止一次问题往往不在代码逻辑而在 YAML 元数据声明和目录结构这两个最容易被忽略的地方。OpenClaw 的 skill 本质上是一份写给 AI 看的说明书。它由两部分组成顶部的 YAML frontmatter 负责告诉系统“我是谁、我什么时候该被调用、我依赖什么”下面的 Markdown 正文负责告诉 AI“具体怎么做”。系统在启动时会扫描 skills 目录解析每个 SKILL.md 的 YAML 头部把 name 和 description 注入到提示词里。如果 YAML 格式有误或者 name 字段不符合命名规则这个 skill 就会被静默跳过你在对话里怎么喊都不会触发。适合读这篇的人有三类第一类是想把重复工作流封装成一句话指令的开发者第二类是需要给团队内部工具写 AI 调用说明的技术负责人第三类是想理解 Agent 技能系统设计思路的学习者。你不需要精通 Python 或 Shell但需要会基本的 Markdown 和 YAML 缩进规则。我试过用最笨的办法排查一个不触发的 skill最后发现是 description 里写了一句“这个技能可以处理文件”太泛了AI 根本判断不出什么时候该用它。后来改成“当用户要求批量重命名工作区内的图片文件时使用此技能”立刻就正常触发了。这个坑后面会详细展开。整篇内容会按六个部分推进先讲清楚 skill 系统的加载逻辑和常见失败场景然后给出 TaoToken 作为模型接入层的前置配置接着交付可直接复制的 SKILL.md 模板和 YAML 字段说明再通过一次完整的本地加载验证确认 skill 被正确识别之后对照真实报错做排查最后给出接入文档和 API Keys 的获取路径。目标很明确你跟着走完手里会有一个能跑起来的 skill 骨架。2. TaoToken 前置配置让 OpenClaw 的 skill 调用有稳定的模型后端OpenClaw 的 skill 系统本身不绑定特定模型它把 SKILL.md 的元数据和正文注入到提示词后需要一个模型来完成意图理解和工具调用决策。如果你本地没有配置模型接入层skill 写得再好也不会被触发因为系统根本没有可用的推理后端。TaoToken 在这里的角色是提供统一的 API 入口让 OpenClaw 通过一个 Base URL 和 Key 就能调用多种模型不需要在每个 skill 里单独处理鉴权。配置入口在控制台的 API Keys 页面地址是 https://taotoken.net/api-keys 。进去之后创建一个新的 Key复制出来备用。注意这个 Key 只在创建时完整显示一次关掉页面就看不到了所以先存到安全的地方。如果你还没有账号从官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 进去注册即可。拿到 Key 之后OpenClaw 的模型配置通常写在 settings 文件或环境变量里。不同版本的 OpenClaw 配置路径略有差异但核心字段是一致的Base URL 填 https://taotoken.net/api API Key 填你刚创建的那串字符Model ID 填你要用的模型标识。这三个字段缺一不可尤其是 Model ID写错了会直接报 model not found。如果你用的是 Claude Code 类的编码环境来辅助开发 skill可以在 settings.json 里这样写{ model: claude-sonnet-4-20250514, baseUrl: https://taotoken.net/api, apiKey: sk-你的Key }如果你用的是 Cline 或类似的 VS Code 插件来写 skill 脚本配置方式类似在插件设置里找到 API Provider选择 OpenAI Compatible然后填入 Base URL 和 Key。Model ID 根据你实际要用的模型填写比如 gpt-4o 或 claude-sonnet-4-20250514。这里有一个容易踩的坑Base URL 末尾不要加斜杠。https://taotoken.net/api 是正确的https://taotoken.net/api/ 在某些客户端里会导致路径拼接错误报 404。另外API Key 不要硬编码在 SKILL.md 里skill 文件是会被注入到提示词的写进去等于泄露。正确的做法是把 Key 放在环境变量或 OpenClaw 的全局配置里skill 正文只引用配置项名称。配置完成后你可以先用一个最简单的请求验证模型通道是否通畅。在终端里执行curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的Key \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: 回复OK}], max_tokens: 10 }如果返回的 JSON 里有 choices 字段且 content 是“OK”说明模型通道没问题。这一步很关键因为后面 skill 不触发时你需要先排除是模型层的问题还是 skill 本身的问题。如果这个 curl 就报 401那说明 Key 或 Base URL 配错了跟 skill 无关。TaoToken 的模型对话页面在 https://taotoken.net/chat 你可以直接在那里测试模型是否正常响应。对于长期做 skill 开发和调试的场景Coding Plan 会更划算地址是 https://taotoken.net/coding-plan 适合需要频繁调用模型来验证 skill 触发逻辑的开发者。3. 可复制的 SKILL.md 模板与 YAML 字段配置从零写出一个能被加载的 skill现在进入核心部分。一个合法的 OpenClaw skill 最少只需要两个 YAML 字段name 和 description。但要让 skill 稳定触发、正确执行、方便维护你需要理解每个字段的作用和写法。先看最小可用模板--- name: rename-images description: 当用户要求批量重命名工作区内的图片文件时使用此技能。支持按序号、日期或自定义前缀重命名 jpg/png/webp 文件。 --- # 批量重命名图片 ## 快速开始 使用以下命令按序号重命名当前目录下所有 jpg 文件 bash python3 scripts/rename.py --pattern *.jpg --prefix img --start 1参数说明参数必填说明--pattern是文件匹配模式如 *.jpg--prefix是新文件名前缀--start否起始序号默认 1--dry-run否只预览不执行这个模板里YAML frontmatter 用三个连字符包裹name 是小写字母加连字符description 写清楚了“什么时候用”和“能做什么”。正文部分用 Markdown 组织包含快速开始、参数表格和代码块。 接下来逐个拆解 YAML 字段。 name 字段的命名规则很严格只能用小写字母、数字和连字符不能有空格、下划线或大写字母。rename-images 是合法的Rename_Images 和 rename images 都会导致解析失败。建议用动词开头比如 send-notification、rotate-pdf、query-database这样一看就知道技能干什么。 description 是整个 skill 里最重要的字段没有之一。AI 决定用不用你的 skill几乎完全依赖这句话。好的 description 包含三个要素技能做什么、什么时候触发、有什么前提条件。对比一下 yaml # 差的写法太泛AI 判断不出触发时机 description: 这个技能可以处理图片 # 好的写法具体动作 触发场景 文件类型 description: 当用户要求批量重命名工作区内的图片文件时使用此技能。支持按序号、日期或自定义前缀重命名 jpg/png/webp 文件。差的写法里“处理图片”可以是压缩、裁剪、加水印、重命名AI 无法判断用户说“把图片改个名”时该不该调用这个 skill。好的写法直接锁定了“批量重命名”和“图片文件”两个关键语义触发准确率会高很多。metadata 字段是可选的但强烈建议加上。它的结构是嵌套的 YAMLmetadata: openclaw: emoji: requires: config: [workspace.path] bins: [python3] tools: [exec, read, write]emoji 用于在技能列表和日志里展示方便你快速识别。requires 下面的三类依赖会在运行时被检查config 检查配置文件里是否有对应字段bins 检查系统里是否有对应命令tools 检查 OpenClaw 是否启用了对应工具。如果任何一项不满足这个 skill 会被禁用不会出现在可用列表里。这里有一个实际开发中很容易犯的错误requires.bins 里写了 python3但你的脚本实际用的是 python3.11 的某个特性而系统默认 python3 指向的是 3.9。这种情况下 skill 会被加载但执行时报语法错误。解决办法是在脚本开头用 shebang 指定版本或者在 SKILL.md 正文里明确写“需要 Python 3.10”。Markdown 正文的写作原则是“简洁但完整”。AI 不需要你教它常识但需要你告诉它这个技能特有的规则。比如文件路径必须用绝对路径、某个参数不支持相对时间、输出格式必须是 JSON 等。这些是 AI 无法从通用知识里推断出来的必须写清楚。正文里推荐用表格做参数速查用代码块给可复制的命令用引用块标注关键注意事项。比如注意所有文件路径必须使用绝对路径相对路径会导致脚本找不到文件。这种格式在注入提示词后AI 能快速定位到关键约束减少执行错误。如果你要写的 skill 涉及多个平台或多种模式不要把全部内容塞进 SKILL.md。把详细说明拆到 references/ 目录下SKILL.md 里只保留核心流程和引用链接。这样做的原因是 OpenClaw 采用三级渐进式披露第一级只加载 name 和 description第二级在触发后加载 SKILL.md 正文第三级在需要时才读取 references/ 下的文件。把内容拆开可以节省上下文窗口让 AI 在处理其他任务时不被无关内容干扰。目录结构建议这样组织skills/ └── rename-images/ ├── SKILL.md ├── scripts/ │ └── rename.py ├── references/ │ └── advanced-patterns.md └── assets/ └── template.txtscripts/ 放可执行脚本references/ 放详细文档assets/ 放模板或静态资源。SKILL.md 里用相对路径引用这些文件比如scripts/rename.pyOpenClaw 会基于 skill 目录解析。4. 本地加载验证确认你的 skill 被 OpenClaw 正确识别写完 SKILL.md 之后不要急着在对话里测试。先做本地加载验证确认文件被系统正确解析。这一步能帮你把 YAML 语法错误、命名违规、依赖缺失等问题提前暴露出来。第一步检查目录结构。OpenClaw 默认从工作区的 skills/ 目录加载技能每个技能一个子目录子目录名通常和 name 字段一致。你可以用 tree 命令确认tree skills/rename-images/预期输出skills/rename-images/ ├── SKILL.md └── scripts/ └── rename.py如果 SKILL.md 不在技能子目录的根层级或者文件名大小写不对比如 skill.md系统不会识别。第二步验证 YAML 语法。YAML 对缩进极其敏感一个多余的空格就会导致解析失败。用 Python 快速检查python3 -c import yaml with open(skills/rename-images/SKILL.md) as f: content f.read() frontmatter content.split(---)[1] meta yaml.safe_load(frontmatter) print(name:, meta.get(name)) print(description:, meta.get(description)) print(metadata:, meta.get(metadata)) 如果输出正常打印出 name 和 description说明 YAML 部分没问题。如果报 yaml.scanner.ScannerError那就是缩进或特殊字符的问题。常见错误包括冒号后面没加空格、字符串里包含未转义的引号、用了 Tab 而不是空格。第三步检查 name 字段是否符合命名规则。用正则快速验证python3 -c import re name rename-images if re.match(r^[a-z0-9-]$, name): print(name 合法) else: print(name 非法只能包含小写字母、数字和连字符) 第四步启动 OpenClaw 并查看技能列表。不同版本的命令可能不同常见的是openclaw skills list或者在 OpenClaw 的交互界面里输入 /skills 查看已加载的技能。如果你的 skill 出现在列表里说明加载成功。如果没有出现检查日志输出openclaw --log-level debug 21 | grep -i skill日志里通常会写明哪个 skill 被跳过以及原因比如“skill rename-images skipped: invalid name format”或“skill rename-images skipped: missing required field description”。第五步在对话中做触发测试。用 description 里写明的触发场景来提问比如“帮我把工作区里的 jpg 文件批量重命名前缀用 photo”。观察 AI 是否调用了你的 skill。如果 AI 回复“我没有这个能力”或直接用自己的方式处理说明触发失败。触发失败时先检查 description 是否足够具体。一个实用的调试技巧是临时把 description 改得非常直白比如“当用户说重命名图片时使用此技能”然后重启测试。如果这样能触发说明原来的 description 语义太模糊需要补充触发词。第六步验证脚本可执行。如果 skill 包含 scripts/ 下的脚本手动跑一次确认没有语法错误和路径问题python3 skills/rename-images/scripts/rename.py --help预期输出应该显示参数说明。如果报 ModuleNotFoundError说明依赖没装如果报 Permission denied说明文件没有执行权限用 chmod x 加上。完成这六步之后你手里就有一个经过验证的 skill 骨架了。接下来可以在对话里反复测试不同的用户说法观察触发率和执行结果根据反馈优化 description 和正文指令。5. 常见报错排查401、local proxy failed、reading choices、OAuth 对照解决即使按照上面的步骤操作实际开发中还是会遇到各种报错。这一节对照真实错误信息给出排查路径。401 Unauthorized这个报错通常出现在模型调用层不是 skill 本身的问题。原因有三种API Key 填错了、Key 过期了、Base URL 配错了。先检查 Key 是否完整复制有没有多余的空格或换行。然后确认 Base URL 是 https://taotoken.net/api 而不是其他地址。如果用的是环境变量检查变量名是否和 OpenClaw 读取的一致。在终端里用 curl 直接测试 Key 是否有效curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的Key \ -H Content-Type: application/json \ -d {model:claude-sonnet-4-20250514,messages:[{role:user,content:test}],max_tokens:5}如果 curl 也报 401说明 Key 本身有问题去控制台重新创建一个。如果 curl 正常但 OpenClaw 报 401说明 OpenClaw 的配置没生效检查配置文件路径是否正确、是否需要重启。local proxy failed这个报错说明 OpenClaw 尝试通过本地代理转发请求但代理没有启动或端口不对。如果你没有特意配置代理检查环境变量里是否有 HTTP_PROXY 或 HTTPS_PROXY 被设置成了本地地址。有些开发工具会自动设置这些变量导致 OpenClaw 把请求发到不存在的本地端口。解决办法是在启动 OpenClaw 前 unset 这些变量unset HTTP_PROXY HTTPS_PROXY http_proxy https_proxy openclaw如果你确实需要通过代理访问外部服务确认代理进程在运行且端口正确。但注意TaoToken 的 API 地址是直接可访问的不需要额外代理配置。Error reading choices / reading choices这个报错通常出现在模型返回的 JSON 结构不符合预期时。OpenClaw 期望返回体里有 choices 数组但实际拿到的可能是错误信息或空响应。原因可能是 Model ID 写错了导致服务端返回了错误格式也可能是请求体里的参数不合法比如 max_tokens 设成了负数。先检查 Model ID 是否和 TaoToken 支持的模型列表一致然后检查请求参数。用 curl 发一个最小请求确认返回结构curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的Key \ -H Content-Type: application/json \ -d {model:claude-sonnet-4-20250514,messages:[{role:user,content:hi}],max_tokens:5} | python3 -m json.tool如果返回的 JSON 里有 choices 字段说明模型通道正常问题在 OpenClaw 的解析逻辑或 skill 注入的内容上。如果返回的是 error 字段根据错误信息调整。OAuth 相关报错如果你用的是 Claude Code 或 Codex 类的工具来辅助开发 skill可能会遇到 OAuth token 过期或刷新失败的问题。这类工具通常有自己的鉴权流程和 TaoToken 的 API Key 是两套体系。排查时先确认你是在哪个环节遇到 OAuth 报错如果是 Claude Code 本身登录失效重新走一遍登录流程如果是 Codex 的 auth.json 配置问题检查文件里的 token 字段是否完整。对于 Codex 类的配置auth.json 通常长这样{ token: 你的OAuth token, baseUrl: https://taotoken.net/api, model: claude-sonnet-4-20250514 }注意 baseUrl 和 model 要和 TaoToken 的配置一致。如果 auth.json 里写的是其他地址会导致请求发到错误的服务端。skill 加载了但不触发这个不是报错但比报错更让人头疼。排查顺序是先确认 skill 出现在技能列表里然后检查 description 是否包含用户可能说的关键词再检查 requires 里的依赖是否全部满足。一个实用的方法是临时把 description 改成非常具体的触发句比如“当用户输入‘测试技能触发’时使用此技能”然后在对话里原样输入这句话。如果能触发说明加载没问题是 description 的语义匹配问题如果不能触发说明 skill 根本没被加载回到加载验证步骤重新检查。脚本执行报路径错误skill 正文里写的路径和实际执行时的工作目录可能不一致。OpenClaw 执行脚本时的工作目录通常是工作区根目录不是 skill 目录。所以脚本里引用文件要用绝对路径或者在 SKILL.md 里明确写“先 cd 到 skill 目录再执行”。推荐的做法是在脚本内部用os.path.dirname(os.path.abspath(__file__))获取脚本所在目录然后基于这个目录拼接路径这样不管从哪个目录调用都不会出错。6. 接入文档与 API Keys把验证过的 skill 接到真实工作流走到这一步你的 skill 已经能在本地加载和触发了。接下来要把它接到真实的模型调用链里让每次触发都有稳定的推理后端支撑。API Keys 的创建和管理在 https://taotoken.net/api-keys 。建议为 OpenClaw 单独创建一个 Key不要和其他的项目混用。这样做的原因是第一方便追踪调用量第二如果 Key 泄露可以单独吊销而不影响其他服务第三不同项目可能需要不同的权限或配额。接入文档在 https://taotoken.net/doc 里面有完整的接口说明、参数列表和错误码对照。写 skill 时如果涉及模型调用可以参考文档里的请求示例来构造参数。文档里也说明了不同模型的上下文窗口大小和计费方式这些信息在决定 skill 正文长度时很有用——上下文窗口小的模型不适合注入太长的 SKILL.md。如果你需要长期做 skill 开发和调试Coding Plan 提供了更稳定的调用配额地址是 https://taotoken.net/coding-plan 。对于需要频繁触发 skill 来验证触发逻辑的场景这个方案比按量付费更可控。模型对话页面在 https://taotoken.net/chat 你可以直接在那里测试 skill 注入后的提示词效果。具体做法是把 SKILL.md 的 YAML 头部和正文粘贴到对话里然后输入触发语句观察模型是否能正确理解并调用。这个页面也适合快速验证 description 的触发准确率不需要每次都启动完整的 OpenClaw 环境。Claude Code 的接入配置在 https://taotoken.net/claude-code-anthropic 如果你用 Claude Code 来写 skill 脚本和调试可以参考这个页面里的配置说明。核心还是三个字段Base URL 填 https://taotoken.net/api API Key 填你创建的 KeyModel ID 填你要用的模型。最后给一个实用建议每写完一个 skill先在本地的模型对话页面里做一次“纯提示词测试”——把 SKILL.md 内容作为系统提示词然后输入三到五种不同的用户说法看模型是否都能正确触发。这个测试比在 OpenClaw 里反复重启快得多能帮你快速迭代 description 的写法。等触发率稳定了再放进 OpenClaw 做端到端验证。