1. 为什么你的 AI 数字员工需要“技能插件”OpenClaw 是一个能动手干活的 AI 数字员工框架它和普通对话模型的区别在于模型负责理解意图插件负责真正执行。你可以把它理解成一台可扩展的机器人大脑是接入的大模型手脚就是一个个技能插件。没有插件它只能聊天装上插件它才能查数据、调接口、跑脚本、操作文件。这篇内容聚焦一个最小闭环用SKILL.md声明技能元信息用index.js实现执行逻辑30 分钟内让一个自定义技能在本地被加载、被触发、被验证。适合已经装好 OpenClaw、想给数字员工加新能力的开发者也适合刚接触插件机制、想先跑通一个能用的例子再深入的人。我试过从零搭一个“查天气”技能踩过几个典型坑比如插件目录放错、SKILL.md字段写错导致技能不注册、index.js导出方式不对导致调用无响应。下面把可复制的目录骨架、字段模板、入口示例和验证动作一次讲清楚你照着做就能跑通。2. TaoToken 前置给插件一个稳定的模型调用入口插件本身是执行逻辑但 OpenClaw 在解析用户意图、决定调用哪个技能时仍然需要模型能力。也就是说你的数字员工要“听懂”用户说“帮我查北京明天天气”背后得有一次模型推理。如果模型调用不稳定插件再对也触发不了。TaoToken 在这里的角色是提供统一的模型接入入口。你可以在 TaoToken 控制台创建 API Key然后把 OpenClaw 的模型请求指向 TaoToken 的 API 地址。这样插件开发阶段不用来回切换多个模型供应商调试意图解析时也更省心。具体操作路径打开控制台创建密钥https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite查看接入文档确认请求格式https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteAPI 基础地址使用https://taotoken.net/api注意API 地址不要加 UTM 参数保持干净的基础路径即可。控制台和文档链接带 UTM 是为了区分来源不影响功能。如果你还没创建 Key先去 API Keys 页面生成一个复制保存好。后面在 OpenClaw 的模型配置里会用到。插件开发本身不直接依赖 TaoToken但技能触发依赖模型解析所以这一步是前置条件。3. 可复制配置插件目录骨架与两个核心文件OpenClaw 的技能插件遵循一个很轻的约定一个文件夹就是一个技能文件夹名建议用英文短横线命名比如weather-query。文件夹里至少要有两个文件skills/ └── weather-query/ ├── SKILL.md └── index.jsSKILL.md是技能的“身份证”告诉 OpenClaw 这个技能叫什么、能做什么、需要什么环境变量、是否允许用户直接调用。index.js是执行入口负责接收参数、调用外部接口、返回结果。3.1 SKILL.md 字段模板下面是一个可直接改用的模板字段含义我逐条标注--- name: weather-query description: 自然语言查询城市天气支持今日、明日、近3天 metadata: {openclaw:{emoji:,requires:{env:[WEATHER_API_KEY],os:[darwin,linux,win32]}}} user-invocable: true --- # 天气查询技能 ## 功能说明 支持用户用自然语言查询任意城市的天气自动解析城市名和时间范围调用公共天气接口返回结果。 ## 使用方法 用户可以直接说 - 帮我查上海今天的天气 - 北京明天会下雨吗 - 广州近3天天气怎么样 ## 实现逻辑 1. 从用户指令中提取城市和时间 2. 读取环境变量中的天气 API 密钥 3. 调用天气接口获取数据 4. 格式化结果返回给用户关键字段解释name是技能唯一标识不能和其他技能重复。description会参与模型匹配写得越清楚模型越容易在合适的时候选中它。metadata里的requires.env声明依赖的环境变量OpenClaw 启动时会检查缺失会提示。user-invocable: true表示用户可以直接用自然语言触发设为false则只能由模型内部调用。3.2 index.js 入口示例在同一个文件夹里新建index.js内容如下const { tool, parseUserIntent } require(openclaw-sdk); tool.register(weather-query, async (params) { try { const { city, time 今日 } parseUserIntent(params.content, { city: { type: city, required: true }, time: { type: enum, options: [今日, 明日, 近3天] } }); const apiKey process.env.WEATHER_API_KEY; if (!apiKey) { return 请先在环境变量中配置 WEATHER_API_KEY; } const response await fetch( https://api.openweathermap.org/data/2.5/weather?q${city}appid${apiKey}unitsmetriclangzh_cn ); const data await response.json(); return ${city}${time}天气${data.weather[0].description}温度${data.main.temp}℃湿度${data.main.humidity}%; } catch (error) { return 查询失败${error.message}请检查城市名或 API 密钥; } });这段代码做了四件事注册技能名、解析用户意图、读取环境变量、调用接口并返回格式化结果。parseUserIntent是 OpenClaw SDK 提供的意图解析工具你只需要声明参数类型它会结合模型能力从自然语言里抽取。3.3 环境变量配置在工作区根目录的.env文件里加上WEATHER_API_KEY你的天气接口密钥天气接口密钥可以去 OpenWeatherMap 免费申请。如果你暂时不想申请也可以把index.js里的接口换成任意返回 JSON 的公共接口先验证插件机制跑通。4. 验证请求加载插件、触发技能、查看日志配置写完后按下面顺序验证。第一步确认插件目录位置正确。OpenClaw 默认扫描工作区下的skills/目录所以你的路径应该是你的工作区/skills/weather-query/SKILL.md 你的工作区/skills/weather-query/index.js第二步重启 OpenClaw 网关让插件生效openclaw restart第三步查看技能是否被识别。可以执行openclaw skills list如果输出里出现weather-query说明SKILL.md解析成功。如果没有出现优先检查name字段是否有拼写错误、文件是否放在skills/下、SKILL.md的 frontmatter 是否用---正确包裹。第四步在对话界面输入帮我查北京明天的天气预期结果是返回一段包含城市、天气描述、温度、湿度的文本。如果返回的是“请先配置 WEATHER_API_KEY”说明环境变量没被读取检查.env文件位置和变量名是否一致。第五步查看日志确认调用链openclaw logs --tail 50日志里应该能看到技能被匹配、index.js被调用、接口请求发出的记录。如果技能没被匹配日志里通常会有意图解析的结果可以据此调整description的写法。5. 本篇常见错排查插件不生效skills list里没有。最常见原因是目录层级不对。必须是工作区/skills/技能名/不能多一层也不能少一层。另一个原因是SKILL.md的 frontmatter 格式错误比如---前后有空格、字段缩进不对。技能被识别但触发不了。检查user-invocable是否为true。如果设为false用户直接说自然语言不会触发只能由模型在内部决策时调用。另外description写得太模糊也会导致模型匹配不上建议把典型用户说法写进去。index.js报模块找不到。确认openclaw-sdk是 OpenClaw 原生提供的不需要额外npm install。如果你在插件目录里单独跑了node index.js会因为缺少运行环境而报错正确做法是通过 OpenClaw 网关加载。环境变量读取不到。.env文件要放在工作区根目录不是插件目录里。变量名要和SKILL.md里requires.env声明的一致大小写敏感。改了代码不生效。OpenClaw 默认不会热重载插件改完index.js或SKILL.md后需要openclaw restart。部分版本支持技能监视器可以在配置里开启自动刷新但初次调试建议手动重启避免缓存干扰。接口返回 401 或 403。天气接口密钥无效或未激活。OpenWeatherMap 新注册的 Key 有时需要等几分钟才生效。另外确认请求用的是 HTTPS明文 HTTP 会被拒绝。6. 下一步把插件接入你的模型调用链插件跑通后你可以继续扩展更多技能比如文件操作、日程查询、内部 API 调用。每个技能都遵循同样的结构SKILL.md声明元信息index.js实现逻辑。技能越多你的 AI 数字员工能做的事就越多。如果你在调试意图解析时发现模型响应慢或不稳定可以把 OpenClaw 的模型请求切到 TaoToken 的 API 地址用同一个 Key 管理多个模型的调用。需要长期跑编码类或 Agent 类任务的话可以看看 Coding Plan 的额度方案https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite想先验证模型对话是否通畅可以直接在模型对话页测试https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite接入文档里有完整的请求示例和参数说明排障时对照看更快https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite插件开发的核心不是写多少代码而是把“声明”和“执行”分开SKILL.md负责让模型知道什么时候用index.js负责真正干活。这个最小闭环跑通一次后面加技能就是复制文件夹、改字段、换逻辑的事。