openclaw skills 命令全解：list / install / update / verify / check 各自解决什么问题

一、先说个场景

你刚接触 OpenClaw，学会 openclaw skills list 之后就觉得差不多了。结果有一天技能装了但列表里没有，想更新却不知道会不会覆盖，看到别人提 verify 也不知道要不要跑。其实 OpenClaw 的 skills 子命令有清晰的职责边界，知道每个命令的脾气，排障效率能提高十倍。

这篇文章按命令逐个拆解：list、install、update、verify、check，再加上 gateway restart。不讲空话，只讲它们实际输出的含义和正确的使用时机。

二、为什么是这样

OpenClaw 的 CLI 是围绕”技能生命周期”设计的。一个技能从被发现、安装、加载、校验到更新、禁用、删除，每一步都有对应的命令。你不会用 install 做 update 的事，也不会用 list 去校验安全。把命令分开，是为了让自动化和排障都有抓手。

openclaw skills list          # 发现 / 加载视图
openclaw skills install       # 把来源里的 skill 放进本地
openclaw skills update        # 只跟踪 ClawHub 安装的技能升级
openclaw skills verify        # 校验 ClawHub 信任信封
openclaw skills check         # 状态自检
openclaw gateway restart      # 刷新技能快照

三、跟着做：分步操作

1. list — 看当前会话加载了哪些技能

openclaw skills list

它显示的是当前会话可见的技能，不是磁盘上所有文件。如果某个 skill 在磁盘里但不在列表中，可能是因为：

• 需要开新会话 /new；
• Gateway 没有刷新，需要 openclaw gateway restart；
• 被更高优先级的同名 skill 遮住；
• 被 agents.entries.*.skills 白名单过滤掉了。

2. install — 把技能装进合适的 root

# ClawHub → workspace
openclaw skills install @owner/slug

# ClawHub → 全局
openclaw skills install @owner/slug --global

# 其他来源
openclaw skills install skills-sh:owner/repo/slug
openclaw skills install git:owner/repo@ref
openclaw skills install ./path/to/skill --as my-tool

slugs 推断规则：

• 优先用 SKILL.md frontmatter 里的 name；
• 没有才回退目录名或仓库名；
• --as my-tool 覆盖。

Git 和本地安装要求 SKILL.md 在源码根目录。

3. update — 只认 ClawHub

# 更新 workspace 里从 ClawHub 装的全部技能
openclaw skills update --all

# 更新某个全局技能
openclaw skills update @owner/slug --global

# 更新全部全局技能
openclaw skills update --all --global

关键限制：update 只跟踪 ClawHub 安装。如果你从 Git 或本地装的 skill，想更新必须重新 install。

4. verify — 装之前先安检

openclaw skills verify @owner/slug
openclaw skills verify @owner/slug --card

它会向 ClawHub 查询该技能的 clawhub.skill.verify.v1 信任信封。已装的 ClawHub 技能还会对照 .clawhub/origin.json 里的版本和注册表信息。ClawHub 判定失败时，命令会非零退出，这就是个明确的红色信号。

--card 会打印生成的 Skill Card，方便你做最终检查。

5. check — 状态扫描

openclaw skills check

这个命令用来做内部状态检查，比如有没有损坏的引用、配置里的 entries 是否合法、路径包含是否异常等。遇到列表和实际目录对不上时，可以先跑它。

6. gateway restart — 强制刷新

openclaw gateway restart

当你改了 SKILL.md、换了技能目录、或者 watcher 没有触发时，重启 Gateway 能保证 agent 拿到最新的技能快照。

install 很聪明的一点，是它能从来源串识别该去哪取：以 @ 开头当作 ClawHub 注册表；skills-sh: 当作外部引用；git: 当作源码仓库；以 ./ 或路径形式则当作本地目录。你不用额外加开关告诉它”这是 Git”，写法本身就带了语义。知道这套约定，你看到别人的安装命令就能立刻判断它从哪来、会不会写进你的 workspace 还是全局。

四、可以复制的指令

# 查看当前加载的技能
openclaw skills list

# 从 ClawHub 安装
openclaw skills install @openclaw/weather

# 更新所有通过 ClawHub 安装的技能
openclaw skills update --all

# 校验 ClawHub 信任信封
openclaw skills verify @openclaw/weather

# 状态自检
openclaw skills check

