openclaw-vainplex/docs/zh-CN/tools/skills.md

read_when	summary	title	x-i18n
添加或修改技能 更改技能门控或加载规则	技能：托管型与工作区型、门控规则，以及配置/环境变量连接	技能	generated_at model provider source_hash source_path workflow 2026-02-01T21:43:46Z claude-opus-4-5 pi 54685da5885600b367ccdad6342497199fcb168ce33f8cdc00391d993f3bab7e tools/skills.md 15

技能（OpenClaw）

OpenClaw 使用与 AgentSkills 兼容的技能文件夹来教智能体如何使用工具。每个技能是一个目录，包含带有 YAML frontmatter 和说明的 SKILL.md 文件。OpenClaw 加载内置技能以及可选的本地覆盖，并在加载时根据环境、配置和二进制文件是否存在进行过滤。

位置和优先级

技能从三个位置加载：

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

如果技能名称冲突，优先级为：

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

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

按智能体与共享技能

在多智能体设置中，每个智能体拥有自己的工作区。这意味着：

• 按智能体技能位于该智能体专属的 <workspace>/skills 中。
• 共享技能位于 ~/.openclaw/skills（托管/本地），对同一机器上的所有智能体可见。
• 共享文件夹也可以通过 skills.load.extraDirs（最低优先级）添加，如果你希望多个智能体使用同一套技能包。

如果同一技能名称存在于多个位置，适用通常的优先级规则：工作区优先，然后是托管/本地，最后是内置。

插件 + 技能

插件可以通过在 openclaw.plugin.json 中列出 skills 目录（相对于插件根目录的路径）来附带自己的技能。插件技能在插件启用时加载，并参与正常的技能优先级规则。你可以通过插件配置项上的 metadata.openclaw.requires.config 进行门控。参见插件了解发现/配置，参见工具了解这些技能教授的工具功能。

ClawHub（安装 + 同步）

ClawHub 是 OpenClaw 的公共技能注册中心。浏览地址：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 必须至少包含：

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

说明：

• 我们遵循 AgentSkills 规范的布局/意图。
• 内嵌智能体使用的解析器仅支持单行 frontmatter 键。
• metadata 应为单行 JSON 对象。
• 在说明中使用 {baseDir} 引用技能文件夹路径。
• 可选的 frontmatter 键：

  • 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）在加载时过滤技能：

---
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 存在于沙箱容器中才能在其中运行。

安装器示例：

---
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 时选 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，Gateway 会先通过 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）

内置/托管技能可以切换启用状态并提供环境变量值：

{
  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：

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

这是限定在智能体运行范围内的，而非全局 shell 环境。

会话快照（性能）

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

技能也可以在会话中途刷新，当技能监视器启用时或当新的符合条件的远程节点出现时（见下文）。可以将其理解为热重载：刷新后的列表会在下一个智能体轮次中被使用。

远程 macOS 节点（Linux Gateway）

如果 Gateway 运行在 Linux 上，但有一个macOS 节点已连接且允许 system.run（执行审批安全级别未设为 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）。开销是确定性的：

• **基础开销（仅在有 ≥1 个技能时）：**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 用于本地覆盖（例如，在不更改内置副本的情况下固定/修补某个技能）。工作区技能由用户拥有，在名称冲突时覆盖两者。

配置参考

参见技能配置了解完整的配置模式。

想要更多技能？

浏览 https://clawhub.com。

---