1. 为什么你的 OpenClaw 装了 Skill 却像没装很多人第一次接触 OpenClaw 的 Skill 机制都会经历同一个困惑明明按文档把文件夹丢进去了openclaw doctor也跑了可对话时模型就是不调用那个技能。问题往往不在模型而在 Skill 的安装路径、目录结构、SKILL.md 的 frontmatter 三者中至少有一个没对齐。OpenClaw 的 Skill 本质上是一份写给大模型看的“操作说明书”。它不是一个可执行插件而是一个 Markdown 文件加上若干可选资源Gateway 在组装 System Prompt 时会把 SKILL.md 的正文塞进去模型读到name和description后判断当前任务是否匹配再决定要不要按里面的步骤走。所以 Skill 能不能生效取决于两件事Gateway 有没有扫描到它以及 SKILL.md 写得够不够“让模型一眼看懂什么时候该用”。这篇面向正在用 ClawHub CLI 管理 Skill 的开发者把安装、挂载、编写、自检串成一条可复制的闭环。我会给出 ClawHub CLI 的安装与更新命令、本地挂载的目录规则、一份能直接改的 SKILL.md 骨架以及openclaw doctor报错时的排查顺序。另外Skill 里如果涉及调用外部模型Key 和 API 通道怎么统一管理我会用 TaoToken 做示例避免每个 Skill 各配一套密钥。适合谁看已经跑起 OpenClaw、想扩展自定义能力的人被clawhub install卡住或openclaw doctor报 skill not found 的人以及想写第一个 SKILL.md 但不知道 frontmatter 该填什么的人。2. 前置准备ClawHub CLI 与 TaoToken 通道2.1 安装 ClawHub CLIClawHub 是 OpenClaw 生态里的 Skill 注册中心CLI 负责拉取、更新、同步。前提是本机已经有 Node.js 环境建议 18 以上然后全局安装npm install -g openclaw/clawhub-cli装完验证版本确认命令可用clawhub --version如果提示command not found检查 npm 全局 bin 目录是否在 PATH 里。Windows 下通常是C:\Users\用户名\AppData\Roaming\npmmacOS/Linux 下是/usr/local/bin或~/.npm-global/bin。2.2 为什么 Skill 里要统一 Key 通道写 Skill 时一个绕不开的问题是如果这个 Skill 需要调用大模型比如做摘要、做代码审查Key 从哪来最糟的做法是把 Key 硬编码进 SKILL.md 或脚本里一旦 Skill 被分享出去就泄露了。更稳的做法是让 Skill 通过统一的环境变量读取 API 通道。我习惯用 TaoToken 做这层统一入口它兼容 OpenAI 风格的接口一个 Key 可以给多个 Skill 和工具复用。你可以在控制台创建 Key# 控制台创建 API Key 后写入环境变量 export TAOTOKEN_API_KEYsk-你的key export TAOTOKEN_BASE_URLhttps://taotoken.net/api这样 Skill 的脚本里只引用TAOTOKEN_API_KEY不出现任何明文密钥。模型对话、编码类 Skill 都能走同一个通道换工具时不用重新配一遍。如果你还没建 Key可以先到控制台的 API Keys 页面生成一个再回来继续。3. 可复制配置安装、挂载与 SKILL.md 骨架3.1 用 ClawHub CLI 安装与更新标准安装方式是从注册中心直接拉取命令格式是作者/技能名clawhub install openclaw/agent-browser安装完成后必须重启网关让路由和 System Prompt 重新加载openclaw gateway restart批量更新已安装的 Skillclawhub update --all扫描本地并同步发布更新clawhub sync --all注意clawhub install依赖网络到注册中心如果拉取很慢或超时可以改用下面的本地挂载方式把 Skill 文件夹直接放进工作区效果一样。3.2 本地挂载的目录规则开发自定义 Skill 时直接把文件夹放进 OpenClaw 的工作区即可。路径分两种作用域作用域路径说明全局生效~/.openclaw/skills/所有 Agent 都能用单 Agent 专属~/.openclaw/agents/agentId/skills/只对该 Agent 生效工作区级当前文件夹/skills/随项目走适合团队共享Windows 下如果用 npm 安装内置技能在C:\Users\用户名\AppData\Roaming\npm\node_modules\openclaw\skills这里预装了 clawhub、coding-agent、healthcheck 等几十个内置技能。自定义技能建议放在托管目录C:\Users\用户名\.openclaw\workspace\skillsclawhub 的默认安装目录也在这里。名称冲突时的读取优先级是工作区 Skills 单 Agent 专属 全局。也就是说项目里的同名 Skill 会覆盖全局的。3.3 标准目录结构Gateway 解析 Skill 时真正必读的只有 SKILL.md其余目录都是给脚本和参考资料用的my-skill/ ├── SKILL.md # 必须模型读的就是它 ├── scripts/ # 可选脚本 │ ├── run.py │ └── helper.sh ├── references/ # 可选参考文档 │ └── usage.md ├── assets/ # 可选模板、样例 │ └── template.json └── LICENSE.txt # 可选3.4 一份能直接改的 SKILL.md 骨架frontmatter 里的name和description是模型判断“要不要用这个技能”的唯一依据description 要写清楚触发场景而不是功能罗列。下面这份骨架可以直接复制改名--- name: find-skills description: 当用户问“怎么做 X”“有没有做 X 的技能”“能不能帮我做 X”或表达想扩展 Agent 能力时使用。帮助用户发现并安装可用的 Skill。 --- # Find Skills 这个技能帮助用户从 Skill 生态中发现并安装技能。 ## 何时使用 当用户出现以下情况时触发 - 问“怎么做 X”而 X 可能是已有技能覆盖的常见任务 - 说“找一个做 X 的技能” - 问“你能做 X 吗”而 X 是某种专门能力 - 想搜索工具、模板或工作流 ## 执行步骤 1. 识别领域和具体任务判断是否属于常见场景 2. 用关键词搜索npx skills find [query] 3. 把结果连同安装命令一起呈现给用户 4. 用户确认后执行安装npx skills add owner/reposkill -g -y ## 约束 - 搜索关键词要具体“react testing”优于“testing” - 一次没搜到就换同义词再试 - 找不到时如实告知并建议用户用 npx skills init 自建 ## 失败处理 如果搜索无结果不要编造技能名直接说明未找到并提议用通用能力直接完成任务。这份结构对应了经典写法先声明何时用再定义名词然后分步骤执行最后给约束和失败处理。模型读到“何时使用”和“执行步骤”后匹配到对应意图就会按流程走。4. 验证openclaw doctor 与一次真实调用4.1 用 openclaw doctor 自检把 Skill 放进目录后运行openclaw doctor它会扫描所有 Skill 路径检测并注册新加入的本地技能。正常输出里会列出识别到的技能名和来源路径。如果某个 Skill 没出现说明路径或 frontmatter 有问题往下看第 5 节的排查。4.2 验证 Skill 内的模型调用通道如果 Skill 脚本需要调模型先单独验证 TaoToken 通道是否通curl https://taotoken.net/api/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: 回复 ok}] }返回里能看到正常的choices结构就说明 Key 和通道没问题Skill 脚本里可以放心引用同一套环境变量。想先在网页端确认模型可用可以直接用模型对话页面试一句省去配环境的步骤。4.3 触发一次真实调用重启网关后在对话里输入一个能命中 description 的请求比如“帮我找一个做 React 性能优化的技能”。如果 Skill 生效模型会按 SKILL.md 里的步骤先搜索再给安装命令。这一步能跑通说明从安装到自检的闭环完整了。5. 本篇常见错排查5.1 openclaw doctor 不显示新 Skill先确认文件夹名和 frontmatter 里的name是否一致再确认 SKILL.md 是否在文件夹根目录而不是子目录。frontmatter 必须以---开头和结尾中间不能有空行或多余缩进。YAML 里冒号后要有空格name:find-skills这种写法会解析失败。5.2 装了但模型不调用九成是 description 写得太泛。像“处理文档相关任务”这种描述模型无法判断何时触发。改成具体场景把用户可能说的原话写进去比如“当用户要求合并多个 Excel 或生成目录时使用”。description 是给模型看的触发条件不是给人看的功能简介。5.3 clawhub install 卡住或超时注册中心拉取受网络影响较大可以改用本地挂载手动下载 Skill 文件夹放进~/.openclaw/skills/再跑openclaw doctor。功能完全一致只是少了自动更新。5.4 同名 Skill 行为不对检查是否有多个同名 Skill 分布在不同路径。按优先级工作区会覆盖全局。用openclaw doctor的输出确认实际加载的是哪一个把不需要的删掉或改名。5.5 Skill 脚本读不到 Key确认环境变量是在启动 Gateway 的那个 shell 里 export 的。如果 Gateway 是 systemd 或后台服务启动需要在服务配置里注入TAOTOKEN_API_KEY而不是只在当前终端设置。脚本里用os.environ.get(TAOTOKEN_API_KEY)读取不要写死。6. 把 Skill 接入长期工作流单个 Skill 跑通之后下一步通常是把它接进日常编码或 Agent 流程。这时候 Key 和通道的稳定性比单个 Skill 的写法更重要因为多个 Skill 会共享同一套 API 通道。如果你的 Skill 组合偏向长期编码、代码审查、自动化任务可以考虑用 Coding Plan 统一管理额度避免每个 Skill 单独配 Key 导致混乱。接入文档里有完整的鉴权和参数说明写 Skill 脚本前过一遍能省不少调试时间。整个流程走下来核心就三件事路径放对、frontmatter 写准、doctor 跑通。剩下的都是在这三件事上做微调。
