Skills（OpenClaw）

OpenClaw 使用兼容 AgentSkills 的 Skill 文件夹来教 Agent 如何使用工具。每个 Skill 就是一个目录，包含带有 YAML 前置元数据和说明的 SKILL.md。OpenClaw 加载内置 Skills 和可选的本地覆盖，并在加载时根据环境、配置和二进制文件是否存在来过滤。

位置和优先级

Skills 从三个位置加载：

  1. 内置 Skills：随安装一起发布（npm 包或 OpenClaw.app）
  2. 托管/本地 Skills：~/.openclaw/skills
  3. 工作区 Skills：<workspace>/skills

名称冲突时的优先级：

<workspace>/skills（最高）→ ~/.openclaw/skills → 内置 Skills（最低）

此外，你可以在 ~/.openclaw/openclaw.json 中通过 skills.load.extraDirs 配置额外的 Skill 文件夹（优先级最低）。

按 Agent vs 共享 Skills

在多 Agent 架构中，每个 Agent 有自己的工作区。也就是说：

  • 按 Agent 的 Skills 放在该 Agent 的 <workspace>/skills 中，仅该 Agent 可见。
  • 共享 Skills 放在 ~/.openclaw/skills（托管/本地），同一台机器上的所有 Agent 可见。
  • 共享文件夹 也可以通过 skills.load.extraDirs 添加（优先级最低），方便多个 Agent 使用同一套 Skills 包。

如果同名 Skill 存在于多个位置，照常按优先级生效：工作区优先，然后托管/本地，最后内置。

插件 + Skills

插件可以在 openclaw.plugin.json 中列出 skills 目录（路径相对于插件根目录）来附带 Skills。插件 Skills 在插件启用时加载，参与正常的优先级规则。 你可以通过插件配置入口的 metadata.openclaw.requires.config 来控制它们的门控。参见 插件 了解发现/配置，以及 工具 了解这些 Skills 所教授的工具能力。

ClawHub（安装 + 同步）

ClawHub 是 OpenClaw 的公共 Skills 注册中心。浏览地址： https://clawhub.com。用它来发现、安装、更新和备份 Skills。 完整指南：ClawHub。

常用操作：

  • 将 Skill 安装到工作区：
    • clawhub install <skill-slug>
  • 更新所有已安装的 Skills：
    • clawhub update --all
  • 同步（扫描 + 发布更新）：
    • clawhub sync --all

默认情况下，clawhub 安装到当前工作目录下的 ./skills（或回退到配置的 OpenClaw 工作区）。OpenClaw 会在下一个会话中将其识别为 <workspace>/skills。

安全须知

  • 将第三方 Skills 视为不可信代码。启用前请仔细阅读。
  • 对不可信输入和高风险工具，优先使用沙箱化运行。参见 沙箱。
  • 工作区和额外目录的 Skill 发现只接受已解析真实路径在配置根目录内的 Skill 根目录和 SKILL.md 文件。
  • skills.entries.*.env 和 skills.entries.*.apiKey 将密钥注入该 Agent 轮次的主机进程（不是沙箱）。请将密钥远离提示词和日志。
  • 更广泛的威胁模型和检查清单，参见 安全。

格式（AgentSkills + Pi 兼容）

SKILL.md 至少需要包含：

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

说明：

  • 遵循 AgentSkills 规范的布局/意图。
  • 内嵌 Agent 使用的解析器仅支持单行前置元数据 key。
  • metadata 应该是单行 JSON 对象。
  • 在说明中使用 {baseDir} 引用 Skill 文件夹路径。
  • 可选的前置元数据 key：

    • homepage — 在 macOS Skills UI 中显示为”Website”的 URL（也支持通过 metadata.openclaw.homepage 设置）。

    • user-invocable — true|false（默认 true）。为 true 时，Skill 作为用户斜杠命令暴露。

    • disable-model-invocation — true|false（默认 false）。为 true 时，Skill 从模型提示词中排除（仍可通过用户调用使用）。

    • 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）过滤 Skills：

---
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 — 始终包含该 Skill（跳过其他门控）。
  • emoji — macOS Skills UI 使用的可选 emoji。
  • homepage — macOS Skills UI 中显示为”Website”的可选 URL。
  • os — 可选的平台列表（darwin、linux、win32）。设置后，Skill 仅在这些操作系统上可用。
  • requires.bins — 列表；每个都必须存在于 PATH 上。
  • requires.anyBins — 列表；至少一个必须存在于 PATH 上。
  • requires.env — 列表；环境变量必须存在或在配置中提供。
  • requires.config — openclaw.json 路径列表，必须为真值。
  • primaryEnv — 与 skills.entries.<name>.apiKey 关联的环境变量名。
  • install — macOS Skills UI 使用的可选安装器规范数组（brew/node/go/uv/download）。

