技能 (OpenClaw)

OpenClaw 使用 AgentSkills-兼容的技能文件夹来教授代理如何使用工具。每个技能都是一个目录,包含一个带有 YAML 前置元数据和指令的 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 将密钥注入该代理轮次的宿主进程(而非沙箱)。不要在提示词和日志中包含密钥。
有关更广泛的威胁模型和清单,请参阅安全。

格式(AgentSkills + Pi-兼容)

SKILL.md 必须至少包含:

markdown

---
name: nano-banana-pro
description: Generate or edit images via Gemini 3 Pro Image
---

注意:

我们遵循 AgentSkills 规范的布局/意图。
嵌入式代理使用的解析器仅支持单行前置元数据键。
metadata 应该是一个单行 JSON 对象。
在指令中使用 {baseDir} 来引用技能文件夹路径。
可选的前置元数据键:
- homepage — 在 macOS 技能 UI 中作为"网站"显示的 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)在加载时过滤技能:

markdown

---
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 使用的可选表情符号。
homepage — 在 macOS 技能 UI 中作为"网站"显示的可选 URL。
os — 可选的平台列表(darwin、linux、win32)。如果设置,该技能仅在这些操作系统上符合条件。
requires.bins — 列表;每个都必须存在于 PATH 上。
requires.anyBins — 列表;至少有一个必须存在于 PATH 上。
requires.env — 列表;环境变量必须存在或在配置中提供。
requires.config — 必须为真值的 openclaw.json 路径列表。
primaryEnv — 与 skills.entries.<name>.apiKey 关联的环境变量名。
install — macOS 技能 UI 使用的可选安装器规范数组(brew/node/go/uv/download)。

关于沙箱的注意事项:

requires.bins 在技能加载时在宿主上检查。
如果代理被沙箱化,二进制文件也必须存在于容器内部。通过 agents.defaults.sandbox.docker.setupCommand(或自定义镜像)安装。 setupCommand 在容器创建后运行一次。包安装还需要网络出口、可写根文件系统和沙箱中的 root 用户。示例:summarize 技能(skills/summarize/SKILL.md)需要沙箱容器中的 summarize CLI 才能在那里运行。

安装器示例:

markdown

---
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)",
            },
          ],
      },
  }
---

注意:

如果列出多个安装器,网关会选择单个首选选项(如果可用则选择 brew,否则选择 node)。
如果所有安装器都是 download,OpenClaw 会列出每个条目,以便您可以看到可用的工件。
安装器规范可以包含 os: ["darwin"|"linux"|"win32"] 来按平台过滤选项。
Node 安装遵循 openclaw.json 中的 skills.install.nodeManager(默认:npm;选项:npm/pnpm/yarn/bun)。这仅影响技能安装;Gateway 运行时应仍使用 Node (不推荐 Bun 用于 WhatsApp/Telegram)。
Go 安装:如果 go 缺失且 brew 可用,网关首先通过 Homebrew 安装 Go,并在可能的情况下将 GOBIN 设置为 Homebrew 的 bin。
Download 安装:url(必需)、archive(tar.gz | tar.bz2 | zip)、extract(默认:检测到归档时自动)、stripComponents、targetDir(默认:~/.openclaw/tools/<skillKey>)。

如果没有 metadata.openclaw,该技能始终符合条件(除非在配置中禁用或被捆绑技能的 skills.allowBundled 阻止)。

配置覆盖(`~/.openclaw/openclaw.json`)

捆绑/托管技能可以切换并提供环境变量值:

json5

