1. 从“能聊天”到“能干活”OpenClaw 技能扩展到底解决什么问题很多人第一次用 OpenClaw会觉得它跟普通对话工具差不多能读文件、能跑命令、能查网页但也就那样。真正让它从“会聊天的助手”变成“能替你干活的自动化平台”的是 Skill 技能扩展机制。你可以把 OpenClaw 本体理解成一部刚出厂的手机系统自带电话、短信、相机而 Skill 就是你后来装上去的 AppClawdHub 则是那个应用商店。手机能不能变成生产力工具取决于你装了什么 App。这篇是 OpenClaw 系列的第八篇聚焦一条完整链路从 ClawdHub 拉取现成 Skill到按规范写一个自定义 Skill再到本地调试、验证它是否被正确加载执行。中间会顺带把模型调用通道配好——因为 Skill 里只要涉及“让模型判断一下再决定调哪个工具”就需要一个稳定的 API 入口。我用的是 TaoToken 的统一 Key 通道一个 Key 走通对话和编码类模型省得在多个平台之间来回切。适合谁看已经装好 OpenClaw、能跑通基础对话但还没碰过 Skill 目录的人想给团队做内部专属能力比如读内部表格、发通知、调内部接口的开发者以及被“技能不生效”“装完没反应”折腾过的新手。整篇按可跟做的步骤写命令、目录结构、manifest 配置都会给全你照着敲就能跑出结果。先说清楚一个概念边界避免后面混淆。OpenClaw 里的 Skill 不是那种重量级插件框架它极度轻量一个入口文件加一份描述配置就能跑。它的价值在于把“一段确定性逻辑”包装成模型可以主动调用的能力。模型负责理解你要干什么Skill 负责真正执行。两者配合才有“一句话触发自动化”的效果。我实测下来最容易卡住新手的不是写代码而是三件事Skill 放错目录导致根本没被扫描到manifest 里字段写错导致加载报错但提示不明显Skill 内部要调模型时API 配置散落在各处导致 401。这篇会把这三个坑都填上。2. TaoToken 前置准备给 Skill 一个统一的模型调用入口在写 Skill 之前先把模型通道准备好。原因很简单很多 Skill 不是纯本地逻辑它需要“让模型先理解再执行”。比如一个“智能日报”Skill得先让模型把零散记录整理成结构化内容再调用发送接口。如果每个 Skill 各自配一套 API Key维护起来会非常痛苦。统一走 TaoToken 的 Key是最省事的做法。TaoToken 在这里扮演的角色是“统一模型接入层”。你拿到一个 Key就能通过兼容接口调用多种模型对话类、编码类都能覆盖。对 OpenClaw 这种需要频繁调用模型的场景来说好处是配置只写一份Skill 里引用同一个环境变量即可。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 注意 API 地址后面不加任何查询参数。第一步去控制台创建 Key。打开 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 登录后在 API Keys 页面新建一个密钥。建议按用途命名比如openclaw-skill方便以后区分。创建后立刻复制保存页面刷新后就看不到完整 Key 了。第二步把 Key 写进环境变量而不是硬编码进 Skill 代码。这是安全底线也是后面排障时能快速定位问题的前提。Linux/macOS 下编辑 shell 配置# 写入 ~/.bashrc 或 ~/.zshrc export TAOTOKEN_API_KEYsk-你的实际Key export TAOTOKEN_BASE_URLhttps://taotoken.net/apiWindows PowerShell 用setx TAOTOKEN_API_KEY sk-你的实际Key setx TAOTOKEN_BASE_URL https://taotoken.net/api改完记得重开终端或者source ~/.zshrc让变量生效。验证一下echo $TAOTOKEN_BASE_URL # 应输出 https://taotoken.net/api第三步确认 OpenClaw 的模型配置指向这个通道。OpenClaw 的模型配置通常在项目根目录的配置文件里找到模型相关段落把 base URL 和 Key 引用改成环境变量。不同版本字段名略有差异核心是三项Base URL、API Key、Model ID。这三件套必须齐全缺一个就会在调用时报错。注意不要把 Key 提交到 Git 仓库。如果你在团队里共享 OpenClaw 配置用.env文件并把它加进.gitignore或者用密钥管理服务注入环境变量。配好之后建议先用一次最简单的模型对话验证通道是否通。打开 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 在页面里发一条测试消息能正常返回就说明 Key 和通道没问题。这一步别跳过否则后面 Skill 报错时你分不清是 Skill 的问题还是通道的问题。3. 可复制配置ClawdHub 安装命令与自定义 Skill 目录结构这一节是整篇的核心操作区。先讲从 ClawdHub 拉现成 Skill再讲自己写一个最后给出可直接复制的 manifest 配置片段。3.1 从 ClawdHub 安装现成 SkillOpenClaw 内置了技能管理命令不需要你手动下载解压。先列出 ClawdHub 上可用的技能npm run skill:list这条命令会拉取远程技能索引并打印列表包含技能名、版本、简介。找到你想要的比如一个通知类技能直接安装npm run skill:install feishu-notifier安装完成后查看已装列表npm run skill:list --installed卸载和更新分别是npm run skill:uninstall feishu-notifier npm run skill:update安装类操作完成后新技能一般会被自动扫描到不需要重启。但如果你改了技能目录结构或 manifest重启一次更稳妥。3.2 自定义 Skill 的目录结构自定义 Skill 放在项目根目录的skills/下每个技能一个独立文件夹。标准结构如下skills/ └── my-custom-skill/ ├── index.js # 技能入口导出 run 方法 ├── manifest.json # 技能描述与参数声明 ├── config.json # 可选运行时配置 └── README.md # 可选说明文档manifest.json是模型识别技能的关键字段写错会导致技能加载失败或模型无法正确调用。一个可复制的最小 manifest{ name: my-custom-skill, version: 1.0.0, description: 读取指定 CSV 文件并统计行数返回摘要, entry: index.js, parameters: { type: object, properties: { filePath: { type: string, description: CSV 文件的相对路径 } }, required: [filePath] } }parameters用的是 JSON Schema 风格模型会根据这里的描述决定传什么参数。描述写得越清楚模型调用越准。比如你把filePath描述成“CSV 文件的相对路径”模型就不会传一个不存在的绝对路径进来。3.3 技能入口代码index.js导出一个对象核心是run方法// skills/my-custom-skill/index.js const fs require(fs); const path require(path); module.exports { name: my-custom-skill, description: 读取 CSV 并统计行数, version: 1.0.0, async run({ args }) { const filePath args.filePath; const abs path.resolve(process.cwd(), filePath); if (!fs.existsSync(abs)) { return 文件不存在${filePath}; } const content fs.readFileSync(abs, utf-8); const lines content.split(\n).filter(Boolean); return 文件 ${filePath} 共 ${lines.length} 行含表头。; } };如果技能内部需要调用模型比如做内容总结就在run里用环境变量里的 Key 发起请求async run({ args }) { const resp await fetch(${process.env.TAOTOKEN_BASE_URL}/v1/chat/completions, { method: POST, headers: { Content-Type: application/json, Authorization: Bearer ${process.env.TAOTOKEN_API_KEY} }, body: JSON.stringify({ model: 你的模型ID, messages: [{ role: user, content: 总结以下内容${args.text} }] }) }); const data await resp.json(); return data.choices[0].message.content; }注意这里 Base URL 和 Key 都从环境变量读跟第二节配的完全一致。这样无论你有多少个 Skill模型通道只有一份配置。3.4 本地调试写完放进skills/后重启 OpenClaw 触发扫描。然后直接在对话里触发调用 my-custom-skill读取 data/user.csv如果模型正确识别并执行你会看到返回的行数统计。如果没反应先看日志目录logs/OpenClaw 会把加载错误和调用错误分开记录定位起来比盲猜快得多。4. 验证请求一次真实触发确认 Skill 被正确加载与执行配置写完不验证等于没写。这一节用一次完整触发把“加载—识别—执行—返回”四个环节都走一遍并给出成功结果的判断标准。先确认技能已被扫描到。重启 OpenClaw 后在对话里问一句现在有哪些可用的技能正常情况下模型会列出已安装技能包括你刚写的my-custom-skill。如果列表里没有它说明扫描没通过直接跳到第五节排障。接着做真实触发。准备一个测试文件mkdir -p data printf name,age\nAlice,30\nBob,25\n data/user.csv然后在对话里输入调用 my-custom-skill读取 data/user.csv预期返回文件 data/user.csv 共 3 行含表头。看到这个结果说明四件事都对了manifest 被正确解析、模型识别到了技能、参数传递正确、run方法执行成功。如果返回的是“文件不存在”检查你运行 OpenClaw 的工作目录是不是项目根目录因为代码里用的是process.cwd()。再验证一个带模型调用的技能。假设你写了一个总结技能触发调用 summarize-skill把 data/user.csv 的内容总结成一句话如果返回了模型生成的摘要说明 TaoToken 通道也通了。这一步同时验证了 Skill 机制和模型通道是最有价值的端到端测试。提示验证阶段建议把日志级别调成 debug这样能看到模型决定调用哪个技能的中间过程。很多“技能不生效”其实是模型没选中它而不是技能本身有问题。成功结果的判断标准可以记一下技能列表里能看到它、触发后返回符合预期的内容、日志里没有加载错误。三条都满足才算真正跑通。只满足第一条说明只是被扫描到但调用失败只满足后两条但列表里没有可能是缓存问题重启即可。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth排障这部分按真实报错来每个都给出原因和修法。这些是我在配 Skill TaoToken 通道时实际遇到过的按出现频率排序。401 Unauthorized。最常见几乎都是 Key 的问题。三种可能环境变量没生效、Key 复制时带了空格、Key 被撤销。先验证echo $TAOTOKEN_API_KEY如果输出为空说明变量没加载重开终端或 source 配置。如果输出正常但请求仍 401检查代码里是不是把Bearer拼错了或者 Base URL 写成了带路径的地址。正确组合是 Base URL 为https://taotoken.net/api请求路径为/v1/chat/completionsHeader 为Authorization: Bearer sk-xxx。三件套Base URL Key Model ID缺一不可Model ID 写错有时也会返回鉴权类错误别只盯着 Key。local proxy failed。这个报错通常出现在 OpenClaw 尝试通过本地代理转发请求时。原因一般是代理配置残留或者环境变量里设置了HTTP_PROXY/HTTPS_PROXY指向一个已经失效的地址。检查env | grep -i proxy如果有输出且地址不可用清掉这些变量再试。OpenClaw 直连 TaoToken 通道即可不需要额外代理层。reading choices。典型报错是Cannot read properties of undefined (reading choices)。这说明请求返回的结构里没有choices字段代码却直接取了data.choices[0]。原因通常是请求根本没成功返回的是错误对象或者返回体不是预期的 JSON 结构。修法是先打印完整响应再取字段const data await resp.json(); if (!data.choices) { return 模型返回异常${JSON.stringify(data)}; } return data.choices[0].message.content;这样报错信息会直接告诉你服务端返回了什么比盲猜快得多。OAuth 相关报错。如果你在 OpenClaw 里配了需要 OAuth 的模型通道又同时用 Key 方式接 TaoToken可能会冲突。表现是提示 token 过期或授权失败。处理方式是明确区分Skill 内部调用统一走 Key 方式不要混用 OAuth 流程。检查配置文件里是否有残留的 OAuth 字段清掉后重启。技能加载了但模型不调用。这不是报错但很常见。原因是 manifest 里的description写得太模糊模型判断不出什么时候该用它。把描述改具体比如把“处理文件”改成“读取指定 CSV 文件并统计行数”命中率会明显提升。CC Switch / Cline MCP / Codex auth.json 场景。如果你在 OpenClaw 之外还用这些工具配置逻辑是一样的三件套Base URL、Key、Model ID。以 Codex 的auth.json为例确保里面的 base URL 指向https://taotoken.net/apiKey 与环境变量一致Model ID 填你实际要用的模型。三处不一致是这类工具报错的头号原因。排障时记住一个原则先确认通道通不通用模型对话页面测再确认技能加载没加载看技能列表最后确认模型选没选中技能看 debug 日志。按这个顺序90% 的问题能快速定位。6. 把 Skill 用起来从单点能力到可持续扩展的工作流走到这里你已经能装技能、写技能、验证技能、排错了。最后聊点实际用法帮你把这套机制变成日常能依赖的东西。第一从“高频重复动作”入手写第一个自定义 Skill。别一上来就搞复杂系统先挑一个你每天都要做、步骤固定的小事比如“把某个目录下的日志按日期归档”“把固定格式的表格转成 JSON”。这类逻辑确定、不需要模型判断的写成 Skill 最稳也最容易验证成功。跑通一个你对整套机制的手感就建立了。第二涉及模型判断的 Skill把 prompt 写进技能内部而不是让用户每次输入。比如一个“智能分类”Skill分类规则和输出格式应该固化在代码里用户只需要传待分类的内容。这样触发时更稳定也避免每次都要重复描述需求。第三统一模型通道的价值会随着 Skill 数量增加而放大。你写的 Skill 越多越不想在每个里面重复配 Key。用 TaoToken 一个 Key 覆盖对话和编码类模型新增 Skill 时只引用环境变量维护成本几乎为零。需要长期跑编码类或 Agent 类任务的话可以了解下 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 按用量规划比零散调用更可控。第四给技能写 README。不是为了别人是为了三个月后的你自己。写清楚这个技能干什么、参数怎么传、依赖什么环境变量、失败时看哪里。技能多了之后这份文档就是你的索引。第五调试期善用日志。OpenClaw 的logs/目录把加载错误和运行错误分开记录遇到问题先看日志再改代码比反复重启试错高效得多。我踩过的坑里有一半是没看日志直接猜结果绕了远路。如果你还没拿到 Key先去控制台建一个https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。接入细节和字段说明看文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。想先感受模型通道是否顺畅直接去模型对话页面发一条消息https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。Claude Code 相关的接入配置可以参考https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaude-code-anthropicutm_campaignrewrite 。技能扩展这件事真正的门槛不在写代码而在“想清楚要自动化什么”。想清楚了剩下的就是照这篇的目录结构、manifest 和验证步骤走一遍。跑通第一个后面就是复制和迭代。