OpenClaw 安装简历筛选技能踩坑实录：为什么明明加了 skill，却提示系统里没有

这次折腾 OpenClaw 的简历筛选能力，表面上看只是“装一个 zip 包”，实际上中间踩了几个非常典型、非常容易让新手懵掉的坑。尤其是最容易把人绕进去的一点：到底是 plugin，还是 skill；为什么界面里明明已经出现了技能卡片，聊天里却还提示“系统中没有 resume-screening 技能”。

这篇文档，我把整个过程按真实踩坑顺序梳理清楚。你后面自己再装别的能力，或者教别人装，都可以直接照着这篇走。

一、事情的起点：我下载了一个 zip 包，想用 OpenClaw 装上

一开始的想法很自然：既然下载下来的是一个 zip 包，那就用命令行安装。于是执行了下面这条命令：

openclaw plugins install /Users/jt/Downloads/resume-screening-1.0.0.zip

看起来很合理，因为“install zip 包”这件事，本能上就会想到插件安装命令。

结果终端报错了，核心报错信息是：

Error: unexpected archive layout (dirs: )

这一步就是第一个坑。

很多人看到这里会以为是：

第一，zip 损坏了；
第二，OpenClaw 装坏了；
第三，权限不够；
第四，命令写错了。

但这几个都不是本质原因。

二、第一个关键认知：这个报错不一定代表装不了，而可能代表“装错类型了”

这个错误的真正含义，不是“OpenClaw 完全不支持这个包”，而是：

你当前使用的安装方式，和这个压缩包的实际类型不匹配。

也就是说，你拿一种“插件的安装方式”，去安装一个“并不是插件”的东西。OpenClaw 在 zip 里找它预期的插件结构，结果没找到，所以才会报 archive layout 不符合预期。

说白了，不是这个 zip 一定坏了，而是你可能“把 skill 当成 plugin 装了”。

这就是本次踩坑里最重要的第一个分水岭。

三、第二步排查：把 zip 解压，别猜，直接看里面到底是什么

遇到这种情况，最稳的方法不是继续瞎试命令，而是直接看包里的内容。

解压之后，发现里面只有两个核心文件：

_meta.json
SKILL.md

这一眼就已经足够判断了。

因为只要你在 OpenClaw 的能力包里看到 SKILL.md，基本就可以确定：这不是 plugin，而是 skill。

这个判断逻辑要牢牢记住，因为以后你遇到任何 zip 包，都可以这么判断。

不是看它的名字是不是“xx插件”，也不是看它来自哪里，而是看它解压后的关键文件。

只要有 SKILL.md，就按 skill 处理。

如果将来你看到的是类似插件清单文件，那才按 plugin 处理。

四、第二个关键认知：ClawHub 只是来源，不代表里面全是 plugin

这里又踩了一个特别容易混淆的坑。

很多人会潜意识以为：只要是从 ClawHub 下来的，那就是 plugin。

其实不是。

ClawHub 更像是一个资源仓库、能力市场、分发来源。它里面既可能有 skills，也可能有 plugins。你不能因为它来自 ClawHub，就自动把它归类成 plugin。

所以正确的认知应该是：

ClawHub 是“来源”。
Skill 和 plugin 是“类型”。

来源和类型不是一回事。

这次下载的 resume-screening，虽然来自 ClawHub，但它解压后有 SKILL.md，所以它就是 skill，而不是 plugin。

这一步想明白后，整个安装方式就不再混乱了。

五、第三个关键认知：skill 不是用 plugins install 装，而是直接放到 skills 目录

既然确认这是一个 skill，那么正确安装方式就不是：

openclaw plugins install xxx.zip

而是把它直接解压到 OpenClaw 的 skills 目录下。

正确做法是：

mkdir -p ~/.openclaw/skills/resume-screening
unzip /Users/jt/Downloads/resume-screening-1.0.0.zip -d ~/.openclaw/skills/resume-screening

执行完成后，再确认一下目录结构是否正确。

理想情况下，你应该看到类似这样的结构：

~/.openclaw/skills/resume-screening/SKILL.md
~/.openclaw/skills/resume-screening/_meta.json

这说明 skill 已经被正确放到了 OpenClaw 会扫描的 skills 路径中。

这里还有一个很容易踩的小坑，就是“多套一层目录”。

比如有些 zip 解压后会变成这样：

~/.openclaw/skills/resume-screening/resume-screening/SKILL.md

如果多包了一层文件夹，有些系统页面也许还能勉强扫到，但运行时可能出问题。所以安装后一定要确认 SKILL.md 不要藏得太深。

最稳的状态，就是它直接位于 skill 目录的第一层。

六、第四个关键认知：界面里显示 skill，不等于当前聊天一定能调用它

装好之后，技能页面里出现了 resume-screening，而且状态还是 eligible。看到这里，很自然会以为：已经成功了，接下来聊天里直接调用就行。

但真正一测试，聊天里却提示：

“我注意到系统中没有 resume-screening 技能，但我可以直接帮你评估这份简历。”

这一步特别让人抓狂，因为从人的直觉来看，这简直矛盾：

明明已经有了，为什么又说没有？

这里就踩到了本次流程中的第四个坑，也是最具迷惑性的坑。

OpenClaw 里，“技能页面可见”和“当前会话实际可调用”不是完全等价的。

你可以把它理解成两个层面：

第一个层面，是系统资源层。也就是 OpenClaw 已经在磁盘上看到了这个 skill，并且把它列在技能页里。
第二个层面，是聊天运行层。也就是你当前这场对话、当前这个 agent、当前这个模型模式，是否真的把这个 skill 绑定进来了。

