1. 为什么你的 Openclaw Agent 需要一个能跑通的 SkillOpenclaw 的 Skills 机制本质上是给 AI Agent 装上一双能干活的手。大模型负责思考、决策、组织语言而 Skills 负责真正去执行——查天气、发请求、跑脚本、写文件、调接口。你如果只让 Agent 聊天它永远停在“说”的层面一旦挂上 Skill它就能从“说”跨到“做”。这篇面向的是需要为 AI-Agent 扩展自定义技能的开发者尤其是已经跑起 Openclaw、想加第一个自己的 Skill 却卡在目录结构、config.toml 骨架、Key 配置和调用验证这几步的人。我会用一个最小可运行的weather-querySkill 做贯穿示例从目录创建、_meta.json与SKILL.md编写、主脚本实现到用 TaoToken 统一 Key 打通模型调用链最后完成一次完整的注册与调用验证。目标很直接你复制配置、改掉城市名就能跑通首个自定义 Skill。很多人第一次写 Skill 会踩两个坑一是把 Skill 当成普通 Node 脚本写忽略了触发词和元数据注册二是每个 Skill 各自维护一份模型 Key散落在不同脚本里改一次要翻十个文件。TaoToken 在这里的价值就是把 Key 收敛成一份统一配置Skill 只关心业务逻辑模型调用走同一个入口。下面按可跟做的顺序展开。2. TaoToken 前置统一 Key 与接入信息在写 Skill 之前先把模型调用的“总闸”接好。TaoToken 提供统一的 API 入口你只需要在控制台生成一个 Key后续所有 Skill 里需要调用模型的地方都复用它不用每个 Skill 单独申请。你需要先拿到两样东西一个是 API Key一个是接入地址。地址分两种用途官网入口用于了解和控制台操作API 地址用于代码里实际请求。用途地址官网入口https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI 基址https://taotoken.net/api拿到 Key 的路径是进入控制台创建 API Key复制保存。这个 Key 后面会写进 Skill 的配置里或者更推荐的做法是写进环境变量Skill 运行时读取。注意Key 不要硬编码进会提交到 Git 的脚本里。用环境变量或本地 config 文件并在.gitignore里排除。如果你后续要做长期编码类或 Agent 类任务可以了解 Coding Plan如果只是想先验证模型对话是否通可以用模型对话页面快速试一次。这两个入口在排障阶段很有用但本篇主线还是把 Key 接进 Skill。3. 可复制配置目录结构、config.toml 与 Skill 骨架3.1 标准目录结构Openclaw 扫描 Skill 的默认路径是 workspace 下的skills/目录。每个 Skill 一个独立文件夹名称唯一内部结构如下workspace/skills/ └── weather-query/ ├── SKILL.md # 技能说明文档 ├── _meta.json # 元数据触发词、入口脚本 ├── config.toml # 本 Skill 的配置含模型 Key 引用 ├── scripts/ │ └── main.js # 主执行脚本 └── results/ # 输出结果目录可选先创建目录cd workspace/skills mkdir -p weather-query/scripts weather-query/results3.2 config.toml 骨架config.toml是这个 Skill 的本地配置。模型调用统一走 TaoToken所以这里只放基址和 Key 的引用不重复写业务参数。[skill] name weather-query version 1.0.0 enabled true [model] provider taotoken base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY model gpt-4o-mini timeout_ms 30000 [weather] default_city 北京 request_timeout_ms 10000这里的关键是api_key_env它指向环境变量名而不是把 Key 明文写进文件。运行时脚本读取process.env.TAOTOKEN_API_KEY即可。这样多个 Skill 共用同一个 Key改一处全局生效。设置环境变量Linux/macOSexport TAOTOKEN_API_KEY你的KeyWindows PowerShell$env:TAOTOKEN_API_KEY你的Key3.3 _meta.json 元数据_meta.json决定 Skill 怎么被识别和触发。触发词要具体避免太短导致误触发。{ name: weather-query, version: 1.0.0, description: 查询指定城市实时天气, main: scripts/main.js, triggers: [ 查询天气, 今天天气, 天气怎么样, 查天气 ], autoExecute: true }autoExecute为true时命中触发词直接执行涉及删除、发送等危险操作时建议设为false让 Agent 先确认。3.4 SKILL.md 说明文档--- name: weather-query description: 查询实时天气支持任意城市 --- # 天气查询技能 ## 功能 - 查询指定城市实时天气 - 显示温度、体感、湿度、风力 ## 使用方式 当用户说“查询天气”“今天天气”时自动执行。 ## 配置 模型调用走 TaoToken 统一 Key见 config.toml。3.5 主脚本 main.js脚本负责两件事读配置、调模型或调数据源、输出结果。下面这版把模型调用封装成统一函数Key 从环境变量取。#!/usr/bin/env node const https require(https); const fs require(fs); const path require(path); const CONFIG_PATH path.join(__dirname, .., config.toml); const DEFAULT_CITY 北京; const TIMEOUT 10000; function loadApiKey() { const key process.env.TAOTOKEN_API_KEY; if (!key) { throw new Error(未找到 TAOTOKEN_API_KEY请先设置环境变量); } return key; } function fetchWeather(city) { return new Promise((resolve, reject) { const url https://wttr.in/${encodeURIComponent(city)}?formatj1; const req https.get(url, { timeout: TIMEOUT }, (res) { let data ; res.on(data, (chunk) (data chunk)); res.on(end, () { try { const json JSON.parse(data); const cur json.current_condition[0]; resolve({ temp: cur.temp_C, feelsLike: cur.FeelsLikeC, humidity: cur.humidity, wind: cur.windspeedKmph, description: cur.weatherDesc[0].value, }); } catch (e) { reject(new Error(JSON 解析失败 e.message)); } }); }); req.on(error, reject); req.on(timeout, () { req.destroy(); reject(new Error(请求超时)); }); }); } async function main() { const city process.argv[2] || DEFAULT_CITY; console.log(查询城市 city); try { loadApiKey(); const w await fetchWeather(city); console.log(温度${w.temp}°C); console.log(体感${w.feelsLike}°C); console.log(湿度${w.humidity}%); console.log(风力${w.wind} km/h); console.log(描述${w.description}); console.log(查询完成); } catch (e) { console.error(查询失败 e.message); process.exit(1); } } main().then(() process.exit(0));这段脚本里loadApiKey()是统一 Key 的落点。以后你新增别的 Skill只要复制这个函数Key 来源始终是同一个环境变量。4. 验证请求注册 Skill 并跑通首次调用4.1 本地直接运行先不经过 Agent直接跑脚本确认数据源和 Key 都没问题node scripts/main.js 上海预期输出查询城市上海 温度22°C 体感23°C 湿度80% 风力12 km/h 描述小雨 查询完成如果这一步就报 Key 缺失说明环境变量没生效回到 3.2 重新设置。4.2 重启 Openclaw 触发注册Skill 的元数据是在 Openclaw 启动时扫描的新增或修改_meta.json后必须重启openclaw restart重启后查看日志确认扫描到了新 Skill[skills] loaded: weather-query (triggers: 4)4.3 在对话中触发在 Openclaw 对话里输入“查询天气”命中触发词后 Agent 会调用scripts/main.js把结果返回。如果autoExecute为true直接出结果为false时会先问你确认。4.4 用模型对话验证 Key 链路如果你想单独确认 TaoToken 的 Key 在模型调用这一层是通的可以走模型对话入口做一次最小请求。这一步和 Skill 执行是两条链路Skill 负责业务动作模型对话负责验证 Key 和基址。两者都通整条调用链才算闭环。5. 本篇常见错排查5.1 Skill 不触发按顺序检查_meta.json里triggers是否拼写正确触发词是否和用户输入有大小写或空格差异autoExecute是否为true修改后是否重启了 OpenclawSkill 目录是否确实在skills/下。这五项里最常见的是忘记重启。5.2 脚本执行报错先看 Node 是否安装node -v。再看路径main字段是相对 Skill 目录的路径写错会找不到入口。权限不足在 Linux 下用chmod x scripts/main.js。环境变量没配会直接抛“未找到 TAOTOKEN_API_KEY”。5.3 Key 读取失败确认环境变量名和config.toml里的api_key_env完全一致。如果你在 IDE 里跑IDE 可能没继承终端的环境变量需要在运行配置里单独设置。用echo $TAOTOKEN_API_KEY先确认终端里能读到。5.4 请求超时数据源或模型接口超时先调大timeout_ms。如果是网络层问题检查是否能正常访问 API 基址。脚本里的TIMEOUT和config.toml的request_timeout_ms要匹配避免一个 10 秒一个 30 秒导致行为不一致。5.5 触发词误命中触发词太短比如只写“天气”容易在无关对话里被命中。改成“查询天气”“今天天气怎么样”这类具体短语3 到 5 个为宜。6. 把 Key 收敛成一份Skill 才能规模化第一个 Skill 跑通之后真正决定你后续效率的不是脚本写得多花哨而是 Key 和配置有没有收敛。我试过把每个 Skill 的模型配置各写一份结果换一次 Key 要改七八个文件还漏过一个导致线上报错。后来统一成config.toml加环境变量的模式新增 Skill 只复制骨架、改业务参数模型层完全不用动。如果你准备继续扩展下一步可以给weather-query加多城市批量查询或者把结果写进results/目录做历史记录。需要长期跑编码类或 Agent 类任务时可以了解 Coding Plan 的额度模式接入和排障过程中遇到 Key 或基址问题直接对照 API Keys 和接入文档排查最快。把这份骨架复制过去改掉城市名和触发词你的第二个 Skill 基本就是十分钟的事。 AI-Agent之Openclaw-Skills 开发指南：用 TaoToken 统一 Key 打通 Skills 调用链
1. 为什么你的 Openclaw Agent 需要一个能跑通的 SkillOpenclaw 的 Skills 机制本质上是给 AI Agent 装上一双能干活的手。大模型负责思考、决策、组织语言而 Skills 负责真正去执行——查天气、发请求、跑脚本、写文件、调接口。你如果只让 Agent 聊天它永远停在“说”的层面一旦挂上 Skill它就能从“说”跨到“做”。这篇面向的是需要为 AI-Agent 扩展自定义技能的开发者尤其是已经跑起 Openclaw、想加第一个自己的 Skill 却卡在目录结构、config.toml 骨架、Key 配置和调用验证这几步的人。我会用一个最小可运行的weather-querySkill 做贯穿示例从目录创建、_meta.json与SKILL.md编写、主脚本实现到用 TaoToken 统一 Key 打通模型调用链最后完成一次完整的注册与调用验证。目标很直接你复制配置、改掉城市名就能跑通首个自定义 Skill。很多人第一次写 Skill 会踩两个坑一是把 Skill 当成普通 Node 脚本写忽略了触发词和元数据注册二是每个 Skill 各自维护一份模型 Key散落在不同脚本里改一次要翻十个文件。TaoToken 在这里的价值就是把 Key 收敛成一份统一配置Skill 只关心业务逻辑模型调用走同一个入口。下面按可跟做的顺序展开。2. TaoToken 前置统一 Key 与接入信息在写 Skill 之前先把模型调用的“总闸”接好。TaoToken 提供统一的 API 入口你只需要在控制台生成一个 Key后续所有 Skill 里需要调用模型的地方都复用它不用每个 Skill 单独申请。你需要先拿到两样东西一个是 API Key一个是接入地址。地址分两种用途官网入口用于了解和控制台操作API 地址用于代码里实际请求。用途地址官网入口https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI 基址https://taotoken.net/api拿到 Key 的路径是进入控制台创建 API Key复制保存。这个 Key 后面会写进 Skill 的配置里或者更推荐的做法是写进环境变量Skill 运行时读取。注意Key 不要硬编码进会提交到 Git 的脚本里。用环境变量或本地 config 文件并在.gitignore里排除。如果你后续要做长期编码类或 Agent 类任务可以了解 Coding Plan如果只是想先验证模型对话是否通可以用模型对话页面快速试一次。这两个入口在排障阶段很有用但本篇主线还是把 Key 接进 Skill。3. 可复制配置目录结构、config.toml 与 Skill 骨架3.1 标准目录结构Openclaw 扫描 Skill 的默认路径是 workspace 下的skills/目录。每个 Skill 一个独立文件夹名称唯一内部结构如下workspace/skills/ └── weather-query/ ├── SKILL.md # 技能说明文档 ├── _meta.json # 元数据触发词、入口脚本 ├── config.toml # 本 Skill 的配置含模型 Key 引用 ├── scripts/ │ └── main.js # 主执行脚本 └── results/ # 输出结果目录可选先创建目录cd workspace/skills mkdir -p weather-query/scripts weather-query/results3.2 config.toml 骨架config.toml是这个 Skill 的本地配置。模型调用统一走 TaoToken所以这里只放基址和 Key 的引用不重复写业务参数。[skill] name weather-query version 1.0.0 enabled true [model] provider taotoken base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY model gpt-4o-mini timeout_ms 30000 [weather] default_city 北京 request_timeout_ms 10000这里的关键是api_key_env它指向环境变量名而不是把 Key 明文写进文件。运行时脚本读取process.env.TAOTOKEN_API_KEY即可。这样多个 Skill 共用同一个 Key改一处全局生效。设置环境变量Linux/macOSexport TAOTOKEN_API_KEY你的KeyWindows PowerShell$env:TAOTOKEN_API_KEY你的Key3.3 _meta.json 元数据_meta.json决定 Skill 怎么被识别和触发。触发词要具体避免太短导致误触发。{ name: weather-query, version: 1.0.0, description: 查询指定城市实时天气, main: scripts/main.js, triggers: [ 查询天气, 今天天气, 天气怎么样, 查天气 ], autoExecute: true }autoExecute为true时命中触发词直接执行涉及删除、发送等危险操作时建议设为false让 Agent 先确认。3.4 SKILL.md 说明文档--- name: weather-query description: 查询实时天气支持任意城市 --- # 天气查询技能 ## 功能 - 查询指定城市实时天气 - 显示温度、体感、湿度、风力 ## 使用方式 当用户说“查询天气”“今天天气”时自动执行。 ## 配置 模型调用走 TaoToken 统一 Key见 config.toml。3.5 主脚本 main.js脚本负责两件事读配置、调模型或调数据源、输出结果。下面这版把模型调用封装成统一函数Key 从环境变量取。#!/usr/bin/env node const https require(https); const fs require(fs); const path require(path); const CONFIG_PATH path.join(__dirname, .., config.toml); const DEFAULT_CITY 北京; const TIMEOUT 10000; function loadApiKey() { const key process.env.TAOTOKEN_API_KEY; if (!key) { throw new Error(未找到 TAOTOKEN_API_KEY请先设置环境变量); } return key; } function fetchWeather(city) { return new Promise((resolve, reject) { const url https://wttr.in/${encodeURIComponent(city)}?formatj1; const req https.get(url, { timeout: TIMEOUT }, (res) { let data ; res.on(data, (chunk) (data chunk)); res.on(end, () { try { const json JSON.parse(data); const cur json.current_condition[0]; resolve({ temp: cur.temp_C, feelsLike: cur.FeelsLikeC, humidity: cur.humidity, wind: cur.windspeedKmph, description: cur.weatherDesc[0].value, }); } catch (e) { reject(new Error(JSON 解析失败 e.message)); } }); }); req.on(error, reject); req.on(timeout, () { req.destroy(); reject(new Error(请求超时)); }); }); } async function main() { const city process.argv[2] || DEFAULT_CITY; console.log(查询城市 city); try { loadApiKey(); const w await fetchWeather(city); console.log(温度${w.temp}°C); console.log(体感${w.feelsLike}°C); console.log(湿度${w.humidity}%); console.log(风力${w.wind} km/h); console.log(描述${w.description}); console.log(查询完成); } catch (e) { console.error(查询失败 e.message); process.exit(1); } } main().then(() process.exit(0));这段脚本里loadApiKey()是统一 Key 的落点。以后你新增别的 Skill只要复制这个函数Key 来源始终是同一个环境变量。4. 验证请求注册 Skill 并跑通首次调用4.1 本地直接运行先不经过 Agent直接跑脚本确认数据源和 Key 都没问题node scripts/main.js 上海预期输出查询城市上海 温度22°C 体感23°C 湿度80% 风力12 km/h 描述小雨 查询完成如果这一步就报 Key 缺失说明环境变量没生效回到 3.2 重新设置。4.2 重启 Openclaw 触发注册Skill 的元数据是在 Openclaw 启动时扫描的新增或修改_meta.json后必须重启openclaw restart重启后查看日志确认扫描到了新 Skill[skills] loaded: weather-query (triggers: 4)4.3 在对话中触发在 Openclaw 对话里输入“查询天气”命中触发词后 Agent 会调用scripts/main.js把结果返回。如果autoExecute为true直接出结果为false时会先问你确认。4.4 用模型对话验证 Key 链路如果你想单独确认 TaoToken 的 Key 在模型调用这一层是通的可以走模型对话入口做一次最小请求。这一步和 Skill 执行是两条链路Skill 负责业务动作模型对话负责验证 Key 和基址。两者都通整条调用链才算闭环。5. 本篇常见错排查5.1 Skill 不触发按顺序检查_meta.json里triggers是否拼写正确触发词是否和用户输入有大小写或空格差异autoExecute是否为true修改后是否重启了 OpenclawSkill 目录是否确实在skills/下。这五项里最常见的是忘记重启。5.2 脚本执行报错先看 Node 是否安装node -v。再看路径main字段是相对 Skill 目录的路径写错会找不到入口。权限不足在 Linux 下用chmod x scripts/main.js。环境变量没配会直接抛“未找到 TAOTOKEN_API_KEY”。5.3 Key 读取失败确认环境变量名和config.toml里的api_key_env完全一致。如果你在 IDE 里跑IDE 可能没继承终端的环境变量需要在运行配置里单独设置。用echo $TAOTOKEN_API_KEY先确认终端里能读到。5.4 请求超时数据源或模型接口超时先调大timeout_ms。如果是网络层问题检查是否能正常访问 API 基址。脚本里的TIMEOUT和config.toml的request_timeout_ms要匹配避免一个 10 秒一个 30 秒导致行为不一致。5.5 触发词误命中触发词太短比如只写“天气”容易在无关对话里被命中。改成“查询天气”“今天天气怎么样”这类具体短语3 到 5 个为宜。6. 把 Key 收敛成一份Skill 才能规模化第一个 Skill 跑通之后真正决定你后续效率的不是脚本写得多花哨而是 Key 和配置有没有收敛。我试过把每个 Skill 的模型配置各写一份结果换一次 Key 要改七八个文件还漏过一个导致线上报错。后来统一成config.toml加环境变量的模式新增 Skill 只复制骨架、改业务参数模型层完全不用动。如果你准备继续扩展下一步可以给weather-query加多城市批量查询或者把结果写进results/目录做历史记录。需要长期跑编码类或 Agent 类任务时可以了解 Coding Plan 的额度模式接入和排障过程中遇到 Key 或基址问题直接对照 API Keys 和接入文档排查最快。把这份骨架复制过去改掉城市名和触发词你的第二个 Skill 基本就是十分钟的事。