关于沙箱化的说明：

  • requires.bins 在 Skill 加载时在主机上检查。
  • 如果 Agent 是沙箱化的，二进制文件也必须存在于容器内。 通过 agents.defaults.sandbox.docker.setupCommand（或自定义镜像）安装。 setupCommand 在容器创建后运行一次。 包安装还需要网络出站、可写根文件系统和沙箱中的 root 用户。 示例：summarize skill（skills/summarize/SKILL.md）需要 summarize CLI 在沙箱容器中才能运行。

安装器示例：

---
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）。 这只影响 Skills 安装；Gateway 运行时应该继续用 Node （WhatsApp/Telegram 不推荐用 Bun）。
  • Go 安装：如果缺少 go 但有 brew，Gateway 会先通过 Homebrew 安装 Go，并尽可能将 GOBIN 设为 Homebrew 的 bin。
  • Download 安装：url（必需）、archive（tar.gz | tar.bz2 | zip）、extract（默认：检测到归档时自动）、stripComponents、targetDir（默认 ~/.openclaw/tools/<skillKey>）。

如果没有 metadata.openclaw，Skill 始终可用（除非在配置中禁用或被内置 Skills 的 skills.allowBundled 阻止）。

配置覆盖（~/.openclaw/openclaw.json）

内置/托管 Skills 可以切换开关和提供环境变量值：

{
  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 },
    },
  },
}

注意：如果 Skill 名称包含连字符，需要引用 key（JSON5 允许带引号的 key）。

配置 key 默认匹配 Skill 名称。如果 Skill 定义了 metadata.openclaw.skillKey，请在 skills.entries 下使用该 key。

规则：

  • enabled: false 即使是内置/已安装的 Skill 也会被禁用。
  • env：仅在变量尚未在进程中设置时注入。
  • apiKey：便捷字段，用于声明了 metadata.openclaw.primaryEnv 的 Skills。支持纯文本字符串或 SecretRef 对象（{ source, provider, id }）。
  • config：可选的自定义按 Skill 字段容器；自定义 key 必须放在这里。
  • allowBundled：可选的内置 Skills 白名单。设置后，只有列表中的内置 Skills 有资格加载（托管/工作区 Skills 不受影响）。

环境注入（按 Agent 运行）

Agent 运行开始时，OpenClaw 会：

  1. 读取 Skill 元数据。
  2. 将 skills.entries.<key>.env 或 skills.entries.<key>.apiKey 应用到 process.env。
  3. 用符合条件的 Skills 构建系统提示词。
  4. 运行结束后恢复原始环境。

这是按 Agent 运行隔离的，不是全局 shell 环境。

会话快照（性能）

OpenClaw 在会话开始时对符合条件的 Skills 做快照，并在同一会话的后续轮次中复用。Skills 或配置的变更在下一个新会话生效。

Skills 也可以在会话内刷新，当 Skills 监视器启用或有新的符合条件的远程节点出现时（见下文）。可以理解为热重载：刷新后的列表在下一次 Agent 轮次被感知。

远程 macOS 节点（Linux Gateway）

如果 Gateway 运行在 Linux 上，但连接了一个允许 system.run 的 macOS 节点（Exec 审批安全级别不是 deny），OpenClaw 可以在该节点上存在所需二进制文件时将 macOS 专属 Skills 视为可用。Agent 应通过 nodes 工具（通常 nodes.run）来执行这些 Skills。

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

Skills 监视器（自动刷新）

默认情况下，OpenClaw 监视 Skills 文件夹，当 SKILL.md 文件变更时更新 Skills 快照。在 skills.load 下配置：

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

Token 影响（Skills 列表）

当有符合条件的 Skills 时，OpenClaw 将紧凑的 XML Skills 列表注入系统提示词（通过 pi-coding-agent 中的 formatSkillsForPrompt）。消耗是确定性的：

  • 基础开销（仅在有 1 个以上 Skill 时）： 195 字符。
  • 每个 Skill： 97 字符 + XML 转义后的 <name>、<description> 和 <location> 值的长度。

公式（字符数）：

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

说明：

  • XML 转义将 & < > " ' 扩展为实体（&amp;、&lt; 等），增加长度。
  • Token 数因模型分词器而异。OpenAI 风格的粗略估算是每 token 约 4 字符，所以 97 字符 ≈ 24 token 再加上实际字段长度。

托管 Skills 生命周期

OpenClaw 将一套基线 Skills 作为内置 Skills 随安装一起发布（npm 包或 OpenClaw.app）。~/.openclaw/skills 用于本地覆盖（例如在不修改内置副本的情况下固定/修补一个 Skill）。工作区 Skills 由用户拥有，在名称冲突时覆盖两者。

配置参考

完整配置 schema 参见 Skills 配置。

想找更多 Skills？

浏览 https://clawhub.com。

arrow_back
上一页
Slash Commands
下一页
Skills Config
arrow_forward