技能页里能看到，只能证明第一层没问题。
聊天里能调用，才说明第二层也通了。

而这次的问题，就是第一层通了，第二层没通透。

七、为什么会出现“有 skill，但当前聊天说没有”的现象

结合整个过程，这种现象通常有三个原因。

第一个原因，是当前聊天是旧会话。

也就是说，你是在某个聊天已经打开的情况下，后面才把 skill 装进去的。这样当前聊天可能还保留着旧上下文，根本没有重新加载最新的技能列表。

所以最简单粗暴的办法，不是一直在当前 main 会话里死磕，而是新建一个聊天，再重新测试。

第二个原因，是当前模式并不是“带 skill 的代理模式”。

你截图里顶部显示的是某个模型通道，例如 coder-model · qwen-portal。这就意味着你当前可能只是“模型直聊”模式，而不是“带工具、带技能、带 agent 能力”的模式。

通俗一点说，就是你现在打开的是“会说话的脑子”，不是“带工具箱的脑子”。

skill 虽然装在系统里，但这个聊天窗口未必自动挂载它。

第三个原因，是你调用时写的名字，可能不是它真正的运行时名称。

页面看到的标题可能叫 resume-screening，但 _meta.json 里实际注册名，未必就是这个字符串。有时候展示名、文件夹名、内部 name、工具调用名不完全一致。

所以当你在聊天里写“请调用 resume-screening”，模型有可能并没有找到这个精确的运行时对象。

八、所以，安装成功之后，不能立刻默认“已经可调用”，还要做二次验证

这次最大的经验之一就是：安装和调用是两步，不是一件事。

安装成功只意味着文件放对地方了，系统页面能看到它。
调用成功才意味着当前运行时真的把它挂进来了。

所以正确流程应该是：

先确认 skill 文件已经放进正确目录。
再确认 OpenClaw 已重启。
然后新建一个聊天。
接着测试当前会话能否列出可用技能。
最后再正式调用 skill 去做简历筛选。

如果你跳过中间这几步，直接拿长简历去测，往往只会得到一个让人更糊涂的结果：界面有，聊天却说没有。

九、重启 OpenClaw 这件事，不能只理解成“页面刷新一下”

很多新手会以为，只要我页面上已经看到 skill 了，就说明不需要重启，或者随便刷新一下页面就行。

但这次过程说明，真正需要的是让 OpenClaw 的运行时重新扫描和加载 skill。

最稳妥的办法就是：

先停止当前 OpenClaw 进程，再重新启动。

如果是在当前终端里启动的，直接按 Ctrl + C 停掉，然后重新运行启动命令。

如果已经开了多个终端，搞不清哪个在跑，可以直接：

pkill -f openclaw
openclaw

这个动作的意义，不是为了“心理安慰式刷新”，而是为了让后台运行时重新读取 skills 目录。

十、这次流程中最容易混淆的概念，我帮你彻底捋顺

很多坑，其实都来自几个概念混在一起。

第一个，zip 包，不等于 plugin。
zip 只是压缩格式，不代表内容类型。

第二个，ClawHub，不等于 plugin 仓库。
它只是能力分发来源，里面既可以放 skill，也可以放 plugin。

第三个，技能页里出现，不等于聊天一定能用。
页面扫描成功，只说明系统层看到了；会话层是否加载，还要另外验证。

第四个，安装成功，不等于调用成功。
这两个步骤必须分开看。

第五个，展示名，不一定等于调用名。
有时候必须去看 _meta.json 才能确认实际名称。

你只要把这五层关系理清，以后遇到 OpenClaw 里“界面有、聊天没”的问题，就不会慌。

十一、给小白的最终结论：以后如何最快判断该怎么装

以后你拿到一个 OpenClaw 相关 zip 包，不要先急着敲命令。

第一步，先解压。
第二步，看里面有没有 SKILL.md。
如果有，那就是 skill，直接解压到 ~/.openclaw/skills/对应目录。
如果没有，再看是不是插件清单，插件才走 openclaw plugins install。

你只要遵守“先看文件，再决定安装方式”这个原则，基本就不会再踩这次这个坑。

十二、这次最实用的一套标准操作流程

以后你可以直接照这个流程走。

先把 zip 解压看内容。
如果看到 SKILL.md，就创建对应 skills 目录，把它解压进去。
确认 SKILL.md 和 _meta.json 在合理层级。
彻底重启 OpenClaw。
新建一个聊天，而不是继续用老会话。
先让系统列出当前可用技能，确认 skill 已挂载。
最后再正式输入岗位要求和简历内容做测试。

这个流程虽然多了几步，但它能大幅减少你被各种“明明装了却说没有”的假象误导。

十三、回头看，这次踩坑真正值钱的不是命令，而是认知升级

表面看，这次我们只是多敲了几条命令。
但真正值钱的，不是某条命令本身，而是你搞明白了 OpenClaw 里几个非常核心的运行逻辑：

它的能力分为 skill 和 plugin，不是一锅炖；
skill 的安装和 plugin 的安装机制不同；
页面展示和运行时加载是两个层次；
聊天模式、会话上下文、技能绑定会影响最终调用效果。

一旦这些逻辑想清楚，后面你不止能装这个简历筛选 skill，装别的本地 skill、排查别的调用问题，也会快很多。

十四、最后给一句最浓缩的经验总结

这次的核心经验可以浓缩成一句话：

不要看到 zip 就默认用插件命令装，不要看到技能页有就默认聊天能调用；先认清它是 skill 还是 plugin，再确认它有没有真正挂到当前会话里。

这才是这次踩坑中，最值钱的干货。