★ FEATURED ARTICLE 1. 为什么你的 OpenClaw 装完还是“裸机”Skills 安装到底卡在哪很多人第一次接触 OpenClaw会默认它像普通命令行工具一样装完就自带全部能力。实际跑起来才发现它更像一个刚刷完系统的手机系统有了但日历、天气、邮件这些 App 还得自己装。OpenClaw 里这些“App”就叫 Skills而 ClawHub 就是它的应用商店。你从 ClawHub 拉取 Skills 到本地调试的完整流程正是这篇要讲清楚的事。Skills 是什么一句话它是 OpenClaw 的功能扩展包。一个 Skill 通常是一个包含SKILL.md的目录里面声明了这个技能能做什么、需要哪些依赖、暴露哪些命令。OpenClaw 启动时会扫描技能目录把满足条件的 Skill 注册进当前会话。适合谁适合所有想让 OpenClaw 从“能聊天”变成“能干活”的人尤其是需要日历管理、天气查询、邮件收发、图片处理这类具体任务的用户。我见过最常见的误区有三个。第一以为clawhub install完就立刻生效结果在旧会话里怎么试都没反应。第二不知道 Skills 有“工作区级”和“全局级”两种安装位置复制错目录导致只有某个项目能用。第三遇到缺少环境变量或外部命令时直接放弃其实openclaw skills check已经把缺什么列得明明白白。这篇的路径是这样先确认 OpenClaw 和 Node 环境再装 ClawHub 命令行工具接着搜索、安装、重启会话验证最后处理依赖和配置。每一步都给可复制的命令和预期输出你照着敲就能在本地跑通第一个自定义 Skill。如果你还没配好模型侧可以先用 TaoToken 模型对话 验证请求链路再回来装 Skills两边互不干扰。需要提前说明的是Skills 的安装和模型调用是两条线。Skills 决定 OpenClaw“会做什么”模型决定它“怎么想”。所以哪怕你 Skills 装得再全模型 Key 没配好任务照样跑不动。反过来模型通了但 Skills 没装它就只会空谈。把这两件事分开排查能省掉大量来回试错的时间。2. 装 Skills 前先把地基打好OpenClaw 环境与 ClawHub 工具准备在从 ClawHub 拉取任何 Skill 之前先确认三件事OpenClaw 本体能跑、Node 版本够、ClawHub 命令行工具装得上。这三步任何一步出问题后面都会以奇怪报错的形式冒出来所以值得花五分钟确认。先看 OpenClaw 是否可用。打开终端执行openclaw --version正常会输出版本号比如1.0.x。如果提示command not found说明 OpenClaw 没装或没进 PATH。Skills 是 OpenClaw 的子命令体系本体不在后面全免谈。再看 Node 和包管理器。ClawHub 是通过 npm 或 pnpm 全局安装的Node 版本建议 18 以上node -v npm -v如果node -v低于 18先升级 Node。用 nvm 的话nvm install 20 nvm use 20接着装 ClawHub 命令行工具二选一即可# 使用 npm 安装推荐 npm i -g clawhub # 或使用 pnpm 安装 pnpm add -g clawhub装完验证clawhub --version如果提示权限不足EACCESMac/Linux 在命令前加sudoWindows 用管理员身份打开终端。但更推荐的做法是配置 npm 全局目录避免每次都 sudonpm config set prefix ~/.npm-global export PATH~/.npm-global/bin:$PATH把上面这行export写进~/.zshrc或~/.bashrc以后新开终端都生效。这里插一句模型侧的准备。Skills 跑起来后往往要调用模型如果你还没配好接入点可以先去 TaoToken API Keys 拿一个 KeyBase URL 用https://taotoken.net/api。这一步不是 Skills 安装的必需项但能让你在验证 Skill 时少一个变量。配置方式在 OpenClaw 里通常是写进~/.openclaw/openclaw.json后面配置章节会给完整片段。环境确认清单可以记成四行openclaw --version有输出、node -v≥ 18、clawhub --version有输出、全局 bin 目录在 PATH 里。四行都过再往下走。3. 从 ClawHub 拉取并安装第一个 Skill可复制命令与目录结构这一节是核心操作。ClawHub 是 OpenClaw 的官方 Skills 商店里面有社区分享的各种技能。整个流程分四步搜索、安装、确认目录、重启会话。第一步搜索你需要的 Skill。关键词用英文比如 calendar、weather、email# 搜索关键词 clawhub search calendar # 限制结果数量 clawhub search weather --limit 5输出会列出匹配的 Skill 名称slug、简述和版本。记下你要的那个 slug比如weather-skill。第二步安装# 安装指定 Skills clawhub install skills 名称 # 例如 clawhub install weather-skill安装完成后ClawHub 会把 Skill 放到 OpenClaw 的技能目录。默认情况下工作区级技能在~/.openclaw/workspace/skills/全局级在~/.openclaw/skills/。你可以用clawhub list确认已安装列表clawhub list第三步确认目录结构。一个标准 Skill 目录长这样~/.openclaw/workspace/skills/weather-skill/ ├── SKILL.md # 技能声明名称、描述、依赖、命令 ├── index.js # 技能入口逻辑 ├── package.json # 依赖声明如有 └── README.md # 使用说明SKILL.md是关键文件OpenClaw 靠它识别技能。你可以打开看看cat ~/.openclaw/workspace/skills/weather-skill/SKILL.md里面通常有name、description、requires等字段。requires里会写明需要哪些环境变量或外部命令这是后面排障的依据。第四步重启 OpenClaw 会话让新 Skill 生效。在 OpenClaw 交互界面里输入/new或/reset新会话启动时会重新扫描技能目录把新装的 Skill 注册进来。很多人卡在“装了没反应”九成是没重启会话。如果你要手动安装比如 Skill 没发布到 ClawHub把包含SKILL.md的目录复制过去即可# 复制到工作区仅当前项目可用 cp -r /path/to/skill ~/.openclaw/workspace/skills/ # 复制到全局目录所有会话可用 cp -r /path/to/skill ~/.openclaw/skills/复制完同样要/new重启会话。手动安装适合本地开发调试改完代码重启就能看到效果比走 ClawHub 发布流程快得多。关于模型配置如果你希望 Skill 调用模型时走统一入口可以在~/.openclaw/openclaw.json里加一段。下面是一个可复制的 JSON 片段路径和字段名按你本地实际文件为准{ skills: { entries: { weather-skill: { enabled: true, apiKey: 你的 API 密钥, env: { WEATHER_API_KEY: 你的 API 密钥 } } } } }注意enabled控制开关env里的变量名要和SKILL.md的requires对上。改完配置文件也要重启会话。4. 验证 Skill 是否真的生效list、info、check 三连与成功结果装完不验证等于没装。OpenClaw 提供了三个命令来确认 Skill 状态我习惯叫它们“三连”list、info、check。先列出所有可用 Skillsopenclaw skills list输出会显示技能名称、状态、来源。如果你只想看当前满足运行条件的openclaw skills list --eligible--eligible很实用它把缺依赖、被禁用的都过滤掉只留能直接用的。如果新装的 Skill 没出现在这里说明它还不满足运行条件。再看某个 Skill 的详细信息openclaw skills info weather-skill输出包括描述、版本、依赖项、当前是否启用。重点看requires部分它会列出需要的环境变量和外部命令。最后做依赖检查openclaw skills check这个命令会扫描所有已安装 Skill报告哪些缺少依赖。典型输出会指出“缺少环境变量 WEATHER_API_KEY”或“缺少命令 gemini”。按提示补齐即可。验证生效的最终动作是在 OpenClaw 会话里实际调用一次。重启会话后直接问它一个该 Skill 负责的问题比如装了天气 Skill 就问“今天北京天气怎么样”。如果它返回结构化天气数据而不是泛泛而谈说明 Skill 已经接管了这个任务。成功结果通常有三个特征一是响应里出现 Skill 名称或它定义的工具调用二是返回的是实时/结构化数据不是模型编的三是openclaw skills list --eligible里能看到它。三条都满足这个 Skill 就算跑通了。如果模型侧你用的是 TaoToken可以在 TaoToken 接入文档 里核对 Base URL 和 Model ID 的写法。Skills 和模型是两层验证 Skill 时如果模型报错先确认模型链路再回来看 Skill。5. 装完不生效OpenClaw Skills 常见报错逐条排查这一节按真实报错来。你遇到的大部分问题都能在下面找到对应。报错一command not found: clawhub说明 ClawHub 没装进 PATH。先确认npm i -g clawhub是否成功再检查全局 bin 目录npm config get prefix如果 prefix 是/usr/localbin 在/usr/local/bin。把它加进 PATH或按第 2 节配置~/.npm-global。报错二401 Unauthorized或invalid api key这通常不是 Skills 本身的问题而是模型或 Skill 依赖的外部 API Key 无效。检查~/.openclaw/openclaw.json里的apiKey和env字段确认没有多余空格、没有用错环境的 Key。如果你用的是 TaoTokenBase URL 应为https://taotoken.net/apiKey 从 TaoToken API Keys 获取。改完配置记得/new。报错三local proxy failed或连接超时这类报错指向网络链路。先确认本机能否访问目标地址再检查 OpenClaw 配置里有没有写错的 endpoint。Skills 调用外部服务时如果 endpoint 拼错或端口不对就会以连接失败的形式出现。逐项核对SKILL.md里声明的地址和配置文件里的值是否一致。报错四reading choices相关解析错误这多半是模型返回格式和 Skill 预期不匹配。常见于 Skill 硬编码了某种响应结构而模型侧返回了不同格式。排查方法先用 TaoToken 模型对话 单独测一次模型返回确认格式正常再回来看 Skill 的解析逻辑。必要时在 Skill 的index.js里加日志打印原始响应。报错五OAuth相关失败部分 Skill 需要 OAuth 授权比如邮件类。这类报错通常伴随一个授权链接或设备码。按提示完成授权后把拿到的 token 写进配置。注意 token 有有效期过期后要重新授权。报错六Skill 装了但list --eligible里没有按顺序查三件事SKILL.md是否存在且格式正确、requires里的依赖是否满足、会话是否重启。用openclaw skills check能看到具体缺什么。补齐依赖后重启会话。报错七缺少外部命令如gemini某些 Skill 依赖外部 CLI。按提示安装# Mac brew install gemini-cli # 通用 npm i -g gemini-cli装完再跑openclaw skills check确认。排查顺序建议固定成openclaw skills check看缺什么 → 补依赖 →/new重启 →list --eligible确认 → 实际调用验证。这个顺序能覆盖九成问题。如果你在配 Codex 或 Claude Code 这类编码 Agent涉及auth.json或 settings 片段时务必把 Base URL、Key、Model ID 三件套写全缺一个都会以认证失败的形式报出来。长期跑编码任务的话TaoToken Coding Plan 可以作为统一入口省去每个工具单独配的麻烦。6. 把 Skills 用顺手的几个实操习惯跑通第一个 Skill 之后真正影响效率的是日常习惯。分享几个我踩过坑后固定下来的做法。第一区分工作区和全局安装。项目专用的 Skill 放~/.openclaw/workspace/skills/通用工具放~/.openclaw/skills/。这样换项目时不会互相污染排查也简单。第二定期更新。ClawHub 上的 Skill 会迭代用下面命令保持最新# 更新所有已安装的 Skills clawhub update --all # 更新单个 Skills clawhub update skills 名称更新后同样要/new重启会话。第三禁用而不是删除。临时不用的 Skill在~/.openclaw/openclaw.json里设enabled: false比删掉再装回来省事{ skills: { entries: { 某个 skills: { enabled: false } } } }第四手动调试时直接改工作区目录。本地开发 Skill 时把目录复制到~/.openclaw/workspace/skills/改完index.js重启会话就能看到效果不用走发布流程。这是从 ClawHub 拉取到本地调试闭环里最快的一环。第五把openclaw skills check当成体检命令。每次装新 Skill 或改配置后跑一次比等到调用失败再查要省时间。最后说下模型侧的长期选择。Skills 装多了模型调用会变频繁这时候统一入口的价值就出来了。你可以从 TaoToken 控制台 管理 Key 和用量Base URL 固定用https://taotoken.net/apiModel ID 按文档填。这样无论装多少 Skill模型侧只维护一份配置。Skills 负责能力模型负责推理两条线各自清晰本地调试才不会互相干扰。
阅读完成 · 觉得有帮助？
