技能（OpenClaw）
OpenClaw 使用 AgentSkills 兼容的技能文件夹来教代理如何使用工具。每个技能是一个目录，包含一个带 YAML frontmatter 和说明的 SKILL.md。OpenClaw 加载捆绑技能加上可选的本地覆盖，并根据环境、配置和二进制文件存在在加载时过滤它们。
位置和优先级
技能从三个地方加载：
- 捆绑技能：随安装一起提供（npm 包或 OpenClaw.app）
- 托管/本地技能：
~/.openclaw/skills - 工作区技能：
<workspace>/skills
如果技能名称冲突，优先级是：
<workspace>/skills（最高）> ~/.openclaw/skills > 捆绑技能（最低）
此外，你可以通过 ~/.openclaw/openclaw.json 中的 skills.load.extraDirs 配置额外的技能文件夹（最低优先级）。
每代理 vs 共享技能
在多代理设置中，每个代理有自己的工作区。这意味着：
- 每代理技能仅存在于该代理的
<workspace>/skills中。 - 共享技能存在于
~/.openclaw/skills（托管/本地），在同一机器上的所有代理都可见。 - 如果你想要多个代理使用的公共技能包，也可以通过
skills.load.extraDirs（最低优先级）添加共享文件夹。
如果同一技能名称存在于多个地方，适用通常的优先级：工作区胜出，然后是托管/本地，然后是捆绑。
插件 + 技能
插件可以通过在 openclaw.plugin.json 中列出 skills 目录来附带自己的技能（路径相对于插件根目录）。当插件启用时，插件技能加载并参与正常的技能优先级规则。你可以通过插件配置条目上的 metadata.openclaw.requires.config 对它们进行门控。关于发布配置见插件，关于这些技能教的工具表面见工具。
ClawHub（安装 + 同步）
ClawHub 是 OpenClaw 的公共技能注册表。在 https://clawhub.com 浏览。使用它来发现、安装、更新和备份技能。完整指南：ClawHub。
常见流程：
- 将技能安装到你的工作区：
clawhub install <skill-slug>
- 更新所有已安装的技能：
clawhub update --all
- 同步（扫?+ 发布更新）：
clawhub sync --all
默认情况下，clawhub 安装到当前工作目录下?./skills（或回退到配置的 OpenClaw 工作区）。OpenClaw 在下一个会话中将其作为 <workspace>/skills 获取?
安全说明
- 将第三方技能视?不受信任的代?。启用前阅读它们?
- 对于不受信任的输入和风险工具，优先使用沙箱化运行。沙箱?
skills.entries.*.env?skills.entries.*.apiKey?secrets 注入该代理轮次的主机进程（不是沙箱）。将 secrets 排除在提示和日志之外?- 更广泛威胁模型和检查清单见安全?
格式（AgentSkills + Pi 兼容?
SKILL.md 必须至少包括?
---
name: nano-banana-pro
description: Generate or edit images via Gemini 3 Pro Image
---注意?
- 我们遵循 AgentSkills 规范进行布局/意图?
- 嵌入式代理使用的解析器仅支持单行 frontmatter 键?
metadata应该?单行 JSON 对象*?- 在说明中使用
{baseDir}引用技能文件夹路径? - 可?frontmatter 键：
-
homepage??macOS 技?UI 中显示为”Website”?URL（也通过metadata.openclaw.homepage支持）? -
user-invocable?true|false（默认：true）。当?true时，技能作为用户斜杠命令公开? -
disable-model-invocation?true|false（默认：false）。当?true时，技能从模型提示中排除（仍可通过用户调用使用）? -
command-dispatch?tool（可选）。当设为tool时，斜杠命令绕过模型直接分派到工具? -
command-tool?当设?command-dispatch: tool时要调用的工具名称? -
command-arg-mode?raw（默认）。对于工具分派，将原始参数字符串转发给工具（无核心解析）?工具使用以下参数调用?
{ command: "<raw args>", commandName: "<slash command>", skillName: "<skill name>" }?
-
门控（加载时过滤?
OpenClaw 使用 metadata（单?JSON）在**加载时过滤技?*?
---
name: nano-banana-pro
description: Generate or edit images via Gemini 3 Pro Image
metadata:
{
"openclaw":
{
"requires": { "bins": ["uv"], "env": ["GEMINI_API_KEY"], "config": ["browser.enabled"] },
"primaryEnv": "GEMINI_API_KEY",
},
}
---metadata.openclaw 下的字段?
always: true?始终包含技能（跳过其他门控）?emoji?macOS 技?UI 使用的可?emoji?homepage??macOS 技?UI 中显示为”Website”的可?URL?os?可选平台列表（darwin、linux、win32）。如果设置，技能仅在这?OS 上符合条件?requires.bins?列表；每个必须存在于PATH上?requires.anyBins?列表；至少一个必须存在于PATH上?requires.env?列表；环境变量必须存?*?*在配置中提供?requires.config?必须?truthy ?openclaw.json路径列表?primaryEnv??skills.entries.<name>.apiKey关联的环境变量名称?install?macOS 技?UI 使用的可选安装程序规范数组（brew/node/go/uv/download）?
关于沙箱的说明：
requires.bins在技能加载时?*主机**上检查?- 如果代理是沙箱化的，二进制文件也必须存在?容器??
通过
agents.defaults.sandbox.docker.setupCommand（或自定义镜像）安装?setupCommand在容器创建后运行一次? 包安装还需要网络出口、可写根 FS 和沙箱中的根用户? 示例：技?summarize（skills/summarize/SKILL.md）需要在沙箱容器中运行?
安装程序示例?
---
name: gemini
description: Use Gemini CLI for coding assistance and Google search lookups.
metadata:
{
"openclaw":
{
"emoji": "♊️",
"requires": { "bins": ["gemini"] },
"install":
[
{
"id": "brew",
"kind": "brew",
"formula": "gemini-cli",
"bins": ["gemini"],
"label": "Install Gemini CLI (brew)",
},
],
},
}
---注意?
- 如果列出了多个安装程序，gateway 选择单个首选选项（可用时 brew，否?node）?
- 如果所有安装程序都?
download，OpenClaw 列出每个条目以便你可以看到可用的工件? - 安装程序规范可以包含
os: ["darwin"|"linux"|"win32"]按平台过滤选项? - Node 安装尊重
openclaw.json中的skills.install.nodeManager（默认：npm；选项：npm/pnpm/yarn/bun）? 这仅影响**技能安?*；Gateway 运行时仍应是 Node（WhatsApp/Telegram 不推?Bun）? - Go 安装：如果缺?
go?brew可用，gateway 首先通过 Homebrew 安装 Go 并尽可能?GOBIN设置?Homebrew ?bin? - 下载安装：
url（必需）、archive（tar.gz|tar.bz2|zip）、extract（检测到 archive 时默认：auto）、stripComponents、targetDir（默认：~/.openclaw/tools/<skillKey>）?
如果没有 metadata.openclaw，技能始终符合条件（除非在配置中禁用或被捆绑技能的 skills.allowBundled 阻止）?
配置覆盖（~/.openclaw/openclaw.json?
捆绑/托管技能可以切换并提供环境值：
{
skills: {
entries: {
"nano-banana-pro": {
enabled: true,
apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // 或明文字符串
env: {
GEMINI_API_KEY: "GEMINI_KEY_HERE",
},
config: {
endpoint: "https://example.invalid",
model: "nano-pro",
},
},
peekaboo: { enabled: true },
sag: { enabled: false },
},
},
}注意：如果技能名称包含连字符，引号键（JSON5 允许带引号的键）?
配置键默认匹?技能名?。如果技能定?metadata.openclaw.skillKey，在 skills.entries 下使用该键?
规则?
enabled: false即使已捆?安装也禁用技能?env：仅在变量未在进程中设置时才注入?apiKey：为声明metadata.openclaw.primaryEnv的技能提供的便利。支持明文字符串?SecretRef 对象（{ source, provider, id }）?config：可选的自定义每技能字段袋；自定义键必须在这里?allowBundled：仅?*捆绑**技能的可选白名单。如果设置，仅列表中的捆绑技能符合条件（托管/工作区技能不受影响）?
环境变量注入（每代理运行?
当代理运行开始时，OpenClaw?
- 读取技能元数据?
- 将任?
skills.entries.<key>.env?skills.entries.<key>.apiKey应用?process.env? - ?*符合条件**的技能构建系统提示?
- 运行结束后恢复原始环境?
这是作用域到代理运行，不是全局 shell 环境?
会话快照（性能?
OpenClaw ?*会话开始时**快照符合条件的技能，并在同一会话的后续轮次中重用该列表。更改技能或配置在下一个新会话中生效?
当技能监视器启用或出现新的符合条件的远程节点时，技能也可以在会话中期刷新（见下文）。将其视?热重?：刷新的列表在下一个代理轮次中被获取?
远程 macOS 节点（Linux gateway?
如果 Gateway ?Linux 上运行但macOS 节点已连?*且允?system.run**（Exec 批准安全未设?deny），当该节点上存在所需二进制文件时，OpenClaw 可以将仅 macOS 技能视为符合条件。代理应通过 nodes 工具执行这些技能（通常 nodes.run）?
这依赖于节点报告其命令支持以及通过 system.run 的二进制探测。如?macOS 节点稍后离线，技能保持可见；调用可能会失败，直到节点重新连接?
技能监视器（自动刷新）
默认情况下，OpenClaw 监视技能文件夹并在 SKILL.md 文件更改时更新技能快照。在 skills.load 下配置：
{
skills: {
load: {
watch: true,
watchDebounceMs: 250,
},
},
}Token 影响（技能列表）
当技能符合条件时，OpenClaw 将可用技能的紧凑 XML 列表注入系统提示（通过 pi-coding-agent 中的 formatSkillsForPrompt）。成本是确定性的?
- 基础开销（仅?? 技能时）： 195 字符?
- 每个技能： 97 字符 + XML 转义?
<name>、<description>?<location>值的长度?
公式（字符）?
total = 195 + Σ (97 + len(name_escaped) + len(description_escaped) + len(location_escaped))注意?
- XML 转义?
& < > " '扩展为实体（&、<等），增加长度? - Token 计数因模型分词器而异。粗略的 OpenAI 风格估计约为 4 字符/token，因?每个技能约 97 字符 ?24 token* 加上你的实际字段长度?
托管技能生命周?
OpenClaw 作为**捆绑技?*随安装一起提供一组基线技能（npm 包或 OpenClaw.app）。~/.openclaw/skills 用于本地覆盖（例如，无需更改捆绑副本即可固定/修补技能）。工作区技能由用户拥有，并在名称冲突时覆盖两者?
配置参?
完整配置 schema 见技能配置?