Skills 安装目录及调用优先级（含自定义技能） |

本文主要介绍SKills技能的存储、优先级、多 Agent 场景下的隔离机制以及自定义技能创建方法等内容。

一、技能存储位置（6 个来源）

OpenClaw 从以下 6 个位置加载技能，按优先级从高到低排列：

优先级	位置	路径	说明
1（最高）	工作空间技能	<workspace>/skills/	当前 Agent 工作空间内的技能
2	项目 Agent 技能	<workspace>/.agents/skills/	当前工作空间下的 .agents 目录
3	个人 Agent 技能	~/.agents/skills/	用户主目录下，跨工作空间通用
4	共享/托管技能	~/.openclaw/skills/	所有 Agent 共享，openclaw skills install 安装到这里
5	内置技能	随 OpenClaw npm 包安装	官方捆绑的技能
6（最低）	额外目录	skills.load.extraDirs 配置指定	自定义加载路径

实际路径示例

优先级 1: ~/.openclaw/workspace/skills/                     ← 工作空间技能
优先级 2: ~/.openclaw/workspace/.agents/skills/             ← 项目 Agent 技能
优先级 3: ~/.agents/skills/                                 ← 个人 Agent 技能
优先级 4: ~/.openclaw/skills/                               ← 共享托管技能
优先级 5: ~/.npm-global/lib/node_modules/openclaw/skills/   ← 内置技能
优先级 6: skills.load.extraDirs 配置的路径                    ← 额外目录

二、Skills调用优先级规则

核心规则

同名技能按优先级覆盖：如果多个位置存在同名技能，高优先级的会覆盖低优先级的。

workspace/skills/ > .agents/skills/ > ~/.agents/skills/ > ~/.openclaw/skills/ > 内置 > extraDirs

覆盖示例

场景	内置技能	工作空间技能	最终生效
仅内置存在	weather（优先级 5）	无	内置版本
工作空间覆盖	weather（优先级 5）	weather（优先级 1）	工作空间版本
仅工作空间存在	无	my-tool（优先级 1）	工作空间版本

三、多 Agent 场景下的隔离

在多 Agent 架构中，每个 Agent 有独立工作空间，技能可见性如下：

范围	位置	可见性
单个 Agent 专属	<agent-workspace>/skills/	仅该 Agent 可见
单个 Agent 专属	<agent-workspace>/.agents/skills/	仅该 Agent 可见
当前用户所有 Agent	~/.agents/skills/	该用户的所有 Agent 共享
所有 Agent 共享	~/.openclaw/skills/	机器上所有 Agent 可见
所有 Agent 共享	内置技能	所有 Agent 可见
所有 Agent 共享	skills.load.extraDirs	所有 Agent 可见

设计思路：越靠近工作空间的技能越「私有」，越远离的越「共享」

四、技能安装方式与对应位置

安装方式	安装到	优先级
skillhub install <name>	当前工作空间 <workspace>/skills/（默认 ./skills/）	1（最高）
openclaw skills install <name>	当前工作空间 <workspace>/skills/	1（最高）
clawhub install <name>	当前工作目录 ./skills/	1（最高）
手动创建目录 + SKILL.md	取决于你放在哪个位置	1~6
插件附带技能（plugins）	等同 extraDirs 级别	6（最低）

安装命令示例

# 从 ClawHub 安装技能到工作空间
openclaw skills install weather

# 从 SkillHub 安装技能到工作空间（国内推荐）
skillhub install weather

# 更新所有已安装的技能
openclaw skills update --all

# 使用 skillhub 更新已安装技能
skillhub upgrade

# 使用 clawhub CLI 同步
clawhub sync --all

五、查看当前技能状态

命令	说明
openclaw skills list	列出所有已加载的技能
openclaw skills info <name>	查看技能详细信息
openclaw skills check	检查哪些技能就绪/缺少依赖
openclaw skills search <query>	搜索 ClawHub 技能市场
openclaw skills install <name>	安装技能
openclaw skills update	更新已安装的技能

六、插件附带的技能

插件可以在 openclaw.plugin.json 中声明 skills 目录：

插件启用后自动加载其附带的技能
插件技能的优先级最低（等同 extraDirs）
任何同名的工作空间/共享/内置技能都会覆盖插件技能
可通过 metadata.openclaw.requires.config 对插件技能进行门控

七、自定义技能创建

基本结构

每个技能是一个包含 SKILL.md 的目录：

skills/
└── my-skill/
    └── SKILL.md

SKILL.md 最小格式

---
name: my-skill
description: 我的自定义技能描述
---

# 我的技能

这里写技能的指令内容...

可选 frontmatter 参数

参数	类型	默认值	说明
name	string	必填	技能名称，转为命令名（a-z0-9_，最长 32 字符）
description	string	必填	技能描述
user-invocable	bool	true	是否暴露为用户快捷命令
disable-model-invocation	bool	false	是否排除出模型提示词
command-dispatch	string	无	设为 tool 则绕过模型直接调用工具
command-tool	string	无	配合 command-dispatch: tool 指定工具名
command-arg-mode	string	raw	参数传递模式
metadata	JSON	无	门控条件、安装器、平台限制等

门控条件（metadata.openclaw）

---
name: image-lab
description: 图片生成和编辑
metadata: {"openclaw": {"requires": {"bins": ["uv"], "env": ["API_KEY"]}, "primaryEnv": "API_KEY"}}
---

门控字段	说明
always: true	始终加载，跳过其他门控
os	限制平台：darwin / linux / win32
requires.bins	必须在 PATH 中存在的二进制文件
requires.anyBins	至少一个存在即可
requires.env	必须存在的环境变量
requires.config	必须为真值的 openclaw.json 配置路径
primaryEnv	关联 skills.entries.<name>.apiKey 的环境变量

八、安全注意事项

第三方技能视为不可信代码，启用前应先阅读其内容
对不可信输入和高风险工具优先使用沙箱运行
技能目录发现仅接受 realpath 在配置根目录内的 SKILL.md
Gateway 内置的技能安装会运行危险代码扫描器，critical 级别默认阻止
skills.entries.*.env 和 apiKey 注入到宿主进程（非沙箱），需保护密钥不泄露

总结

核心原则：越靠近你的工作空间，优先级越高

工作空间技能 > 项目 Agent 技能 > 个人 Agent 技能 > 共享技能 > 内置技能 > 额外目录

同名技能高优先级覆盖低优先级

Skills 安装目录及调用优先级（含自定义技能）