1. 为什么你的 Agent 需要 Skills 系统OpenClaw 的 Skills 系统本质上是一套「插件化能力单元」——每个技能就是一个带SKILL.md的目录框架在会话启动时扫描、过滤、注入到系统提示词里模型据此决定调用哪个工具。如果你只用默认功能大概只发挥了它三成能力一旦需要接入公司内部 API、定制代码审查流程、或者把某个重复操作固化成 slash 命令Skills 就是绕不开的桥。这篇面向需要在本地 Agent 工作流里扩展自定义技能的开发者从源码结构讲到SKILL.md规范再给一份可直接复制的骨架、ClawHub 加载配置以及通过 TaoToken 统一 Key/API 通道接入时的settings.json示例与验证步骤。全程可跟做不需要你先读完整个仓库。适合谁已经跑通 OpenClaw 基础对话、想加第一个自定义技能的人或者技能加载失败、requires一直不通过、想搞清 gating 时机的人。下面所有路径以 macOS/Linux 为例Windows 把~换成你的用户目录即可。2. TaoToken 前置统一 Key 与 API 通道在写技能之前先把模型通道理顺。很多自定义技能会调用外部模型比如让技能内部再跑一次推理如果每个技能各自配 Key管理会非常乱。TaoToken 提供统一的 Key 和 API 入口把模型调用收敛到一个地方技能里只引用环境变量即可。你需要准备两样东西第一一个可用的 API Key。到控制台创建https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite第二确认 API 基地址。对话补全走https://taotoken.net/api注意这个地址不带任何查询参数直接作为base_url使用。创建完 Key 后建议先单独验证一次通道是否通再往技能里塞。用 curl 测一下export TAOTOKEN_API_KEYsk-你的key curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: gpt-4o-mini, messages: [{role: user, content: ping}], max_tokens: 16 }返回里出现choices数组就说明通道正常。这一步很关键——后面技能加载失败时你能快速区分是「技能配置问题」还是「Key/通道问题」。如果你更想先在网页里点着试可以直接用模型对话页https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite注意Key 不要硬编码进SKILL.md或脚本里。统一走环境变量或 OpenClaw 的apiKey引用机制后面第 4 节会讲。3. 可复制配置SKILL.md 骨架与加载配置3.1 三层加载优先级OpenClaw 的技能来源分三层同名技能高优先级覆盖低优先级层级路径用途Workspaceworkspace/skills/当前项目专属最高优先级Managed~/.openclaw/skills/用户级覆盖跨项目共享Bundlednpm 包内skills/内置技能最低优先级优先级链workspace managed bundled。这意味着你可以安全地覆盖任何内置技能而不影响全局。想改内置coding-agent的提示词就在 workspace 下建同名目录放一份SKILL.md。3.2 SKILL.md 完整骨架一个技能的核心就是SKILL.md采用 YAML frontmatter Markdown body。下面这份骨架可以直接复制改名使用--- name: my-custom-skill description: 一句话说明这个技能做什么10-20字会进系统提示词 metadata: { openclaw: { emoji: , requires: { bins: [python3], env: [MY_SKILL_KEY] }, primaryEnv: MY_SKILL_KEY } } --- # 技能标题 用一两句话说明这个技能的用途和边界。 ## 何时使用 - 用户询问 XXX 时 - 需要 YYY 操作时 ## 如何调用 1. 确认参数symbol说明格式 2. 使用 exec 运行 {baseDir}/run.py 3. 解析 JSON 输出并返回给用户 ## 示例 用户帮我查一下 XXX 代理exec python3 {baseDir}/run.py --symbol XXX ## 实现说明 - 脚本依赖见 requirements.txt - Key 从 MY_SKILL_KEY 环境变量读取 - 失败时返回错误信息并建议重试几个必须记住的点name只能用小写字母和连字符description会直接进提示词越短越省 token{baseDir}是技能目录的绝对路径占位符脚本引用一律用它别写死路径。3.3 metadata.openclaw 的 gating 字段这是 OpenClaw 特有的单行 JSON决定技能在什么条件下才被加载字段类型说明alwaysboolean强制启用跳过其他 gateosstring[]限制平台darwin / linux / win32requires.binsstring[]所有二进制必须在 PATH 中requires.anyBinsstring[]至少一个二进制存在requires.envstring[]指定环境变量必须存在requires.configstring[]配置路径必须为真primaryEnvstring关联skills.entries.key.apiKey的 env 名installInstaller[]自动安装说明brew/node/go/downloadgating 在 Agent 会话启动时执行扫描所有技能检查requires.*只加载符合条件的。条件不满足技能直接不可见——这也是「技能不加载」最常见的原因。3.4 ClawHub 技能加载配置ClawHub 是 OpenClaw 的公共技能注册表相当于 Skills 的 npm。安装 CLI 后可以搜索、安装、发布npm install -g clawhub clawhub search stock clawhub install my-stock-quote --version 1.2.0 clawhub update --all安装后技能落在当前工作区的./skills并记录到.clawhub/lock.json。如果你想把技能包放在自定义目录在~/.openclaw/openclaw.json里配置extraDirs{ skills: { allowBundled: [gemini, peekaboo], load: { extraDirs: [~/Projects/agent-scripts/skills], watch: true, watchDebounceMs: 250 }, install: { preferBrew: true, nodeManager: npm }, entries: { my-custom-skill: { enabled: true, apiKey: { source: env, provider: default, id: MY_SKILL_KEY }, env: { MY_SKILL_KEY: 占位实际从环境变量注入 }, config: { endpoint: https://taotoken.net/api, model: gpt-4o-mini } } } } }allowBundled是白名单只列出允许启用的内置技能防止误开load.watch默认 trueSKILL.md改动后热加载无需重启entries.skillKey是每个技能的独立配置enabled: false可显式禁用。3.5 通过 TaoToken 接入的 settings.json 片段如果你的技能内部要调用模型把通道指向 TaoTokenKey 走环境变量引用避免硬编码{ skills: { entries: { my-custom-skill: { enabled: true, apiKey: { source: env, provider: default, id: TAOTOKEN_API_KEY }, config: { baseUrl: https://taotoken.net/api, model: gpt-4o-mini, timeoutMs: 30000 } } } } }apiKey.source: env表示从环境变量读取id指定变量名。这样 Key 只存在于你的 shell 环境配置文件可以安全提交到仓库。技能脚本里读TAOTOKEN_API_KEY即可不用关心具体值。4. 验证请求从加载到成功调用4.1 创建技能目录mkdir -p ~/.openclaw/workspace/skills/china-stock-quote cd ~/.openclaw/workspace/skills/china-stock-quote目录结构china-stock-quote/ ├── SKILL.md # 必需 ├── requirements.txt # 可选 └── quote.py # 可选实现脚本4.2 写一个最小可跑的实现quote.py先用 mock 数据验证链路跑通后再换真实 API#!/usr/bin/env python3 import json import argparse def query_stock(symbol: str) - dict: # TODO: 换成真实数据源 return { symbol: symbol, name: 示例股票 if symbol 600519 else 未知, price: 1688.50, change_percent: 0.73%, } if __name__ __main__: parser argparse.ArgumentParser() parser.add_argument(--symbol, requiredTrue) args parser.parse_args() print(json.dumps(query_stock(args.symbol), ensure_asciiFalse))4.3 触发加载并验证方式一新会话自动发现openclaw agent --message 用 china-stock-quote 查询 600519 的价格方式二当前会话热刷新/skills refresh然后直接对话。查看技能是否被加载openclaw logs | grep china-stock-quote成功时你会看到技能被列入 eligible 列表模型在回复里调用exec python3 quote.py --symbol 600519并返回 JSON 解析后的结果。如果模型没调用先确认SKILL.md的description是否清晰描述了触发场景——模型靠它判断何时用这个技能。5. 本篇常见错排查技能完全不出现。九成是 frontmatter 格式问题。YAML 缩进必须用空格metadata那行是单行 JSON引号别漏。用openclaw logs看有没有解析报错。requires 一直不通过。检查bins里的二进制是否真在 PATHwhich python3。env里的变量是否已 exportecho $MY_SKILL_KEY。注意requires.env只检查存在性不检查值。模型不调用技能。通常是description太模糊或者 body 里没写清「何时使用」。把触发场景写具体比如「用户询问 A 股实时价格时」而不是「查询数据」。改了 SKILL.md 没生效。确认load.watch为 true或者手动/skills refresh。watch 有 250ms 防抖改完稍等一下。技能内脚本报网络错误。默认 sandbox 禁止网络。需要联网的技能要配置tools.exec.sandbox.docker.network或让脚本走 hostgateway。如果脚本调用 TaoToken确认baseUrl是https://taotoken.net/api且 Key 环境变量已注入。多技能冲突。优先级规则已经解决同名 workspace 技能总是胜出。实在冲突就重命名。6. 下一步把通道和技能都固化下来技能跑通后建议做两件事。一是把模型通道统一到 TaoToken所有技能共用一套 Key省去逐个配置的麻烦——到 API Keys 页面创建并管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite二是如果你打算长期跑编码类或 Agent 类技能Coding Plan 比按次调用更划算适合高频场景https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite接入细节和参数说明都在文档里遇到 gating 或 baseUrl 问题可以直接对照https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite最后提醒一句第三方技能一律视为不可信代码跑之前先读SKILL.md和脚本高风险技能放 sandbox。我试过把一个来路不明的技能直接跑在宿主机上结果它偷偷改了工作区外的文件——从那以后所有外部技能都先进 Docker。