{
  skills: {
    entries: {
      "nano-banana-pro": {
        enabled: true,
        apiKey: "GEMINI_KEY_HERE",
        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 的技能提供便利。
config:可选的自定义每技能字段包;自定义键必须位于此处。
allowBundled:仅针对捆绑技能的可选允许列表。如果设置,仅列表中的捆绑技能符合条件(托管/工作区技能不受影响)。

环境注入(每个代理运行)

当代理运行启动时,OpenClaw:

读取技能元数据。
将任何 skills.entries.<key>.env 或 skills.entries.<key>.apiKey 应用到 process.env。
使用符合条件的技能构建系统提示。
在运行结束后恢复原始环境。

这限定于代理运行范围,而不是全局 shell 环境。

会话快照(性能)

OpenClaw 在会话开始时对符合条件的技能进行快照,并在同一会话的后续轮次中重用该列表。对技能或配置的更改将在下一个新会话中生效。

当技能监视器启用或出现新的符合条件的远程节点时,技能也可以在会话中刷新(见下文)。可以将其视为热重载:刷新的列表在下一个代理轮次时被采用。

远程 macOS 节点(Linux 网关)

如果网关在 Linux 上运行,但连接了允许 system.run 的 macOS 节点(Exec 批准安全性未设置为 deny),当该节点上存在所需的二进制文件时,OpenClaw 可以将仅限 macOS 的技能视为符合条件。代理应通过 nodes 工具执行这些技能(通常为 nodes.run)。

这依赖于节点报告其命令支持以及通过 system.run 进行的二进制探测。如果 macOS 节点稍后离线,技能仍然可见;在节点重新连接之前,调用可能会失败。

技能监视器(自动刷新)

默认情况下,OpenClaw 监视技能文件夹,并在 SKILL.md 文件更改时更新技能快照。在 skills.load 下配置:

json5

{
  skills: {
    load: {
      watch: true,
      watchDebounceMs: 250,
    },
  },
}

令牌影响(技能列表)

当技能符合条件时,OpenClaw 会将可用技能的紧凑 XML 列表注入到系统提示中(通过 pi-coding-agent 中的 formatSkillsForPrompt)。成本是确定性的:

**基本开销(仅当 ≥1 个技能时)😗*195 个字符。
**每个技能:**97 个字符 + XML 转义的 <name>、<description> 和 <location> 值的长度。

公式(字符数):

total = 195 + Σ (97 + len(name_escaped) + len(description_escaped) + len(location_escaped))

注意:

XML 转义将 & < > " ' 扩展为实体(&、< 等),增加长度。
令牌计数因模型分词器而异。OpenAI 风格的粗略估算是每令牌约 4 个字符,因此97 个字符 ≈ 每个技能 24 个令牌加上您的实际字段长度。

托管技能生命周期

OpenClaw 作为安装(npm 包或 OpenClaw.app)的一部分提供一组基准技能作为捆绑技能。~/.openclaw/skills 用于本地覆盖(例如,在不更改捆绑副本的情况下固定/修补技能)。工作区技能属于用户所有,并在名称冲突时覆盖两者。

配置参考

有关完整配置架构,请参阅技能配置。

寻找更多技能?

浏览 https://clawhub.com.

技能 (OpenClaw) ​

位置和优先级 ​

每个代理的技能 vs 共享技能 ​

插件 + 技能 ​

ClawHub(安装 + 同步) ​

安全注意事项 ​

格式(AgentSkills + Pi-兼容) ​

门控(加载时过滤器) ​

配置覆盖(~/.openclaw/openclaw.json) ​

环境注入(每个代理运行) ​

会话快照(性能) ​

远程 macOS 节点(Linux 网关) ​

技能监视器(自动刷新) ​

令牌影响(技能列表) ​

托管技能生命周期 ​

配置参考 ​

寻找更多技能? ​

技能 (OpenClaw)

位置和优先级

每个代理的技能 vs 共享技能

插件 + 技能

ClawHub(安装 + 同步)

安全注意事项

格式(AgentSkills + Pi-兼容)

门控(加载时过滤器)

配置覆盖(`~/.openclaw/openclaw.json`)

环境注入(每个代理运行)

会话快照(性能)

远程 macOS 节点(Linux 网关)

技能监视器(自动刷新)

令牌影响(技能列表)

托管技能生命周期

配置参考

寻找更多技能?