OpenClaw 技能系统大揭秘：用 clawhub install 安装并生产自己的 skill

1. 为什么你需要认真对待 OpenClaw 的技能系统OpenClaw 的技能系统Skills本质上是一套「给 AI 助手装 App」的扩展机制。你装了什么 skill它就多出什么能力装天气 skill 就能查天气装 PDF skill 就能拆表格装 Home Assistant skill 就能用自然语言控制家里的灯。ClawHub 是它的技能市场clawhub install是安装入口而SKILL.md是你自己造 skill 时唯一必须写对的文件。这套东西适合三类人一是想让 AI 助手从「通用聊天」变成「专业工具」的普通用户二是想把内部脚本、API 封装成 AI 可调用能力的开发者三是想把自己写的 skill 发布到 ClawHub 分享给社区的人。本文按「发现 → 安装 → 编写 → 本地验证 → 发布」这条链路走一遍每一步都给可复制的命令和文件骨架。另外skill 里如果要调外部模型Key 和 API 通道的管理会变成一个新问题我会在第二节说明怎么用 TaoToken 统一收口避免每个 skill 各配一套 Key。我试过把几个自研 skill 挂到 OpenClaw 上跑最深的感受是skill 的难点不在写提示词而在「让 AI 知道什么时候该调用它」以及「调用失败时怎么排查」。所以下面的内容会重点放在 SKILL.md 的结构规范和本地验证上而不是泛泛讲概念。2. 前置准备OpenClaw 环境与 TaoToken 统一 Key 通道2.1 OpenClaw 侧需要确认的东西在装任何 skill 之前先确认三件事OpenClaw 本体已安装并能正常对话Gateway 服务可以重启后面刷新 skill 要用clawhubCLI 可用。检查命令如下# 查看 openclaw 版本与 gateway 状态 openclaw --version openclaw gateway status # 查看 clawhub CLI 是否可用 clawhub --version如果clawhub提示找不到命令说明 CLI 没装或不在 PATH 里先按官方文档补上再继续。技能目录默认在~/.openclaw/workspace/skills/你可以先ls一下确认这个目录存在ls -la ~/.openclaw/workspace/skills/2.2 为什么 skill 场景下更需要统一 Key一个 skill 只要涉及「调模型」或「调外部 API」就会碰到凭证问题。如果每个 skill 各自写死一个 Key会出现三个麻烦Key 散落在多个 SKILL.md 或脚本里轮换时到处改不同 skill 可能指向不同供应商额度和对账混乱本地调试和线上跑用的 Key 不一致行为对不上。TaoToken 在这里的角色是「统一入口」把模型对话、编码类请求、API Key 管理收敛到一个控制台里skill 侧只认一个 base_url 和一个 Key。这样你写 skill 时不用关心背后接的是哪个模型换模型只改控制台配置不动 skill 代码。具体入口官网了解整体能力https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content控制台管理 Keyhttps://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content创建 API Keyhttps://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content接入文档看 base_url 和参数格式https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI 基础地址是https://taotoken.net/api这个不加 UTM直接用于代码里。如果你只是想先验证模型通不通可以用模型对话页面快速试https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content注意skill 里引用 Key 时建议用环境变量而不是明文写进 SKILL.md。SKILL.md 是会被分享甚至发布到 ClawHub 的明文 Key 一旦发布就等于泄露。3. 从 ClawHub 发现并安装 skillclawhub install 完整流程3.1 在 ClawHub 上找 skillClawHub 是技能市场你可以按关键词搜也可以直接浏览分类。找到目标 skill 后页面上一般会给两条路径点「Install」按钮或者复制一条clawhub install skill-name命令。后者更适合在终端里批量操作。3.2 用 clawhub install 安装安装命令的基本形态# 安装指定 skill clawhub install skill-name # 示例安装一个日历类 skill clawhub install caldav-calendar安装完成后skill 文件会落到~/.openclaw/workspace/skills/skill-name/下。你可以立刻验证ls -la ~/.openclaw/workspace/skills/caldav-calendar/ # 正常应该能看到 SKILL.md可能还有 script.sh、assets/ 等3.3 刷新 Gateway 让 skill 生效装完不刷新AI 是感知不到新 skill 的。刷新命令openclaw gateway restart重启后在对话里提一句和该 skill 相关的话比如「帮我看看下周的日程」如果 AI 开始调用日历能力说明装好了。3.4 自动技能发现是怎么回事ClawHub 支持自动发现当你的请求需要某个能力、而本地没装对应 skill 时AI 会去 ClawHub 搜并拉取。这个机制省事但有两个前提——网络能到 ClawHub以及该 skill 在市场上存在。生产环境里我更建议显式clawhub install因为自动发现的行为不如手动安装可预期排查问题时也少一个变量。3.5 常用 skill 的安装对照skill 名称用途安装命令home-assistant自然语言控制智能家居clawhub install home-assistantcaldav-calendar自托管日历集成clawhub install caldav-calendarr2-upload文件上传到对象存储并生成分享链接clawhub install r2-uploadopenrouter-transcribe多语言音频转录clawhub install openrouter-transcribe装完每个都记得openclaw gateway restart别攒着一起重启否则出问题不好定位是哪个 skill 引起的。4. 编写自己的 SKILL.md从骨架到可运行4.1 技能目录结构一个 skill 的最小结构就是一个目录加一个SKILL.md~/.openclaw/workspace/skills/my-skill/ ├── SKILL.md # 必须技能说明、触发条件、执行逻辑 ├── script.sh # 可选需要执行脚本时放这里 └── assets/ # 可选模板、示例数据等资源复杂一点的 skill 会带 Shell/Python 脚本、外部 API 调用、以及自定义工具函数定义。但无论多复杂SKILL.md都是入口AI 先读它再决定怎么执行。4.2 SKILL.md 骨架可直接复制下面这份骨架我按「描述 → 触发条件 → 执行步骤 → 示例 → 失败处理」组织比只写一段描述要可靠得多# my-skill ## 描述 一句话说明这个 skill 做什么以及它解决什么问题。 ## 触发条件 当用户提到以下意图时启用本技能 - 关键词 A、关键词 B - 需要执行 XXX 操作时 ## 前置依赖 - 环境变量MY_SKILL_API_KEY - 外部命令curl、jq ## 执行步骤 1. 从用户输入中提取参数param1、param2 2. 调用接口POST https://taotoken.net/api/... 示例按实际替换 3. 解析返回结果提取字段 field 4. 用自然语言向用户汇报结果 ## 示例 用户帮我查一下 XXX AI[调用本技能返回结果] ## 失败处理 - 参数缺失向用户追问缺失的字段 - 接口报错返回错误码与简短原因不要编造结果4.3 让 AI 正确触发 skill 的关键很多人写完 SKILL.md 发现 AI 不调用问题通常出在「触发条件」写得太模糊。把触发条件写成明确的意图列表比写「当用户需要相关帮助时」有效得多。另外执行步骤要写成可执行的动作序列而不是「处理一下数据」这种描述——AI 需要的是明确指令。4.4 在 skill 里接入 TaoToken如果 skill 需要调模型把 base_url 指向https://taotoken.net/apiKey 从环境变量读。以 Shell 脚本为例#!/usr/bin/env bash set -euo pipefail : ${TAOTOKEN_API_KEY:?请先设置 TAOTOKEN_API_KEY 环境变量} curl -sS https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer ${TAOTOKEN_API_KEY} \ -H Content-Type: application/json \ -d { model: your-model-name, messages: [ {role: user, content: 用一句话总结这段文本} ] } | jq -r .choices[0].message.content在 SKILL.md 的「前置依赖」里写明需要TAOTOKEN_API_KEY这样别人拿到你的 skill 也知道要配什么。模型名和具体路径以接入文档为准https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content4.5 本地验证 skill 是否被正确加载写完先别急着发布本地验证三步走# 1. 确认文件结构 ls -la ~/.openclaw/workspace/skills/my-skill/ # 2. 重启 gateway openclaw gateway restart # 3. 在对话中触发观察是否调用如果 AI 没有调用先检查 SKILL.md 的触发条件是否覆盖了你的说法再检查 gateway 日志里有没有加载该 skill 的记录。日志一般在 gateway 的运行输出里重启时留意终端打印。5. 验证请求与成功结果跑通一条完整链路5.1 先单独验证 API 通道在把 skill 接进 OpenClaw 之前先确认 TaoToken 通道本身是通的。用一条最小请求curl -sS https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer ${TAOTOKEN_API_KEY} \ -H Content-Type: application/json \ -d { model: your-model-name, messages: [{role: user, content: 回复 OK 两个字母}] }返回里能看到choices[0].message.content为OK说明 Key、base_url、模型名三者都对。这一步不通后面 skill 一定不通先在这里排掉。5.2 再验证 skill 被触发通道通了之后重启 gateway在对话里用 SKILL.md 里写好的触发词试一次。成功的标志是AI 明确表示在调用该 skill并返回了符合预期的结果而不是用通用知识瞎答。5.3 发布到 ClawHub本地验证通过后用clawhub publish发布clawhub publish发布前建议再检查一遍 SKILL.md 里没有明文 Key、没有内部地址、示例数据不含敏感信息。发布后你的 skill 就会出现在 ClawHub 上别人可以clawhub install安装。6. 本篇常见错误排查6.1 clawhub install 报找不到 skill先确认 skill 名拼写和 ClawHub 上一致再确认网络能访问 ClawHub。如果名字对、网络也通可能是该 skill 已下架或改名回市场页面重新复制安装命令。6.2 装完 AI 不调用九成是没重启 gateway。先openclaw gateway restart再试。如果重启后仍不调用检查 SKILL.md 的触发条件是否写得太泛或太窄以及文件是否真的落在~/.openclaw/workspace/skills/skill-name/下。6.3 skill 调用报鉴权失败如果 skill 里用了 TaoToken报 401 通常是TAOTOKEN_API_KEY没设置或已失效。用echo $TAOTOKEN_API_KEY确认环境变量在当前 shell 里可见注意 gateway 是以哪个用户、哪个环境启动的——环境变量要在那个上下文里存在。Key 可以在控制台重新生成https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content6.4 返回结果为空或格式解析失败常见于脚本里用jq解析但字段路径写错。先把原始返回打印出来看结构再改jq表达式。另外注意有些接口在出错时返回的不是choices结构脚本里要加错误分支别直接取choices[0]。6.5 发布后别人装不上检查 SKILL.md 里是否引用了只有你本地才有的路径或私有依赖。发布版应该只依赖公开可获取的命令和用户自己配置的环境变量。7. 接下来怎么走按场景选入口如果你现在卡在「Key 怎么配、base_url 填什么」先去创建 API Key 并对照接入文档https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 和 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content如果你只是想先确认某个模型在 skill 场景下表现如何用模型对话页面直接试最省事https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content如果你打算长期写 skill、跑编码类或 Agent 类任务把额度集中管理会更省心可以看 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content最后给一个实操建议每写一个新 skill先在本地用 curl 把要调的接口跑通再写进 SKILL.md。顺序反了的话你会分不清是 skill 写错了还是接口本身不通排查成本翻倍。