# 强制刷新技能快照
openclaw gateway restart

list 的”可见性”受好几层影响：加载优先级决定同名的谁胜出，agent 的白名单决定谁能进这个会话，网关的监听状态决定新增的有没有被拍进快照。所以同样一份技能，在不同 agent、不同会话里看到的可能不一样——这不是 bug，是设计。理解这一点，你就不会在 A 会话看到、B 会话看不到时惊慌，而是去查白名单和优先级，定位”为什么这一侧没它”。

五、实战案例

你发现列表里少了一个刚装的 skill。

排查流程：

1. 先确认磁盘上有没有：ls ~/.openclaw/workspace/skills/
2. 跑 openclaw skills list，确认真的没有。
3. 在聊天里输入 /new，再看一次。
4. 还不行就 openclaw gateway restart。
5. 重启后依然没有，检查 ~/.openclaw/openclaw.json 里的 agents.entries.*.skills 是否把它过滤掉了。
6. 如果还是不 loading，跑 openclaw skills check 看有没有元数据错误。

这个排查顺序从”会话刷新”到”配置过滤”，避免一上来就怀疑 skill 本身有问题。

六、常见误区

• 误区 1：list 和磁盘目录一定完全一致。list 显示的是当前会话可见的技能，受优先级、白名单、watch 状态影响。
• 误区 2：update --all 能更新所有来源的技能。只对 ClawHub 安装生效，Git 和本地要重装。
• 误区 3：verify 装完就不用管。首次安装前校验最有意义，但如果 skill 在 ClawHub 上的安全状态变了，定期复查也有必要。
• 误区 4：check 能代替 verify。check 是本地状态检查，不做安全扫描；verify 才查信任信封。
• 误区 5：gateway restart 会丢聊天记录。它重启的是 Gateway 控制面，不是删除聊天记录；但活跃会话可能需要重新建立。

再展开说 verify：它向 ClawHub 查询该技能的信任信封（clawhub.skill.verify.v1），并对照本地 .clawhub/origin.json 里的版本与注册表信息。一旦 ClawHub 判定不安全，命令以非零状态退出，这就是让你停手的红灯。别以为装那天验过就永久安全——技能在注册表上的状态会变，定期重跑 verify，尤其在更新前后，是低成本高回报的习惯。

把这些命令记熟之后，你会发现自己越来越少去翻文档，越来越多凭直觉排障。这种”知道该按哪个键”的安心感，正是 CLI 设计成职责单一的意义所在。工具顺手了，你才愿意真的用起来，而不是装完就忘。

七、进阶玩法

把常用命令做成你自己的 skill。比如写一个 skill-status skill，里面教 agent：

1. 用 exec 跑 openclaw skills list。
2. 解析输出，按来源分组。
3. 用 exec 跑 openclaw skills check，把异常标红。
4. 把结果发回聊天。

从此你只需说一句”检查我的技能状态”，OpenClaw 就给你一份整理好的报告。

另一个方向是把 verify 集成到安装前的自动化脚本里。例如 CI 中拉取 OpenClaw 技能时，先跑 verify，失败直接中断构建。

把命令用顺手之后，你会发现它们彼此能串成流水线：先用 info 看某个技能的来源与参数，再用 verify 确认它可信，最后才 install。这条”先看、再验、后装”的顺序，配合 update --all 与 sync --all 的例行维护，基本覆盖了个人技能库的全部运维动作。

遇到技能不生效，脑子里按这张顺序过一遍最省事：先想”是不是会话没刷新”——开新会话或重启网关；再想”是不是被白名单或更高优先级盖了”——看配置；最后才想”是不是技能本身坏了”——跑 check、读 SKILL.md。从最便宜、最常见的原因查起，不要一上来就钻进源码。排障的快慢，往往不取决于多懂命令，而取决于查的顺序对不对。

这套命令不需要死记，用多了自然熟。建议你第一次排障时，把”list → check → 重启网关”这条最小路径在脑子里走顺，其余命令等遇到对应场景再学。命令是工具，不是考试；真正值钱的是”出问题知道去翻哪条命令”的意识。等你带新人上手 OpenClaw，你也会自然地把这几条当成常识随口一提。

八、小结

命令不多，但分工明确。记住最关键的一条：update 只爱 ClawHub，verify 是你的安全门，gateway restart 是万能刷新键。