OpenClaw Skills 配置指南:为什么你装了几十个 skill,只有 5 个能用

养了openclaw两个多月，每当让它干活的时候，总是这样不会那样不行，今天让它认真学习了openclaw官方文档，把已经安装好的skills认真清理了一遍，让它自己总结经验教训：

今天花了一整下午，把 OpenClaw 的 skill 系统从”全部禁用”调成了”全部就绪”。踩了一个很隐蔽的坑，值得写出来。

先说结论

Skill 装好了 ≠ skill 能用。

OpenClaw 对 skill 有两层过滤：

• 位置过滤：workspace > managed > bundled
• 名称过滤：文件夹名必须和 SKILL.md 里 name: 字段完全一致

第二层最容易忽略，也是今天所有问题的根源。

一、目录结构别放错

~/.openclaw/skills/           # 通用的，所有 agent 都能用
~/.openclaw/workspace/skills/ # main-agent 专用
~/.openclaw/workspace-XXX/skills/  # 各子 agent 专用

main-agent 用的 skill 就放在 workspace/skills/，别往通用的 ~/.openclaw/skills/ 里塞。

二、两道关卡

关卡 1：谁覆盖谁

同名 skill，优先级高的赢。

关卡 2：文件夹名 vs SKILL.md name

在 openclaw.json 里配置允许列表：

"agents": {
  "defaults": {
    "skills": ["pua", "tavily", "browser-healthcheck", ...]
  }
}

这里填的是文件夹名，但 OpenClaw 过滤时用的是 SKILL.md 里的 name: 字段。两者不匹配 → blocked，不报错，外表看着正常，就是调不动。

修复方法：文件夹改成和 name: 一致，同时更新配置。

三、SKILL.md 损坏会直接 excluded

frontmatter 格式不对，OpenClaw 解析失败，整个 skill 直接 excluded。常见情况：

• AIGC: 开头的大量乱码字段
• 缺少 name: 行
• YAML 语法错误

删除坏的，让 workspace 版本生效即可。

四、诊断命令

# 看哪些实际就绪
openclaw skills list --eligible

# 找出被 blocked 的
openclaw skills list --json | python3 -c "
import json, sys
for s in json.load(sys.stdin)['skills']:
    if s['eligible'] and s['blockedByAgentFilter']:
        print('blocked:', s['name'])
"

# 检查文件夹名和 name 字段是否一致
for d in ~/.openclaw/workspace/skills/*/; do
    name=$(grep '^name:' "$d/SKILL.md" | cut -d: -f2 | tr -d ' ')
    folder=$(basename "$d")
    [ "$name" != "$folder" ] && echo "不一致: $folder → name=$name"
done

五、今天的修复记录

1. 删了 ~/.openclaw/skills/agent-browser（SKILL.md 乱码）
2. 删了 ~/.openclaw/skills/self-improvement（覆盖了 workspace 版本）
3. 删了 ~/.openclaw/skills/wechat-publisher（workspace 已有）
4. 把 browser-use 移到了 workspace/skills/
5. 重命名了 5 个文件夹匹配 SKILL.md name
6. 更新了配置，重启 Gateway

最终：10 个 skill 全部就绪。

六、经验

1. 装完 skill 必须验证 modelVisible: true
2. 文件夹名和 SKILL.md name 是两回事
3. 改完配置要重启 Gateway 才生效
4. 优先用 workspace 版本，不要放 managed
5. 同名情况下，高优先级版本坏了会拖累整个 skill

基于 OpenClaw 2026.5.12