技能

技能 (OpenClaw)

OpenClaw 使用 AgentSkills 兼容的技能文件夹来教 Agent 如何使用工具。每个技能是一个包含带有 YAML 前置事项和说明的 SKILL.md 的目录。OpenClaw 加载捆绑技能加上可选的本地覆盖，并根据环境、配置和二进制存在性在加载时过滤它们。

位置和优先级

技能从 三个 地方加载：

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

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

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

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

每个 Agent vs 共享技能

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

如果同一名称的技能存在于多个地方，应用通常的优先级规则：工作区获胜，然后是托管/本地，最后是捆绑。

插件 + 技能

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

ClawdHub（安装 + 同步）

ClawdHub 是 OpenClaw 的公共技能注册表。在 https://clawdhub.com 浏览。用它来发现、安装、更新和备份技能。
完整指南：[ClawdHub(../tools/clawdhub.html)。

常见流程：

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

安全说明

格式 (AgentSkills + Pi 兼容)

SKILL.md 必须至少包含：

---
name: nano-banana-pro
description: 通过 Gemini 3 Pro Image 生成或编辑图像
---

说明：

门控（加载时过滤器）

OpenClaw 在加载时使用 metadata（单行 JSON）过滤技能：

---
name: nano-banana-pro
description: 通过 Gemini 3 Pro Image 生成或编辑图像
metadata: {"openclaw":{"requires":{"bins":["uv"],"env":["GEMINI_API_KEY"],"config":["browser.enabled"]},"primaryEnv":"GEMINI_API_KEY"}}
---

metadata.openclaw 下的字段：

关于沙盒化的说明：

安装程序示例：

---
name: gemini
description: 使用 Gemini CLI 进行编码协助和 Google 搜索查找。
metadata: {"openclaw":{"emoji":"♊️","requires":{"bins":["gemini"]},"install":[{"id":"brew","kind":"brew","formula":"gemini-cli","bins":["gemini"],"label":"安装 Gemini CLI (brew)"}]}}
---

说明：

如果没有 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 下的该键。

规则：

环境注入（每个 Agent 运行）

当 Agent 运行开始时，OpenClaw：

  1. 读取技能元数据。
  2. 应用任何 skills.entries.<key>.env 或 skills.entries.<key>.apiKey 到
    process.env。
  3. 用 有效 技能构建系统提示。
  4. 运行结束后恢复原始环境。

这 限定于 Agent 运行，不是全局 shell 环境。

会话快照（性能）

OpenClaw 在会话开始时快照有效技能，并在同一会话的后续轮次中重用该列表。技能或配置的更改在下一次新会话时生效。

当启用技能监视器或新的有效远程节点出现时，技能也可以在会话中刷新（见下文）。将其视为 热重载：刷新的列表在下一次 Agent 轮次中获取。

远程 macOS 节点（Linux Gateway）

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

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

技能监视器（自动刷新）

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

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

令牌影响（技能列表）

当技能有效时，OpenClaw 将可用技能的紧凑 XML 列表注入系统提示（通过 pi-coding-agent 中的 formatSkillsForPrompt）。成本是确定的：

公式（字符）：

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

说明：

托管技能生命周期

OpenClaw 将一组基线技能作为 捆绑技能 随安装一起发布（npm 包或 OpenClaw.app）。~/.openclaw/skills 存在用于本地覆盖（例如，固定/修补技能而不更改捆绑副本）。工作区技能是用户拥有的，在名称冲突时覆盖两者。

配置参考

参见 [技能配置(../tools/skills-config.html) 了解完整配置模式。

寻找更多技能？

浏览 https://clawdhub.com。