1. 手动装 skill 到底在解决什么问题OpenClaw 的 skill 机制本质上是一套「能力插件」核心运行时只负责调度、会话和模型调用具体能干什么——读本地文件、查数据库、调外部接口、跑一段脚本——都交给 skill 来扩展。官方市场里能一键装的那些当然方便但真实开发场景里你经常遇到的是内网机器出不去、公司网络只放行特定域名、某个 skill 是同事私下改过的版本、或者你想把一个内部脚本包装成 skill 自己用。这时候「手动安装」就不是可选项而是唯一路径。手动安装 skill 这件事说穿了就三件事把文件放到对的目录、让 OpenClaw 知道它的存在、确认它真的能被加载并调用。听起来简单但坑基本都集中在第二步和第三步——目录放错了不报错、依赖没声明清楚加载时静默失败、模型通道没配好 skill 跑起来调不通。这篇就按「目录结构 → 依赖声明 → 本地加载 → 通道配置 → 验证 → 排障」的顺序把每一步拆到能直接复制执行。适合读这篇的人需要在离线或受限网络环境下扩展 OpenClaw 能力的开发者手里已经有一个 skill 包自己写的或别人给的想把它挂到本地 OpenClaw 上跑起来以及已经装上了但调用时报错、想搞清楚到底哪一环断了的人。全文以 Windows 路径为主macOS/Linux 的差异我会在对应位置标出来逻辑完全一致。先明确一个前提OpenClaw 的 skill 目录默认在用户主目录下的.openclaw/skills。Windows 是C:\Users\用户名\.openclaw\skillsmacOS/Linux 是~/.openclaw/skills。这个路径是后面所有操作的基准记不住没关系下面会给校验命令。2. TaoToken 前置把模型通道先打通skill 装好了不代表能跑。绝大多数 skill 在执行过程中都要调用大模型——做意图识别、生成参数、总结结果。如果你的模型通道没配好skill 加载成功但一调用就报 401 或者连接失败你会误以为是 skill 本身有问题白白排查半天。所以我的建议是装 skill 之前先把模型通道配通。TaoToken 在这里的角色是统一入口你不需要为每个 skill 单独去配不同厂商的 Key而是通过一个 Base URL 加一个 Key让 OpenClaw 里所有需要模型调用的 skill 都走同一条通道。这对多 skill 场景特别省事——换模型、换额度、加限制只改一处。你需要准备两样东西一个 API Key以及确认要用的模型 ID。Key 在控制台的 API Keys 页面创建地址是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。创建后复制出来注意它通常只完整显示一次。模型 ID 这块OpenClaw 的 skill 一般会在自己的配置里声明默认模型你也可以在全局配置里覆盖。常见的选择是 Claude 系列用于需要长上下文和工具调用的 skill或者按 skill 文档指定的模型来。拿不准用哪个可以先去模型对话页面实际发一条消息确认通道和模型都正常https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。这里有个关键点要提前说清楚OpenClaw 的模型配置里Base URL 填的是https://taotoken.net/api注意结尾不带斜杠也不要加任何多余路径。很多 401 和 404 就是因为这里多写了一段或者少写了一段。Key 就是刚才创建的那串Model ID 填你要用的模型标识。这三件套Base URL Key Model ID在后面配置 skill 时会反复出现先记住。如果你打算长期跑编码类或 Agent 类 skill调用量会比较大可以考虑 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 。3. 可复制配置skill 目录模板与加载声明现在进入正题。一个能被 OpenClaw 正确加载的 skill目录结构是有约定的。下面这个模板你可以直接复制把名字和内容换成自己的。.openclaw/ └── skills/ └── my-first-skill/ ├── skill.json # 必需skill 元信息与依赖声明 ├── index.js # 入口文件按 skill.json 里的 entry 指定 ├── package.json # 可选Node 依赖 └── README.md # 可选说明文档skill.json是核心OpenClaw 靠它识别这个目录是不是一个合法 skill。一个最小可用的声明长这样{ name: my-first-skill, version: 1.0.0, description: 一个用于演示手动安装的最小 skill, entry: index.js, runtime: node, model: { provider: openai-compatible, baseUrl: https://taotoken.net/api, apiKeyEnv: TAOTOKEN_API_KEY, modelId: claude-sonnet-4-5 }, permissions: [fs.read], triggers: [demo, 示例] }几个字段值得单独说。entry指向入口文件路径是相对 skill 目录的别写成绝对路径。runtime目前常见的是node如果你的 skill 是 Python 写的这里要按 OpenClaw 支持的运行时填。model块是重点baseUrl固定填https://taotoken.net/apiapiKeyEnv表示从环境变量读 Key而不是把 Key 硬编码进文件——这一点很重要硬编码的 Key 一旦提交到仓库就是事故。modelId填你实际要用的模型。环境变量怎么设Windows 下用 PowerShell$env:TAOTOKEN_API_KEY 你的Key想永久生效就写进用户环境变量[Environment]::SetEnvironmentVariable(TAOTOKEN_API_KEY, 你的Key, User)macOS/Linux 写进~/.bashrc或~/.zshrcexport TAOTOKEN_API_KEY你的Key如果你更习惯用 TOML 做全局配置OpenClaw 的全局配置文件通常在~/.openclaw/config.toml可以这样写[model] provider openai-compatible base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY model_id claude-sonnet-4-5 [skills] dir ~/.openclaw/skills auto_load true注意base_url这里同样不带结尾斜杠。auto_load true表示启动时自动扫描 skills 目录手动安装的 skill 放进去就能被识别不用额外注册命令。把 skill 目录整个复制到C:\Users\用户名\.openclaw\skills\下面。复制完先确认目录结构对dir $env:USERPROFILE\.openclaw\skills\my-first-skill应该能看到skill.json和index.js。如果skill.json在更深一层比如多套了一个同名文件夹OpenClaw 是扫不到的这是新手最常见的错误之一。4. 验证请求确认 skill 真的被加载文件放好了接下来要验证它是不是真的被 OpenClaw 加载了。分两步先看加载日志再实际调用一次。启动 OpenClaw 时留意输出正常加载会打印类似loaded skill: my-first-skill的日志。如果没看到说明扫描没命中回到上一步检查目录层级和skill.json是否合法。skill.json里任何一个字段写错比如 JSON 语法错误、少了逗号整个 skill 会被跳过而且不一定有明显报错所以建议用工具校验一下node -e JSON.parse(require(fs).readFileSync(skill.json,utf8)); console.log(JSON OK)在 skill 目录下执行输出JSON OK就说明格式没问题。加载确认后实际调用一次。OpenClaw 里触发 skill 一般通过对话里的关键词对应skill.json里的triggers。比如我配了demo就在会话里发一条包含demo的消息。如果 skill 内部要调模型这一步会真正走 TaoToken 通道。调用成功你会看到 skill 返回的结果如果 skill 里有日志也能看到它请求模型的过程。想更直接地验证模型通道本身通不通可以单独发一个请求curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-5, messages: [{role: user, content: ping}] }返回里有正常的choices结构说明 Key、Base URL、模型 ID 三件套都对。这一步能过skill 里调模型基本不会因为通道问题失败。Windows PowerShell 里curl是Invoke-WebRequest的别名建议直接用 Git Bash 或者改用curl.exe执行上面的命令。实测下来把「通道验证」和「skill 加载验证」分开做排障效率会高很多——出问题时你能立刻判断是通道断了还是 skill 本身没加载不用两头猜。5. 本篇常见错排查手动装 skill 报的错就那么几类对照着看基本能定位。401 UnauthorizedKey 不对或没读到。先确认环境变量在当前终端里真的存在echo $env:TAOTOKEN_API_KEYPowerShell或echo $TAOTOKEN_API_KEYbash。如果为空说明设了但没生效——永久环境变量设完要重开终端。如果 Key 有值还报 401检查是不是复制时带了空格或换行重新从控制台复制一次。local proxy failed / connection refused这类错误通常不是 Key 的问题而是 Base URL 写错或网络到不了。确认baseUrl是https://taotoken.net/api没有多余路径、没有结尾斜杠。如果你在受限网络里确认该域名在放行列表内。reading choices of undefined这个报错说明请求发出去了但返回结构里没有choices多半是模型 ID 写错或者返回的是一段错误信息被当成了正常响应。回到第 4 节的 curl 命令把model换成你配置里的modelId单独跑一次看返回体到底是什么。模型 ID 拼错、大小写不对都会触发这个。OAuth 相关报错如果你用的是 Claude Code 这类带 OAuth 流程的工具报 OAuth 失败通常是认证方式没选对。走 TaoToken 通道时应该用 API Key 方式而不是 OAuth 登录方式。检查配置里是不是残留了 OAuth 的字段把它去掉改用apiKeyEnv指向环境变量。skill 加载了但触发不了检查triggers里的关键词和你实际输入的是否匹配大小写敏感的话要对上。另外确认auto_load是true或者你手动执行了注册命令。依赖缺失导致 skill 静默失败如果 skill 有package.json进到 skill 目录执行npm install。Node 依赖没装入口文件require时会抛错但有些情况下错误被吞掉表现为 skill「加载了但不干活」。排查时记住一个顺序先 curl 验通道再看加载日志最后看 skill 内部日志。这个顺序能帮你快速缩小范围。6. 把通道和 skill 一起管起来手动安装 skill 这件事真正花时间的从来不是复制文件而是让「skill 能加载」和「模型能调通」这两件事同时成立。我的做法是把模型通道的配置集中在一处——环境变量加全局config.tomlskill 自己的skill.json只引用环境变量名不写死任何 Key。这样你装十个 skill通道配置还是那一份换模型、换额度只改一个地方。对于需要长期跑、调用量大的 skill用 Coding Plan 会比按量更省心额度稳定适合 Agent 类持续调用https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。Key 的管理和创建都在控制台https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。接入细节和字段说明以文档为准https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。最后留一个我踩过的坑skill 目录名和skill.json里的name最好保持一致。不一致时 OpenClaw 有时能加载但日志和触发会混乱排查起来很费劲。装完第一个 skill 后先别急着装第二个把加载和调用完整跑通一遍后面就是复制粘贴的事了。