1. 为什么我要给 OpenClaw 写自定义技能OpenClaw 这个项目最吸引我的地方是它把「助手能力」拆成了一个个可以自己写的技能目录。你不需要改它的核心代码只要在 workspace 里放一个带SKILL.md的文件夹它就能在对话里发现并调用。说白了技能就是给模型看的「说明书 工具清单」模型读到之后就知道遇到什么场景该干什么。但很多人卡在第一步技能目录到底怎么建、SKILL.md的 frontmatter 写哪些字段、触发词和参数怎么声明、写完怎么让 OpenClaw 重新索引。更现实的问题是技能跑起来要调模型如果每个技能各自配一套 Key管理起来会非常乱。我实测下来比较顺的做法是让 OpenClaw 统一走 TaoToken 的 API 通道一个 Key 覆盖对话和编码类请求技能侧只关心业务逻辑。这篇就按「从零落地一个自定义技能」的路径走先给可直接抄的SKILL.md骨架再给config.toml接入 TaoToken 统一 Key 的配置片段最后用一次真实调用验证技能是否被正确加载。适合已经在用 OpenClaw、想扩展它能力但不想动核心代码的开发者。读完你至少能得到一个能跑起来的技能模板以及一套不会再为 Key 发愁的接入方式。2. OpenClaw 技能机制与 TaoToken 前置准备2.1 技能目录长什么样OpenClaw 默认从工作区的skills/目录扫描技能路径通常是~/.openclaw/workspace/skills/。每个技能是一个独立文件夹里面必须有SKILL.md可选带脚本或资源文件。结构大概是这样~/.openclaw/workspace/skills/ └── hello-world/ ├── SKILL.md └── scripts/ └── greet.shSKILL.md分两部分顶部 YAML frontmatter 存元数据名字、描述、工具定义下面用 Markdown 写指令。模型读的是「描述 指令」所以描述写得越清楚触发越准。2.2 为什么统一走 TaoToken技能多了之后每个技能如果各自持有模型 Key轮换和额度管理会很痛苦。TaoToken 提供的是统一 API 通道OpenClaw 的模型请求指向它技能本身不碰 Key。这样你换模型、调额度只改一处配置。需要提前准备两样东西一个 TaoToken 的 API Key以及确认你要用的模型名。Key 在控制台创建地址是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。创建完先别关页面后面config.toml要用。模型名和可用列表可以在模型对话页确认https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。注意Key 只放在本地配置文件里不要写进SKILL.md技能文件是给模型读的写进去等于把凭证暴露给对话上下文。3. 可复制配置SKILL.md 骨架与 config.toml 接入3.1 创建技能目录先建目录名字用英文小写加连字符避免空格mkdir -p ~/.openclaw/workspace/skills/hello-world/scripts cd ~/.openclaw/workspace/skills/hello-world3.2 写 SKILL.md下面这份骨架包含 frontmatter 元数据、触发词说明、参数声明和工具调用指令可以直接改--- name: hello_world description: 当用户请求问候、打招呼或测试技能是否加载时使用。返回一句自定义问候语。 version: 1.0.0 tools: - name: echo description: 输出一段文本 parameters: type: object properties: message: type: string description: 要输出的内容 required: - message --- # Hello World Skill 当用户说「打个招呼」「测试技能」「hello」时调用 echo 工具 message 参数填 Hello from your custom skill!。 ## 触发条件 - 用户明确要求问候 - 用户想验证自定义技能是否生效 ## 参数说明 - message字符串必填要输出的问候内容 ## 安全约束 - 不允许把用户原始输入直接拼进 shell 命令 - 只输出固定问候语不执行外部命令frontmatter 里的name是技能唯一标识description决定模型什么时候想起它tools声明这个技能能用哪些工具。如果你想让技能调用系统 bash把工具名换成bash但一定要在指令里写死允许的命令范围别让用户输入直接进命令。3.3 config.toml 接入 TaoTokenOpenClaw 的模型通道配置在config.toml把 base_url 指向 TaoTokenKey 填进去[model] provider openai-compatible base_url https://taotoken.net/api api_key sk-你的TaoToken密钥 model claude-sonnet-4-5 [workspace] skills_dir ~/.openclaw/workspace/skills auto_reload truebase_url用https://taotoken.net/api不要加多余路径。auto_reload true让 OpenClaw 在技能目录变化后自动重新索引省得每次手动刷新。改完保存重启 gateway 或让助手执行「刷新技能」。4. 验证请求确认技能被正确加载4.1 刷新并列出技能先让 OpenClaw 重新扫描openclaw gateway restart openclaw skills list如果hello_world出现在列表里说明目录结构和 frontmatter 没问题。没出现的话九成是 YAML 缩进错了或者文件不在skills_dir下。4.2 发起一次真实调用用命令行直接触发技能openclaw agent --message 用我的新技能打个招呼预期返回类似[skill: hello_world] Hello from your custom skill!看到[skill: hello_world]前缀就说明模型正确匹配到了技能并调用了echo工具。这一步同时验证了两件事技能被索引以及模型请求通过 TaoToken 通道正常返回。如果只返回普通对话而没有技能前缀说明description没让模型联想到把触发词写得更具体一点。4.3 参数传递验证再测一次带参数的场景确认 frontmatter 里的参数声明生效openclaw agent --message 调用 hello_worldmessage 填 测试参数返回里应该带上你传入的内容。如果报参数缺失检查required字段和properties的拼写。5. 本篇常见错排查技能不出现先确认SKILL.md在技能文件夹根目录不是嵌套在子目录里。再检查 frontmatter 的---是否成对YAML 里冒号后面要有空格。模型不触发技能description太泛比如只写「一个技能」。改成具体场景描述把用户可能说的词写进去。调用报 401 或鉴权失败config.toml里的api_key没填对或者base_url写成了带/v1的地址。TaoToken 的 base 就是https://taotoken.net/api。改了技能不生效auto_reload没开或者 gateway 没重启。手动执行openclaw gateway restart最稳。bash 工具被滥用指令里没写安全约束模型可能把用户输入拼进命令。务必在SKILL.md里限定允许的命令白名单。Key 泄露风险不要把 Key 写进SKILL.md或脚本注释只放config.toml并且该文件不要提交到公开仓库。6. 把技能通道固定下来技能写多了之后真正省事的是把模型通道固定成一套。OpenClaw 这边只认config.toml里的 base_url 和 Key技能侧完全不感知模型来源。你新增技能时只需要复制SKILL.md骨架、改name和description模型请求自动走同一条通道。如果你后面要做长期编码类技能或 Agent 循环调用可以看下 Coding Plan 的额度方式https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。接入细节和字段说明在文档里https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。需要新建或轮换 Key 时控制台入口是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。我自己的习惯是每写一个新技能先在hello-world上验证通道通不通再改业务逻辑。这样出问题时能快速判断是技能写法问题还是通道配置问题省掉很多来回试的时间。
)
