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 CLI
ClawHub 是 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\npm，macOS/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_KEY="sk-你的key" export TAOTOKEN_BASE_URL="https://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批量更新已安装的 Skill：
clawhub 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\skills，clawhub 的默认安装目录也在这里。
名称冲突时的读取优先级是：工作区 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/repo@skill> -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 跑通。剩下的都是在这三件事上做微调。
