Skills (OpenClaw)

OpenClaw 使用 AgentSkills 兼容的 skill 文件夹来教 Agent 如何使用工具。每个 skill 是一个包含 SKILL.md 的目录，文件中有 YAML frontmatter 和指令。OpenClaw 会加载内置 skills 以及可选的本地覆盖版本，并在加载时根据环境、配置和二进制文件是否存在来过滤它们。

位置和优先级

Skills 从三个地方加载：

内置 skills：随安装包一起发布（npm 包或 OpenClaw.app）
管理型/本地 skills：~/.openclaw/skills
Workspace skills：<workspace>/skills

如果 skill 名称冲突，优先级是：

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

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

单 Agent vs 共享 skills

在多 Agent 设置中，每个 Agent 都有自己的 Workspace。这意味着：

单 Agent skills 位于 <workspace>/skills，仅供该 Agent 使用。
共享 skills 位于 ~/.openclaw/skills（管理型/本地），对同一台机器上的所有 Agents 可见。
共享文件夹 也可以通过 skills.load.extraDirs 添加（优先级最低），如果你想让多个 Agents 使用同一套 skills。

如果同一个 skill 名称在多个地方存在，应用常规优先级规则：Workspace 优先，然后是管理型/本地，最后是内置。

Plugins + skills

Plugins 可以通过在 openclaw.plugin.json 中列出 skills 目录来提供自己的 skills（路径相对于 plugin 根目录）。Plugin skills 在 plugin 启用时加载，并参与正常的 skill 优先级规则。你可以通过 plugin 配置项上的 metadata.openclaw.requires.config 来设置加载条件。参见 Plugins 了解发现/配置，参见 Tools 了解这些 skills 教授的工具接口。

ClawHub（安装 + 同步）

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

常见操作：

安装 skill 到你的 Workspace：
- clawhub install <skill-slug>
更新所有已安装的 skills：
- clawhub update --all
同步（扫描 + 发布更新）：
- clawhub sync --all

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

安全注意事项

将第三方 skills 视为不可信代码。启用前先阅读它们。
对于不可信输入和高风险工具，优先使用沙箱运行。参见 Sandboxing。
skills.entries.*.env 和 skills.entries.*.apiKey 会将密钥注入到该 Agent 回合的宿主进程中（不是 Sandbox）。不要在 prompts 和日志中暴露密钥。
更广泛的威胁模型和检查清单，参见 Security。

格式（AgentSkills + Pi 兼容）

SKILL.md 至少要包含：

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

注意事项：

我们遵循 AgentSkills 规范的布局/意图。
嵌入式 Agent 使用的解析器仅支持单行 frontmatter 键。
metadata 应该是单行 JSON 对象。
在指令中使用 {baseDir} 来引用 skill 文件夹路径。
可选的 frontmatter 键：
- homepage — URL，在 macOS Skills UI 中显示为 “Website”（也支持通过 metadata.openclaw.homepage 设置）。
- user-invocable — true|false（默认：true）。为 true 时，skill 会作为用户斜杠命令暴露。
- disable-model-invocation — true|false（默认：false）。为 true 时，skill 会从模型 prompt 中排除（仍可通过用户调用使用）。
- command-dispatch — tool（可选）。设置为 tool 时，斜杠命令会绕过模型直接分发到工具。
- command-tool — 当 command-dispatch: tool 设置时要调用的工具名称。
- command-arg-mode — raw（默认）。对于工具分发，将原始参数字符串转发给工具（无核心解析）。
  
  工具会以以下参数调用： { command: "<raw args>", commandName: "<slash command>", skillName: "<skill name>" }。

加载过滤（load-time filters）

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 — 可选的 emoji，macOS Skills UI 使用。
homepage — 可选的 URL，在 macOS Skills UI 中显示为 “Website”。
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 在容器创建后运行一次。包安装还需要网络出口、可写的根文件系统和 Sandbox 中的 root 用户。示例：summarize skill（skills/summarize/SKILL.md）需要在 Sandbox 容器中有 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）。这仅影响 skill 安装；Gateway Runtime 仍应使用 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，skill 始终可用（除非在配置中禁用或被 skills.allowBundled 阻止，针对内置 skills）。

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

内置/管理型 skills 可以切换并提供环境变量值：

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

注意：如果 skill 名称包含连字符，请用引号括起键（JSON5 允许带引号的键）。

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

规则：

enabled: false 会禁用 skill，即使它是内置/已安装的。
env：仅在进程中尚未设置该变量时注入。
apiKey：为声明了 metadata.openclaw.primaryEnv 的 skills 提供便利。
config：可选的自定义单 skill 字段包；自定义键必须放在这里。
allowBundled：可选的内置 skills 白名单。如果设置，只有列表中的内置 skills 可用（管理型/Workspace skills 不受影响）。

环境变量注入（每次 Agent 运行）

当 Agent 运行开始时，OpenClaw：

读取 skill 元数据。
将任何 skills.entries.<key>.env 或 skills.entries.<key>.apiKey 应用到 process.env。
使用可用的 skills 构建系统 prompt。
运行结束后恢复原始环境。

这是限定在 Agent 运行范围内的，不是全局 shell 环境。

Session 快照（性能）

OpenClaw 在 Session 开始时对可用 skills 进行快照，并在同一 Session 的后续回合中重用该列表。对 skills 或配置的更改会在下一个新 Session 中生效。

当启用 skills 监视器或出现新的可用远程节点时，Skills 也可以在 Session 中刷新（见下文）。可以将其视为热重载：刷新后的列表会在下一个 Agent 回合中被使用。

远程 macOS 节点（Linux Gateway）

如果 Gateway 在 Linux 上运行，但连接了一个 macOS 节点****且允许 system.run（Exec 审批安全性未设置为 deny），当所需的二进制文件存在于该节点上时，OpenClaw 可以将仅限 macOS 的 skills 视为可用。Agent 应通过 nodes 工具（通常是 nodes.run）执行这些 skills。

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

Skills 监视器（自动刷新）

默认情况下，OpenClaw 会监视 skill 文件夹，并在 SKILL.md 文件更改时更新 skills 快照。在 skills.load 下配置：

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

Token 影响（skills 列表）

当 skills 可用时，OpenClaw 会将可用 skills 的紧凑 XML 列表注入到系统 prompt 中（通过 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 转义会将 & < > " ' 扩展为实体（&、< 等），增加长度。
Token 计数因模型分词器而异。粗略的 OpenAI 风格估算是约 4 字符/token，所以 97 字符 ≈ 24 tokens 每个 skill，加上你的实际字段长度。

管理型 skills 生命周期

OpenClaw 作为安装的一部分（npm 包或 OpenClaw.app）提供一组基线 skills 作为内置 skills。~/.openclaw/skills 用于本地覆盖（例如，在不更改内置副本的情况下固定/修补 skill）。Workspace skills 由用户拥有，在名称冲突时覆盖两者。

配置参考

完整配置架构参见 Skills config。

寻找更多 skills？

浏览 https://clawhub.com。

Skills (OpenClaw)

位置和优先级

单 Agent vs 共享 skills

Plugins + skills

ClawHub（安装 + 同步）

安全注意事项

格式（AgentSkills + Pi 兼容）

加载过滤（load-time filters）

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

环境变量注入（每次 Agent 运行）

Session 快照（性能）

远程 macOS 节点（Linux Gateway）

Skills 监视器（自动刷新）

Token 影响（skills 列表）

管理型 skills 生命周期

配置参考

寻找更多 skills？

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