OpenClaw中文社区

主题

技能 ​

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

位置和优先级 ​

技能从三个位置加载：

  1. 捆绑技能：随安装一起提供（npm 包或 OpenClaw.app）
  2. 托管/本地技能：~/.openclaw/skills
  3. 工作区技能：<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 来限制它们。请参阅插件了解发现/配置，以及工具了解这些技能教授的工具界面。

ClawdHub（安装 + 同步） ​

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

常见流程：

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

默认情况下，clawdhub 安装到当前工作目录下的 ./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 规范的布局和意图。
  • 嵌入式智能体使用的解析器仅支持单行前置matter键。
  • metadata 应该是单行 JSON 对象。
  • 在说明中使用 {baseDir} 引用技能文件夹路径。
  • 可选的前置matter键：

    • 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）。如果设置，技能仅在这些 OS 上符合条件。
  • 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）。 这仅影响技能安装；网关运行时仍应为 Node（Bun 不推荐用于 WhatsApp/Telegram）。
  • Go 安装：如果缺少 go 且 brew 可用，网关会先通过 Homebrew 安装 Go，并在可能时将 GOBIN 设置为 Homebrew 的 bin。
  • Download 安装：url（必需）、archive（tar.gz | tar.bz2 | zip）、extract（默认：检测到 archive 时自动提取）、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：

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

这是作用域到智能体运行，而不是全局 shell 环境。

会话快照（性能） ​

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

当启用技能监视器或出现新的符合资格的远程节点时，技能也可以在会话中期刷新（见下文）。将其视为热重载：刷新后的列表会在下次智能体轮次时被拾取。

远程 macOS 节点（Linux 网关） ​

如果网关在 Linux 上运行，但macOS 节点已连接且允许 system.run（执行批准安全性未设置为 deny），OpenClaw 可以在所需二进制文件存在于该节点上时，将 macOS 专属技能视为符合条件。智能体应该通过 nodes 工具（通常是 nodes.run）执行这些技能。

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

技能监视器（自动刷新） ​

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

json5
{
  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 转义将 & < > " ' 转换为实体（&amp;、&lt; 等），增加长度。
  • Token 数量因模型分词器而异。粗略的 OpenAI 风格估计是 ~4 个字符/token，所以 97 个字符 ≈ 24 个token 加上你的实际字段长度。

托管技能生命周期 ​

OpenClaw 作为安装的一部分（npm 包或 OpenClaw.app）随附一组基线技能作为捆绑技能。~/.openclaw/skills 用于本地覆盖（例如，无需更改捆绑副本即可固定/修补技能）。工作区技能是用户拥有的，并在名称冲突时覆盖两者。

配置参考 ​

有关完整的配置模式，请参阅技能配置。

寻找更多技能？ ​

浏览 https://clawdhub.com。

基于 MIT 许可发布

Copyright © 2026-present OpenClaw中文社区